2.4. DejaGnu configuration files

Configuration files are used to set global variables and to define helper functions.

DejaGnu has a number of global variables which are set to correspond to runtest command line arguments. However they can alternatively be set in the various configuration files (if both are used, the command line takes precedence). The DejaGnu guide [3] documents them in full, but some of the most useful are shown in in Table 2.1.

runtest	expect	Description
`--all`	`all_flag`	Display all test results if set (default is only to display failures).
`--srcdir`	`srcdir`	The directory containing test sub-directories and the tool specific configuration directory, `lib`.
`--tool`	`tool`	The name of the tool being tested.
`--verbose`	`verbosity`	The degree of verbosity required. Default is 0. Value of the variable is incremented for each time it appears on the command line.

Table 2.1. runtest options and corresponding expect variables.

DejaGnu has a plethora of configuration files, each of which contain expect script that is processed before each test. The historical naming of some of these files can be confusing.

Although these configuration files are all optional, runtest may complain if it can't find them. So it's worth setting them up, just to stop the messages.

The configuration files are read in the following sequence.

Personal config file

This is in the user's home directory, ~/.dejagnurc. In general it is only used to set variables that control personal taste in output.

Local config file

This is always named site.exp and is looked for in the directory where the tests are being run. In general it is used to set variables specific to the tool or tools being tested.

If GNU autotools (autoconf, automake and libtool) are being used to drive DejaGnu this file will be created automatically whenever make is run. It will be placed in the main test suite directory, but within the build directory hierarchy, not the source directory hierarchy. It is this directory from which runtest will be executed.

When GNU autotools generate site.exp, the file is created in two halves, separated by a comment line. Only the first part is regenerated every time make is run, so changes may safely be made in the second half.

This is a convenient place for quickly testing changes. However the local config file in an autotools environment is inherently transient (it is in the build directory, not the source directory), so permanent changes should be placed in one of the other config files.

Global config file

This is intended as a file to allow a group testing the same product to share common settings. It is identified by the DEJAGNU environment variable, which should always be set to avoid warnings.

Board config file

This is used for settings specific to a particular target board, as specified by the --target_board option to runtest (see Section 2.1). If no target board is specified, then DejaGnu running on a POSIX system will typically decide the target is Unix and look for a file named unix.exp.

The search path for board configuration files is in the global variable boards_dir, which by default includes /usr/share/dejagnu/baseboards and /usr/share/dejagnu/config.

It is common to append additional directories to this search path in one of the earlier configuration directories (typically the global config file) to provide additional board specific information. This can be done by using the TCL lappend function. For example, to look in the config sub-directory of the main test directory for board specific settings, the following would be suitable in the global configuration file.

lappend boards_dir "$srcdir/boards"

	Note
	If multiple board configuration files are found in the different directories, they will all be used in the order they are found.

Tool config file

Finally DejaGnu will load code from a tool specific configuration file. This will be found in the lib sub-directory of the main test directory. For a tool named toolname, the file will be lib/toolname.exp.

This is the place to put helper functions for use by test code.

Note

When running runtest, multiple test programs may be found in the test directory or directories. These are effectively concatenated, so they are run one after the other after running all the configurations.

The important thing to remember is that this means the configuration files are only read once, not once for each test.