Chapter 3. Customizing DejaGnu

Table of Contents
Local Config File
Global Config File
Board Config File
Remote Host Testing
Config File Values

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. If this file is setup correctly, it is possible to execute a test suite merely by typing runtest.

DejaGnu supports two site.exp files. The multiple instances of site.exp are loaded in a fixed order built into DejaGnu. The first file loaded is the local file site.exp, and then the optional global site.exp file as pointed to by the DEJAGNU environment variable.

There is an 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. 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 local 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 global site.exp file.

You can usually generate or update the testsuite's local 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 the all_flag so all the output gets printed, or your own verbosity levels. This file is usually restricted to setting command line options.

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.

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 global site.exp in the installed DejaGnu library. This file is mostly for supplying tool specific info that is required by the test suite.

All local site.exp 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.

Example 3-1. 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.)

Example 3-2. 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.

Here's an example local site.exp file, as used for GCC/G++ testing.

Example 3-3. Local Config File

  
      ## these variables are automatically generated by make ##
      # Do not edit here. If you wish to override these values
      # add them to the last section
      set rootme "/build/devo-builds/i586-pc-linux-gnulibc1/gcc"
      set host_triplet i586-pc-linux-gnulibc1
      set build_triplet i586-pc-linux-gnulibc1
      set target_triplet i586-pc-linux-gnulibc1
      set target_alias i586-pc-linux-gnulibc1
      set CFLAGS ""
      set CXXFLAGS "-I/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -I$srcdir/../libg++/src -I$srcdir/../libio -I$srcdir/../libstdc++ -I$srcdir/../libstdc++/stl -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libg++ -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libstdc++"
      append LDFLAGS " -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../ld"
      set tmpdir /build/devo-builds/i586-pc-linux-gnulibc1/gcc/testsuite
      set srcdir "${srcdir}/testsuite"
      ## All variables above are generated by configure. Do Not Edit ##
    
      

This file defines the required fields for a local config file, namely the three config triplets, and the srcdir. It also defines several other Tcl variables that are used exclusivly by the GCC test suite. For most test cases, the CXXFLAGS and LDFLAGS are supplied by DejaGnu itself for cross testing, but to test a compiler, GCC needs to manipulate these itself.