Go to the first, previous, next, last section, table of contents.

Setting `runtest` defaults

The site configuration file, `site.exp', captures configuration-dependent values and propagates them to the DejaGnu test environment using Tcl variables. This ties the DejaGnu test scripts into the configure and make programs.

DejaGnu supports more than one `site.exp' file. The multiple instances of `site.exp' are loaded in a fixed order built into DejaGnu (the more local last). The first file loaded is the optional ~/.dejagnurc, then the local files, and finally the global file.

There is am optional "master" `site.exp', capturing configuration values that apply to DejaGnu across the board, in each configuration-specific subdirectory of the DejaGnu library directory. runtest loads these values first. See section Installing DejaGnu. The master `site.exp' contains the default values for all targets and hosts supported by DejaGnu. This master file is identified by setting the environment variable DEJAGNU to the name of the file. This is also refered to as the "global" config file.
Any directory containing a configured test suite also has a `site.exp', capturing configuration values specific to the tool under test. Since runtest loads these values last, the individual test configuration can either rely on and use, or override, any of the global values from the "master" `site.exp'. You can usually generate or update the testsuite `site.exp' by typing `make site.exp' in the test suite directory, after the test suite is configured.
You can also have a file in your home directory called .dejagnurc. This gets loaded first before the other config files. Usually this is used for personal stuff, like setting all_flag so all the output gets printed, or verbosity levels.

You can further override the default values in a user-editable section of any `site.exp', or by setting variables on the runtest command line.

Config Variables

DejaGnu uses a named array in Tcl to hold all the info for each machine. In the case of a canadian cross, this means host information as well as target information. The named array is called target_info, and it has two indices. The following fields are part of the array.

name: The name of the target. (mostly for error messages) This should also be the string used for this target's array. It should also be the same as the linker script so we can find them dynamically. This should be the same as the argument used for push_target{}.
ldflags: This is the linker flags required to produce a fully linked executable. For libgloss supported targets this is usually just the name of the linker script.
config: The target canonical for this target. This is used by some init files to make sure the target is supported.
cflags: The flags required to produce an object file from a source file.
connect: This is the connectmode for this target. This is for both IP and serial connections. Typically this is either telnet, rlogin, or rsh.
target: This is the hostname of the target. This is for TCP/IP based connections, and is also used for version of tip that use /etc/remote.
serial: This is the serial port. This is typically /dev/tty? or com?:.
netport: This is the IP port. This is commonly used for telneting to target boards that are connected to a terminal server. In that case the IP port specifies the which serial port to use.
baud: This is the baud rate for a serial port connection.
x10: This is the parameters for an x10 controller. These are simple devices that let us power cycle or reset a target board remotely.
fileid: This is the fileid or spawn id of of the connection.
prompt: a glob style pattern to recognize the prompt.
abbrev: abbreviation for tool init files.
ioport: This is the port for I/O on dual port systems. In this configuration, the main serial port 0 is usually used for stdin and stdout, which the second serial port can be used for debugging.

The first index into the array is the same value as used in the name field. This is usually a short version of the name of the target board. For an example, here's the settings I use for my Motorola's IDP board and my Motorola 6U VME MVME135-1 board. (both m68k targets)

# IDP board
set target_info(idp,name)       "idp"
set target_info(idp,ldflags)    "-Tidp.ld"
set target_info(idp,config)     m68k-unknown-aout
set target_info(idp,cflags)     ""
set target_info(idp,connect)    telnet
set target_info(idp,target)     "s7"
set target_info(idp,serial)     "tstty7"
set target_info(idp,netport)    "wharfrat:1007"
set target_info(idp,baud)       "9600"
# MVME 135 board
set target_info(idp,name)       "mvme"
set target_info(idp,ldflags)    "-Tmvme.ld"
set target_info(idp,config)     m68k-unknown-aout
set target_info(idp,cflags)     ""
set target_info(idp,connect)    telnet
set target_info(idp,target)     "s8"
set target_info(idp,serial)     "tstty8"
set target_info(idp,netport)    "wharfrat:1008"
set target_info(idp,baud)       "9600"

DejaGnu can use this information to switch between multiple targets in one test run. This is done through the use of the push_target procedure, which is discussed elsewhere.

This array can also hold information for a remote host, which is used when testing a candain cross. In this case, the only thing different is the index is just host. Here's the settings I use to run tests on my NT machine while running DejaGnu on a Unix machine. (in this case a Linux box)

set target_info(host,name)      "nt-host"
set target_info(host,config)    "386-unknown-winnt"
set target_info(host,connect)   "telnet"
set target_info(host,target)    "ripple"

There is more info on how to use these variables in the sections on the config files. See section Master Config File.

In the user editable second section of `site.exp', you can not only override the configuration variables captured in the first section, but also specify default values for all the runtest command line options. Save for `--debug', `--help', and `--version', each command line option has an associated Tcl variable. Use the Tcl set command to specify a new default value (as for the configuration variables). The following table describes the correspondence between command line options and variables you can set in `site.exp'. See section Using runtest, for explanations of the command-line options.

Master Config File

The master config file is where all the target specific config variables get set for a whole site get set. The idea is that for a centralized testing lab where people have to share a target between multiple developers. There are settings for both remote targets and remote hosts. Here's an example of a Master Config File (also called the Global config file) for a canadian cross. A canadian cross is when you build and test a cross compiler on a machine other than the one it's to be hosted on.

Here we have the config settings for our California office. Note that all config values are site dependant. Here we have two sets of values that we use for testing m68k-aout cross compilers. As both of these target boards has a different debugging protocol, we test on both of them in sequence.

global CFLAGS
global CXXFLAGS

case "$target_triplet" in {
    { "native" } {
        set target_abbrev unix
    }
    { "m68*-unknown-aout" } {
        set target_abbrev               "rom68k"
        # IDP target                    # IDP board with rom68k monitor
        set target_info(idp,name)       "idp"
        set target_info(idp,ldflags)    "-Tidp.ld"
        set target_info(idp,config)     m68k-unknown-aout
        set target_info(idp,cflags)     ""
        set target_info(idp,connect)    telnet
        set target_info(idp,target)     "s7"
        set target_info(idp,serial)     "tstty12"
        set target_info(idp,netport)    "truckin:1007"
        set target_info(idp,baud)       "9600"
        # MVME target                   # Motorola MVME 135 with BUG monitor
        set target_info(mvme,name)      "mvme"
        set target_info(mvme,ldflags)   "-Tmvme.ld"
        set target_info(mvme,config)    m68k-unknown-aout
        set target_info(mvme,cflags)    ""
        set target_info(mvme,connect)   telnet
        set target_info(mvme,target)    "s4"
        set target_info(mvme,serial)    "tstty8"
        set target_info(mvme,netport)   "truckin:1004"
        set target_info(mvme,baud)      "9600"
     }
}

In this case, we have support for several remote hosts for our m68k-aout cross compiler. Typically the remote Unix hosts run DejaGnu locally, but we also use them for debugging the testsuites when we find problems in running on remote hosts. Expect won't run on NT, so DejaGnu is run on the local build machine, and it'll connect to the NT host and run all the tests for this cross compiler on that host.

case "$host_triplet" in {
    "native" {
    }
    "i?86-*-linux*" {                   # Linux host
        set target_info(host,name)      "linux-host"
        set target_info(host,config)    $host_triplet
        set target_info(host,connect)   rlogin
        set target_info(host,target)    chinadoll
    }
    "i?86-*-winnt                       # NT host
        set target_info(host,name)      "nt-host"
        set target_info(host,config)    i386-unknown-winnt
        set target_info(host,connect)   telnet
        set target_info(host,target)    ripple
    }
    "hppa*-hp-hpux*" {                  # HP-UX host
        set target_info(host,name)      "hpux-host"
        set target_info(host,config)    $host_triplet
        set target_info(host,connect)   rlogin
        set target_info(host,target)    slipknot
        }
    "sparc-sun-sunos*" {                # SunOS (sun4)
        set target_info(host,name)      "sunos-host"
        set target_info(host,config)    $host_triplet
        set target_info(host,connect)   rlogin
        set target_info(host,target)    darkstar
    }
}

Local Config File

It is usually more convenient to keep these "manual overrides" in the `site.exp' local to each test directory, rather than in the "master" `site.exp' in the DejaGnu library.

All local `site.exp' usually files have two sections, separated by comment text. The first section is the part that is generated by make. It is essentially a collection of Tcl variable definitions based on `Makefile' environment variables. Since they are generated by make, they contain the values as specified by configure. (You can also customize these values by using the `--site' option to configure.) In particular, this section contains the `Makefile' variables for host and target configuration data. Do not edit this first section; if you do, your changes are replaced next time you run make.

The first section starts with:

## these variables are automatically generated by make ##
# Do not edit here. If you wish to override these values
# add them to the last section

In the second section, you can override any default values (locally to DejaGnu) for all the variables. The second section can also contain your preferred defaults for all the command line options to runtest. This allows you to easily customize runtest for your preferences in each configured test-suite tree, so that you need not type options repeatedly on the command line. (The second section may also be empty, if you do not wish to override any defaults.)

The first section ends with this line:

## All variables above are generated by configure. Do Not Edit ##

You can make any changes under this line. If you wish to redefine a variable in the top section, then just put a duplicate value in this second section. Usually the values defined in this config file are related to the configuration of the test run. This is the ideal place to set the variables host_triplet, build_triplet, target_triplet. All other variables are tool dependant. ie for testing a compiler, the value for CC might be set to a freshly built binary, as opposed to one in the user's path.

Personal Config File

The personal config file is used to customize runtest's behaviour for each person. It's typically used to set the user prefered setting for verbosity, and any experimental Tcl procedures. My personal `~/.dejagnurc' file looks like:

set all_flag 1
set RLOGIN /usr/ucb/rlogin
set RSH /usr/ucb/rsh