5.4 Target dependent procedures

Each combination of target and tool requires some target-dependent procedures. The names of these procedures have a common form: the tool name, followed by an underbar ‘_’, and finally a suffix describing the procedure’s purpose. For example, a procedure to extract the version from GDB is called ‘gdb_version’. See section Initialization Module, for a discussion of how DejaGnu arranges to find the right procedures for each target.

runtest itself calls only two of these procedures, tool_exit and tool_version; these procedures use no arguments.

The other two procedures, tool_start and tool_load, are only called by the test suites themselves (or by testsuite-specific initialization code); they may take arguments or not, depending on the conventions used within each test suite.

tool_start

Starts a particular tool. For an interactive tool, tool_start starts and initializes the tool, leaving the tool up and running for the test cases; an example is gdb_start, the start function for GDB. For a batch oriented tool, tool_start is optional; the recommended convention is to let tool_start run the tool, leaving the output in a variable called comp_output. Test scripts can then analyze ‘$comp_output’ to determine the test results. An example of this second kind of start function is gcc_start, the start function for GCC.

runtest itself does not call tool_start. The initialization module ‘tool_init.exp’ must call tool_start for interactive tools; for batch-oriented tools, each individual test script calls tool_start (or makes other arrangements to run the tool).

tool_load

Loads something into a tool. For an interactive tool, this conditions the tool for a particular test case; for example, gdb_load loads a new executable file into the debugger. For batch oriented tools, tool_load may do nothing—though, for example, the GCC support uses gcc_load to load and run a binary on the target environment. Conventionally, tool_load leaves the output of any program it runs in a variable called ‘exec_output’. Writing tool_load can be the most complex part of extending DejaGnu to a new tool or a new target, if it requires much communication coding or file downloading.

Test scripts call tool_load.

tool_exit

Cleans up (if necessary) before runtest exits. For interactive tools, this usually ends the interactive session. You can also use tool_exit to remove any temporary files left over from the tests.

runtest calls tool_exit.

tool_version

Prints the version label and number for tool. This is called by the DejaGnu procedure that prints the final summary report. The output should consist of the full path name used for the tested tool, and its version number.

runtest calls tool_version.

The usual convention for return codes from any of these procedures (although it is not required by runtest) is to return 0 if the procedure succeeded, 1 if it failed, and -1 if there was a communication error.