DejaGnu: The GNU Testing Framework
PrevNext

8. Reference

8.1. Obtaining DejaGnu

You can obtain DejaGnu from the DejaGnu web site at the Free Software Foundation, which is at www.gnu.org/software/dejagnu/

8.2. Installation

Once you have the DejaGnu source unpacked and available, you must first configure the software to specify where it is to run (and the associated defaults); then you can proceed to installing it.

8.2.1. Configuring DejaGnu

It is usually best to configure in a directory separate from the source tree, specifying where to find the source with the optional --srcdir option to configure. DejaGnu uses the GNU autoconf to configure itself. For more info on using autoconf, read the GNU autoconf manual. To configure, execute the configure program, no other options are required. For an example, to configure in a separate tree for objects, execute the configure script from the source tree like this:


        ../dejagnu-1.4.5/configure

DejaGnu doesn't care at config time if it's for testing a native system or a cross system. That is determined at runtime by using the config files.

You may also want to use the configure option --prefix to specify where you want DejaGnu and its supporting code installed. By default, installation is in subdirectories of /usr/local, but you can select any alternate directory altdir by including --prefix{altdir}} on the configure command line. (This value is captured in the Makefile variables prefix and execprefix}.)

Save for a small number of example tests, the DejaGnu distribution itself does not include any testsuites; these are available separately. Testsuites for the GNU development tools are included in those releases. After configuring the top-level DejaGnu directory, unpack and configure the test directories for the tools you want to test; then, in each test directory, run make check to build auxiliary programs required by some of the tests, and run the test suites.

8.2.2. Installing DejaGnu

To install DejaGnu in your filesystem (either in /usr/local, or as specified by your --prefix option to configure), execute.


        eg$ make install

make installdoes these things for DejaGnu:

  • Look in the path specified for executables $exec_prefix) for directories called lib and bin. If these directories do not exist, make install creates them.

  • Create another directory in the share directory, called dejagnu, and copy all the library files into it.

  • Create a directory in the dejagnu/share directory, called config, and copy all the configuration files into it.

  • Copy the runtest shell script into $exec_prefix/bin.

  • Copy runtest.exp into $exec_prefix/lib/dejagnu. This is the main Tcl code implementing DejaGnu.

8.3. Builtin Procedures

DejaGnu provides these Tcl procedures.

8.3.1. Core Internal Procedures

8.3.1.1. Mail_file Procedure

mail_file(file to subject);

8.3.1.2. Open_logs Procedure

open_logs();

8.3.1.3. Close_logs Procedure

close_logs();

8.3.1.4. Isbuild Procedure

Tests for a particular build host environment. If the currently configured host matches the argument string, the result is 1; otherwise the result is 0. host must be a full three-part configure host name; in particular, you may not use the shorter nicknames supported by configure (but you can use wildcard characters, using shell syntax, to specify sets of names). If it is passed a NULL string, then it returns the name of the build canonical configuration.

isbuild(pattern);

pattern

8.3.1.5. Is_remote Procedure

is_remote(board);

8.3.1.6. is3way Procedure

Tests for a canadian cross. This is when the tests will be run on a remotely hosted cross compiler. If it is a canadian cross, then the result is 1; otherwise the result is 0.

is3way();

8.3.1.7. Ishost Procedure

Tests for a particular host environment. If the currently configured host matches the argument string, the result is 1; otherwise the result is 0. host must be a full three-part configure host name; in particular, you may not use the shorter nicknames supported by configure (but you can use wildcard characters, using shell syntax, to specify sets of names).

ishost(pattern);

8.3.1.8. Istarget Procedure

Tests for a particular target environment. If the currently configured target matches the argument string, the result is 1 ; otherwise the result is 0. target must be a full three-part configure target name; in particular, you may not use the shorter nicknames supported by configure (but you can use wildcard characters, using shell syntax, to specify sets of names). If it is passed a NULL string, then it returns the name of the build canonical configuration.

istarget(args);

8.3.1.9. Isnative Procedure

Tests whether the current configuration has the same host and target. When it runs in a native configuration this procedure returns a 1; otherwise it returns a 0.

isnative();

8.3.1.10. Unknown Procedure

unknown(args);

args

8.3.1.11. Clone_output Procedure

clone_output(message);

message

8.3.1.12. Reset_vars Procedure

reset_vars();

8.3.1.13. Log_and_exit Procedure

log_and_exit();

8.3.1.14. Log_summary Procedure

log_summary(args);

args

8.3.1.15. Cleanup Procedure

cleanup();

8.3.1.16. Setup_xfail Procedure

Declares that the test is expected to fail on a particular set of configurations. The config argument must be a list of full three-part configure target name; in particular, you may not use the shorter nicknames supported by configure (but you can use the common shell wildcard characters to specify sets of names). The bugid argument is optional, and used only in the logging file output; use it as a link to a bug-tracking system such as GNATS.

Once you use setup_xfail, the fail and pass procedures produce the messages XFAIL and XPASS respectively, allowing you to distinguish expected failures (and unexpected success!) from other test outcomes.

Warning

Warning you must clear the expected failure after using setup_xfail in a test case. Any call to pass or fail clears the expected failure implicitly; if the test has some other outcome, e.g. an error, you can call clear_xfail to clear the expected failure explicitly. Otherwise, the expected-failure declaration applies to whatever test runs next, leading to surprising results.

setup_xfail(config bugid);

config

The config triplet to trigger whether this is an unexpected or expect failure.

bugid

The optional bugid, used to tie this test case to a bug tracking system.

8.3.1.17. Record_test Procedure

record_test(type message args);

type

message

args

8.3.1.18. Pass Procedure

Declares a test to have passed. pass writes in the log files a message beginning with PASS (or XPASS, if failure was expected), appending the argument string.

pass(string);

string

The string to use for this PASS message.

8.3.1.19. Fail Procedure

Declares a test to have failed. fail writes in the log files a message beginning with FAIL (or XFAIL, if failure was expected), appending the argument string.

fail(string);

string

The string to use for this FAIL message.

8.3.1.20. Xpass Procedure

Declares a test to have unexpectably passed, when it was expected to be a failure. xpass writes in the log files a message beginning with XPASS (or XFAIL, if failure was expected), appending the argument string.

xpass(string);

string

The string to use for this output state.

8.3.1.21. Xfail Procedure

Declares a test to have expectably failed. xfail writes in the log files a message beginning with XFAIL (or PASS, if success was expected), appending the argument string.

xpass(string);

string

The string to use for this output state.

8.3.1.22. Set_warning_threshold Procedure

Sets the value of warning_threshold. A value of 0 disables it: calls to warning will not turn a PASS or FAIL into an UNRESOLVED.

set_warning_threshold(threshold);

threshold

This is the value of the new warning threshold.

8.3.1.23. Get_warning_threshold Procedure

Returns the current value of {warning_threshold. The default value is 3. This value controls how many warning procedures can be called before becoming UNRESOLVED.

get_warning_threshold();

8.3.1.24. Warning Procedure

Declares detection of a minor error in the test case itself. warning writes in the log files a message beginning with WARNING, appending the argument string. Use warning rather than perror for cases (such as communication failure to be followed by a retry) where the test case can recover from the error. If the optional number is supplied, then this is used to set the internal count of warnings to that value.

As a side effect, warning_threshold or more calls to warning in a single test case also changes the effect of the next pass or fail command: the test outcome becomes UNRESOLVED since an automatic PASS or FAIL may not be trustworthy after many warnings. If the optional numeric value is 0, then there are no further side effects to calling this function, and the following test outcome doesn't become UNRESOLVED. This can be used for errors with no known side effects.

warning(string number );

string

number

The optional number to set the error counter. This is only used to fake out the counter when using the xfail procedure to control when it flips the output over to UNRESOLVED state.

8.3.1.25. Perror Procedure

Declares a severe error in the testing framework itself. perror writes in the log files a message beginning with ERROR, appending the argument string.

As a side effect, perror also changes the effect of the next pass or fail command: the test outcome becomes UNRESOLVED, since an automatic PASS or FAIL cannot be trusted after a severe error in the test framework. If the optional numeric value is 0, then there are no further side effects to calling this function, and the following test outcome doesn't become UNRESOLVED. This can be used for errors with no known side effects.

perror(string number );

string

number

The optional number to set the error counter. This is only used to fake out the counter when using the xfail procedure to control when it flips the output over to UNRESOLVED state.

8.3.1.26. Note Procedure

Appends an informational message to the log file. note writes in the log files a message beginning with NOTE, appending the argument string. Use note sparingly. The verbose should be used for most such messages, but in cases where a message is needed in the log file regardless of the verbosity level use note.

note(string);

string

The string to use for this note.

8.3.1.27. Untested Procedure

Declares a test was not run. untested writes in the log file a message beginning with UNTESTED, appending the argument string. For example, you might use this in a dummy test whose only role is to record that a test does not yet exist for some feature.

untested(string);

string

The string to use for this output state.

8.3.1.28. Unresolved Procedure

Declares a test to have an unresolved outcome. unresolved writes in the log file a message beginning with UNRESOLVED, appending the argument string. This usually means the test did not execute as expected, and a human being must go over results to determine if it passed or failed (and to improve the test case).

unresolved(string);

string

The string to use for this output state.

8.3.1.29. Unsupported Procedure

Declares that a test case depends on some facility that does not exist in the testing environment. unsupported writes in the log file a message beginning with UNSUPPORTED, appending the argument string.

unsupported(string);

string

The string to use for this output state.

8.3.1.30. Init_testcounts Procedure

init_testcounts();

8.3.1.31. Incr_count Procedure

incr_count(name args);

name

args

8.3.1.32. transform Procedure

Generates a string for the name of a tool as it was configured and installed, given its native name (as the argument toolname). This makes the assumption that all tools are installed using the same naming conventions: For example, for a cross compiler supporting the m68k-vxworks configuration, the result of transform gcc is m68k-vxworks-gcc.

transform(toolname);

toolname

The name of the cross-development program to transform.

8.3.1.33. Check_conditional_xfail Procedure

This procedure adds a conditional xfail, based on compiler options used to create a test case executable. If an include options is found in the compiler flags, and it's the right architecture, it'll trigger an XFAIL. Otherwise it'll produce an ordinary FAIL. You can also specify flags to exclude. This makes a result be a FAIL, even if the included options are found. To set the conditional, set the variable compiler_conditional_xfail_data to the fields 

"[message string] [targets list] [includes
	  list] [excludes list]"
(descriptions below). This is the checked at pass/fail decision time, so there is no need to call the procedure yourself, unless you wish to know if it gets triggered. After a pass/fail, the variable is reset, so it doesn't effect other tests. It returns 1 if the conditional is true, or 0 if the conditional is false.

check_conditional_xfail(message targets includes excludes);

message

This is the message to print with the normal test result.

targets

This is a string with the list targets to activate this conditional on.

includes

This is a list of sets of options to search for in the compiler options to activate this conditional. If the list of sets of options is empty or if any set of the options matches, then this conditional is true. (It may be useful to specify an empty list of include sets if the conditional is always true unless one of the exclude sets matches.)

excludes

This is a list of sets of options to search for in the compiler options to activate this conditional. If any set of the options matches, (regardless of whether any of the include sets match) then this conditional is de-activated.

Example 42. Specifying the conditional xfail data


	  set compiler_conditional_xfail_data { \
	       "I sure wish I knew why this was hosed" \
               "sparc*-sun*-* *-pc-*-*" \
               {"-Wall -v" "-O3"} \
               {"-O1" "-Map"} \
          }

What this does is it matches only for these two targets if "-Wall -v" or "-O3" is set, but neither "-O1" or "-Map" is set. For a set to match, the options specified are searched for independently of each other, so a "-Wall -v" matches either "-Wall -v" or "-v -Wall". A space separates the options in the string. Glob-style regular expressions are also permitted.

8.3.1.34. Clear_xfail Procedure

Cancel an expected failure (previously declared with setup_xfail) for a particular set of configurations. The config argument is a list of configuration target names. It is only necessary to call clear_xfail if a test case ends without calling either pass or fail, after calling setup_xfail.

clear_xfail(config);

config

The configuration triplets to clear.

8.3.1.35. Verbose Procedure

Test cases can use this function to issue helpful messages depending on the number of --verbose options on the runtest command line. It prints string if the value of the variable verbose is higher than or equal to the optional number. The default value for number is 1. Use the optional -log argument to cause string to always be added to the log file, even if it won't be printed. Use the optional -x argument to log the test results into a parsable XML file. Use the optional -n argument to print string without a trailing newline. Use the optional -- argument if string begins with "-".

verbose(-log -x -n -r string number);

-x

-log

-n

--

string

number

8.3.1.36. Load_lib Procedure

Loads a DejaGnu library file by searching a fixed path built into DejaGnu. If DejaGnu has been installed, it looks in a path starting with the installed library directory. If you are running DejaGnu directly from a source directory, without first running make install, this path defaults to the current directory. In either case, it then looks in the current directory for a directory called lib. If there are duplicate definitions, the last one loaded takes precedence over the earlier ones.

load_lib(filespec);

filespec

The name of the DejaGnu library file to load.

8.3.2. Procedures For Remote Communication

lib/remote.exp defines these functions, for establishing and managing communications. Each of these procedures tries to establish the connection up to three times before returning. Warnings (if retries will continue) or errors (if the attempt is abandoned) report on communication failures. The result for any of these procedures is either -1, when the connection cannot be established, or the spawn ID returned by the Expect command spawn.

It use the value of the connect field in the target_info array (was connectmode as the type of connection to make. Current supported connection types are tip, kermit, telnet, rsh, rlogin, and netdata. If the --reboot option was used on the runtest command line, then the target is rebooted before the connection is made.

8.3.2.1. Call_remote Procedure

call_remote(type proc dest args);

proc

dest

args

8.3.2.2. Check_for_board_status Procedure

check_for_board_status(variable);

variable

8.3.2.3. File_on_build Procedure

file_on_build(op file args);

op

file

args

8.3.2.4. File_on_host Procedure

file_on_host(op file args);

op

file

args

8.3.2.5. Local_exec Procedure

local_exec(commandline inp outp timeout);

inp

outp

timeout

8.3.2.6. Remote_binary Procedure

remote_binary(host);

host

8.3.2.7. Remote_close Procedure

remote_close(shellid);

shellid

This is the value returned by a call to remote_open. This closes the connection to the target so resources can be used by others. This parameter can be left off if the fileid field in the target_info array is set.

8.3.2.8. Remote_download Procedure

remote_download(dest file args);

dest

file

args

8.3.2.9. Remote_exec Procedure

remote_exec(hostname program args);

hostname

program

args

8.3.2.10. Remote_expect Procedure

remote_expect(board timeout args);

board

timeout

args

8.3.2.11. Remote_file Procedure

remote_file(dest args);

dest

args

8.3.2.12. Remote_ld Procedure

remote_ld(dest prog);

dest

prog

8.3.2.13. Remote_load Procedure

remote_load(dest prog args);

dest

prog

args

8.3.2.14. Remote_open Procedure

remote_open(type);

type

This is passed host or target. Host or target refers to whether it is a connection to a remote target, or a remote host. This opens the connection to the desired target or host using the default values in the configuration system. It returns that spawn_id of the process that manages the connection. This value can be used in Expect or exp_send statements, or passed to other procedures that need the connection process's id. This also sets the fileid field in the target_info array.

8.3.2.15. Remote_pop_conn Procedure

remote_pop_conn(host);

host

8.3.2.16. Remote_push_conn Procedure

remote_push_conn(host);

host

8.3.2.17. Remote_raw_binary Procedure

remote_raw_binary(host);

host

8.3.2.18. Remote_raw_close Procedure

remote_raw_close(host);

host

8.3.2.19. Remote_raw_file Procedure

remote_raw_file(dest args);

dest

args

8.3.2.20. remote_raw_ld Procedure

remote_raw_ld(dest prog);

dest

prog

8.3.2.21. Remote_raw_load Procedure

remote_raw_load(dest prog args);

dest

prog

args

8.3.2.22. Remote_raw_open Procedure

remote_raw_open(args);

args

8.3.2.23. Remote_raw_send Procedure

remote_raw_send(dest string);

dest

string

8.3.2.24. Remote_raw_spawn Procedure

remote_raw_spawn(dest commandline);

dest

commandline

8.3.2.25. Remote_raw_transmit Procedure

remote_raw_transmit(dest file);

dest

file

8.3.2.26. Remote_raw_wait Procedure

remote_raw_wait(dest timeout);

dest

timeout

8.3.2.27. Remote_reboot Procedure

remote_reboot(host);

host

8.3.2.28. Remote_send Procedure

remote_send(dest string);

dest

string

8.3.2.29. Remote_spawn Procedure

remote_spawn(dest commandline args);

dest

commandline

args

8.3.2.30. Remote_swap_conn Procedure

remote_swap_conn(host);

8.3.2.31. Remote_transmit Procedure

remote_transmit(dest file);

dest

file

8.3.2.32. Remote_upload Procedure

remote_upload(dest srcfile arg);

dest

srcfile

arg

8.3.2.33. Remote_wait Procedure

remote_wait(dest timeout);

dest

timeout

8.3.2.34. Standard_close Procedure

standard_close(host);

host

8.3.2.35. Standard_download Procedure

standard_download(dest file destfile);

dest

file

destfile

8.3.2.36. Standard_exec Procedure

standard_exec(hostname args);

hostname

args

8.3.2.37. Standard_file Procedure

standard_file(dest op args);

8.3.2.38. Standard_load Procedure

standard_load(dest prog args);

dest

prog

args

8.3.2.39. Standard_reboot Procedure

standard_reboot(host);

host

8.3.2.40. Standard_send Procedure

standard_send(dest string);

dest

string

8.3.2.41. Standard_spawn Procedure

standard_spawn(dest commandline);

dest

commandline

8.3.2.42. Standard_transmit Procedure

standard_transmit(dest file);

dest

file

8.3.2.43. Standard_upload Procedure

standard_upload(dest srcfile destfile);

dest

srcfile

destfile

8.3.2.44. Standard_wait Procedure

standard_wait(dest timeout);

dest

timeout

8.3.2.45. Unix_clean_filename Procedure

unix_clean_filename(dest file);

dest

file

8.3.3. Procedures For Using Utilities to Connect

telnet, rsh, tip, kermit

8.3.3.1. telnet Procedure

telnet(hostname port);

rlogin(hostname);

8.3.3.2. rsh Procedure

rsh(hostname);

hostname

This refers to the IP address or name (for example, an entry in /etc/hosts) for this target. The procedure names reflect the Unix utility used to establish a connection. The optional port is used to specify the IP port number. The value of the netport field in the target_info array is used. (was $netport) This value has two parts, the hostname and the port number, separated by a :. If host or target is used in the hostname field, than the config array is used for all information.

8.3.3.3. Tip Procedure

tip(port);

port

Connect using the Unix utility tip. Portmust be a name from the tip configuration file /etc/remote. Often, this is called hardwire, or something like ttya. This file holds all the configuration data for the serial port. The value of the serial field in the target_info array is used. (was $serialport) If host or target is used in the port field, than the config array is used for all information. the config array is used for all information.

8.3.3.4. Kermit Procedure

kermit(port bps);

port

Connect using the program kermit. Port is the device name, e.g. /dev/ttyb.

bps

bps is the line speed to use (in its per second) for the connection. The value of the serial field in the target_info array is used. (was $serialport) If host or target is used in the port field, than the config array is used for all information. the config array is used for all information.

8.3.3.5. kermit_open Procedure

kermit_open(dest args);

dest

args

8.3.3.6. Kermit_command Procedure

kermit_command(dest args);

dest

args

8.3.3.7. Kermit_send Procedure

kermit_send(dest string args);

dest

string

args

8.3.3.8. Kermit_transmit Procedure

kermit_transmit(dest file args);

dest

file

args

8.3.3.9. Telnet_open Procedure

telnet_open(hostname args);

hostname

args

8.3.3.10. Telnet_binary Procedure

telnet_binary(hostname);

hostname

8.3.3.11. Telnet_transmit Procedure

telnet_transmit(dest file args);

dest

file

args

8.3.3.12. Tip_open Procedure

tip_open(hostname);

hostname

8.3.3.13. Rlogin_open Procedure

rlogin_open(arg);

arg

8.3.3.14. Rlogin_spawn Procedure

rlogin_spawn(dest cmdline);

dest

cmdline

8.3.3.15. Rsh_open Procedure

rsh_open(hostname);

hostname

8.3.3.16. Rsh_download Procedure

rsh_download(desthost srcfile destfile);

desthost

srcfile

destfile

8.3.3.17. Rsh_upload Procedure

rsh_upload(desthost srcfile destfile);

desthost

srcfile

destfile

8.3.3.18. Rsh_exec Procedure

rsh_exec(boardname cmd args);

boardname

cmd

args

8.3.3.19. Ftp_open Procedure

ftp_open(host);

host

8.3.3.20. Ftp_upload Procedure

ftp_upload(host remotefile localfile);

host

remotefile

localfile

8.3.3.21. Ftp_download Procedure

ftp_download(host localfile remotefile);

host

localfile

remotefile

8.3.3.22. Ftp_close Procedure

ftp_close(host);

host

8.3.3.23. Tip_download Procedure

tip_download(spawnid file);

spawnid

Download file to the process spawnid (the value returned when the connection was established), using the ~put command under tip. Most often used for single board computers that require downloading programs in ASCII S-records. Returns 1 if an error occurs, 0 otherwise.

file

This is the filename to download.

8.3.4. Procedures For Target Boards

8.3.4.1. Default_link Procedure

default_link(board objects destfile flags);

board

objects

destfile

flags

8.3.4.2. Default_target_assemble Procedure

default_target_assemble(source destfile flags);

source

destfile

flags

8.3.4.3. default_target_compile Procedure

default_target_compile(source destfile type options);

source

destfile

type

options

8.3.4.4. Pop_config Procedure

pop_config(type);

type

8.3.4.5. Prune_warnings Procedure

prune_warnings(text);

text

8.3.4.6. Push_build Procedure

push_build(name);

name

8.3.4.7. push_config Procedure

push_config(type name);

type

name

8.3.4.8. Reboot_target Procedure

reboot_target();

8.3.4.9. Target_assemble Procedure

target_assemble(source destfile flags);

source

destfile

flags

8.3.4.10. Target_compile Procedure

target_compile(source destfile type options);

source

destfile

type

options

8.3.5. Target Database Procedures

8.3.5.1. Board_info Procedure

board_info(machine op args);

machine

op

args

8.3.5.2. Host_info Procedure

host_info(op args);

op

args

8.3.5.3. Set_board_info Procedure

set_board_info(entry value);

entry

value

8.3.5.4. Set_currtarget_info Procedure

set_currtarget_info(entry value);

entry

value

8.3.5.5. Target_info Procedure

target_info(op args);

op

args

8.3.5.6. Unset_board_info Procedure

unset_board_info(entry);

entry

8.3.5.7. Unset_currtarget_info Procedure

unset_currtarget_info(entry);

entry

8.3.5.8. Push_target Procedure

This makes the target named name be the current target connection. The value of name is an index into the target_info array and is set in the global config file.

push_target(name);

name

The name of the target to make current connection.

8.3.5.9. Pop_target Procedure

This unsets the current target connection.

pop_target();

8.3.5.10. List_targets Procedure

This lists all the supported targets for this architecture.

list_targets();

8.3.5.11. Push_host Procedure

This makes the host named name be the current remote host connection. The value of name is an index into the target_info array and is set in the global config file.

push_host(name);

name

8.3.5.12. Pop_host Procedure

This unsets the current host connection.

pop_host();

8.3.5.13. Compile Procedure

This invokes the compiler as set by CC to compile the file file. The default options for many cross compilation targets are guessed by DejaGnu, and these options can be added to by passing in more parameters as arguments to compile. Optionally, this will also use the value of the cflags field in the target config array. If the host is not the same as the build machines, then then compiler is run on the remote host using execute_anywhere.

compile(file);

file

8.3.5.14. Archive Procedure

This produces an archive file. Any parameters passed to archive are used in addition to the default flags. Optionally, this will also use the value of the arflags field in the target config array. If the host is not the same as the build machines, then then archiver is run on the remote host using execute_anywhere.

archive(file);

file

8.3.5.15. Ranlib Procedure

This generates an index for the archive file for systems that aren't POSIX yet. Any parameters passed to ranlib are used in for the flags.

ranlib(file);

file

8.3.5.16. Execute_anywhere Procedure

This executes the cmdline on the proper host. This should be used as a replacement for the Tcl command exec as this version utilizes the target config info to execute this command on the build machine or a remote host. All config information for the remote host must be setup to have this command work. If this is a canadian cross, (where we test a cross compiler that runs on a different host then where DejaGnu is running) then a connection is made to the remote host and the command is executed there. It returns either REMOTERROR (for an error) or the output produced when the command was executed. This is used for running the tool to be tested, not a test case.

execute_anywhere(cmdline);

cmdline

8.3.6. Platform 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.

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 testsuite.

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.

8.3.6.1. ${tool}_start Procedure

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.

DejaGnu 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}_start();

8.3.6.2. ${tool}_load Procedure

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}_load();

8.3.6.3. ${tool}_exit Procedure

Cleans up (if necessary) before DejaGnu 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}_exit();

8.3.6.4. ${tool}_version Procedure

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.

${tool}_version();

8.3.7. Utility Procedures

8.3.7.1. Getdirs Procedure

Returns a list of all the directories in the single directory a single directory that match an optional pattern.

getdirs(rootdir pattern);

args

pattern

If you do not specify pattern, Getdirs assumes a default pattern of *. You may use the common shell wildcard characters in the pattern. If no directories match the pattern, then a NULL string is returned.

8.3.7.2. Find Procedure

Search for files whose names match pattern (using shell wildcard characters for filename expansion). Search subdirectories recursively, starting at rootdir. The result is the list of files whose names match; if no files match, the result is empty. Filenames in the result include all intervening subdirectory names. If no files match the pattern, then a NULL string is returned.

find(rootdir pattern);

rootdir

The top level directory to search the search from.

pattern

A csh "glob" style regular expression representing the files to find.

8.3.7.3. Which Procedure

Searches the execution path for an executable file binary, like the BSD which utility. This procedure uses the shell environment variable PATH. It returns 0 if the binary is not in the path, or if there is no PATH environment variable. If binary is in the path, it returns the full path to binary.

which(file);

binary

The executable program or shell script to look for.

8.3.7.4. Grep Procedure

Search the file called filename (a fully specified path) for lines that contain a match for regular expression regexp. The result is a list of all the lines that match. If no lines match, the result is an empty string. Specify regexp using the standard regular expression style used by the Unix utility program grep.

Use the optional third argument line to start lines in the result with the line number in filename. (This argument is simply an option flag; type it just as shown --line.)

grep(filename regexp --line);

filename

The file to search.

regexp

The Unix style regular expression (as used by the grep Unix utility) to search for.

--line

Prefix the line number to each line where the regexp matches.

8.3.7.5. Prune Procedure

This procedure is deprecated and will be removed in the next release of DejaGnu. If a testsuite uses this procedure, a copy of the procedure should be made and placed in the lib directory of the testsuite.

8.3.7.6. Slay Procedure

This procedure is deprecated and will be removed in the next release of DejaGnu. If a testsuite uses this procedure, a copy of the procedure should be made and placed in the lib directory of the testsuite.

8.3.7.7. Absolute Procedure

This procedure is deprecated and will be removed in the next release of DejaGnu. If a testsuite uses this procedure, a copy of the procedure should be made and placed in the lib directory of the testsuite.

8.3.7.8. Psource Procedure

This procedure is deprecated and will be removed in the next release of DejaGnu. If a testsuite uses this procedure, a copy of the procedure should be made and placed in the lib directory of the testsuite.

8.3.7.9. Runtest_file_p Procedure

Search runtests for testcase and return 1 if found, 0 if not. runtests is a list of two elements. The first is a copy of what was on the right side of the = if 

foo.exp="..."
" was specified, or an empty string if no such argument is present. The second is the pathname of the current testcase under consideration. This is used by tools like compilers where each testcase is a file.

runtest_file_p(runtests testcase);

runtests

The list of patterns to compare against.

testcase

The test case filename.

8.3.7.10. Diff Procedure

Compares the two files and returns a 1 if they match, or a 0 if they don't. If verbose is set, then it'll print the differences to the screen.

diff(file_1 file_2);

file_1

The first file to compare.

file_2

The second file to compare.

8.3.7.11. Setenv Procedure

Sets the environment variable var to the value val.

setenv(var val);

var

The environment variable to set.

val

The value to set the variable to.

8.3.7.12. unsetenv Procedure

Unsets the environment variable var.

unsetenv(var);

var

The environment variable to unset.

8.3.7.13. Getenv Procedure

Returns the value of var in the environment if it exists, otherwise it returns NULL.

getenv(var);

var

The environment variable to get the value of.

8.3.7.14. Prune_system_crud Procedure

For system system, delete text the host or target operating system might issue that will interfere with pattern matching of program output in text. An example is the message that is printed if a shared library is out of date.

prune_system_crud(system test);

system

The system error messages to look for to screen out .

text

The Tcl variable containing the text.

8.3.8. Libgloss, A Free BSP

Libgloss is a free BSP (Board Support Package) commonly used with GCC and G++ to produce a fully linked executable image for an embedded systems.

8.3.8.1. Libgloss_link_flags Procedure

libgloss_link_flags(args);

args

8.3.8.2. Libgloss_include_flags Procedure

libgloss_include_flags(args);

args

8.3.8.3. Newlib_link_flags Procedure

newlib_link_flags(args);

args

8.3.8.4. Newlib_include_flags Procedure

newlib_include_flags(args);

args

8.3.8.5. Libio_include_flags Procedure

libio_include_flags(args);

args

8.3.8.6. Libio_link_flags Procedure

libio_link_flags(args);

args

8.3.8.7. G++_include_flags Procedure

g++_include_flags(args);

args

8.3.8.8. G++_link_flags Procedure

g++_link_flags(args);

args

8.3.8.9. Libstdc++_include_flags Procedure

libstdc++_include_flags(args);

args

8.3.8.10. Libstdc++_link_flags Procedure

libstdc++_link_flags(args);

args

8.3.8.11. Get_multilibs Procedure

get_multilibs(args);

args

8.3.8.12. Find_binutils_prog Procedure

find_binutils_prog(name);

name

8.3.8.13. Find_gcc Procedure

find_gcc();

8.3.8.14. Find_gcj Procedure

find_gcj();

8.3.8.15. Find_g++ Procedure

find_g++();

8.3.8.16. Find_g77 Procedure

find_g77();

8.3.8.17. Process_multilib_options Procedure

process_multilib_options(args);

args

8.3.8.18. Add_multilib_option Procedure

add_multilib_option(args);

args

8.3.8.19. Find_gas Procedure

find_gas();

8.3.8.20. Find_ld Procedure

find_ld();

8.3.8.21. Build_wrapper Procedure

build_wrapper(gluefile);

gluefile

8.3.8.22. Winsup_include_flags Procedure

winsup_include_flags(args);

args

8.3.8.23. Winsup_link_flags Procedure

winsup_link_flags(args);

args

8.3.9. Procedures for debugging your Tcl code.

lib/debugger.expdefines these utility procedures:

8.3.9.1. Dumpvars Procedure

This takes a csh style regular expression (glob rules) and prints the values of the global variable names that match. It is abbreviated as dv.

dumpvars(vars);

vars

The variables to dump.

8.3.9.2. Dumplocals Procedure

This takes a csh style regular expression (glob rules) and prints the values of the local variable names that match. It is abbreviated as dl.

dumplocals(args);

args

8.3.9.3. Dumprocs Procedure

This takes a csh style regular expression (glob rules) and prints the body of all procs that match. It is abbreviated as dp.

dumprocs(pattern);

pattern

The csh "glob" style pattern to look for.

8.3.9.4. Dumpwatch Procedure

This takes a csh style regular expression (glob rules) and prints all the watchpoints. It is abbreviated as dw.

dumpwatch(pattern);

pattern

The csh "glob" style pattern to look for.

8.3.9.5. Watcharray Procedure

watcharray(element type);

type

The csh "glob" style pattern to look for.

8.3.9.6. Watchvar Procedure

watchvar(var type);

8.3.9.7. Watchunset Procedure

This breaks program execution when the variable var is unset. It is abbreviated as wu.

watchunset(arg);

args

8.3.9.8. Watchwrite Procedure

This breaks program execution when the variable var is written. It is abbreviated as ww.

watchwrite(var);

var

The variable to watch.

8.3.9.9. Watchread Procedure

This breaks program execution when the variable var is read. It is abbreviated as wr.

watchread(var);

var

The variable to watch.

8.3.9.10. Watchdel Procedure

This deletes a watchpoint from the watch list. It is abbreviated as wd.

watchdel(args);

args

8.3.9.11. Print Procedure

This prints the value of the variable var. It is abbreviated as p.

print(var);

var

8.3.9.12. Quit Procedure

This makes runtest exit. It is abbreviated as q.

quit();

8.4. File Map

This is a map of the files in DejaGnu.

PrevHomeNext
Unit Testing Unit Testing API