---

2.2.2 Invoking runtest

This is the full set of command line options that runtest recognizes. Option names may be abbreviated to the shortest unique string.

-a, --all

Display all test output. By default, runtest shows only the output of tests that produce unexpected results; that is, tests with status FAIL (unexpected failure), XPASS (unexpected success), or ERROR (a severe error in the test case itself). Specify --all to see output for tests with status PASS (success, as expected) XFAIL (failure, as expected), or WARNING (minor error in the test case itself).

--build [triplet]

triplet is a system triplet of the form cpu-manufacturer-os. This is the type of machine DejaGnu and the tools to be tested are built on. For a normal cross environment this is the same as the host, but for a Canadian cross, they are different.

-D0, -D1

Start the internal Tcl debugger. The Tcl debugger supports breakpoints, single stepping, and other common debugging activities. See the document Debugger for Tcl Applications by Don Libes. If you specify -D1, the expect shell stops at a breakpoint as soon as DejaGnu invokes it. If you specify -D0, DejaGnu starts as usual, but you can enter the debugger by sending an interrupt (e.g. by typing Ctrl-c).

--debug

Turns on the Expect internal debugging output. Debugging output is displayed as part of the runtest output, and logged to a file called dbg.log. The extra debugging output does not appear on standard output, unless the verbose level is greater than 2 (for instance, to see debug output immediately, specify --debug -v -v). The debugging output shows all attempts at matching the test output of the tool with the scripted patterns describing expected output. The output generated with --strace also goes into dbg.log.

--global_init [name]

Use name as the global init file instead of site.exp in libdir. The default is, of course, site.exp. Note that this option accepts a relative file name, interpreted starting at libdir, so a file in a subdirectory may be used. This is probably less useful for most sites, but is orthogonal with the --local_init option and may be useful in large testing labs.

--help

Prints out a short summary of the runtest options, then exits (even if you specify other options).

--host [triplet]

triplet is a system triplet of the form cpu-manufactuer-os. Use this option to override the default string recorded by your configuration’s choice of host. This choice does not change how anything is actually configured unless –build is also specified; it affects only DejaGnu procedures that compare the host string with particular values. The procedures ishost, istarget, isnative, and setup_xfail are affected by --host. In this usage, host refers to the machine that the tests are to be run on, which may not be the same as the build machine. If --build is also specified, then --host refers to the machine that the tests will be run on, not the machine DejaGnu is run on.

--host_board [name]

The host board to use.

--ignore [tests(s)]

The name(s) of specific tests to ignore.

--local_init [name]

Use name as the testsuite local init file instead of site.exp in the current directory and in objdir. The default is, of course, site.exp. Note that this option accepts a relative file name, so a file in a subdirectory may be used.

--log_dialog

Emit Expect output to stdout. The Expect output is usually only written to the .log file. By enabling this option, they are also printed to standard output.

--mail [address(es)]

Send test results to one or more email addresses.

--objdir [path]

Use path as the top directory containing any auxiliary compiled test code. The default is ’.’. Use this option to locate pre-compiled test code. You can normally prepare any auxiliary files needed with make.

--outdir [path]

Write log files in directory path. The default is ’.’, the directory where you start runtest. This option affects only the summary (.sum) and the detailed log files (.log). The DejaGnu debug log dbg.log always appears (when requested) in the local directory.

--reboot [name]

Reboot the target board when runtest starts. When running tests on a separate target board, it is safer to reboot the target to be certain of its state. However, when developing test scripts, rebooting can take a lot of time.

--srcdir [path]

Use path as the top directory for test scripts to run. runtest looks in this directory for any subdirectory whose name begins with the toolname (specified with --tool). For instance, with --tool gdb, runtest uses tests in subdirectories gdb.* (with the usual shell-like filename expansion). If you do not use --srcdir, runtest looks for test directories under the current working directory.

--strace [n]

Turn on internal tracing for expect, to n levels deep. By adjusting the level, you can control the extent to which your output expands multi-level Tcl statements. This allows you to ignore some levels of case or if statements. Each procedure call or control structure counts as one “level”. The output is recorded in the same file, dbg.log, used for output from --debug.

--target [triplet]

Use this option to override the default setting (native testing). triplet is a system triplet of the form cpu-manufacturer-os. This option changes the configuration runtest uses for the default tool names, and other setup information.

--target_board [name(s)]

The list of target boards to run tests on.

--tool [name(s)]

Specifies which testsuite to run, and what initialization module to use. --tool is used only for these two purposes. It is not used to name the executable program to test. Executable tool names (and paths) are recorded in site.exp and you can override them by specifying Tcl variables on the command line.

For example, including --tool gcc on the command line runs tests from all test subdirectories whose names match gcc.*, and uses one of the initialization modules named config/*-gcc.exp. To specify the name of the compiler (perhaps as an alternative path to what runtest would use by default), use GCC=path-to-gcc on the runtest command line.

--tool_exec [name]

The path to the tool executable to test.

--tool_opts [options]

A list of additional options to pass to the tool.

-v, --verbose

Turns on more output. Repeating this option increases the amount of output displayed. Level one (-v) is simply test output. Level two (-v -v) shows messages on options, configuration, and process control. Verbose messages appear in the detailed (*.log) log file, but not in the summary (*.sum) log file.

-V, --version

Prints out the version numbers of DejaGnu, Expect, and Tcl.

-x, --xml

Generate XML output. The output file is named after the tool with an .xml extension.

testfile.exp[=arg(s)]

Specify the names of testsuites to run. By default, runtest runs all tests for the tool, but you can restrict it to particular testsuites by giving the names of the .exp scripts that control them. testsuite.exp cannot include directory names, only plain filenames.

arg(s) specifies a subset of test cases to run. For compiler or assembler tests, which often use a single .exp script covering many different test case files, this option allows you to further restrict the tests by listing particular test cases. For larger testsuites such as that included in GCC, this can save a lot of time. Some tools support wildcards here, but this varies from tool to tool. Typically the wildcards ?, *, and [chars] are recognized.

tclvar=value

You can define Tcl variables for use by your test scripts in the same style used with make for environment variables. For example, runtest GDB=gdb.old defines a variable called GDB; when your scripts refer to $GDB in this run, they use the value gdb.old.

The default Tcl variables used for most tools are defined in the main DejaGnu Makefile; their values are captured in the site.exp file.