1 \input texinfo @c -*- Texinfo -*-
2 @setfilename dejagnu.info
3 @documentencoding us-ascii
12 @c man begin COPYRIGHT
13 Copyright @copyright{} 1992-2020 Free Software Foundation, Inc.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.3 or
17 any later version published by the Free Software Foundation; with no
18 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
19 Texts. A copy of the license is included in the section entitled
20 ``GNU Free Documentation License''.
25 @dircategory Software development
27 * DejaGnu: (dejagnu). The GNU testing framework.
32 @ifset VERSION_PACKAGE
33 @subtitle @value{VERSION_PACKAGE}
35 @subtitle Version @value{VERSION}
37 @subtitle @value{UPDATED}
38 @author Rob Savoye et al.
39 @author Cygnus Support and the GNU Project
42 @vskip 0pt plus 1filll
47 @node Top, Introduction, , (dir)
53 * Running other DejaGnu commands::
54 * Customizing DejaGnu::
57 * Built-in Procedures::
58 * GNU Free Documentation License::
68 * New in this release: Release Notes
70 * A POSIX conforming test framework: A POSIX Conforming Test Framework.
75 * Running 'make check': Make Check.
76 * Running runtest: Runtest.
77 * Output files: Output Files.
79 Running other DejaGnu commands
81 * Invoking dejagnu:: Command line options for the launcher itself.
82 * Invoking dejagnu help:: Reading man pages for dejagnu subcommands.
83 * Invoking dejagnu report card:: Summarizing test results from many tools.
87 * Global configuration file::
88 * Local configuration file::
89 * Board configuration file::
90 * Remote host testing::
91 * Configuration file values::
95 * Adding a new testsuite::
97 * Adding a new target::
98 * Adding a new board::
100 * Writing a test case::
101 * Debugging a test case::
102 * Adding a test case to a testsuite::
103 * Test case special variables: Test case variables.
107 * What is unit testing?::
108 * The dejagnu.h header file: The dejagnu_h header file.
109 * C unit testing API::
110 * C++ unit testing API::
114 * Built-in Procedures::
125 @node Introduction, Running tests, Top, Top
126 @chapter Introduction
130 * New in this release: Release Notes.
132 * A POSIX compliant test framework: A POSIX Conforming Test Framework.
136 @node What is DejaGnu?, Release Notes, , Introduction
137 @section What is DejaGnu?
139 DejaGnu is a framework for testing other programs, providing a single
140 front-end for all tests. You can think of it as a library of Tcl
141 procedures to help with writing a test harness. A @emph{test harness}
142 is the infrastructure that is created to test a specific program or
143 tool. Each program can have multiple testsuites, all supported by a
144 single test harness. DejaGnu is written in Expect, which in turn uses
145 Tcl, the Tool command language. There is more information on Tcl at
146 the @uref{http://www.tcl.tk,Tcl/Tk web site} and the
147 @uref{http://expect.nist.gov,Expect web site}.
149 Julia Menapace first coined the term @emph{DejaGnu} to describe an
150 earlier testing framework she wrote at Cygnus Support for testing GDB.
151 When we replaced it with the Expect-based framework, it was like
152 DejaGnu all over again. More importantly, it was also named after my
153 daughter, Deja Snow Savoye, who was a toddler during DejaGnu's
156 DejaGnu offers several advantages for testing:
161 The flexibility and consistency of the DejaGnu framework make it easy to
162 write tests for any program, with either batch-oriented, or interactive
166 DejaGnu provides a layer of abstraction which allows you to write
167 tests that are portable to any host or target where a program must be
168 tested. For instance, a test for @code{GDB} can run from any
169 supported host system on any supported target system. DejaGnu runs
170 tests on many single board computers, whose operating software ranges
171 from a simple boot monitor to a real-time OS.
174 All tests have the same output format. This makes it easy to
175 integrate testing into other software development processes.
176 DejaGnu's output is designed to be parsed by other filtering script
177 and it is also human readable.
180 Using Tcl and Expect, it's easy to create wrappers for existing
181 testsuites. By incorporating existing tests under DejaGnu, it's
182 easier to have a single set of report analyse programs..
185 Running tests requires two things: the testing framework and the
186 testsuites themselves. Tests are usually written in Expect using Tcl,
187 but you can also use a Tcl script to run a testsuite that is not based
188 on Expect. Expect script filenames conventionally use @file{.exp} as
189 a suffix. For example, the main implementation of the DejaGnu test
190 driver is in the file @file{runtest.exp}.
192 @node Release Notes, Design goals, What is DejaGnu?, Introduction
193 @section New in this release
195 The following major, user-visible changes have been introduced since
201 Support for target communication via SSH has been added.
204 A large number of very old config and baseboard files have been
205 removed. If you need to resurrect these, you can get them from
206 version 1.5.3. If you can show that a board is still in use, it can
207 be put back in the distribution.
210 The @command{--status} command line option is now the default. This
211 means that any error in the testsuite Tcl scripts will cause runtest
212 to abort with exit status code 2. The @command{--status} option has
213 been removed from the documentation, but will continue to be accepted
214 for backward compatibility.
217 @command{runtest} now exits with exit code 0 if the testsuite
218 "passed", 1 if something unexpected happened (eg, FAIL, XPASS or
219 UNRESOLVED), and 2 if an exception is raised by the Tcl interpreter.
222 @command{runtest} now exits with the standard exit codes of programs
223 that are terminated by the SIGINT, SIGTERM and SIGQUIT signals.
226 The user-visible utility procedures @code{absolute}, @code{psource}
227 and @code{slay} have been removed. If a testsuite uses any of these
228 procedures, a copy of the procedure should be made and placed in the
229 lib directory of the testsuite.
232 Support was added for testing the D compiler.
235 @file{~/.dejagnurc} is now loaded last, not first. This allows the
236 user to have the ability to override anything in their environment
237 (even the @file{site.exp} file specified by @code{$DEJAGNU}).
240 The user-visible utility procedure @code{unsetenv} is
241 @strong{deprecated} and will be removed in the next release. If a
242 testsuite uses this procedure, a copy should be made and placed in the
243 lib directory of the testsuite.
247 @node Design goals, A POSIX Conforming Test Framework, Release Notes, Introduction
248 @section Design goals
251 DejaGnu grew out of the internal needs of Cygnus Solutions (formerly
252 Cygnus Support). Cygnus maintained and enhanced a variety of free
253 programs in many different environments and needed a testing tool
259 was useful to developers while fixing bugs;
262 automated running many tests during a software release process;
265 was portable among a variety of host computers;
268 supported a cross-development environment;
271 permitted testing of interactive programs like @code{GDB}; and
274 permitted testing of batch-oriented programs like @code{GCC}.
277 Some of the requirements proved challenging. For example, interactive
278 programs do not lend themselves very well to automated testing. But
279 all the requirements are important. For instance, it is imperative to
280 make sure that @code{GDB} works as well when cross-debugging as it
281 does in a native configuration.
283 Probably the greatest challenge was testing in a cross-development
284 environment. Most cross-development environments are customized by
285 each developer. Even when buying packaged boards from vendors there
286 are many differences. The communication interfaces vary from a serial
287 line to Ethernet. DejaGnu was designed with a modular communication
288 setup, so that each kind of communication can be added as required and
289 supported thereafter. Once a communication procedure is written, any
290 test can use it. Currently DejaGnu can use @code{ssh}, @code{rsh},
291 @code{rlogin}, @code{telnet}, @code{tip}, and @code{kermit} for remote
294 @node A POSIX Conforming Test Framework, Installation, Design goals, Introduction
295 @section A POSIX compliant test framework
296 @cindex POSIX compliant test framework
299 DejaGnu conforms to the POSIX 1003.3 standard for test frameworks.
300 Rob Savoye was a member of that committee.
302 POSIX standard 1003.3 defines what a testing framework needs to
303 provide to create a POSIX compliant testsuite. This standard is
304 primarily oriented to checking POSIX conformance, but its requirements
305 also support testing of features not related to POSIX conformance.
306 POSIX 1003.3 does not specify a particular testing framework, but at
307 this time there is only one other POSIX conforming test framework.
308 TET was created by Unisoft for a consortium comprised of X/Open, Unix
309 International and the Open Software Foundation.
312 The POSIX documentation refers to @dfn{assertions}. An assertion is a
313 description of behavior. For example, if a standard says ``The sun
314 shall shine'', a corresponding assertion might be ``The sun is
315 shining.'' A test based on this assertion would pass or fail
316 depending on whether it is day or night. It is important to note that
317 the standard being tested is never 1003.3; the standard being tested
318 is some other standard, for which the assertions were written.
320 As there is no testsuite to verify that testing frameworks are POSIX
321 1003.3 compliant, this is done by repeatedly reading the standard and
322 experimenting. One of the main things POSIX 1003.3 does specify is
323 the set of allowed output messages and their definitions. Four
324 messages are supported for a required feature of POSIX conforming
325 systems and a fifth for a conditional feature. DejaGnu supports all
326 five output messages. In this sense a testsuite that uses exactly
327 these messages can be considered POSIX compliant. These definitions
328 specify the output of a test case:
333 A test has succeeded. That is, it demonstrated that the assertion is
337 A test has not succeeded -- the assertion is false. The @emph{FAIL}
338 message is based on this test case only. Other messages are used to
339 indicate a failure of the framework. As with @emph{PASS}, POSIX tests
340 must return @emph{FAIL} rather than @emph{XFAIL} even if a failure was
344 POSIX 1003.3 does not incorporate the notion of expected failures, so
345 @emph{PASS}, instead of @emph{XPASS}, must also be returned for test
346 cases which were expected to fail and did not. This means that
347 @emph{PASS} is in some sense more ambiguous than if @emph{XPASS} is
351 A test produced indeterminate results. Usually, this means the test
352 executed in an unexpected fashion. This outcome requires a human to
353 go over results to determine if the test should have passed or failed.
354 This message is also used for any test that requires human
355 intervention because it is beyond the abilities of the testing
356 framework. Any unresolved test should resolved to @emph{PASS} or
357 @emph{FAIL} before a test run can be considered finished.
359 Note that for POSIX, each assertion must produce a test result code.
360 If the test isn't actually run, it must produce @emph{UNRESOLVED}
361 rather than just leaving that test out of the output. This means that
362 you have to be careful when writing tests to not carelessly use Tcl
363 commands like @emph{return}---if you alter the flow of control of the
364 Tcl code you must insure that every test still produces some result
367 Here are some of the ways a test may wind up @emph{UNRESOLVED}:
373 Execution of a test is interrupted.
376 A test does not produce a clear result. This is usually because there
377 was an @emph{ERROR} from DejaGnu while processing the test, or because
378 there were three or more @emph{WARNING} messages. Any @emph{WARNING}
379 or @emph{ERROR} messages can invalidate the output of the test. This
380 usually requires a human to examine the output to determine what
381 really happened -- and to improve the test case.
384 A test depends on a previous test, which has failed.
387 The test was set up incorrectly.
390 A test script aborts due to a Tcl error. In this case, the DejaGnu
391 framework inserts an @emph{UNRESOLVED} result as a placeholder for an
392 unknown number of tests that were not run because the script crashed.
398 A test was not run. This is a placeholder used when there is no real
405 There is no support for the tested case. This may mean that a
406 conditional feature of an operating system, or of a compiler, is not
407 implemented. DejaGnu also uses this message when a testing
408 environment (often a ``bare board'' target) lacks basic support for
409 compiling or running the test case. For example, a test for the
410 system subroutine @emph{gethostname} would never work on a target
411 board running only a boot monitor.
414 DejaGnu uses the same output procedures to produce these messages for
415 all testsuites and these procedures are already known to conform to
416 POSIX 1003.3. For a DejaGnu testsuite to conform to POSIX 1003.3, you
417 must avoid the @emph{setup_xfail} procedure as described in the
418 @emph{PASS} section above and you must be careful to return
419 @emph{UNRESOLVED} where appropriate, as described in the
420 @emph{UNRESOLVED} section above.
422 @node Installation, , A POSIX Conforming Test Framework, Introduction
423 @section Installation
425 Refer to the @file{INSTALL} in the source distribution for detailed
426 installation instructions. Note that there is no compilation step as
427 with many other GNU packages, as DejaGnu consists of interpreted code
430 Save for its own small testsuite, the DejaGnu distribution does not
431 include any testsuites. Testsuites for the various GNU development
432 tools are included with those packages. After configuring the
433 top-level DejaGnu directory, unpack and configure the test directories
434 for the tools you want to test; then, in each test directory, run
435 @emph{make check} to build auxiliary programs required by some of the
436 tests, and run the test suites.
438 @node Running tests, Running other DejaGnu commands, Introduction, Top
439 @chapter Running tests
441 There are two ways to execute a testsuite. The most common way is
442 when there is existing support in the @file{Makefile} of the tool
443 being tested. This usually consists of a @emph{check} target. The
444 other way is to execute the @code{runtest} program directly. To run
445 @code{runtest} directly from the command line requires either all of
446 the correct command line options, or a @ref{Local configuration file}
447 must be set up correctly.
450 * Running 'make check': Make Check.
451 * Running runtest: Runtest.
452 * Output files: Output Files.
455 @node Make Check, Runtest, , Running tests
456 @section Running 'make check'
458 To run tests from an existing collection, first use @code{configure}
459 as usual to set up the build directory. Then type @code{make check}.
460 If the @emph{check} target exists, it usually saves you some trouble.
461 For instance, it can set up any auxiliary programs or other files
462 needed by the tests. The most common file the @emph{check} target
463 depends on is the @file{site.exp} file. The @file{site.exp} contains
464 various variables that DejaGnu uses to determine the configuration of
465 the program being tested.
467 Once you have run @emph{make check} to build any auxiliary files, you
468 can invoke the test driver @code{runtest} directly to repeat the
469 tests. You will also have to execute @code{runtest} directly for test
470 collections with no @emph{check} target in the @file{Makefile}.
472 GNU Automake has built-in support for DejaGnu. To add DejaGnu support
473 to your generated @file{Makefile.in}, just add the keyword
474 @code{dejagnu} to the AUTOMAKE_OPTIONS variable in @file{Makefile.am}.
475 This will ensure that the generated @file{Makefile.in} has a
476 @code{check} target that invokes DejaGnu correctly.
478 @node Runtest, Output Files, Make Check, Running tests
479 @section Running runtest
482 @code{runtest} is the test driver for DejaGnu. You can specify two
483 kinds of things on the @code{runtest} command line: command line
484 options, and Tcl variables that are passed to the test scripts. The
485 options are listed alphabetically below.
487 @code{runtest} returns one of the following exit codes:
491 if all tests passed including expected failures and unsupported tests.
493 if any test failed, passed unexpectedly, or was unresolved.
495 if Expect encountered any error in the test scripts.
501 * Common Options: Common Operations.
504 @node Output States, Invoking runtest, , Runtest
505 @subsection Output States
506 @cindex output states
508 @file{runtest} flags the outcome of each test as one of these cases.
509 See @ref{A POSIX Conforming Test Framework} for a discussion of how
510 POSIX specifies the meanings of these cases.
515 The most desirable outcome: the test was expected to succeed and did
519 A pleasant kind of failure: a test was expected to fail, but
520 succeeded. This may indicate progress; inspect the test case to
521 determine whether you should amend it to stop expecting failure.
524 A test failed, although it was expected to succeed. This may indicate
525 regress; inspect the test case and the failing software to locate the
529 A test failed, but it was expected to fail. This result indicates no
530 change in a known bug. If a test fails because the operating system
531 where the test runs lacks some facility required by the test, the
532 outcome is @emph{UNSUPPORTED} instead.
535 Output from a test requires manual inspection; the testsuite could not
536 automatically determine the outcome. For example, your tests can
537 report this outcome is when a test does not complete as expected.
540 A test case is not yet complete, and in particular cannot yet produce
541 a @emph{PASS} or @emph{FAIL}. You can also use this outcome in dummy
542 ``tests'' that note explicitly the absence of a real test case for a
546 A test depends on a conditionally available feature that does not
547 exist (in the configured testing environment). For example, you can
548 use this outcome to report on a test case that does not work on a
549 particular target because its operating system support does not
550 include a required subroutine.
553 @code{runtest} may also display the following messages:
558 Indicates a major problem (detected by the test case itself) in
559 running the test. This is usually an unrecoverable error, such as a
560 missing file or loss of communication to the target. POSIX testsuites
561 should not emit this message; use @emph{UNSUPPORTED}, @emph{UNTESTED},
562 or @emph{UNRESOLVED} instead, as appropriate.
565 Indicates a possible problem in running the test. Usually warnings
566 correspond to recoverable errors, or display an important message
567 about the following tests.
570 An informational message about the test case.
573 @node Invoking runtest, Common Operations, Output States, Runtest
574 @subsection Invoking runtest
575 @cindex runtest, invoking
577 This is the full set of command line options that @code{runtest}
578 recognizes. Option names may be abbreviated to the shortest unique
583 @item @code{-a}, @code{--all}
584 Display all test output. By default, @emph{runtest} shows only the
585 output of tests that produce unexpected results; that is, tests with
586 status @emph{FAIL} (unexpected failure), @emph{XPASS} (unexpected
587 success), or @emph{ERROR} (a severe error in the test case itself).
588 Specify @code{--all} to see output for tests with status @emph{PASS}
589 (success, as expected) @emph{XFAIL} (failure, as expected), or
590 @emph{WARNING} (minor error in the test case itself).
592 @item @code{--build [triplet]}
593 @emph{triplet} is a system triplet of the form
594 @emph{cpu-manufacturer-os}. This is the type of machine DejaGnu and
595 the tools to be tested are built on. For a normal cross environment
596 this is the same as the host, but for a Canadian cross, they are
599 @item @code{-D0}, @code{-D1}
600 Start the internal Tcl debugger. The Tcl debugger supports
601 breakpoints, single stepping, and other common debugging activities.
602 See the document @uref{http://expect.sourceforge.net/doc/tcl-debug.ps,
603 Debugger for Tcl Applications} by Don Libes. If you specify
604 @emph{-D1}, the @emph{expect} shell stops at a breakpoint as soon as
605 DejaGnu invokes it. If you specify @emph{-D0}, DejaGnu starts as
606 usual, but you can enter the debugger by sending an interrupt (e.g. by
607 typing @key{Ctrl}-@key{c}).
610 Turns on the Expect internal debugging output. Debugging output is
611 displayed as part of the @emph{runtest} output, and logged to a file
612 called @file{dbg.log}. The extra debugging output does @emph{not}
613 appear on standard output, unless the verbose level is greater than 2
614 (for instance, to see debug output immediately, specify @code{--debug
615 -v -v}). The debugging output shows all attempts at matching the test
616 output of the tool with the scripted patterns describing expected
617 output. The output generated with @code{--strace} also goes into
620 @item @code{--global_init [name]}
621 Use @emph{name} as the global init file instead of @file{site.exp} in
622 @emph{libdir}. The default is, of course, @file{site.exp}. Note that
623 this option accepts a relative file name, interpreted starting at
624 @emph{libdir}, so a file in a subdirectory may be used. This is
625 probably less useful for most sites, but is orthogonal with the
626 @code{--local_init} option and may be useful in large testing labs.
629 Prints out a short summary of the @emph{runtest} options, then exits
630 (even if you specify other options).
632 @item @code{--host [triplet]}
633 @emph{triplet} is a system triplet of the form
634 @emph{cpu-manufactuer-os}. Use this option to override the default
635 string recorded by your configuration's choice of host. This choice
636 does not change how anything is actually configured unless --build is
637 also specified; it affects @emph{only} DejaGnu procedures that compare
638 the host string with particular values. The procedures @emph{ishost},
639 @emph{istarget}, @emph{isnative}, and @emph{setup_xfail} are affected
640 by @code{--host}. In this usage, @emph{host} refers to the machine
641 that the tests are to be run on, which may not be the same as the
642 @emph{build} machine. If @code{--build} is also specified, then
643 @code{--host} refers to the machine that the tests will be run on, not
644 the machine DejaGnu is run on.
646 @item @code{--host_board [name]}
647 The host board to use.
649 @item @code{--ignore [tests(s)] }
650 The name(s) of specific tests to ignore.
652 @item @code{--local_init [name]}
653 Use @emph{name} as the testsuite local init file instead of
654 @file{site.exp} in the current directory and in @emph{objdir}. The
655 default is, of course, @file{site.exp}. Note that this option accepts
656 a relative file name, so a file in a subdirectory may be used.
658 @item @code{--log_dialog}
659 Emit Expect output to stdout. The Expect output is usually only
660 written to the @file{.log} file. By enabling this option, they are
661 also printed to standard output.
663 @item @code{--mail [address(es)]}
664 Send test results to one or more email addresses.
666 @item @code{--objdir [path]}
667 Use @emph{path} as the top directory containing any auxiliary compiled
668 test code. The default is '.'. Use this option to locate
669 pre-compiled test code. You can normally prepare any auxiliary files
670 needed with @emph{make}.
672 @item @code{--outdir [path]}
673 Write log files in directory @file{path}. The default is '.', the
674 directory where you start @emph{runtest}. This option affects only
675 the summary (@file{.sum}) and the detailed log files (@file{.log}).
676 The DejaGnu debug log @file{dbg.log} always appears (when requested)
677 in the local directory.
679 @item @code{--reboot [name]}
680 Reboot the target board when @code{runtest} starts. When running
681 tests on a separate target board, it is safer to reboot the target to
682 be certain of its state. However, when developing test scripts,
683 rebooting can take a lot of time.
685 @item @code{--srcdir [path]}
686 Use @file{path} as the top directory for test scripts to run.
687 @emph{runtest} looks in this directory for any subdirectory whose name
688 begins with the toolname (specified with @code{--tool}). For
689 instance, with @code{--tool gdb}, @emph{runtest} uses tests in
690 subdirectories @file{gdb.*} (with the usual shell-like filename
691 expansion). If you do not use @code{--srcdir}, @emph{runtest} looks
692 for test directories under the current working directory.
694 @item @code{--strace [n]}
695 Turn on internal tracing for @emph{expect}, to n levels deep. By
696 adjusting the level, you can control the extent to which your output
697 expands multi-level Tcl statements. This allows you to ignore some
698 levels of @emph{case} or @emph{if} statements. Each procedure call or
699 control structure counts as one ``level''. The output is recorded in
700 the same file, @file{dbg.log}, used for output from @code{--debug}.
702 @item @code{--target [triplet]}
703 Use this option to override the default setting (native testing).
704 @emph{triplet} is a system triplet of the form
705 @emph{cpu-manufacturer-os}. This option changes the configuration
706 @code{runtest} uses for the default tool names, and other setup
709 @item @code{--target_board [name(s)]}
710 The list of target boards to run tests on.
712 @item @code{--tool [name(s)]}
713 Specifies which testsuite to run, and what initialization module to
714 use. @code{--tool} is used @emph{only} for these two purposes. It is
715 @emph{not} used to name the executable program to test. Executable
716 tool names (and paths) are recorded in @file{site.exp} and you can
717 override them by specifying Tcl variables on the command line.
719 For example, including @code{--tool} gcc on the command line runs
720 tests from all test subdirectories whose names match @file{gcc.*}, and
721 uses one of the initialization modules named @file{config/*-gcc.exp}.
722 To specify the name of the compiler (perhaps as an alternative path to
723 what @emph{runtest} would use by default), use @emph{GCC=path-to-gcc}
724 on the @emph{runtest} command line.
726 @item @code{--tool_exec [name]}
727 The path to the tool executable to test.
729 @item @code{--tool_opts [options]}
730 A list of additional options to pass to the tool.
732 @item @code{-v}, @code{--verbose}
733 Turns on more output. Repeating this option increases the amount of
734 output displayed. Level one (@emph{-v}) is simply test output. Level
735 two (@emph{-v -v}) shows messages on options, configuration, and
736 process control. Verbose messages appear in the detailed
737 (@file{*.log}) log file, but not in the summary (@file{*.sum}) log
740 @item @code{-V}, @code{--version}
741 Prints out the version numbers of DejaGnu, Expect, and Tcl.
743 @item @code{-x}, @code{--xml}
744 Generate XML output. The output file is named after the tool with an
747 @item @file{testfile}.exp[=arg(s)]
748 Specify the names of testsuites to run. By default, @emph{runtest}
749 runs all tests for the tool, but you can restrict it to particular
750 testsuites by giving the names of the @emph{.exp} scripts that control
751 them. @emph{testsuite}.exp cannot include directory names, only plain
754 @code{arg(s)} specifies a subset of test cases to run. For compiler
755 or assembler tests, which often use a single @emph{.exp} script
756 covering many different test case files, this option allows you to
757 further restrict the tests by listing particular test cases. For
758 larger testsuites such as that included in GCC, this can save a lot of
759 time. Some tools support wildcards here, but this varies from tool to
760 tool. Typically the wildcards @emph{?}, @emph{*}, and @emph{[chars]}
763 @item @code{tclvar}=value
764 You can define Tcl variables for use by your test scripts in the same
765 style used with @emph{make} for environment variables. For example,
766 @emph{runtest GDB=gdb.old} defines a variable called @code{GDB}; when
767 your scripts refer to @code{$GDB} in this run, they use the value
770 The default Tcl variables used for most tools are defined in the main
771 DejaGnu @emph{Makefile}; their values are captured in the
772 @file{site.exp} file.
775 @node Common Operations, , Invoking runtest, Runtest
776 @subsection Common Options
777 @cindex options, common
779 Typically, you don't need to use any command line options. The
780 @code{--tool} option is only required when there is more than one
781 testsuite in the same directory. The default options are in the local
782 @file{site.exp} file, created by @code{make site.exp}.
784 For example, if the directory @file{gdb/testsuite} contains a
785 collection of DejaGnu tests for GDB, you can run them like this:
792 The test output follows, then ends with:
797 # of expected passes 508
798 # of expected failures 103
799 /usr/latest/bin/gdb version 4.14.4 -nx
802 You can use the option @code{--srcdir} to point to some other
803 directory containing a collection of tests:
806 $ runtest --srcdir /devo/gdb/testsuite
809 By default, @code{runtest} prints only the names of the tests it runs,
810 output from any tests that have unexpected results, and a summary
811 showing how many tests passed and how many failed. To display output
812 from all tests (whether or not they behave as expected), use the
813 @code{-a} (all) option. For more verbose output about processes being
814 run, communication, and so on, use @code{-v} (verbose). To see even
815 more output, use multiple @code{-v} options. See @ref{Invoking
816 runtest} for a more detailed explanation of each @code{runtest}
819 @node Output Files, , Runtest, Running tests
820 @section Output files
822 DejaGnu always writes two kinds of output files. Summary output is
823 written to the @file{.sum} file, and detailed output is written to the
824 @file{.log} file. The tool name determines the prefix for these
825 files. For example, after running with @code{--tool gdb}, the output
826 files will be called @file{gdb.sum} and @file{gdb.log}. For
827 troubleshooting, a debug log file that logs the operation of Expect is
828 available. Each of these will be described in turn.
832 * Detailed log file::
836 @node Summary log file, Detailed log file, , Output Files
837 @subsection Summary log file
838 @cindex output file, summary log
840 DejaGnu always produces a summary (@file{.sum}) output file. This
841 summary lists the names of all test files run. For each test file,
842 one line of output from each @code{pass} command (showing status
843 @emph{PASS} or @emph{XPASS}) or @code{fail} command (status
844 @emph{FAIL} or @emph{XFAIL}), trailing summary statistics that count
845 passing and failing tests (expected and unexpected), the full pathname
846 of the tool tested, and the version number of the tool. All possible
847 outcomes, and all errors, are always reflected in the summary output
848 file, regardless of whether or not you specify @code{--all}.
850 If any of your tests use the procedures @code{unresolved},
851 @code{unsupported}, or @code{untested}, the summary output also
852 tabulates the corresponding outcomes.
854 For example, after running @code{runtest --tool binutils} a summary
855 log file will be written to @file{binutils.sum}. Normally, DejaGnu
856 writes this file in your current working directory. Use the
857 @code{--outdir} option to select a different output directory.
859 @strong{Sample summary log}
862 Test Run By bje on Sat Nov 14 21:04:30 AEDT 2015
866 Running ./gdb.t00/echo.exp ...
868 Running ./gdb.all/help.exp ...
869 PASS: help add-symbol-file
871 PASS: help breakpoint "bre" abbreviation
872 FAIL: help run "r" abbreviation
873 Running ./gdb.t10/crossload.exp ...
874 PASS: m68k-elf (elf-big) explicit format; loaded
875 XFAIL: mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed C types
877 @ === gdb Summary ===
879 # of expected passes 5
880 # of expected failures 1
881 # of unexpected failures 1
882 /usr/latest/bin/gdb version 4.6.5 -q
886 @node Detailed log file, Debug log file, Summary log file, Output Files
887 @subsection Detailed log file
888 @cindex output file, detailed log
890 DejaGnu also saves a detailed log file (@file{.log}), showing any
891 output generated by test cases as well as the summary output. For
892 example, after running @code{runtest --tool binutils}, a detailed log
893 file will be written to @file{binutils.log}. Normally, DejaGnu writes
894 this file in your current working directory. Use the @code{--outdir}
895 option to select a different output directory.
897 @strong{Sample detailed log for g++ tests}
900 Test Run By bje on Sat Nov 14 21:07:23 AEDT 2015
904 Running ./g++.other/t01-1.exp ...
907 Running ./g++.other/t01-2.exp ...
909 p0000646.C: In function `int warn_return_1 ()':
910 p0000646.C:109: warning: control reaches end of non-void function
911 p0000646.C: In function `int warn_return_arg (int)':
912 p0000646.C:117: warning: control reaches end of non-void function
913 p0000646.C: In function `int warn_return_sum (int, int)':
914 p0000646.C:125: warning: control reaches end of non-void function
915 p0000646.C: In function `struct foo warn_return_foo ()':
916 p0000646.C:132: warning: control reaches end of non-void function
917 Running ./g++.other/t01-4.exp ...
919 900403_04.C:8: zero width for bit-field `foo'
920 Running ./g++.other/t01-3.exp ...
921 FAIL: segment violation
922 900519_12.C:9: parse error before `;'
923 900519_12.C:12: Segmentation violation
924 /usr/latest/bin/gcc: Internal compiler error: program cc1plus got fatal signal
926 @ === g++ Summary ===
928 # of expected passes 1
929 # of expected failures 3
930 /usr/latest/bin/g++ version cygnus-2.0.1
934 @node Debug log file, , Detailed log file, Output Files
935 @subsection Debug log file
936 @cindex output file, debug log
938 The @code{runtest} option @code{--debug} creates a file showing the
939 output from Expect in debugging mode. The @file{dbg.log} file is
940 created in the current directory. The log file shows the string sent
941 to the tool being tested by each @code{send} command and the pattern
942 it compares with the tool output by each @code{expect} command.
944 The log messages begin with a message of the form:
947 expect: does @{tool output@} (spawn_id n)
948 match pattern @{expected pattern@}?
951 For every unsuccessful match, Expect issues a @emph{no} after this
952 message. If other patterns are specified for the same Expect command,
953 they are reflected also, but without the first part of the message
954 (@emph{expect... match pattern}).
956 When Expect finds a match, the log for the successful match ends with
957 @emph{yes}, followed by a record of the Expect variables set to
958 describe a successful match.
960 @strong{Example debug log file for a GDB test}
963 send: sent @{break gdbme.c:34\n@} to spawn id 6
964 expect: does @{@} (spawn_id 6) match pattern @{Breakpoint.*at.* file
965 gdbme.c, line 34.*\(gdb\) $@}? no
967 expect: does @{@} (spawn_id 0) match pattern @{return@} ? no
976 Breakpoint 8 at 0x23d8: file gdbme.c, line 34.
977 (gdb) expect: does @{break gdbme.c:34\r\nBreakpoint 8 at 0x23d8:
978 file gdbme.c, line 34.\r\n(gdb) @} (spawn_id 6) match pattern
979 @{Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $@}? yes
980 expect: set expect_out(0,start) @{18@}
981 expect: set expect_out(0,end) @{71@}
982 expect: set expect_out(0,string) @{Breakpoint 8 at 0x23d8: file
983 gdbme.c, line 34.\r\n(gdb) @}
984 epect: set expect_out(spawn_id) @{6@}
985 expect: set expect_out(buffer) @{break gdbme.c:34\r\nBreakpoint 8
986 at 0x23d8: file gdbme.c, line 34.\r\n(gdb) @}
987 PASS: 70 0 breakpoint line number in file
991 This example exhibits three properties of Expect and DejaGnu that
992 might be surprising at first glance:
997 Empty output for the first attempted match. The first set of
998 attempted matches shown ran against the output @emph{@{@}} --- that
999 is, no output. Expect begins attempting to match the patterns
1000 supplied immediately; often, the first pass is against incomplete
1001 output (or completely before all output, as in this case).
1004 Interspersed tool output. The beginning of the log entry for the
1005 second attempted match may be hard to spot: this is because the prompt
1006 @emph{@{(gdb) @}} appears on the same line, just before the
1007 @emph{expect:} that marks the beginning of the log entry.
1010 Fail-safe patterns. Many of the patterns tested are fail-safe
1011 patterns provided by GDB testing utilities, to reduce possible
1012 indeterminacy. It is useful to anticipate potential variations caused
1013 by extreme system conditions (GDB might issue the message
1014 @emph{virtual memory exhausted} in rare circumstances), or by changes
1015 in the tested program (@emph{Undefined command} is the likeliest
1016 outcome if the name of a tested command changes).
1018 The pattern @emph{@{return@}} is a particularly interesting fail-safe
1019 to notice; it checks for an unexpected @key{RET} prompt. This may
1020 happen, for example, if the tested tool can filter output through a
1023 These fail-safe patterns (like the debugging log itself) are primarily
1024 useful while developing test scripts. Use the @code{error} procedure
1025 to make the actions for fail-safe patterns produce messages starting
1026 with @emph{ERROR} on standard output, and in the detailed log file.
1030 @node Running other DejaGnu commands, Customizing DejaGnu, Running tests, Top
1031 @chapter Running other DejaGnu commands
1033 DejaGnu now features auxiliary commands not directly related to
1034 running tests, but somehow related to the broader purpose of testing.
1036 These commands are run via the @command{dejagnu} multiplex launcher,
1037 which locates an appropriate script and the required interpreter and
1038 then runs the requested command.
1041 * Invoking dejagnu:: Command line options for the launcher itself.
1042 * Invoking dejagnu help:: Reading man pages for dejagnu subcommands.
1043 * Invoking dejagnu report card:: Summarizing test results from many tools.
1046 @node Invoking dejagnu, Invoking dejagnu help, Running other DejaGnu commands, Running other DejaGnu commands
1047 @section Invoking @command{dejagnu}
1048 @cindex dejagnu, invoking
1050 The @command{dejagnu} launcher is primarily designed to pass most
1051 options on to the scripts that it runs, but does process the
1052 @option{--help} and @option{--version} options entirely internally,
1053 while also recognizing the @option{--verbose} option.
1056 @command{dejagnu} <command> [options...]
1057 @command{dejagnu} --help
1058 @command{dejagnu} --version
1061 Note that the command names may contain multiple words. In this case,
1062 the command can be given as separate arguments to @command{dejagnu} or
1063 combined with dashes (@samp{-}); both forms are equivalent.
1065 All words of the command name must appear before any options. The
1066 search for a command terminates when an option is found.
1068 Note that the first valid command found is used. A longer command
1069 name can be shadowed by a shorter command name that happens to be a
1070 prefix of the longer name, if the command name is given as multiple
1071 arguments. The equivalent form with the longer command name combined
1072 using dashes into a single argument will correctly refer to the
1073 otherwise shadowed command.
1075 The @command{dejagnu} launcher can also be run using symbolic links,
1076 provided that the shell places the name under which @command{dejagnu}
1077 was invoked in @code{$0}. Any dash-separated words after ``dejagnu''
1078 in the name of such a link are taken to be the leading words of a
1081 The @command{dejagnu} launcher supports alternate implementations
1082 depending upon available interpreters.
1084 Options for the @command{dejagnu} launcher itself cannot be
1085 abbreviated, since the launcher has no way to know which abbreviations
1086 are unique and which would be ambiguous to the invoked command.
1091 Print a help message instead of running a command.
1093 @item @code{-V}, @code{--version}
1094 Print a version banner for the launcher itself including the version
1095 of DejaGnu. Any command given is ignored.
1097 @item @code{-v}, @code{--verbose}
1098 Emit additional output describing the inner workings of the
1099 @command{dejagnu} launcher. This option is also passed on to the
1104 All arguments after the command name are passed to the invoked
1107 @node Invoking dejagnu help, Invoking dejagnu report card, Invoking dejagnu, Running other DejaGnu commands
1108 @section Invoking @command{dejagnu help}
1109 @cindex dejagnu help, invoking
1111 The @command{dejagnu help} tool displays long-form documentation for
1112 DejaGnu auxiliary commands that are invoked using the
1113 @command{dejagnu} launcher.
1116 @command{dejagnu help} [options...] <command>
1119 Again, command names may contain multiple words. This command forms
1120 an operand by joining all words in the command name using dashes
1121 (@samp{-}) and prepending @samp{dejagnu-}. This is then used as the
1122 name of a manual page and passed to the @command{man} command.
1124 If the manual page is in a particular directory relative to the script
1125 implementing this command, a full file name is produced, otherwise,
1126 @command{man} performs its normal search.
1128 The @option{--verbose} option causes additional output describing the
1129 inner workings of the @command{dejagnu help} command to be produced.
1131 The @option{--path}, @option{-w}, and @option{-W} options are passed
1134 @node Invoking dejagnu report card, , Invoking dejagnu help, Running other DejaGnu commands
1135 @section Invoking @command{dejagnu report card}
1136 @cindex dejagnu report card, invoking
1137 @cindex dejagnu report-card, invoking
1139 The @command{dejagnu report card} tool produces a tabular summary of
1140 the results from test runs by reading the summary files that DejaGnu
1144 @command{dejagnu report card} [<option>|<tool>|<file>]...
1147 The @option{--verbose} option causes additional output describing the
1148 inner workings of the @command{dejagnu report card} command to be
1151 Aside from options, the command may include a list of tools or files.
1152 Names ending in @samp{.sum} are used as-is. Names ending in
1153 @samp{.log} are changed to instead refer to the summary file. Names
1154 ending with a simple dot (@samp{.}) have @samp{sum} appended, for
1155 convenience when using Readline filename completion in a shell, which
1156 will complete to the dot, since there are both @samp{.sum} and
1157 @samp{.log} files produced for each tool tested. Lastly, all other
1158 names are taken as tool names and @samp{.sum} is appended to refer to
1159 the summary file produced by DejaGnu.
1161 The relevant summary files are read and an ASCII-art table is
1162 produced. The table has columns for counts of tests passed, failed,
1163 unsupported, unresolved, and untested. Tests that are expected to
1164 pass and tests that are expected to fail are counted in separate
1165 columns, but known failures (@samp{KFAIL} and @samp{KPASS}) are
1166 summarized together with expected failures (@samp{XFAIL} and
1167 @samp{XPASS}) in two additional columns: @samp{?PASS} and
1168 @samp{?FAIL}. Additionally, if a test produced any warnings or
1169 errors, tags @samp{!W!} or @samp{!E!} are added at the end of the row.
1171 @node Customizing DejaGnu, Extending DejaGnu, Running other DejaGnu commands, Top
1172 @chapter Customizing DejaGnu
1173 @cindex customization
1175 The site configuration file, @file{site.exp}, captures
1176 configuration-dependent values and propagates them to the DejaGnu test
1177 environment using Tcl variables. This ties the DejaGnu test scripts
1178 into the @code{configure} and @code{make} programs. If this file is
1179 setup correctly, it is possible to execute a testsuite merely by
1180 typing @code{runtest}.
1182 DejaGnu supports two @file{site.exp} files. The multiple instances of
1183 @file{site.exp} are loaded in a fixed order. The first file loaded is
1184 the local file @file{site.exp}, and then the optional global
1185 @file{site.exp} file as pointed to by the @code{DEJAGNU} environment
1188 There is an optional global @file{site.exp}, containing configuration
1189 values that apply to DejaGnu site-wide. @code{runtest} loads these
1190 values first. The global @file{site.exp} contains the default values
1191 for all targets and hosts supported by DejaGnu. This global file is
1192 identified by setting the environment variable @code{DEJAGNU} to the
1193 name of the file. If @code{DEJAGNU} is set, but the file cannot be
1194 located, an error will be raised and @code{runtest} will abort.
1196 Any directory containing a configured testsuite also has a local
1197 @file{site.exp}, capturing configuration values specific to the tool
1198 being tested. Since @code{runtest} loads these values last, the
1199 individual test configuration can either rely on and use, or override,
1200 any of the global values from the global @file{site.exp} file.
1202 You can usually generate or update the testsuite's local
1203 @file{site.exp} by typing @code{make site.exp} in the testsuite
1204 directory, after the test suite is configured.
1206 You can also have a file in your home directory called
1207 @file{.dejagnurc}. This gets loaded after the other config files.
1208 Usually this is used for personal stuff, like setting the
1209 @code{all_flag} so all the output gets printed, or your own verbosity
1210 levels. This file is usually restricted to setting command line
1213 You can further override the default values in a user-editable section
1214 of any @file{site.exp}, or by setting variables on the @code{runtest}
1218 * Local configuration file::
1219 * Global configuration file::
1220 * Board configuration file::
1221 * Remote host testing::
1222 * Configuration file values::
1225 @node Global configuration file, Local configuration file, , Customizing DejaGnu
1226 @section Global configuration file
1227 @cindex configuration file, global
1229 The global configuration file is where all the target specific
1230 configuration variables for a site are set. For example, a
1231 centralized testing lab where multiple developers have to share an
1232 embedded development board. There are settings for both remote hosts
1233 and remote targets. Below is an example of a global configuration
1234 file for a Canadian cross environment. A Canadian cross is a
1235 toolchain that is built on, runs on, and targets three different
1236 system triplets (for example, building a Solaris-hosted MIPS R4000
1237 toolchain on a GNU/Linux system). This example is based on a
1238 configuration once used at Cygnus.
1240 @strong{Example global configuration file}
1243 # Make sure we look in the right place for the board description files.
1244 lappend boards_dir "/nfs/cygint/s1/cygnus/dejagnu/boards"
1246 verbose "Global config file: target_triplet is $target_triplet" 2
1249 switch -glob -- $target_triplet @{
1251 @ set target_list "unix"
1254 @ set target_list "sparc64-sim"
1257 @ set target_list "mips-sim wilma barney"
1260 @ set target_list "mips-lsi-sim@{,soft-float,el@}"
1265 In this case, we have support for several cross compilers, that all
1266 run on this host. To run DejaGnu tests on tools hosted on operating
1267 systems that do not run Expect, DejaGnu can be run on the build
1268 machine and connect to the remote host to run all the tests. As you
1269 can see, all one does is set the variable @code{target_list} to the
1270 list of targets and options to test.
1272 In this example, simple cases like @emph{sparc64-elf} only require
1273 setting the name of the single board configuration file. The
1274 @emph{mips-elf} target is more complicated and sets the list to three
1275 target boards. @emph{mips-sim} is a symbolic name for a simulator
1276 ``board'' and @emph{wilma} and @emph{barney} are symbolic names for
1277 physical boards. Symbolic names are covered in the @ref{Adding a new
1278 board} section. The more complicated example is the entry for
1279 @emph{mips-lsi-elf}. This one runs the tests with multiple iterations
1280 using all possible combinations of the @code{--soft-float} and the
1281 @code{--el} (little endian) options. The braced string includes an
1282 initial comma so that the set of combinations includes no options at
1283 all. Needless to say, this last target example is mostly specific to
1286 @node Local configuration file, Board configuration file, Global configuration file, Customizing DejaGnu
1287 @section Local configuration file
1288 @cindex configuration file, local
1290 It is usually more convenient to keep these @emph{manual overrides} in
1291 the @file{site.exp} local to each test directory, rather than in the
1292 global @file{site.exp} in the installed DejaGnu library. This file is
1293 mostly for supplying tool specific info that is required by the
1296 All local @file{site.exp} files have two sections, separated by
1297 comments. The first section is generated by @code{make}. It is
1298 essentially a collection of Tcl variable definitions based on
1299 @file{Makefile} environment variables. Since they are generated by
1300 @code{make}, they contain the values as specified by @code{configure}.
1301 In particular, this section contains the @file{Makefile} variables for
1302 host and target configuration data. Do not edit this first section;
1303 if you do, your changes will be overwritten the next time you run
1304 @code{make}. The first section starts with:
1307 ## these variables are automatically generated by make ##
1308 # Do not edit here. If you wish to override these values
1309 # add them to the last section
1312 In the second section, you can override any default values for all the
1313 variables. The second section can also contain your preferred
1314 defaults for all the command line options to @code{runtest}. This
1315 allows you to easily customize @code{runtest} for your preferences in
1316 each configured testsuite tree, so that you need not type options
1317 repeatedly on the command line. The second section may also be empty
1318 if you do not wish to override any defaults.
1320 @strong{The first section ends with this line}
1323 ## All variables above are generated by configure. Do Not Edit ##
1326 You can make any changes under this line. If you wish to redefine a
1327 variable in the top section, then just put a duplicate value in this
1328 second section. Usually the values defined in this configuration file
1329 are related to the configuration of the test run. This is the ideal
1330 place to set the variables @code{host_triplet}, @code{build_triplet},
1331 @code{target_triplet}. All other variables are tool dependent, i.e.,
1332 for testing a compiler, the value for @code{CC} might be set to a
1333 freshly built binary, as opposed to one in the user's path.
1335 Here's an example local site.exp file, as used for GCC/G++ testing.
1337 @strong{Local Configuration File}
1340 ## these variables are automatically generated by make ##
1341 # Do not edit here. If you wish to override these values
1342 # add them to the last section
1343 set rootme "/build/devo-builds/i686-pc-linux-gnu/gcc"
1344 set host_triplet i686-pc-linux-gnu
1345 set build_triplet i686-pc-linux-gnu
1346 set target_triplet i686-pc-linux-gnu
1347 set target_alias i686-pc-linux-gnu
1349 set CXXFLAGS "-isystem /build/devo-builds/i686-pc-linux-gnu/gcc/../libio -isystem $srcdir/../libg++/src -isystem $srcdir/../libio -isystem $srcdir/../libstdc++ -isystem $srcdir/../libstdc++/stl -L/build/devo-builds/i686-pc-linux-gnu/gcc/../libg++ -L/build/devo-builds/i686-pc-linux-gnu/gcc/../libstdc++"
1350 append LDFLAGS " -L/build/devo-builds/i686-pc-linux-gnu/gcc/../ld"
1351 set tmpdir /build/devo-builds/i686-pc-linux-gnu/gcc/testsuite
1352 set srcdir "$@{srcdir@}/testsuite"
1353 ## All variables above are generated by configure. Do Not Edit ##
1356 This file defines the required fields for a local configuration file,
1357 namely the three system triplets, and the srcdir. It also defines
1358 several other Tcl variables that are used exclusively by the GCC
1359 testsuite. For most test cases, the CXXFLAGS and LDFLAGS are supplied
1360 by DejaGnu itself for cross testing, but to test a compiler, GCC needs
1361 to manipulate these itself.
1363 @vindex test_timeout
1364 The local @file{site.exp} may also set Tcl variables such as
1365 @code{test_timeout} which can control the amount of time (in seconds)
1366 to wait for a remote test to complete. If not specified,
1367 @code{test_timeout} defaults to 300 seconds.
1369 @node Board configuration file, Remote host testing, Local configuration file, Customizing DejaGnu
1370 @section Board configuration file
1371 @cindex configuration file, board
1373 The board configuration file is where board-specific configuration
1374 details are stored. A board configuration file contains all the
1375 higher-level configuration settings. There is a rough inheritance
1376 scheme, where it is possible to derive a new board description file
1377 from an existing one. There are also collections of custom procedures
1378 for common environments. For more information on adding a new board
1379 config file, see @ref{Adding a new board}.
1381 An example board configuration file for a GNU simulator is as follows.
1382 @code{set_board_info} is a procedure that sets the field name to the
1383 specified value. The procedures mentioned in brackets are
1384 @emph{helper procedures}. These are used to find parts of a toolchain
1385 required to build an executable image that may reside in various
1386 locations. This is mostly of use when the startup code, the standard
1387 C libraries, or the toolchain itself is part of your build tree.
1389 @strong{Example file}
1391 # This is a list of toolchains that are supported on this board.
1392 set_board_info target_install @{sparc64-elf@}
1394 # Load the generic configuration for this board. This will define any
1395 # routines needed by the tool to communicate with the board.
1396 load_generic_config "sim"
1398 # We need this for find_gcc and *_include_flags/*_link_flags.
1399 load_base_board_description "basic-sim"
1401 # Use long64 by default.
1402 process_multilib_options "long64"
1406 # We only support newlib on this target. We assume that all multilib
1407 # options have been specified before we get here.
1409 set_board_info compiler "[find_gcc]"
1410 set_board_info cflags "[libgloss_include_flags] [newlib_include_flags]"
1411 set_board_info ldflags "[libgloss_link_flags] [newlib_link_flags]"
1413 set_board_info ldscript ""
1415 # Used by a few gcc.c-torture testcases to delimit how large the
1417 set_board_info gcc,stack_size 16384
1418 # The simulator doesn't return exit status and we need to indicate this
1419 # the standard GCC wrapper will work with this target.
1420 set_board_info needs_status_wrapper 1
1421 # We can't pass arguments to programs.
1422 set_board_info noargs 1
1425 There are five helper procedures used in this example:
1429 @code{find_gcc} looks for a copy of the GNU compiler in your build
1430 tree, or it uses the one in your path. This will also return the
1431 proper transformed name for a cross compiler if you whole build tree
1432 is configured for one. DejaGnu will use this procedure to locate a
1433 compiler if the @code{compiler} field is not set.
1436 @code{libgloss_include_flags} returns the flags to compile using
1437 @ref{Libgloss, libgloss}, the GNU board support package (BSP).
1440 @code{libgloss_link_flags} returns the flags to link an executable
1441 using @ref{Libgloss, libgloss}.
1444 @code{newlib_include_flags} returns the flags to compile using
1445 @uref{https://sourceware.org/newlib, newlib}, a re-entrant standard C
1446 library for embedded systems comprising of non-GPL'd code
1449 @code{newlib_link_flags} returns the flags to link an executable with
1450 @uref{https://sourceware.org/newlib, newlib}.
1454 @node Remote host testing, Configuration file values, Board configuration file, Customizing DejaGnu
1455 @section Remote host testing
1456 @cindex testing on remote hosts
1458 DejaGnu also supports running the tests on a remote host. To set this
1459 up, the remote host needs an FTP server, and a telnet server.
1460 Currently foreign operating systems used as remote hosts are VxWorks,
1461 VRTX, DOS/Windows 3.1, MacOS and Windows.
1463 The recommended source for a Windows-based FTP server is to get IIS
1464 (either IIS 1 or Personal Web Server) from
1465 @uref{http://www.microsoft.com,http://www.microsoft.com}. When you
1466 install it, make sure you install the FTP server - it's not selected
1467 by default. Go into the IIS manager and change the FTP server so that
1468 it does not allow anonymous FTP. Set the home directory to the root
1469 directory (i.e. c:\) of a suitable drive. Allow writing via FTP.
1471 It will create an account like IUSR_FOOBAR where foobar is the name of
1472 your machine. Go into the user editor and give that account a
1473 password that you don't mind hanging around in the clear (i.e. not the
1474 same as your admin or personal passwords). Also, add it to all the
1475 various permission groups.
1477 You'll also need a telnet server. For Windows, go to the
1478 @uref{http://ataman.com,Ataman} web site, pick up the Ataman Remote
1479 Logon Services for Windows, and install it. You can get started on
1480 the eval period anyway. Add IUSR_FOOBAR to the list of allowed users,
1481 set the HOME directory to be the same as the FTP default directory.
1482 Change the Mode prompt to simple.
1484 Now you need to pick a directory name to do all the testing in. For
1485 the sake of this example, we'll call it piggy (i.e. c:\piggy). Create
1488 You'll need a Unix machine. Create a directory for the scripts you'll
1489 need. For this example, we'll use /usr/local/swamp/testing. You'll
1490 need to have a source tree somewhere, say /usr/src/devo. Now, copy
1491 some files from releng's area in SV to your machine:
1493 @strong{Remote host setup}
1496 cd /usr/local/swamp/testing
1498 scp darkstar.welcomehome.org:/dejagnu/cst/bin/MkTestDir .
1499 scp darkstar.welcomehome.org:/dejagnu/site.exp .
1500 scp darkstar.welcomehome.org:/dejagnu/boards/useless98r2.exp boards/foobar.exp
1501 export DEJAGNU=/usr/local/swamp/testing/site.exp
1504 You must edit the boards/foobar.exp file to reflect your machine;
1505 change the hostname (foobar.com), username (iusr_foobar), password,
1506 and ftp_directory (c:/piggy) to match what you selected.
1508 Edit the global @file{ site.exp} to reflect your boards directory:
1510 @strong{Add The Board Directory}
1513 lappend boards_dir "/usr/local/swamp/testing/boards"
1516 Now run MkTestDir, which is in the contrib directory. The first
1517 parameter is the toolchain prefix, the second is the location of your
1518 devo tree. If you are testing a cross compiler (ex: you have
1519 sh-hms-gcc.exe in your PATH on the PC), do something like this:
1521 @strong{Setup Cross Remote Testing}
1524 ./MkTestDir sh-hms /usr/dejagnu/src/devo
1527 If you are testing a native PC compiler (ex: you have gcc.exe in your
1528 PATH on the PC), do this:
1530 @strong{Setup Native Remote Testing}
1533 ./MkTestDir '' /usr/dejagnu/src/devo
1536 To test the setup, @code{ftp} to your PC using the username
1537 (iusr_foobar) and password you selected. CD to the test directory.
1538 Upload a file to the PC. Now telnet to your PC using the same
1539 username and password. CD to the test directory. Make sure the file
1540 is there. Type "set" and/or "gcc -v" (or sh-hms-gcc -v) and make sure
1541 the default PATH contains the installation you want to test.
1543 @strong{Run Test Remotely}
1546 cd /usr/local/swamp/testing
1547 make -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1
1550 To run a specific test, use a command like this (for this example,
1551 you'd run this from the gcc directory that MkTestDir created):
1553 @strong{Run a Test Remotely}
1556 make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c"
1559 Note: if you are testing a cross-compiler, put in the correct target
1560 board. You'll also have to download more .exp files and modify them
1561 for your local configuration. The -v's are optional.
1563 @node Configuration file values, , Remote host testing, Customizing DejaGnu
1564 @section Configuration file values
1565 @cindex configuration values
1568 DejaGnu uses a Tcl associative array to hold all the info for each
1569 machine. In the case of a Canadian cross, this means host information
1570 as well as target information. The named array is called
1571 @code{target_info}, and it has two indices. The following fields are
1575 * Command line option variables::
1576 * User configuration file::
1579 @node Command line option variables, User configuration file, , Configuration file values
1580 @subsection Command line option variables
1582 In the user editable second section of the @ref{User configuration
1583 file} you can not only override the configuration variables captured
1584 in the first section, but also specify default values for all of the
1585 @code{runtest} command line options. Excepting @code{--debug},
1586 @code{--help}, and @code{--version}, each command line option has an
1587 associated Tcl variable. Use the Tcl @code{set} command to specify a
1588 new default value (as for the configuration variables). The following
1589 table describes the correspondence between command line options and
1590 variables you can set in @file{site.exp}. Refer to @ref{Invoking
1591 runtest}, for explanations of the command-line options.
1593 @multitable {--target_board} {TOOL_EXECUTABLE} {verbosity level greater than or equal to 0}
1595 Option@tab Tcl variable@tab Description
1598 -a, --all@tab all_flag@tab display all test results if set
1601 --build@tab build_triplet@tab system triplet for the build host
1604 --dir@tab cmdline_dir_to_run@tab run only tests in the specified directory
1607 --global_init@tab global_init_file@tab file name for global init file in @code{libdir}
1610 --host@tab host_triplet@tab system triplet for the host
1613 --host_board@tab host_board@tab host board definition to use
1616 --ignore@tab ignoretests @tab do not run the specified tests
1619 --local_init@tab local_init_file@tab file name for local init file in @code{objdir}
1622 --log_dialog@tab log_dialog@tab emit Expect output to standard output
1625 --outdir@tab outdir@tab directory for @file{.sum} and @file{.log} files
1628 --objdir@tab objdir@tab directory for pre-compiled binaries
1631 --reboot@tab reboot@tab reboot the target if set to 1
1634 --srcdir@tab srcdir@tab directory of test subdirectories
1637 --target@tab target_triplet@tab system triplet for the target
1640 --target_board@tab target_list@tab list of target boards to run tests on
1643 --tool@tab tool@tab name of tool to test (selects tests to run)
1646 --tool_exec@tab TOOL_EXECUTABLE@tab path to the executable to test
1649 --tool_opts@tab TOOL_OPTIONS@tab additional options to pass to the tool
1652 --tool_root_dir@tab tool_root_dir@tab tool root directory
1655 -v, --verbose@tab verbose@tab verbosity level greater than or equal to 0
1659 @node User configuration file, , Command line option variables, Configuration file values
1660 @subsection Per-user configuration file (.dejagnurc)
1662 The per-user configuration file is named @file{.dejagnurc} in the
1663 user's home directory. It is used to customize the behaviour of
1664 @code{runtest} for each user -- typically the user's preference for
1665 log verbosity, and for storing any experimental Tcl procedures. An
1666 example @file{~/.dejagnurc} file looks like:
1668 @strong{Example .dejagnurc}
1672 set RLOGIN /usr/ucb/rlogin
1673 set RSH /usr/local/sbin/ssh
1676 Here @code{all_flag} is set so that I see all the test cases that PASS
1677 along with the ones that FAIL. I also set @code{RLOGIN} to the BSD
1678 (non-Kerberos) version. I also set @code{RSH} to the SSH secure
1679 shell, as rsh is mostly used to test Unix machines within a local
1682 @node Extending DejaGnu, Unit testing, Customizing DejaGnu, Top
1683 @chapter Extending DejaGnu
1685 @cindex extending DejaGnu
1687 This chapter describes how to extend DejaGnu with new testsuites, new
1688 tools, new targets and new boards.
1691 * Adding a new testsuite::
1692 * Adding a new tool::
1693 * Adding a new target::
1694 * Adding a new board::
1695 * Board file values::
1696 * Writing a test case::
1697 * Debugging a test case::
1698 * Adding a test case to a testsuite::
1699 * Test case special variables: Test case variables.
1702 @node Adding a new testsuite, Adding a new tool, , Extending DejaGnu
1703 @section Adding a new testsuite
1704 @cindex adding, testsuite
1706 The testsuite for a new package should always be located in the source
1707 directory of that package. DejaGnu requires this directory to be
1708 named @file{testsuite}. Under this directory, the test cases go in
1709 various subdirectories whose name begins with the tool name. The
1710 organization of the various testsuite subdirectories is up to you.
1711 For a tool named @code{gdb}, for instance, each subdirectory
1712 containing tests must start with @samp{gdb.}.
1714 @node Adding a new tool, Adding a new target, Adding a new testsuite, Extending DejaGnu
1715 @section Adding a new tool
1717 In general, the best way to learn how to write code, or even prose, is
1718 to read something similar. This principle applies to test cases and
1719 to testsuites. Unfortunately, well-established testsuites have a way
1720 of developing their own conventions: as test writers become more
1721 experienced with DejaGnu and with Tcl, they accumulate more utilities,
1722 and take advantage of more and more features of Expect and Tcl in
1723 general. Inspecting such established testsuites may make the prospect
1724 of creating an entirely new testsuite appear overwhelming.
1725 Nevertheless, it is straightforward to start a new testsuite.
1727 To help orient you further in this task, here is an outline of the
1728 steps to begin building a testsuite for a program example.
1730 Create or select a directory to contain your new collection of tests.
1731 Change into that directory (shown here as @file{testsuite}):
1733 Create a @file{configure.in} file in this directory, to control
1734 configuration-dependent choices for your tests. So far as DejaGnu is
1735 concerned, the important thing is to set a value for the variable
1736 @code{target_abbrev}; this value is the link to the init file you will
1737 write soon. (For simplicity, we assume the environment is Unix, and
1738 use @emph{unix} as the value.)
1740 What else is needed in @file{configure.in} depends on the requirements
1741 of your tool, your intended test environments, and which configure
1742 system you use. This example is a minimal @file{configure.ac} for use
1745 @subsection Sample Makefile.in Fragment
1747 Create @file{Makefile.in} (if using Autoconf), or @file{Makefile.am}
1748 (if using Automake), the source file used by configure to build your
1749 @file{Makefile}. If you are using GNU Automake.just add the keyword
1750 @emph{dejagnu} to the @emph{AUTOMAKE_OPTIONS} variable in your
1751 @file{Makefile.am} file. This will add all the @file{Makefile}
1752 support needed to run DejaGnu, and support the @ref{Make Check, make
1755 You also need to include two targets important to DejaGnu:
1756 @emph{check}, to run the tests, and @emph{site.exp}, to set up the Tcl
1757 copies of configuration-dependent values. This is called the
1758 @ref{Local configuration file} The @emph{check} target must invoke the
1759 @code{runtest} program to run the tests.
1761 The @emph{site.exp} target should usually set up (among other things)
1762 the @emph{$tool} variable for the name of your program. If the local
1763 @file{site.exp} file is setup correctly, it is possible to execute the
1764 tests by merely typing @code{runtest} on the command line.
1767 # Look for a local version of DejaGnu, otherwise use one in the path
1768 RUNTEST = `if test -f $(top_srcdir)/../dejagnu/runtest; then \
1769 echo $(top_srcdir) ../dejagnu/runtest; \
1774 # Flags to pass to runtest
1779 @ $(RUNTEST) $(RUNTESTFLAGS) --tool $@{example@} --srcdir $(srcdir)
1781 # Make the local config file
1782 site.exp: ./config.status Makefile
1783 @ @@echo "Making a new config file..."
1787 @ -@@mv site.exp site.bak
1788 @ @@echo "## these variables are automatically generated by make ##" > ./tmp0
1789 @ @@echo "# Do not edit here. If you wish to override these values" >> ./tmp0
1790 @ @@echo "# add them to the last section" >> ./tmp0
1791 @ @@echo "set host_os $@{host_os@}" >> ./tmp0
1792 @ @@echo "set host_alias $@{host_alias@}" >> ./tmp0
1793 @ @@echo "set host_cpu $@{host_cpu@}" >> ./tmp0
1794 @ @@echo "set host_vendor $@{host_vendor@}" >> ./tmp0
1795 @ @@echo "set target_os $@{target_os@}" >> ./tmp0
1796 @ @@echo "set target_alias $@{target_alias@}" >> ./tmp0
1797 @ @@echo "set target_cpu $@{target_cpu@}" >> ./tmp0
1798 @ @@echo "set target_vendor $@{target_vendor@}" >> ./tmp0
1799 @ @@echo "set host_triplet $@{host_canonical@}" >> ./tmp0
1800 @ @@echo "set target_triplet $@{target_canonical@}">>./tmp0
1801 @ @@echo "set tool binutils" >> ./tmp0
1802 @ @@echo "set srcdir $@{srcdir@}" >> ./tmp0
1803 @ @@echo "set objdir `pwd`" >> ./tmp0
1804 @ @@echo "set $@{examplename@} $@{example@}" >> ./tmp0
1805 @ @@echo "## All variables above are generated by configure. Do Not Edit ##" >> ./tmp0
1806 @ @@cat ./tmp0 > site.exp
1807 @ @@sed < site.bak \
1808 @ -e '1,/^## All variables above are.*##/ d' \
1813 @subsection Simple tool init file for batch programs
1815 Create a directory (under @file{testsuite}) called @file{config}.
1816 Make a tool init file in this directory. Its name must start with the
1817 @code{target_abbrev} value, or be named @file{default.exp} so call it
1818 @file{config/unix.exp} for our Unix based example. This is the file
1819 that contains the target-dependent procedures. Fortunately, on a
1820 native Unix system, most of them do not have to do very much in order
1821 for @code{runtest} to run. If the program being tested is not
1822 interactive, you can get away with this minimal @file{unix.exp} to
1826 proc myprog_exit @{@} @{@}
1827 proc myprog_version @{@} @{@}
1830 If the program being tested is interactive, however, you might as well
1831 define a @emph{start} routine and invoke it by using a tool init file
1834 @subsection Simple tool init file for interactive programs
1837 proc myprog_exit @{@} @{@}
1838 proc myprog_version @{@} @{@}
1840 proc myprog_start @{@} @{
1841 @ global $@{examplename@}
1842 @ spawn $@{examplename@}
1848 # Start the program running we want to test
1852 Create a directory whose name begins with your tool's name, to contain
1853 tests. For example, if the tool name is @emph{example}, then the
1854 directories all need to start with @samp{example.}. Create a sample
1855 test file ending in @file{.exp}. You can name the file
1856 @file{first-try.exp}. To begin with, just write one line of Tcl code
1860 send_user "Testing: one, two...\n"
1863 @subsection Testing A New Tool Config
1865 Back in the @file{testsuite} (top level) directory, run
1866 @code{configure}. Typically you do this while in the build directory.
1867 You are now ready to type @code{make check} or @code{runtest}. You
1868 should see something like this:
1871 Test Run By bje on Sat Nov 14 15:08:54 AEDT 2015
1873 @ === example tests ===
1875 Running ./example.0/first-try.exp ...
1876 Testing: one, two...
1878 @ === example Summary ===
1881 There is no output in the summary, because so far the example does not
1882 call any of the procedures that report a test outcome.
1884 Write some real tests. For an interactive tool, you should probably
1885 write a real exit routine in fairly short order. In any case, you
1886 should also write a real version routine soon.
1888 @node Adding a new target, Adding a new board, Adding a new tool, Extending DejaGnu
1889 @section Adding a new target
1890 @cindex adding, target
1892 DejaGnu has some additional requirements for target support, beyond
1893 the general-purpose provisions of a @code{configure} script. DejaGnu
1894 must actively communicate with the target, rather than simply
1895 generating or managing code for the target architecture. Therefore,
1896 each tool requires an initialization module for each target. For new
1897 targets, you must supply a few Tcl procedures to adapt DejaGnu to the
1900 Usually the best way to write a new initialization module is to edit
1901 an existing initialization module; some trial and error will be
1902 required. If necessary, you can use the @code{--debug} option to see
1903 what is really going on.
1905 When you code an initialization module, be generous in printing
1906 information using the @code{verbose} procedure. In cross-development
1907 environments, most of the work is in getting the communications right.
1908 Code for communicating via TCP/IP networks or serial lines is
1909 available in a DejaGnu library files such as @file{lib/telnet.exp}.
1911 If you suspect a communication problem, try running the connection
1912 interactively from Expect. (There are three ways of running Expect as
1913 an interactive interpreter. You can run Expect with no arguments, and
1914 control it completely interactively; or you can use @code{expect -i}
1915 together with other command-line options and arguments; or you can run
1916 the command @code{interpreter} from any Expect procedure. Use
1917 @code{return} to get back to the calling procedure (if any), or
1918 @code{return -tcl} to make the calling procedure itself return to its
1919 caller; use @code{exit} or end-of-file to leave Expect altogether.)
1920 Run the program whose name is recorded in @code{$connectmode}, with
1921 the arguments in @code{$targetname}, to establish a connection. You
1922 should at least be able to get a prompt from any target that is
1923 physically connected.
1925 @node Adding a new board, Board file values, Adding a new target, Extending DejaGnu
1926 @section Adding a new board
1927 @cindex adding, board
1929 Adding a new board consists of creating a new board configuration
1930 file. Examples are in @file{dejagnu/baseboards}. Usually to make a
1931 new board file, it's easiest to copy an existing one. It is also
1932 possible to have your file be based on a @emph{baseboard} file with
1933 only one or two changes needed. Typically, this can be as simple as
1934 just changing the linker script. Once the new baseboard file is done,
1935 add it to the @code{boards_DATA} list in the
1936 @file{dejagnu/baseboards/Makefile.am}, and regenerate the Makefile.in
1937 using automake. Then just rebuild and install DejaGnu. You can test
1940 There is a crude inheritance scheme going on with board files, so you
1941 can include one board file into another, The two main procedures used
1942 to do this are @code{load_generic_config} and
1943 @code{load_base_board_description}. The generic configuration file
1944 contains other procedures used for a certain class of target. The
1945 board description file is where the board specific settings go.
1946 Commonly there are similar target environments with just different
1949 @strong{Testing a New Board Configuration File}
1952 make check RUNTESTFLAGS="--target_board=newboardfile".
1955 Here's an example of a board configuration file. There are several
1956 @emph{helper procedures} used in this example. A helper procedure is
1957 one that look for a tool of files in commonly installed locations.
1958 These are mostly used when testing in the build tree, because the
1959 executables to be tested are in the same tree as the new DejaGnu
1960 files. The helper procedures are the ones in brackets, which
1961 indicates a Tcl procedure call.
1963 @strong{Example Board Configuration File}
1966 # Load the generic configuration for this board. This will define a basic
1967 # set of routines needed by the tool to communicate with the board.
1968 load_generic_config "sim"
1970 # basic-sim.exp is a basic description for the standard Cygnus simulator.
1971 load_base_board_description "basic-sim"
1973 # The compiler used to build for this board. This has *nothing* to do
1974 # with what compiler is tested if we're testing gcc. Further, this is
1975 # the default, so this line is optional for most boards.
1976 set_board_info compiler "[find_gcc]"
1978 # We only support newlib on this target.
1979 # However, we include libgloss so we can find the linker scripts.
1980 set_board_info cflags "[newlib_include_flags] [libgloss_include_flags]"
1981 set_board_info ldflags "[newlib_link_flags]"
1983 # No linker script for this board.
1984 set_board_info ldscript "-Tsim.ld"
1986 # The simulator doesn't return exit statuses and we need to indicate this.
1987 set_board_info needs_status_wrapper 1
1989 # Can't pass arguments to this target.
1990 set_board_info noargs 1
1993 set_board_info gdb,nosignals 1
1995 # And it can't call functions.
1996 set_board_info gdb,cannot_call_functions 1
1999 @node Board file values, Writing a test case, Adding a new board, Extending DejaGnu
2000 @section Board configuration file values
2002 The following fields are in the @code{board_info} array. These are
2003 set by the @code{set_board_info} procedure (or @code{add_board_info}
2004 procedure for appending to lists). Both procedures take a field name
2005 and a value for the field (or is added to the field), respectively.
2006 Some common board info fields are shown below.
2008 @multitable @columnfractions 0.2 0.2 0.6
2010 @strong{Field} @tab @strong{Example value} @tab @strong{Description}
2012 compiler@tab @code{[find_gcc]}@tab The path to the compiler to use.
2014 cflags@tab @code{-mca}@tab Compilation flags for the compiler.
2016 ldflags@tab @code{[libgloss_link_flags] [newlib_link_flags]}@tab Linking flags for the compiler.
2018 ldscript@tab @code{-Wl,-Tidt.ld}@tab The linker script to use when cross compiling.
2020 libs@tab @code{-lgcc}@tab Any additional libraries to link in.
2022 shell_prompt@tab @code{cygmon>}@tab The command prompt of the remote shell.
2024 hex_startaddr@tab @code{0xa0020000}@tab The Starting address as a string.
2026 start_addr@tab 0xa0008000@tab The starting address as a value.
2028 startaddr@tab @code{a0020000}@tab
2030 exit_statuses_bad@tab 1@tab Whether there is an accurate exit status.
2032 reboot_delay@tab 10@tab The delay between power off and power on.
2034 unreliable@tab 1@tab Whether communication with the board is unreliable.
2036 sim@tab [find_sim]@tab The path to the simulator to use.
2038 objcopy@tab $tempfil@tab The path to the @code{objcopy} program.
2040 support_libs@tab @code{$@{prefix_dir@}/i386-coff/}@tab Support libraries needed for cross compiling.
2042 addl_link_flags@tab @code{-N}@tab Additional link flags, rarely used.
2044 remotedir@tab @code{/tmp/runtest.[pid]}@tab Directory on the remote target in which executables are downloaded and executed.
2047 These fields are used by the GCC and GDB tests, and are mostly only
2048 useful to somewhat trying to debug a new board file for one of these
2049 tools. Many of these are used only by a few testcases, and their
2050 purpose is esoteric. These are listed with sample values as a guide
2051 to better guessing if you need to change any of these.
2053 @strong{Board Info Fields For GCC & GDB}
2055 @multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333
2057 Field@tab Sample Value@tab Description
2059 strip@tab $tempfile@tab Strip the executable of symbols.
2061 gdb_load_offset@tab "0x40050000"@tab
2063 gdb_protocol@tab "remote"@tab The GDB debugging protocol to use.
2065 gdb_sect_offset@tab "0x41000000";@tab
2067 gdb_stub_ldscript@tab "-Wl,-Teva-stub.ld"@tab The linker script to use with a GDB stub.
2069 gdb,noargs@tab 1@tab Whether the target can take command line arguments.
2071 gdb,nosignals@tab 1@tab Whether there are signals on the target.
2073 gdb,short_int@tab 1@tab
2075 gdb,target_sim_options@tab "-sparclite"@tab Special options to pass to the simulator.
2077 gdb,timeout@tab 540@tab Timeout value to use for remote communication.
2079 gdb_init_command@tab "set mipsfpu none"@tab A single command to send to GDB before the program being
2080 debugged is started.
2082 gdb_init_commands@tab "print/x \$fsr = 0x0"@tab Same as @emph{gdb_init_command}, except
2083 that this is a list, more commands can be added.
2085 gdb_load_offset@tab "0x12020000"@tab
2087 gdb_opts@tab "--command gdbinit"@tab
2089 gdb_prompt@tab "\\(gdb960\\)"@tab The prompt GDB is using.
2091 gdb_run_command@tab "jump start"@tab
2093 gdb_stub_offset@tab "0x12010000"@tab
2095 use_gdb_stub@tab 1@tab Whether to use a GDB stub.
2097 wrap_m68k_aout@tab 1@tab
2099 gcc,no_label_values@tab 1@tab
2101 gcc,no_trampolines@tab 1@tab
2103 gcc,no_varargs@tab 1@tab
2105 gcc,stack_size@tab 16384@tab Stack size to use with some GCC testcases.
2107 ieee_multilib_flags@tab "-mieee"@tab
2109 is_simulator@tab 1@tab
2111 needs_status_wrapper@tab 1@tab
2115 no_long_long@tab 1@tab
2119 target_install@tab @{sh-hms@}@tab
2122 @node Writing a test case, Debugging a test case, Board file values, Extending DejaGnu
2123 @section Writing a test case
2124 @cindex Writing a test case
2126 The easiest way to prepare a new test case is to base it on an
2127 existing one for a similar situation. There are two major categories
2128 of tests: batch-oriented and interactive. Batch-oriented tests are
2129 usually easier to write.
2131 The GCC tests are a good example of batch-oriented tests. All GCC
2132 tests consist primarily of a call to a single common procedure, since
2133 all the tests either have no output, or only have a few warning
2134 messages when successfully compiled. Any non-warning output
2135 constitutes a test failure. All the C code needed is kept in the test
2136 directory. The test driver, written in Tcl, need only get a listing
2137 of all the C files in the directory, and compile them all using a
2138 generic procedure. This procedure and a few others supporting for
2139 these tests are kept in the library module @file{lib/c-torture.exp} of
2140 the GCC testsuite. Most tests of this kind use very few Expect
2141 features, and are coded almost purely in Tcl.
2143 Writing the complete suite of C tests, then, consisted of these steps:
2147 Copying all the C code into the test directory. These tests were
2148 based on the C-torture test created by Torbjorn Granlund (on behalf of
2149 the Free Software Foundation) for GCC development.
2152 Writing (and debugging) the generic Tcl procedures for compilation.
2155 Writing the simple test driver: its main task is to search the
2156 directory (using the Tcl procedure @emph{glob} for filename expansion
2157 with wildcards) and call a Tcl procedure with each filename. It also
2158 checks for a few errors from the testing procedure.
2161 Testing interactive programs is intrinsically more complex. Tests for
2162 most interactive programs require some trial and error before they are
2165 However, some interactive programs can be tested in a simple fashion
2166 reminiscent of batch tests. For example, prior to the creation of
2167 DejaGnu, the GDB distribution already included a wide-ranging testing
2168 procedure. This procedure was very robust, and had already undergone
2169 much more debugging and error checking than many recent DejaGnu test
2170 cases. Accordingly, the best approach was simply to encapsulate the
2171 existing GDB tests, for reporting purposes. Thereafter, new GDB tests
2172 built up a family of Tcl procedures specialized for GDB testing.
2174 @subsection Hints on writing a test case
2175 @cindex hints on writing a test case
2176 @cindex test cases, writing
2178 To preserve basic sanity, no should test ever pass if there was any
2179 kind of problem in the test case. To take an extreme case, tests that
2180 pass even when the tool will not spawn are misleading. Ideally, a
2181 test in this sort of situation should not fail either. Instead, print
2182 an error message by calling one of the DejaGnu procedures
2183 @code{perror} or @code{warning}. Note that using @code{perror} will
2184 cause the next text result to be reported as @samp{UNRESOLVED}, so
2185 printing an error and allowing the test to fail is a good option.
2187 If you have trouble understanding why a pattern does not match the
2188 program output, try using the @code{--debug} option to @code{runtest},
2189 and examine the debug log carefully.
2191 If you use glob patterns, you will need to escape any @samp{*},
2192 @samp{?}, @samp{[}, @samp{]}, and @samp{\} characters that are meant
2193 to match literally. If you use regular expressions, see the
2194 @cite{re_syntax(n)} manual page from Tcl for the syntax details, and
2195 be sure to understand what punctuation characters match literally and
2196 what characters have special meanings in regular expressions.
2198 Tcl has a few options for quoting; the most notable are @samp{@{@}}
2199 and @samp{""}. These quotes behave differently: @samp{@{@}} must
2200 balance, while @samp{""} performs various interpolations. In
2201 @samp{@{@}} quotes, unbalanced @samp{@{} or @samp{@}} characters must
2202 be escaped with @samp{\} and these escapes are @emph{not} removed;
2203 fortunately, backslash-escaped braces match literal braces in Tcl
2204 regular expressions. In @samp{""} quotes, any embedded @samp{"}
2205 characters must be escaped, a literal @samp{$} begins a variable
2206 substitution, and unescaped @samp{[]} introduce a Tcl command
2209 @subsubheading Synchronization with the tested program
2211 A DejaGnu testsuite executes concurrently with the programs that it
2212 tests. As a result, DejaGnu may see parts of the tested program's
2213 output while the tested program is still producing more output.
2214 Expect patterns must be written to handle the possibility that
2215 incomplete output from the tested program will be considered for
2218 Expect reads the output from the tested program into an internal
2219 matching buffer and removes everything from the start of the buffer to
2220 the end of the match when a match is found. Any given character can
2221 be matched at most once, or skipped if a match is found starting later
2222 in the buffer or the buffer reaches its capacity. Anything left in
2223 the buffer after the end of the match remains in the buffer and is
2224 considered for the next @code{expect} command. If @code{expect} is
2225 invoked and no patterns match, Expect waits for more text to arrive.
2226 New text is appended to the buffer as it is read. If the buffer
2227 reaches its capacity, the entire contents of the buffer are discarded
2228 and Expect resumes reading.
2230 In Expect patterns, the regular expression anchors @samp{^} and
2231 @samp{$} match at the beginning and end of the @emph{buffer}, not at
2232 line boundaries. The @samp{$} anchor must be used with care because
2233 it will match at the end of what Expect @emph{has} read, but the
2234 program may have produced more output that Expect @emph{has not yet}
2235 read. Similarly, regular expressions ending with the @samp{*}
2236 quantifier can potentially match a prefix of the intended text, only
2237 for the rest to arrive shortly thereafter.
2239 Maintaining synchronization with the tested program is easier if the
2240 patterns match all of the output generated by the tested program; this
2243 For interactive programs, a prompt is usually a good synchronization
2244 point, provided that the program's prompt can be uniquely recognized.
2245 Since the prompt is usually the last output until the program receives
2246 further input, the @samp{$} anchor can be useful here.
2248 If the output from the tested program is organized into lines,
2249 matching end-of-line using @samp{\n} is usually a good way to process
2250 one line at a time. Note that terminal settings may result in the
2251 insertion of additional @samp{\r} characters, usually translating
2252 @samp{\n} to @samp{\r\n}.
2254 Be careful not to neglect output generated by setup rather than by the
2255 interesting parts of a test case. For example, while testing GDB, a
2256 @samp{set height 0\n} command is issued. The purpose is simply to
2257 make sure GDB never calls a paging program. The @samp{set height}
2258 command in GDB does not generate any output; but running any command
2259 makes GDB issue a new @samp{(gdb) } prompt. If there were no
2260 @code{expect} command to match this prompt, the @samp{(gdb) } prompt
2261 will remain in the buffer and begin the text seen by the next
2262 @code{expect} command---which might make that pattern fail to match.
2264 @subsubheading Priority of Expect patterns
2266 Be particularly careful about how you write the patterns. Expect
2267 attempts to match each pattern in the order that they are written in
2268 the @code{expect} command. Unless a regexp pattern is anchored at the
2269 beginning of the buffer, Expect can search ahead for a match for a
2270 pattern that appears earlier in the @code{expect} command and skip
2271 over text that would match a later pattern. @emph{The text thus
2272 skipped is discarded.} This is a source of very hard to trace bugs,
2273 especially when reading input from batch-oriented unit tests.
2275 For example, consider a simple model once used by the DejaGnu
2276 testsuite for unit testing. In this example, a test has failed, but
2277 the tests before and after it have passed. First the relevant input
2286 The test script is reading this with two Expect patterns, simplified
2287 for this example by omitting handling of the actual messages and other
2292 -re @{PASSED: [^\r\n]+[\r\n]+@} @{ pass ... @}
2293 -re @{FAILED: [^\r\n]+[\r\n]+@} @{ fail ... @}
2297 At every cycle, Expect attempts to match each pattern in the order
2298 that they are written against the available input. If DejaGnu is
2299 processing the input as quickly as it arrives, this example will
2300 actually work. However, if the system scheduler sets DejaGnu aside
2301 for a bit, or the external program produces output in a burst, Expect
2302 can find that its input buffer contains the text in the first example
2303 above all at once as the cycle begins.
2305 If this occurs, Expect will first attempt to match @code{@{PASSED:
2306 [^\r\n]+[\r\n]+@}} against the input and will succeed, since the input
2307 begins with @samp{PASSED: foo}. The @code{pass} procedure is called
2308 and the test result recorded. Expect then starts a new matching
2311 If the input had been presented one line at a time, the expected
2312 result would occur: the @code{@{FAILED: [^\r\n]+[\r\n]+@}} pattern
2313 would match and the test driver would work correctly. But we are
2314 considering the case where all three lines arrived ``at once'' so we
2315 must examine what Expect will do in this case. After the first line
2316 has been processed, the Expect buffer now contains:
2323 Expect again attempts to match each pattern in order. Expect will
2324 attempt to match @code{@{PASSED: [^\r\n]+[\r\n]+@}} before attempting
2325 to match @code{@{FAILED: [^\r\n]+[\r\n]+@}} and the first attempt
2326 succeeds because the pattern is not anchored. The @samp{FAILED: bar}
2327 message is simply discarded when Expect finds the later
2328 @samp{PASSED:baz} message in the buffer.
2330 How to prevent this? There are two ways: either group all of your
2331 test matches into a single regexp using alternation, or ensure that
2332 all patterns can match only at the start of Expect's buffer. Both
2333 options can be made to work. Grouping all status results into a
2334 single regexp allows some other unspecified text to still be silently
2335 discarded, while ensuring that all patterns are anchored absolutely
2336 requires closure, as any unmatched text will cause Expect to run out
2337 of buffer space. Expect discards the entire buffer when this occurs.
2339 @node Debugging a test case, Adding a test case to a testsuite, Writing a test case, Extending DejaGnu
2340 @section Debugging a test case
2341 @cindex test cases, debugging
2343 These are the kinds of debugging information available from DejaGnu:
2348 Output controlled by test scripts themselves, explicitly allowed for
2349 by the test author. This kind of debugging output appears in the
2350 detailed output recorded in the DejaGnu log file. To do the same for
2351 new tests, use the @code{verbose} procedure (which in turn uses the
2352 Tcl variable @samp{verbose}) to control how much output to generate.
2353 This will make it easier for other people running the test to debug it
2354 if necessary. If @samp{verbose} is zero, there should be no output
2355 other than the output from the framework (eg. FAIL). Then, to
2356 whatever extent is appropriate for the particular test, allow
2357 successively higher values of @samp{verbose} to generate more
2358 information. Be kind to other programmers who use your tests --
2359 provide plenty of debugging information.
2362 Output from the internal debugging functions of Tcl and Expect. There
2363 is a command line options for each; both forms of debugging output are
2364 recorded in the file @file{dbg.log} in the current directory.
2366 Use @code{--debug} for information from Expect. It logs how Expect
2367 attempts to match the tool output with the patterns specified. This
2368 can be very helpful while developing test scripts, since it shows
2369 precisely the characters received. Iterating between the latest
2370 attempt at a new test script and the corresponding @file{dbg.log} can
2371 allow you to create the final patterns by ``cut and paste''. This is
2372 sometimes the best way to write a test case.
2375 Use @code{--strace} to see more detail from Tcl. This logs how Tcl
2376 procedure definitions are expanded as they execute. The trace level
2377 argument controls the depth of definitions expanded.
2380 If the value of @samp{verbose} is 3 or greater (@code{runtest -v -v
2381 -v}), DejaGnu activates the Expect command @code{log_user}. This
2382 command prints all Expect actions to standard output, to the
2383 @file{.log} file and, if @code{--debug} is given, to @file{dbg.log}.
2386 @node Adding a test case to a testsuite, Test case variables, Debugging a test case, Extending DejaGnu
2387 @section Adding a test case to a testsuite
2388 @cindex test cases, adding
2390 There are two slightly different ways to add a test case. One is to
2391 add the test case to an existing directory. The other is to create a
2392 new directory to hold your test. The existing test directories
2393 represent several styles of testing, all of which are slightly
2394 different. Examine the testsuite subdirectories for the tool of
2395 interest to see which approach is most suitable.
2397 Adding a GCC test may be very simple: just add the source file to any
2398 test directory beginning with @file{gcc.} and it will be tested on the
2401 Adding a test by creating a new directory involves:
2405 Create the new directory. All subdirectory names begin with the name
2406 of the tool to test; e.g. G++ tests might be in a directory called
2407 @file{g++.other}. There can be multiple testsuite subdirectories with
2408 the same tool name prefix.
2411 Add the new test case to the directory, as above.
2414 @node Test case variables, , Adding a test case to a testsuite, Extending DejaGnu
2415 @section Test case special variables
2417 There are special variables that contain other information from
2418 DejaGnu. Your test cases can inspect these variables, as well as the
2419 variables saved in @file{site.exp}. These variables should never be
2426 The bug tracking system (eg. PRMS/GNATS) number identifying a
2427 corresponding bug report (@emph{0} if you do not specify it).
2431 An optional bug ID, perhaps a bug identification number from another
2432 organization (@emph{0} if you do not specify it).
2436 The subdirectory for the current test case.
2440 This is the output from a @code{$@{tool@}_load} command. This only
2441 applies to tools like GCC and GAS which produce an object file that
2442 must in turn be executed to complete a test.
2446 This is the output from a @code{$@{tool@}_start} command. This is
2447 conventionally used for batch-oriented programs, like GCC and GAS,
2448 that may produce interesting output (warnings, errors) without further
2451 @item $expect_out(buffer)
2452 @vindex expect_out(buffer)
2453 The output from the last command. This is an internal variable set by
2454 Expect. More information can be found in the Expect manual.
2457 @node Unit testing, Built-in Procedures, Extending DejaGnu, Top
2458 @chapter Unit testing
2461 * What is unit testing?::
2462 * The dejagnu.h header file: The dejagnu_h header file.
2463 * C unit testing API::
2464 * C++ unit testing API::
2467 @node What is unit testing?, The dejagnu_h header file, , Unit testing
2468 @section What is unit testing?
2469 @cindex unit testing
2471 Most regression testing as done by DejaGnu is system testing: the
2472 complete application is tested all at once. Unit testing is for
2473 testing single files, or small libraries. In this case, each file is
2474 linked with a test case in C or C++, and each function or class and
2475 method is tested in turn, with the test case having to check private
2476 data or global variables to see if the function or method worked.
2478 This works particularly well for testing APIs and at level where it is
2479 easier to debug them, than by needing to trace through the entire
2480 application. Also if there is a specification for the API to be
2481 tested, the testcase can also function as a compliance test.
2483 @node The dejagnu_h header file, C unit testing API, What is unit testing?, Unit testing
2484 @section The dejagnu.h header file
2485 @cindex dejagnu.h header
2487 DejaGnu uses a single header file, @file{dejagnu.h} to assist in unit
2488 testing. As this file also produces its one test state output, it can
2489 be run stand-alone, which is very useful for testing on embedded
2490 systems. This header file has a C and C++ API for the test states,
2491 with simple totals, and standardized output. Because the output has
2492 been standardized, DejaGnu can be made to work with this test case,
2493 without writing almost any Tcl. The library module, dejagnu.exp, will
2494 look for the output messages, and then merge them into DejaGnu's.
2496 @node C unit testing API, C++ unit testing API, The dejagnu_h header file, Unit testing
2497 @section C unit testing API
2498 @cindex C unit testing API
2500 All of the functions that take a @code{msg} parameter use a C
2501 @code{char *} that is the message to be displayed. There currently is
2502 no support for variable length arguments.
2506 @code{pass} prints a message for a successful test completion.
2509 @t{@b{pass}(@i{msg});}
2513 @code{fail} prints a message for an unsuccessful test completion.
2516 @t{@b{fail}(@i{msg});}
2520 @code{untested} prints a message for an test case that isn't run for
2521 some technical reason.
2524 @t{@b{untested}(@i{msg});}
2528 @code{unresolved} prints a message for an test case that is run, but
2529 there is no clear result. These output states require a human to look
2530 over the results to determine what happened.
2533 @t{@b{unresolved}(@i{msg});}
2537 @code{totals} prints out the total numbers of all the test state
2546 @node C++ unit testing API, , C unit testing API, Unit testing
2547 @section C++ unit testing API
2548 @cindex C++ unit testing API
2550 All of the methods that take a @code{msg} parameter use a C char * or
2551 STL string, that is the message to be displayed. There currently is
2552 no support for variable length arguments.
2557 @code{pass} prints a message for a successful test completion.
2560 @t{@b{TestState::pass}(@i{msg});}
2563 @code{fail} prints a message for an unsuccessful test completion.
2566 @t{@b{TestState::fail}(@i{msg});}
2569 @code{untested} prints a message for an test case that isn't run for
2573 @t{@b{TestState::untested}(@i{msg});}
2577 @code{unresolved} prints a message for an test case that is run, but
2578 there is no clear result. These output states require a human to look
2579 over the results to determine what happened.
2582 @t{@b{TestState::unresolved}(@i{msg});}
2586 @code{totals} prints out the total numbers of all the test state
2590 @t{@b{TestState::totals}(@i{});}
2595 @node Built-in Procedures, GNU Free Documentation License, Unit testing, Top
2596 @appendix Built-in Procedures
2598 DejaGnu provides these Tcl procedures.
2601 * Core Internal Procedures::
2602 * Procedures For Remote Communication::
2603 * Procedures For Using Utilities to Connect: connprocs.
2604 * Procedures For Target Boards::
2605 * Target Database Procedures: target database library file.
2606 * Platform Dependent Procedures: platform dependent procedures.
2607 * Utility Procedures::
2608 * Libgloss, a free board support package (BSP): Libgloss.
2609 * Debugging Procedures::
2612 @node Core Internal Procedures, Procedures For Remote Communication, , Built-in Procedures
2613 @section Core Internal Procedures
2616 * open_logs Procedure: open_logs procedure
2617 * close_logs Procedure: close_logs procedure
2618 * isbuild Procedure: isbuild procedure
2619 * isremote Procedure: isremote procedure
2620 * is_remote Procedure: is_remote procedure
2621 * is3way Procedure: is3way procedure
2622 * ishost Procedure: ishost procedure
2623 * istarget Procedure: istarget procedure
2624 * isnative Procedure: isnative procedure
2625 * log_and_exit Procedure: log_and_exit procedure
2626 * log_summary Procedure: log_summary procedure
2627 * setup_xfail Procedure: setup_xfail procedure
2628 * pass Procedure: pass procedure
2629 * fail Procedure: fail procedure
2630 * xpass Procedure: xpass procedure
2631 * xfail Procedure: xfail procedure
2632 * set_warning_threshold Procedure: set_warning_threshold procedure
2633 * get_warning_threshold Procedure: get_warning_threshold procedure
2634 * warning Procedure: warning procedure
2635 * perror Procedure: perror procedure
2636 * note Procedure: note procedure
2637 * untested Procedure: untested procedure
2638 * unresolved Procedure: unresolved procedure
2639 * unsupported Procedure: unsupported procedure
2640 * transform Procedure: transform procedure
2641 * check_conditional_xfail Procedure: check_conditional_xfail procedure
2642 * clear_xfail Procedure: clear_xfail procedure
2643 * verbose Procedure: verbose procedure
2644 * load_lib Procedure: load_lib procedure
2645 * testsuite Procedure: testsuite procedure
2646 * testcase procedure: testcase procedure
2649 @node open_logs procedure, close_logs procedure, , Core Internal Procedures
2650 @subsubheading open_logs Procedure
2653 Open the output logs.
2659 @node close_logs procedure, isbuild procedure, open_logs procedure, Core Internal Procedures
2660 @subsubheading close_logs Procedure
2663 Close the output logs.
2669 @node isbuild procedure, isremote procedure, close_logs procedure, Core Internal Procedures
2670 @subsubheading isbuild Procedure
2673 Tests for a particular build host environment. If the currently
2674 configured host matches the @code{pattern} argument, the result is
2675 @emph{1}; otherwise the result is @emph{0}. @emph{pattern} must be a
2676 full three-part configure triplet; in particular, you may not use the
2677 shorter aliases supported by @code{configure} (but you can use Tcl
2678 globbing to specify a range of triplets). If called with no arguments
2679 or an empty pattern, this procedure returns the build system triplet.
2682 @t{@b{isbuild} @i{pattern}}
2685 @node isremote procedure, is_remote procedure, isbuild procedure, Core Internal Procedures
2686 @subsubheading isremote Procedure
2689 Is @i{board} remote? Return a non-zero value, if so.
2692 @t{@b{isremote} @i{ board }}
2695 This procedure is to be used instead of @code{is_remote}.
2697 @node is_remote procedure, is3way procedure, isremote procedure, Core Internal Procedures
2698 @subsubheading is_remote Procedure
2701 Is @i{board} remote? Return a non-zero value, if so.
2704 @t{@b{is_remote} @i{ board }}
2707 Note that this procedure is now deprecated. Use @code{isremote}
2710 @node is3way procedure, ishost procedure, is_remote procedure, Core Internal Procedures
2711 @subsubheading is3way Procedure
2714 Tests for a Canadian cross. This is when the tests will be run on a
2715 remotely hosted cross-compiler. If it is a Canadian cross, then the
2716 result is @emph{1}; otherwise @emph{0}.
2722 @node ishost procedure, istarget procedure, is3way procedure, Core Internal Procedures
2723 @subsubheading ishost Procedure
2726 Tests for a particular host environment. If the currently configured
2727 host matches the argument string, the result is @emph{1}; otherwise
2728 the result is @emph{0}. @emph{pattern} must be a full three-part
2729 configure triplet; in particular, you may not use the shorter aliases
2730 supported by @code{configure} (but you can use Tcl globbing to specify
2731 a range of triplets). If called with no arguments or an empty
2732 pattern, this procedure returns the host triplet.
2735 @t{@b{ishost} @i{pattern}}
2738 @node istarget procedure, isnative procedure, ishost procedure, Core Internal Procedures
2739 @subsubheading istarget Procedure
2742 Tests for a particular target environment. If the currently
2743 configured target matches the argument string, the result is @emph{1}
2744 ; otherwise the result is @emph{0}. @emph{pattern} must be a full
2745 three-part configure triplet; in particular, you may not use the
2746 shorter aliases supported by @code{configure} (but you can use Tcl
2747 globbing to specify a range of triplets). If called with no arguments
2748 or an empty pattern, this procedure returns the target triplet.
2751 @t{@b{istarget} @i{pattern} }
2754 @node isnative procedure, log_and_exit procedure, istarget procedure, Core Internal Procedures
2755 @subsubheading isnative Procedure
2758 This procedure returns @emph{1} if the current configuration has the
2759 same host and target (ie. it is a native configuration). Otherwise it
2766 @node log_and_exit procedure, log_summary procedure, isnative procedure, Core Internal Procedures
2767 @subsubheading log_and_exit Procedure
2768 @findex log_and_exit
2771 @t{@b{log_and_exit}}
2774 This procedure writes out the end of the test log and terminates
2778 @node log_summary procedure, setup_xfail procedure, log_and_exit procedure, Core Internal Procedures
2779 @subsubheading log_summary Procedure
2783 @t{@b{log_summary} @i{args}}
2790 @node setup_xfail procedure, pass procedure, log_summary procedure, Core Internal Procedures
2791 @subsubheading setup_xfail Procedure
2794 Declares that the test is expected to fail on a particular set of
2795 configurations. The config argument must be a list of full three-part
2796 configure target name; in particular, you may not use the shorter
2797 nicknames supported by configure (but you can use the common shell
2798 wildcard characters to specify a range of triplets). The @emph{bugid}
2799 argument is optional, and used only in the logging file output; use it
2800 as a link to a bug-tracking system such as GNATS.
2802 Once you use @code{setup_xfail}, the @code{fail} and @code{pass}
2803 procedures produce the messages @emph{XFAIL} and @emph{XPASS}
2804 respectively, allowing you to distinguish expected failures (and
2805 unexpected success!) from other test outcomes.
2811 Warning you must clear the expected failure after using setup_xfail in
2812 a test case. Any call to @code{pass }or @code{fail} clears the
2813 expected failure implicitly; if the test has some other outcome,
2814 e.g. an error, you can call @code{clear_xfail} to clear the expected
2815 failure explicitly. Otherwise, the expected-failure declaration
2816 applies to whatever test runs next, leading to surprising results.
2820 @t{@b{setup_xfail} @i{config} @i{bugid}}
2825 The config triplet to trigger whether this is an unexpected or expect
2829 The optional bugid, used to tie this test case to a bug tracking
2833 @node pass procedure, fail procedure, setup_xfail procedure, Core Internal Procedures
2834 @subsubheading pass Procedure
2837 Declares a test to have passed. @code{pass} writes in the log files a
2838 message beginning with @emph{PASS} (or @emph{XPASS}, if failure was
2839 expected), appending the @code{message} argument.
2842 @t{@b{pass} @i{message} }
2845 @node fail procedure, xpass procedure, pass procedure, Core Internal Procedures
2846 @subsubheading fail Procedure
2849 Declares a test to have failed. @code{fail} writes in the log files a
2850 message beginning with @emph{FAIL} (or @emph{XFAIL}, if failure was
2851 expected), appending the @code{message} argument.
2854 @t{@b{fail} @i{message} }
2857 @node xpass procedure, xfail procedure, fail procedure, Core Internal Procedures
2858 @subsubheading xpass Procedure
2861 Declares a test to have passed when it was expected to fail.
2862 @code{xpass} writes in the log files a message beginning with
2863 @emph{XPASS} (or @emph{XFAIL} if failure was expected) and the
2864 @code{message} argument.
2867 @t{@b{xpass} @i{message} }
2870 @node xfail procedure, set_warning_threshold procedure, xpass procedure, Core Internal Procedures
2871 @subsubheading xfail Procedure
2874 Declares a test to have expectedly failed. @code{xfail} writes in the
2875 log files a message beginning with @emph{XFAIL} (or @emph{PASS}, if
2876 success was expected), appending the @code{message} argument.
2879 @t{@b{xpass} @i{message} }
2882 @node set_warning_threshold procedure, get_warning_threshold procedure, xfail procedure, Core Internal Procedures
2883 @subsubheading set_warning_threshold Procedure
2884 @findex set_warning_threshold
2886 Sets the value of @code{warning_threshold}. A value of @emph{0}
2887 disables it: calls to @code{warning} will not turn a @emph{PASS} or
2888 @emph{FAIL} into an @emph{UNRESOLVED}.
2891 @t{@b{set_warning_threshold} @i{threshold}}
2896 @item @code{threshold}
2897 This is the value of the new warning threshold.
2900 @node get_warning_threshold procedure, warning procedure, set_warning_threshold procedure, Core Internal Procedures
2901 @subsubheading get_warning_threshold Procedure
2902 @findex get_warning_threshold
2904 Returns the current value of @code{@{warning_threshold}. The default
2905 value is 3. This value controls how many @code{warning} procedures
2906 can be called before becoming @emph{UNRESOLVED}.
2909 @t{@b{get_warning_threshold}}
2912 @node warning procedure, perror procedure, get_warning_threshold procedure, Core Internal Procedures
2913 @subsubheading warning Procedure
2916 Declares detection of a minor error in the test case itself.
2917 @code{warning} writes in the log files a message beginning with
2918 @emph{WARNING}, appending the argument @code{string}. Use
2919 @code{warning} rather than @code{perror} for cases (such as
2920 communication failure to be followed by a retry) where the test case
2921 can recover from the error. If the optional @code{number} is
2922 supplied, then this is used to set the internal count of warnings to
2925 As a side effect, @code{warning_threshold} or more calls to warning in
2926 a single test case also changes the effect of the next @code{pass} or
2927 @code{fail} command: the test outcome becomes @emph{UNRESOLVED} since
2928 an automatic @emph{PASS} or @emph{FAIL} may not be trustworthy after
2929 many warnings. If the optional numeric value is @emph{0}, then there
2930 are no further side effects to calling this function, and the
2931 following test outcome doesn't become @emph{UNRESOLVED}. This can be
2932 used for errors with no known side effects.
2935 @t{@b{warning} @i{messsage} @i{number} }
2940 @item @code{message}
2941 The warning message.
2944 The optional number to set the error counter. This is only used to
2945 fake out the counter when using the @code{xfail} procedure to control
2946 when it flips the output over to @emph{UNRESOLVED} state.
2949 @node perror procedure, note procedure, warning procedure, Core Internal Procedures
2950 @subsubheading perror Procedure
2953 Declares a severe error in the testing framework itself.
2954 @code{perror} writes in the log files a message beginning with
2955 @emph{ERROR}, appending the argument @code{string}.
2957 As a side effect, perror also changes the effect of the next
2958 @code{pass} or @code{fail} command: the test outcome becomes
2959 @emph{UNRESOLVED}, since an automatic @emph{PASS} or @emph{FAIL}
2960 cannot be trusted after a severe error in the test framework. If the
2961 optional numeric value is @emph{0}, then there are no further side
2962 effects to calling this function, and the following test outcome
2963 doesn't become @emph{UNRESOLVED}. This can be used for errors with no
2967 @t{@b{perror} @i{message} @i{number} }
2971 @item @code{message}
2972 The message to be logged.
2975 The optional number to set the error counter. This is only used to
2976 fake out the counter when using the @code{xfail} procedure to control
2977 when it flips the output over to @emph{UNRESOLVED} state.
2980 @node note procedure, untested procedure, perror procedure, Core Internal Procedures
2981 @subsubheading note Procedure
2984 Appends an informational message to the log file. @code{note} writes
2985 in the log files a message beginning with @emph{NOTE}, appending the
2986 @code{message} argument. Use @code{note} sparingly. The
2987 @code{verbose} should be used for most such messages, but in cases
2988 where a message is needed in the log file regardless of the verbosity
2989 level use @code{note}.
2992 @t{@b{note} @i{messsage} }
2996 @node untested procedure, unresolved procedure, note procedure, Core Internal Procedures
2997 @subsubheading untested Procedure
3000 Declares a test was not run. @code{untested} writes in the log file a
3001 message beginning with @emph{UNTESTED}, appending the @code{message}
3002 argument. For example, you might use this in a dummy test whose only
3003 role is to record that a test does not yet exist for some feature.
3006 @t{@b{untested} @i{message} }
3010 @node unresolved procedure, unsupported procedure, untested procedure, Core Internal Procedures
3011 @subsubheading unresolved Procedure
3014 Declares a test to have an unresolved outcome. @code{unresolved}
3015 writes in the log file a message beginning with @emph{UNRESOLVED},
3016 appending the @code{message} argument. This usually means the test
3017 did not execute as expected, and a human being must go over results to
3018 determine if it passed or failed (and to improve the test case).
3021 @t{@b{unresolved} @i{message} }
3025 @node unsupported procedure, transform procedure, unresolved procedure, Core Internal Procedures
3026 @subsubheading unsupported Procedure
3029 Declares that a test case depends on some facility that does not exist
3030 in the testing environment. @code{unsupported} writes in the log file
3031 a message beginning with @emph{UNSUPPORTED}, appending the
3032 @code{message} argument.
3035 @t{@b{unsupported} @i{message} }
3039 @node transform procedure, check_conditional_xfail procedure, unsupported procedure, Core Internal Procedures
3040 @subsubheading transform Procedure
3043 Generates a string for the name of a tool as it was configured and
3044 installed, given its native name (as the argument @code{toolname}).
3045 This makes the assumption that all tools are installed using the same
3046 naming conventions: For example, for a cross compiler supporting the
3047 @emph{m68k-vxworks} configuration, the result of transform @code{gcc}
3048 is @code{m68k-vxworks-gcc}.
3051 @t{@b{transform} @i{toolname}}
3056 @item @code{toolname}
3057 The name of the cross-development program to transform.
3060 @node check_conditional_xfail procedure, clear_xfail procedure, transform procedure, Core Internal Procedures
3061 @subsubheading check_conditional_xfail Procedure
3062 @findex check_conditional_xfail
3064 This procedure adds a conditional xfail, based on compiler options
3065 used to create a test case executable. If an include options is found
3066 in the compiler flags, and it's the right architecture, it'll trigger
3067 an @emph{XFAIL}. Otherwise it'll produce an ordinary @emph{FAIL}.
3068 You can also specify flags to exclude. This makes a result be a
3069 @emph{FAIL}, even if the included options are found. To set the
3070 conditional, set the variable @code{compiler_conditional_xfail_data}
3074 "[message string] [targets list] [includes list] [excludes list]"
3077 (descriptions below). This is the checked at pass/fail decision time,
3078 so there is no need to call the procedure yourself, unless you wish to
3079 know if it gets triggered. After a pass/fail, the variable is reset,
3080 so it doesn't effect other tests. It returns @emph{1} if the
3081 conditional is true, or @emph{0} if the conditional is false.
3084 @t{@b{check_conditional_xfail} @i{message} @i{targets} @i{includes}
3090 @item @code{message}
3091 This is the message to print with the normal test result.
3093 @item @code{targets}
3094 This is a string with the list targets to activate this conditional
3097 @item @code{includes}
3098 This is a list of sets of options to search for in the compiler
3099 options to activate this conditional. If the list of sets of options
3100 is empty or if any set of the options matches, then this conditional
3101 is true. (It may be useful to specify an empty list of include sets
3102 if the conditional is always true unless one of the exclude sets
3105 @item @code{excludes}
3106 This is a list of sets of options to search for in the compiler
3107 options to activate this conditional. If any set of the options
3108 matches, (regardless of whether any of the include sets match) then
3109 this conditional is de-activated.
3112 @strong{Specifying the conditional xfail data}
3115 set compiler_conditional_xfail_data @{ \
3116 "I sure wish I knew why this was hosed" \
3117 "sparc*-sun*-* *-pc-*-*" \
3118 @{"-Wall -v" "-O3"@} \
3123 What this does is it matches only for these two targets if @code{-Wall
3124 -v} or @code{-O3} is set, but neither @code{-O1} or @code{-Map} is
3125 set. For a set to match, the options specified are searched for
3126 independently of each other, so a @code{-Wall -v} matches either
3127 @code{-Wall -v} or @code{-v -Wall}. A space separates the options in
3128 the string. Glob patterns are also permitted.
3130 @node clear_xfail procedure, verbose procedure, check_conditional_xfail procedure, Core Internal Procedures
3131 @subsubheading clear_xfail Procedure
3134 Cancel an expected failure (previously declared with
3135 @code{setup_xfail}) for a particular set of configurations. The
3136 @code{config} argument is a list of configuration target names. It is
3137 only necessary to call @code{clear_xfail} if a test case ends without
3138 calling either @code{pass} or @code{fail}, after calling
3142 @t{@b{clear_xfail} @i{config}}
3148 The system triplets to clear.
3151 @node verbose procedure, load_lib procedure, clear_xfail procedure, Core Internal Procedures
3152 @subsubheading verbose Procedure
3155 Test cases can use this procedure to issue helpful messages depending
3156 on the number of @code{-v}/@code{--verbose} options passed on the
3157 command line to @code{runtest}. It prints @i{message} if the value of
3158 the number of @code{-v} options passed is greater than or equal to the
3159 @i{loglevel} argument. The default log level is 1.
3173 Always write @i{message} to the log file, even if it won't be printed
3177 Log the @i{message} into an XML file.
3180 Print @i{message} without a trailing newline.
3183 Use this option if @i{message} begins with @samp{-}.
3185 @item @code{message}
3188 @item @code{loglevel}
3189 The specified log level. The default level is 1.
3192 @node load_lib procedure, testsuite procedure, verbose procedure, Core Internal Procedures
3193 @subsubheading load_lib Procedure
3196 @code{load_lib} loads a DejaGnu library file by searching the default
3197 fixed paths built into DejaGnu. If DejaGnu has been installed, it
3198 looks in a path starting with the installed library directory. If you
3199 are running DejaGnu directly from a source directory, without first
3200 running @code{make install}, this path defaults to the current
3201 directory. In either case, it then looks in the current directory for
3202 a directory called @file{lib}. If there are duplicate definitions,
3203 the last one loaded takes precedence over the earlier ones.
3206 @t{@b{load_lib} @i{filespec}}
3211 @item @code{filespec}
3212 The name of the DejaGnu library file to load.
3215 The global variable @code{libdirs}, handled as a list, is appended to
3216 the default fixed paths built into DejaGnu.
3218 @strong{Additional search directories for load_lib}
3221 # append a non-standard search path
3223 lappend libdirs $srcdir/../../gcc/testsuite/lib
3224 # now loading $srcdir/../../gcc/testsuite/lib/foo.exp works
3228 @node testsuite procedure, testcase procedure, load_lib procedure, Core Internal Procedures
3229 @subsubheading testsuite Procedure
3232 The @code{testsuite} procedure is a multiplex call for retrieving or
3233 providing information about the current testsuite.
3235 @subsubheading testsuite file
3237 The @code{testsuite file} command returns an absolute file name
3238 specified relative to either the testsuite source or object trees.
3241 @t{ @b{testsuite file}
3242 ?@b{-source}|@b{-object}?
3245 ?@b{--}? @i{name}... }
3248 Any number of @i{name}s are accepted and combined as if by @code{file
3249 join} with a directory relevant to the testsuite prepended.
3253 @item @code{-object}
3254 Return a file name in the object tree.
3256 @item @code{-source}
3257 Return a file name in the source tree.
3260 Prepend the @code{testsuite} directory itself.
3263 Prepend the directory containing the current test script.
3265 @item @code{-hypothetical}
3266 Allow the returned value to imply directories that do not exist.
3269 Use this option if the first @i{name} could begin with @samp{-}.
3273 One of @code{-top} or @code{-test} must be given; an error is raised
3276 Unless the @code{-hypothetical} option is given, any directories
3277 implied by the returned value will exist upon return. Implied
3278 directories are created in the object tree if needed. An error is
3279 raised if an implied directory does not exist in the source tree.
3281 @subsubheading testsuite can call api
3283 The @code{testsuite can call api} command is a feature test and
3284 returns a boolean value indicating if a subcommand under a multiplex
3285 point is available. This API call is needed because only the
3286 multiplex points themselves are visible to the Tcl info command.
3289 @t{ @b{testsuite can call api} @i{feature}... }
3292 Any number of words are joined together into a single name, beginning
3293 with a multiplex entry point and forming the full name of an API call
3294 as documented in this manual.
3296 @node testcase procedure, , testsuite procedure, Core Internal Procedures
3297 @subsubheading testcase Procedure
3299 The @code{testcase} procedure is a multiplex call for retrieving or
3300 providing information about the state of the testing process.
3302 @subsubheading testcase group
3304 The @code{testcase group} command provides support for grouping tests
3305 into hierarchical groups within a test script.
3307 Group names are internally tracked as Tcl lists, but are reported as
3308 strings delimited using forward slash (@samp{/}) characters.
3309 Individual name elements may not contain whitespace, but may contain
3310 forward slash. A group entered by traversing intermediate levels must
3311 be left by traversing those same levels. Groups must properly nest.
3313 There are three uses:
3316 @t{ @b{testcase group}}
3319 Return the current group as a string delimited with forward slash
3320 (@samp{/}) characters.
3323 @t{ @b{testcase group begin} @i{name}}
3326 @t{ @b{testcase group end} @i{name}}
3329 These forms allow a group to be explicitly entered and left. The
3330 @i{name} parameter must be identical across a pair of these calls, and
3331 both the @code{begin} and @code{end} calls must be in the same file.
3334 @t{ @b{testcase group eval} @i{name} @{@i{code}@}}
3337 This form is available to wrap the @code{begin} and @code{end} calls
3338 around the execution of the provided @i{code}. This form is preferred
3339 for convenience in top-level scripts, but the @code{begin} and
3340 @code{end} calls are preferred in helper procedures for performance.
3342 @node Procedures For Remote Communication, connprocs, Core Internal Procedures, Built-in Procedures
3343 @section Procedures For Remote Communication
3345 The file @file{lib/remote.exp} defines procedures for establishing and
3346 managing communications. Each of these procedures tries to establish
3347 the connection up to three times before returning. Warnings (if
3348 retries will continue) or errors (if the attempt is abandoned) report
3349 on communication failures. The result for any of these procedures is
3350 either @emph{-1}, when the connection cannot be established, or the
3351 spawn ID returned by the Expect command @code{spawn}.
3353 It use the value of the @code{connect} field in the @code{target_info}
3354 array as the type of connection to make. Current supported connection
3355 types are ssh, tip, kermit, telnet, rsh, and rlogin. If the
3356 @code{--reboot} option was used on the @command{runtest} command line,
3357 then the target is rebooted before the connection is made.
3360 * call_remote Procedure: call_remote procedure
3361 * check_for_board_status Procedure: check_for_board_status procedure
3362 * file_on_build Procedure: file_on_build procedure
3363 * file_on_host Procedure: file_on_host procedure
3364 * local_exec Procedure: local_exec procedure
3365 * remote_binary Procedure: remote_binary procedure
3366 * remote_close Procedure: remote_close procedure
3367 * remote_download Procedure: remote_download procedure
3368 * remote_exec Procedure: remote_exec procedure
3369 * remote_expect Procedure: remote_expect procedure
3370 * remote_file Procedure: remote_file procedure
3371 * remote_ld Procedure: remote_ld procedure
3372 * remote_load Procedure: remote_load procedure
3373 * remote_open Procedure: remote_open procedure
3374 * remote_pop_conn Procedure: remote_pop_conn procedure
3375 * remote_push_conn Procedure: remote_push_conn procedure
3376 * remote_raw_binary Procedure: remote_raw_binary procedure
3377 * remote_raw_close Procedure: remote_raw_close procedure
3378 * remote_raw_file Procedure: remote_raw_file procedure
3379 * remote_raw_ld Procedure: remote_raw_ld procedure
3380 * remote_raw_load Procedure: remote_raw_load procedure
3381 * remote_raw_open Procedure: remote_raw_open procedure
3382 * remote_raw_send Procedure: remote_raw_send procedure
3383 * remote_raw_spawn Procedure: remote_raw_spawn procedure
3384 * remote_raw_transmit Procedure: remote_raw_transmit procedure
3385 * remote_raw_wait Procedure: remote_raw_wait procedure
3386 * remote_reboot Procedure: remote_reboot procedure
3387 * remote_send Procedure: remote_send procedure
3388 * remote_spawn Procedure: remote_spawn procedure
3389 * remote_swap_conn Procedure: remote_swap_conn procedure
3390 * remote_transmit Procedure: remote_transmit procedure
3391 * remote_upload Procedure: remote_upload procedure
3392 * remote_wait Procedure: remote_wait procedure
3393 * standard_close Procedure: standard_close procedure
3394 * standard_download Procedure: standard_download procedure
3395 * standard_exec Procedure: standard_exec procedure
3396 * standard_file Procedure: standard_file procedure
3397 * standard_load Procedure: standard_load procedure
3398 * standard_reboot Procedure: standard_reboot procedure
3399 * standard_send Procedure: standard_send procedure
3400 * standard_spawn Procedure: standard_spawn procedure
3401 * standard_transmit Procedure: standard_transmit procedure
3402 * standard_upload Procedure: standard_upload procedure
3403 * standard_wait Procedure: standard_wait procedure
3404 * unix_clean_filename Procedure: unix_clean_filename procedure
3407 @node call_remote procedure, check_for_board_status procedure, , Procedures For Remote Communication
3408 @subsubheading call_remote Procedure
3411 A standard procedure to call the appropriate @i{proc}. This proceure
3412 first looks for a board-specific version, then a protocol-specific
3413 version, and finally @code{call_remote} will call
3414 @code{standard_$proc}.
3417 @t{@b{call_remote} @i{type} @i{proc} @i{dest} @i{args}}
3426 @node check_for_board_status procedure, file_on_build procedure, call_remote procedure, Procedures For Remote Communication
3427 @subsubheading check_for_board_status Procedure
3428 @findex check_for_board_status
3430 This procedure inspected the named variable within the calling
3431 procedure for the expected output from the status wrapper. A
3432 non-negative value is returned if it exists. Otherwise, it returns
3433 -1. The output from the status wrapper is removed from the variable.
3436 @t{@b{check_for_board_status} @i{variable}}
3440 @item @code{variable}
3441 The name of the variable to check in the calling procedure. Be sure
3442 to pass the name of the variable (@code{var}) and not the value of the
3443 variable (@code{$var}).
3446 @node file_on_build procedure, file_on_host procedure, check_for_board_status procedure, Procedures For Remote Communication
3447 @subsubheading file_on_build Procedure
3448 @findex file_on_build
3451 @t{@b{file_on_build} @i{op} @i{file} @i{args}}
3460 @node file_on_host procedure, local_exec procedure, file_on_build procedure, Procedures For Remote Communication
3461 @subsubheading file_on_host Procedure
3462 @findex file_on_host
3465 @t{@b{file_on_host} @i{op} @i{file} @i{args}}
3474 @node local_exec procedure, remote_binary procedure, file_on_host procedure, Procedures For Remote Communication
3475 @subsubheading local_exec Procedure
3478 Run the specified command on the local machine, redirecting input from
3479 file @code{inp} (if non-empty), redirecting output to file @code{outp}
3480 (if non-empty), and waiting @code{timeout} seconds for the command to
3481 complete before killing it. A two-element list is returned: the exit
3482 status of the command and any output produced by the command. If
3483 output is redirected, this may or may not be empty. If output is
3484 redirected, both stdout and stderr will appear in the specified file.
3487 @t{@b{local_exec} @i{commandline} @i{inp} @i{outp} @i{timeout}}
3492 Redirect input into the input filename if not set to @code{""}.
3495 Redirect output into the output filename if not set to @code{""}.
3497 @item @code{timeout}
3502 @node remote_binary procedure, remote_close procedure, local_exec procedure, Procedures For Remote Communication
3503 @subsubheading remote_binary Procedure
3504 @findex remote_binary
3506 This procedure sets the connection into @i{binary} mode. That is,
3507 there is no processing of input characters.
3510 @t{@b{remote_binary} @i{host}}
3515 The host on which to set a binary connection.
3518 @node remote_close procedure, remote_download procedure, remote_binary procedure, Procedures For Remote Communication
3519 @subsubheading remote_close Procedure
3520 @findex remote_close
3523 @t{@b{remote_close} @i{shellid}}
3528 @item @code{shellid}
3529 This is the value returned by a call to @code{remote_open}. This
3530 closes the connection to the target so resources can be used by
3531 others. This parameter can be left off if the @code{fileid} field in
3532 the @code{target_info} array is set.
3535 @node remote_download procedure, remote_exec procedure, remote_close procedure, Procedures For Remote Communication
3536 @subsubheading remote_download Procedure
3537 @findex remote_download
3539 Download a file to a destination machine. This procedure returns
3540 either an empty string (indicating failure) or the name of the file on
3541 the destination macine.
3544 @t{@b{remote_download} @i{dest} @i{file} @i{args}}
3549 Destination machine name.
3555 If the optional destination filename is specified, that filename will
3556 be used on the destination machine.
3559 @node remote_exec procedure, remote_expect procedure, remote_download procedure, Procedures For Remote Communication
3560 @subsubheading remote_exec Procedure
3563 Execute the supplied program on a remote host. A two-element list is
3564 returned. The first element is the exit status of the program or -1
3565 if execution failed. The second element is any output produced by the
3566 program. This may be an empty string if output from the program was
3570 @t{ @b{remote_exec} @i{hostname} @i{program}
3571 ?@i{options}? ?@i{input}? ?@i{output}? ?@i{timeout}?}
3575 @item @code{hostname}
3576 Name of the host to execute the command on.
3578 @item @code{program}
3581 @item @code{options}
3582 Arguments to pass to the program.
3585 Input filename to feed to standard input of the command.
3588 Output filename where the output from the command should be written.
3590 @item @code{timeout}
3591 Timeout value in seconds.
3595 All of the optional positional arguments accept an empty string as a
3598 @node remote_expect procedure, remote_file procedure, remote_exec procedure, Procedures For Remote Communication
3599 @subsubheading remote_expect Procedure
3600 @findex remote_expect
3603 @t{@b{remote_expect} @i{board} @i{timeout} @i{args}}
3608 @item @code{timeout}
3612 @node remote_file procedure, remote_ld procedure, remote_expect procedure, Procedures For Remote Communication
3613 @subsubheading remote_file Procedure
3617 @t{@b{remote_file} @i{dest} @i{args}}
3627 @node remote_ld procedure, remote_load procedure, remote_file procedure, Procedures For Remote Communication
3628 @subsubheading remote_ld Procedure
3632 @t{@b{remote_ld} @i{dest} @i{prog}}
3640 @node remote_load procedure, remote_open procedure, remote_ld procedure, Procedures For Remote Communication
3641 @subsubheading remote_load Procedure
3645 @t{@b{remote_load} @i{dest} @i{prog} @i{args}}
3654 @node remote_open procedure, remote_pop_conn procedure, remote_load procedure, Procedures For Remote Communication
3655 @subsubheading remote_open Procedure
3658 Open connection to a remote host or target. This requires the
3659 @code{target_info} array be filled in with the proper information to
3660 work. It returns the spawn id of the process that is the connection.
3663 @t{@b{remote_open} @i{type}}
3668 This is passed @code{host} or @code{target}. Host or target refers to
3669 whether it is a connection to a remote target, or a remote host. This
3670 opens the connection to the desired target or host using the default
3671 values in the configuration system. It returns that @code{spawn_id}
3672 of the process that manages the connection. This value can be used in
3673 Expect or @code{exp_send} statements, or passed to other procedures
3674 that need the connection process's id. This also sets the
3675 @code{fileid} field in the @code{target_info} array.
3678 @node remote_pop_conn procedure, remote_push_conn procedure, remote_open procedure, Procedures For Remote Communication
3679 @subsubheading remote_pop_conn Procedure
3680 @findex remote_pop_conn
3682 Pop a previously-pushed connection from the stack. You should have
3683 closed the current connection before calling this procedure. Returns
3684 @code{pass} or @code{fail}.
3687 @t{@b{remote_pop_conn} @i{host}}
3694 @node remote_push_conn procedure, remote_raw_binary procedure, remote_pop_conn procedure, Procedures For Remote Communication
3695 @subsubheading remote_push_conn Procedure
3696 @findex remote_push_conn
3698 Pushes the current connection onto a stack. Returns @code{pass} or
3702 @t{@b{remote_push_conn} @i{host}}
3709 @node remote_raw_binary procedure, remote_raw_close procedure, remote_push_conn procedure, Procedures For Remote Communication
3710 @subsubheading remote_raw_binary Procedure
3711 @findex remote_raw_binary
3714 @t{@b{remote_raw_binary} @i{host}}
3721 @node remote_raw_close procedure, remote_raw_file procedure, remote_raw_binary procedure, Procedures For Remote Communication
3722 @subsubheading remote_raw_close Procedure
3723 @findex remote_raw_close
3726 @t{@b{remote_raw_close} @i{host}}
3733 @node remote_raw_file procedure, remote_raw_ld procedure, remote_raw_close procedure, Procedures For Remote Communication
3734 @subsubheading remote_raw_file Procedure
3735 @findex remote_raw_file
3738 @t{@b{remote_raw_file} @i{dest} @i{args}}
3747 @node remote_raw_ld procedure, remote_raw_load procedure, remote_raw_file procedure, Procedures For Remote Communication
3748 @subsubheading remote_raw_ld Procedure
3749 @findex remote_raw_ld
3752 @t{@b{remote_raw_ld} @i{dest} @i{prog}}
3760 @node remote_raw_load procedure, remote_raw_open procedure, remote_raw_ld procedure, Procedures For Remote Communication
3761 @subsubheading remote_raw_load Procedure
3762 @findex remote_raw_load
3765 @t{@b{remote_raw_load} @i{dest} @i{prog} @i{args}}
3774 @node remote_raw_open procedure, remote_raw_send procedure, remote_raw_load procedure, Procedures For Remote Communication
3775 @subsubheading remote_raw_open Procedure
3776 @findex remote_raw_open
3779 @t{@b{remote_raw_open} @i{args}}
3786 @node remote_raw_send procedure, remote_raw_spawn procedure, remote_raw_open procedure, Procedures For Remote Communication
3787 @subsubheading remote_raw_send Procedure
3788 @findex remote_raw_send
3792 @t{@b{remote_raw_send} @i{dest} @i{string}}
3800 @node remote_raw_spawn procedure, remote_raw_transmit procedure, remote_raw_send procedure, Procedures For Remote Communication
3801 @subsubheading remote_raw_spawn Procedure
3802 @findex remote_raw_spawn
3805 @t{@b{remote_raw_spawn} @i{dest} @i{commandline}}
3810 @item @code{commandline}
3813 @node remote_raw_transmit procedure, remote_raw_wait procedure, remote_raw_spawn procedure, Procedures For Remote Communication
3814 @subsubheading remote_raw_transmit Procedure
3815 @findex remote_raw_transmit
3818 @t{@b{remote_raw_transmit} @i{dest} @i{file}}
3826 @node remote_raw_wait procedure, remote_reboot procedure, remote_raw_transmit procedure, Procedures For Remote Communication
3827 @subsubheading remote_raw_wait Procedure
3828 @findex remote_raw_wait
3831 @t{@b{remote_raw_wait} @i{dest} @i{timeout}}
3836 @item @code{timeout}
3839 @node remote_reboot procedure, remote_send procedure, remote_raw_wait procedure, Procedures For Remote Communication
3840 @subsubheading remote_reboot Procedure
3841 @findex remote_reboot
3843 Reboot the host. The return value of this procedure depends on the
3844 actual implementation of reboot that will be used, in practice it is
3845 expected that @code{remote_reboot} returns @b{1} on success and @b{0}
3849 @t{@b{remote_reboot} @i{host}}
3856 @node remote_send procedure, remote_spawn procedure, remote_reboot procedure, Procedures For Remote Communication
3857 @subsubheading remote_send Procedure
3861 @t{@b{remote_send} @i{dest} @i{string}}
3869 @node remote_spawn procedure, remote_swap_conn procedure, remote_send procedure, Procedures For Remote Communication
3870 @subsubheading remote_spawn Procedure
3871 @findex remote_spawn
3873 Start a command on the destination. By default it is not possible to
3874 redirect I/O. If the command is successfully started, a positive
3875 spawn ID is returned. If the spawn fails, a negative value will be
3876 returned. Once the command has started, you can interact with it
3877 using @code{remote_expect} and @code{remote_wait} procedures.
3880 @t{@b{remote_spawn} @i{dest} @i{commandline} @i{args}}
3887 @item @code{commandline}
3888 The command to execute.
3891 If the optional keyword @code{readonly} is specified, input to the
3892 command may be redirected.
3895 @node remote_swap_conn procedure, remote_transmit procedure, remote_spawn procedure, Procedures For Remote Communication
3896 @subsubheading remote_swap_conn Procedure
3897 @findex remote_swap_conn
3899 Swap the current connection with the topmost one on the stack.
3900 Returns @code{pass} or @code{fail}.
3903 @t{@b{remote_swap_conn} @i{host}}
3910 @node remote_transmit procedure, remote_upload procedure, remote_swap_conn procedure, Procedures For Remote Communication
3911 @subsubheading remote_transmit Procedure
3912 @findex remote_transmit
3915 @t{@b{remote_transmit} @i{dest} @i{file}}
3923 @node remote_upload procedure, remote_wait procedure, remote_transmit procedure, Procedures For Remote Communication
3924 @subsubheading remote_upload Procedure
3925 @findex remote_upload
3928 @t{@b{remote_upload} @i{dest} @i{srcfile} @i{arg}}
3933 @item @code{srcfile}
3937 @node remote_wait procedure, standard_close procedure, remote_upload procedure, Procedures For Remote Communication
3938 @subsubheading remote_wait Procedure
3941 Wait for the last spawned command on the destination to complete. A
3942 list of two values is returned: the exit status (-1 if the program
3943 timed out) and any output produced by the command.
3946 @t{@b{remote_wait} @i{dest} @i{timeout}}
3951 The destination board.
3953 @item @code{timeout}
3954 The timeout in seconds.
3957 @node standard_close procedure, standard_download procedure, remote_wait procedure, Procedures For Remote Communication
3958 @subsubheading standard_close Procedure
3959 @findex standard_close
3961 This procedure closes a connection.
3964 @t{@b{standard_close} @i{host}}
3969 The host to close the connection to.
3972 @node standard_download procedure, standard_exec procedure, standard_close procedure, Procedures For Remote Communication
3973 @subsubheading standard_download Procedure
3974 @findex standard_download
3976 Downloads a file to a destination. It returns either the empty string
3977 (indicating failure) or the name of the file on the destination.
3980 @t{@b{standard_download} @i{dest} @i{file} @i{destfile}}
3988 The name of the file to download.
3990 @item @code{destfile}
3991 If the optional @i{destile} is specified, that filename will be used
3992 on the destination board.
3995 @node standard_exec procedure, standard_file procedure, standard_download procedure, Procedures For Remote Communication
3996 @subsubheading standard_exec Procedure
3997 @findex standard_exec
4000 @t{@b{standard_exec} @i{hostname} @i{args}}
4004 @item @code{hostname}
4008 @node standard_file procedure, standard_load procedure, standard_exec procedure, Procedures For Remote Communication
4009 @subsubheading standard_file Procedure
4010 @findex standard_file
4013 @t{@b{standard_file} @i{dest} @i{op} @i{args}}
4020 @node standard_load procedure, standard_reboot procedure, standard_file procedure, Procedures For Remote Communication
4021 @subsubheading standard_load Procedure
4022 @findex standard_load
4025 @t{@b{standard_load} @i{dest} @i{prog} @i{args}}
4034 @node standard_reboot procedure, standard_send procedure, standard_load procedure, Procedures For Remote Communication
4035 @subsubheading standard_reboot Procedure
4036 @findex standard_reboot
4038 It looks like that this procedure is never called, instead
4039 @code{$@{board@}_reboot} defined in @file{base-config.exp} will be
4040 used because it has higher priority and @file{base-config.exp} is
4041 always imported by @code{runtest}.
4044 @t{@b{standard_reboot} @i{host}}
4051 @node standard_send procedure, standard_spawn procedure, standard_reboot procedure, Procedures For Remote Communication
4052 @subsubheading standard_send Procedure
4053 @findex standard_send
4056 @t{@b{standard_send} @i{dest} @i{string}}
4064 @node standard_spawn procedure, standard_transmit procedure, standard_send procedure, Procedures For Remote Communication
4065 @subsubheading standard_spawn Procedure
4066 @findex standard_spawn
4069 @t{@b{standard_spawn} @i{dest} @i{commandline}}
4074 @item @code{commandline}
4077 @node standard_transmit procedure, standard_upload procedure, standard_spawn procedure, Procedures For Remote Communication
4078 @subsubheading standard_transmit Procedure
4079 @findex standard_transmit
4081 The default transmit procedure if none other exists. This feeds the
4082 file directly into the connection.
4085 @t{@b{standard_transmit} @i{dest} @i{file}}
4095 @node standard_upload procedure, standard_wait procedure, standard_transmit procedure, Procedures For Remote Communication
4096 @subsubheading standard_upload Procedure
4097 @findex standard_upload
4100 @t{@b{standard_upload} @i{dest srcfile destfile}}
4105 @item @code{srcfile}
4106 @item @code{destfile}
4109 @node standard_wait procedure, unix_clean_filename procedure, standard_upload procedure, Procedures For Remote Communication
4110 @subsubheading standard_wait Procedure
4111 @findex standard_wait
4114 @t{@b{standard_wait} @i{dest} @i{timeout}}
4119 @item @code{timeout}
4122 @node unix_clean_filename procedure, , standard_wait procedure, Procedures For Remote Communication
4123 @subsubheading unix_clean_filename Procedure
4124 @findex unix_clean_filename
4126 This procedure returns an absolute version of the filename argument
4127 with @samp{.} and @samp{..} removed.
4130 @t{@b{unix_clean_filename} @i{dest} @i{file}}
4139 @node connprocs, Procedures For Target Boards, Procedures For Remote Communication, Built-in Procedures
4140 @section Procedures For Using Utilities to Connect
4143 * kermit_open Procedure: kermit_open procedure
4144 * kermit_command Procedure: kermit_command procedure
4145 * kermit_send Procedure: kermit_send procedure
4146 * kermit_transmit Procedure: kermit_transmit procedure
4147 * telnet_open Procedure: telnet_open procedure
4148 * telnet_binary Procedure: telnet_binary procedure
4149 * tip_open Procedure: tip_open procedure
4150 * rlogin_open Procedure: rlogin_open procedure
4151 * rlogin_spawn Procedure: rlogin_spawn procedure
4152 * rsh_open Procedure: rsh_open procedure
4153 * rsh_download Procedure: rsh_download procedure
4154 * rsh_upload Procedure: rsh_upload procedure
4155 * rsh_exec Procedure: rsh_exec procedure
4156 * ssh_close Procedure: ssh_close procedure
4157 * ssh_exec Procedure: ssh_exec procedure
4158 * ssh_download Procedure: ssh_download procedure
4159 * ssh_upload Procedure: ssh_upload procedure
4160 * ftp_open Procedure: ftp_open procedure
4161 * ftp_upload Procedure: ftp_upload procedure
4162 * ftp_download Procedure: ftp_download procedure
4163 * ftp_close Procedure: ftp_close procedure
4164 * tip_download Procedure: tip_download procedure
4167 @node kermit_open procedure, kermit_command procedure, connprocs, connprocs
4168 @subsubheading kermit_open Procedure
4172 @t{@b{kermit_open} @i{dest} @i{args}}
4180 @node kermit_command procedure, kermit_send procedure, kermit_open procedure, connprocs
4181 @subsubheading kermit_command Procedure
4182 @findex kermit_command
4185 @t{@b{kermit_command} @i{dest} @i{args}}
4193 @node kermit_send procedure, kermit_transmit procedure, kermit_command procedure, connprocs
4194 @subsubheading kermit_send Procedure
4198 @t{@b{kermit_send} @i{dest string args}}
4207 @node kermit_transmit procedure, telnet_open procedure, kermit_send procedure, connprocs
4208 @subsubheading kermit_transmit Procedure
4209 @findex kermit_transmit
4212 @t{@b{kermit_transmit} @i{dest} @i{file} @i{args}}
4221 @node telnet_open procedure, telnet_binary procedure, kermit_transmit procedure, connprocs
4222 @subsubheading telnet_open Procedure
4225 This procedure opens a connection to a remote host using TELNET. This
4226 procedure sets the @code{fileid} field in the @code{board_info} array
4227 and returns the spawn id (or -1 for error).
4230 @t{@b{telnet_open} @i{hostname} @i{args}}
4234 @item @code{hostname}
4235 The host to connect to with TELNET.
4238 A list of options. Currently the only supported option is @code{raw}.
4241 @node telnet_binary procedure, tip_open procedure, telnet_open procedure, connprocs
4242 @subsubheading telnet_binary Procedure
4243 @findex telnet_binary
4245 Puts an existing TELNET connection into binary mode.
4248 @t{@b{telnet_binary} @i{hostname}}
4252 @item @code{hostname}
4253 Hostname for the connection.
4256 @node tip_open procedure, rlogin_open procedure, telnet_binary procedure, connprocs
4257 @subsubheading tip_open Procedure
4260 Connect to a host using @code{tip(1)}. This procedure sets the board
4261 @code{fileid} field with the @code{spawn_id} on success and,
4262 otherwise, returns -1.
4265 @t{@b{tip_open} @i{hostname}}
4269 @item @code{hostname}
4270 Hostname to connect to.
4273 @node rlogin_open procedure, rlogin_spawn procedure, tip_open procedure, connprocs
4274 @subsubheading rlogin_open Procedure
4278 @t{@b{rlogin_open} @i{arg}}
4285 @node rlogin_spawn procedure, rsh_open procedure, rlogin_open procedure, connprocs
4286 @subsubheading rlogin_spawn Procedure
4287 @findex rlogin_spawn
4290 @t{@b{rlogin_spawn} @i{dest} @i{cmdline}}
4295 @item @code{cmdline}
4298 @node rsh_open procedure, rsh_download procedure, rlogin_spawn procedure, connprocs
4299 @subsubheading rsh_open Procedure
4303 @t{@b{rsh_open} @i{hostname}}
4307 @item @code{hostname}
4310 @node rsh_download procedure, rsh_upload procedure, rsh_open procedure, connprocs
4311 @subsubheading rsh_download Procedure
4312 @findex rsh_download
4315 @t{@b{rsh_download} @i{desthost} @i{srcfile} @i{destfile}}
4319 @item @code{desthost}
4320 @item @code{srcfile}
4321 @item @code{destfile}
4324 @node rsh_upload procedure, rsh_exec procedure, rsh_download procedure, connprocs
4325 @subsubheading rsh_upload Procedure
4329 @t{@b{rsh_upload} @i{desthost} @i{srcfile} @i{destfile}}
4333 @item @code{desthost}
4334 @item @code{srcfile}
4335 @item @code{destfile}
4338 @node rsh_exec procedure, ssh_close procedure, rsh_upload procedure, connprocs
4339 @subsubheading rsh_exec Procedure
4343 @t{@b{rsh_exec} @i{boardname} @i{cmd} @i{args}}
4347 @item @code{boardname}
4352 @node ssh_close procedure, ssh_exec procedure, rsh_exec procedure, connprocs
4353 @subsubheading ssh_close procedure
4357 @t{@b{ssh_close} @i{desthost}}
4361 @item @code{desthost}
4364 @node ssh_exec procedure, ssh_download procedure, ssh_close procedure, connprocs
4365 @subsubheading ssh_exec procedure
4369 @t{@b{ssh_exec} @i{boardname} @i{program} @i{pargs} @i{inp} @i{outp}}
4373 @item @code{boardname}
4374 @item @code{program}
4380 @node ssh_download procedure, ssh_upload procedure, ssh_exec procedure, connprocs
4381 @subsubheading ssh_download procedure
4382 @findex ssh_download
4385 @t{@b{ssh_download} @i{desthost} @i{srcfile} @i{destfile}}
4389 @item @code{desthost}
4390 @item @code{srcfile}
4391 @item @code{destfile}
4394 @node ssh_upload procedure, ftp_open procedure, ssh_download procedure, connprocs
4395 @subsubheading ssh_upload procedure
4399 @t{@b{ssh_upload} @i{desthost} @i{srcfile} @i{destfile}}
4403 @item @code{desthost}
4404 @item @code{srcfile}
4405 @item @code{destfile}
4408 @node ftp_open procedure, ftp_upload procedure, ssh_upload procedure, connprocs
4409 @subsubheading ftp_open Procedure
4412 Open an FTP connection.
4415 @t{@b{ftp_open} @i{host}}
4420 The host to open the FTP connection to.
4423 @node ftp_upload procedure, ftp_download procedure, ftp_open procedure, connprocs
4424 @subsubheading ftp_upload Procedure
4427 Fetches a file from a remote host using FTP.
4430 @t{@b{ftp_upload} @i{host} @i{remotefile} @i{localfile}}
4435 The host to transfer the file from.
4437 @item @code{remotefile}
4438 The filename at the remote end.
4440 @item @code{localfile}
4441 The filename to store locally.
4445 @node ftp_download procedure, ftp_close procedure, ftp_upload procedure, connprocs
4446 @subsubheading ftp_download Procedure
4447 @findex ftp_download
4449 Sends a file to a remote host using FTP.
4452 @t{@b{ftp_download} @i{host} @i{localfile} @i{remotefile}}
4457 The host to transfer the file from.
4459 @item @code{localfile}
4460 The filename on the local system.
4462 @item @code{remotefile}
4463 The filename at the remote end.
4466 @node ftp_close procedure, tip_download procedure, ftp_download procedure, connprocs
4467 @subsubheading ftp_close Procedure
4470 Closes the FTP connection to a host.
4473 @t{@b{ftp_close} @i{host}}
4478 The host connection to close.
4481 @node tip_download procedure, , ftp_close procedure, connprocs
4482 @subsubheading tip_download Procedure
4483 @findex tip_download
4486 @t{@b{tip_download} @i{spawnid} @i{file}}
4491 @item @code{spawnid}
4492 Download @code{file} to the process @code{spawnid} (the value returned
4493 when the connection was established), using the @code{~put} command
4494 under tip. Most often used for single board computers that require
4495 downloading programs in ASCII S-records. Returns @emph{1} if an error
4496 occurs, @emph{0} otherwise.
4499 This is the filename to download.
4502 @node Procedures For Target Boards, target database library file, connprocs, Built-in Procedures
4503 @section Procedures For Target Boards
4506 * default_link Procedure: default_link procedure
4507 * default_target_assemble Procedure: default_target_assemble procedure
4508 * default_target_compile Procedure: default_target_compile procedure
4509 * pop_config Procedure: pop_config procedure
4510 * prune_warnings Procedure: prune_warnings procedure
4511 * push_build Procedure: push_build procedure
4512 * push_config Procedure: push_config procedure
4513 * reboot_target Procedure: reboot_target procedure
4514 * target_assemble Procedure: target_assemble procedure
4515 * target_compile Procedure: target_compile procedure
4516 * target_link Procedure: target_link procedure
4519 @node default_link procedure, default_target_assemble procedure, , Procedures For Target Boards
4520 @subsubheading default_link Procedure
4521 @findex default_link
4524 @t{@b{default_link} @i{board} @i{objects} @i{destfile} @i{flags}}
4527 This is the internal implementation for the @ref{target_link
4528 procedure}, and should not be directly called from testsuite code.
4530 @node default_target_assemble procedure, default_target_compile procedure, default_link procedure, Procedures For Target Boards
4531 @subsubheading default_target_assemble Procedure
4532 @findex default_target_assemble
4535 @t{@b{default_target_assemble} @i{source} @i{destfile} @i{flags}}
4538 This is the internal implementation for the @ref{target_assemble
4539 procedure}, and should not be directly called from testsuite code.
4541 @node default_target_compile procedure, pop_config procedure, default_target_assemble procedure, Procedures For Target Boards
4542 @subsubheading default_target_compile Procedure
4543 @findex default_target_compile
4546 @t{@b{default_target_compile} @i{source} @i{destfile} @i{type}
4550 This is the default implementation for the @ref{target_compile
4551 procedure}, and is used if the current target board does not have a
4552 special procedure for this purpose. @xref{target_compile procedure},
4553 for API details. Calling this procedure directly from testsuite code
4556 @node pop_config procedure, prune_warnings procedure, default_target_compile procedure, Procedures For Target Boards
4557 @subsubheading pop_config Procedure
4561 @t{@b{pop_config} @i{type}}
4568 @node prune_warnings procedure, push_build procedure, pop_config procedure, Procedures For Target Boards
4569 @subsubheading prune_warnings Procedure
4570 @findex prune_warnings
4573 @t{@b{prune_warnings} @i{text}}
4580 @node push_build procedure, push_config procedure, prune_warnings procedure, Procedures For Target Boards
4581 @subsubheading push_build Procedure
4585 @t{@b{push_build} @i{name}}
4592 @node push_config procedure, reboot_target procedure, push_build procedure, Procedures For Target Boards
4593 @subsubheading push_config Procedure
4597 @t{@b{push_config} @i{type} @i{name}}
4606 @node reboot_target procedure, target_assemble procedure, push_config procedure, Procedures For Target Boards
4607 @subsubheading reboot_target Procedure
4608 @findex reboot_target
4613 @t{@b{reboot_target}}
4616 @node target_assemble procedure, target_compile procedure, reboot_target procedure, Procedures For Target Boards
4617 @subsubheading target_assemble Procedure
4618 @findex target_assemble
4621 @t{@b{target_assemble} @i{source destfile flags}}
4626 @item @code{destfile}
4630 @node target_compile procedure, target_link procedure, target_assemble procedure, Procedures For Target Boards
4631 @subsubheading target_compile Procedure
4632 @findex target_compile
4635 @t{@b{target_compile} @i{source} @i{destfile} @i{type} @i{options}}
4640 Source file or other arguments if @var{type} is @code{none}.
4642 Destination file or empty string to request output as return value.
4644 Type of output that should be produced.
4645 @multitable {@code{preprocess}} {Special applications where no source is actually given.}
4647 @tab Special applications where no source is actually given.
4648 @item @code{preprocess}
4649 @tab Run the source files through the C preprocessor.
4650 @item @code{assembly}
4651 @tab Produce assembler source from the compiler.
4653 @tab Produce binary object files.
4654 @item @code{executable}
4655 @tab Produce an executable program.
4658 List of additional options:
4660 @b{Language-selection options:}
4663 Use an Ada compiler.
4667 Use a compiler for the D language.
4669 Use a compiler for Fortran 77.
4671 Use a compiler for Fortran 90.
4673 Use a compiler for Go.
4675 Use a compiler for Rust.
4677 If none of these options are given, the C compiler is used by default.
4678 Giving multiple language-selection options is an error.
4680 The @code{f77} option generally selects the @command{g77} compiler,
4681 while the @code{f90} option selects the newer @command{gfortran}
4682 frontend. Both of these can compile Fortran 77, but only
4683 @command{gfortran} supports Fortran 90.
4685 @b{Search path options:}
4687 @item incdir=@var{dir}
4688 Additional directory to search for preprocessor include files.
4689 Multiple uses of this option add multiple directories to the search
4691 @item libdir=@var{dir}
4692 Additional directory to search for libraries. Multiple uses of this
4693 option add multiple directories to the search path.
4699 Compile with debugging information. Multiple uses of this option are
4700 treated as a single use.
4701 @item dest=@var{target}
4702 Override the current target and compile for @var{target} instead. If
4703 this option is given multiple times, only the last use is significant.
4704 @item compiler=@var{command}
4705 Override the defaults and use @var{command} as the compiler. If
4706 this option is given multiple times, only the last use is significant.
4707 @item linker=@var{command}
4708 Override the defaults and use @var{command} to build executables. If
4709 this option is given multiple times, only the last use is significant.
4710 @item early_flags=@var{flags}
4711 Prepend @var{flags} to the set of arguments to be passed to the compiler.
4712 Multiple uses of this option specify additional arguments.
4713 @item additional_flags=@var{flags}
4714 Add @var{flags} to the set of arguments to be passed to the compiler.
4715 Multiple uses of this option specify additional arguments.
4716 @item optimize=@var{flags}
4717 Specify optimization flags to be passed to the compiler. Nothing
4718 enforces that the flags given with option must actually be related to
4719 optimization, however. If this option is given multiple times, only
4720 the last use is significant.
4721 @item ldflags=@var{flags}
4722 Add @var{flags} to the set of arguments to be passed to the linker.
4723 Note that these are passed literally to the compiler driver, without
4724 adding a special prefix to each option. If a @samp{-Wl,} prefix is
4725 needed with GCC, it must be included in the given @var{flags}. As a
4726 group, the linker flags are only used if an executable is requested
4727 and are given special treatment with some languages. Multiple uses of
4728 this option specify additional arguments.
4729 @item ldscript=@var{script}
4730 Specify a linker script, or more precisely, the argument to pass to
4731 the linker via the compiler driver to select a linker script. The
4732 @var{script} value is passed literally to the compiler driver. If
4733 this option is given multiple times, only the last use is significant.
4734 @item libs=@var{libs}
4735 Specify additional libraries to be included in the link. The
4736 @var{libs} value is a space-separated list of libraries to include.
4737 Each element is checked, and if a file exists with that exact name, it
4738 is added to the list of sources to be given to the compiler.
4739 Otherwise, the element is passed literally to the compiler driver
4740 after any linker flags specified with the @code{ldflags} option.
4741 Multiple uses of this option specify additional lists, which are
4742 concatenated in the order they are given.
4745 @b{Execution options:}
4747 @item timeout=@var{timeout}
4748 Abort the compile job if it is still running after @var{timeout}
4749 seconds. This is intended for compiler tests that are known to cause
4750 infinite loops upon failure.
4751 @item redirect=@var{file}
4752 Instead of returning output emitted on @code{stdout}, place it into
4757 The @code{target_compile} procedure also uses several global Tcl variables as overrides:
4759 @item CFLAGS_FOR_TARGET
4760 If @code{CFLAGS_FOR_TARGET} is set, its value is prepended to the
4761 flags otherwise prepared for the compiler, even ahead of any
4762 board-specific flags inserted as a result of a language-selection
4764 @item LDFLAGS_FOR_TARGET
4765 If @code{LDFLAGS_FOR_TARGET} is set, the set of arguments to be passed
4766 to linker is initialized to its value instead of an empty list. The
4767 @code{ldflags} option appends to this list.
4769 Override default compiler. If no other compiler is given and this
4770 variable is set, its value will be used instead of searching for a
4771 compiler or using the default from the target board configuration.
4772 The @code{compiler} option overrides this variable.
4773 @item CXX_FOR_TARGET
4774 Override C++ compiler. If the @code{c++} option is given, this
4775 compiler will be used and the @code{compiler} option ignored.
4777 Override D language compiler. If the @code{d} option is given, this
4778 compiler will be used and the @code{compiler} option ignored.
4779 @item F77_FOR_TARGET
4780 Override Fortran 77 compiler. If the @code{f77} option is given, this
4781 compiler will be used and the @code{compiler} option ignored.
4782 @item F90_FOR_TARGET
4783 Override Fortran 90 compiler. If the @code{f90} option is given, this
4784 compiler will be used and the @code{compiler} option ignored.
4786 Override Go compiler. If the @code{go} option is given, this
4787 compiler will be used and the @code{compiler} option ignored.
4788 @item GO_LD_FOR_TARGET
4789 Override Go linker. If the @code{go} option is given, this
4790 linker will be used.
4791 @item RUSTC_FOR_TARGET
4792 Override Rust compiler. If the @code{rust} option is given, this
4793 compiler will be used and the @code{compiler} option ignored.
4794 @item GNATMAKE_FOR_TARGET
4795 Override Ada compiler. If the @code{ada} option is given, this
4796 compiler will be used and the @code{compiler} option ignored.
4799 The @code{target_compile} procedure obtains most defaults from the
4800 target board configuration, but additionally inserts any flags
4801 specified as @code{cflags_for_target} on the @emph{host} board
4802 configuration. If no host is set, the @code{unix} board configuration
4803 is checked for a @code{cflags_for_target} key. If the
4804 @code{cflags_for_target} key exists, its value is inserted into the
4805 set of arguments given to the compiler after any arguments given with
4806 the @code{additional_flags} option.
4808 In DejaGnu 1.6.2 and older, this mechanism did not work reliably and
4809 the @code{unix} board configuration was always searched for the
4810 @code{cflags_for_target} key, regardless of the host board selected.
4812 Also in DejaGnu 1.6.2 and older, the @code{dest} option interacted
4813 very badly with the language-selection options. There was no correct
4814 way to combine these options because the language-specific defaults
4815 would be read from the current target board configuration instead of
4816 the board configuration specified with the @code{dest} option. The
4817 closest solution was to always specify the language-selection option
4818 first, but this results in defaults appropriate for the current
4819 target, instead of the target selected with the @code{dest} option.
4821 @node target_link procedure, , target_compile procedure, Procedures For Target Boards
4822 @subsubheading target_link Procedure
4826 @t{@b{target_link} @i{objects} @i{destfile} @i{flags}}
4830 @item @code{objects}
4831 @item @code{destfile}
4835 @node target database library file, platform dependent procedures, Procedures For Target Boards, Built-in Procedures
4836 @section Target Database Procedures
4839 * board_info Procedure: board_info procedure
4840 * host_info Procedure: host_info procedure
4841 * set_board_info Procedure: set_board_info procedure
4842 * add_board_info Procedure: add_board_info procedure
4843 * set_currtarget_info Procedure: set_currtarget_info procedure
4844 * target_info Procedure: target_info procedure
4845 * unset_board_info Procedure: unset_board_info procedure
4846 * unset_currtarget_info Procedure: unset_currtarget_info procedure
4847 * push_target Procedure: push_target procedure
4848 * pop_target Procedure: pop_target procedure
4849 * push_host Procedure: push_host procedure
4850 * pop_host Procedure: pop_host procedure
4853 @node board_info procedure, host_info procedure, , target database library file
4854 @subsubheading board_info Procedure
4857 Searches the @code{board_info} array for the specified information.
4860 @t{@b{board_info} @i{machine} @i{op} @i{args}}
4864 @item @code{machine}
4869 @node host_info procedure, set_board_info procedure, board_info procedure, target database library file
4870 @subsubheading host_info Procedure
4874 @t{@b{host_info} @i{op} @i{args}}
4882 @node set_board_info procedure, add_board_info procedure, host_info procedure, target database library file
4883 @subsubheading set_board_info Procedure
4884 @findex set_board_info
4886 This checks if the @code{board_info} array entry has been set already
4887 and, if not, sets it to given value.
4890 @t{@b{set_board_info} @i{entry} @i{value}}
4895 Field of the @code{board_info} to set.
4898 Value to set the field to.
4901 @node add_board_info procedure, set_currtarget_info procedure, set_board_info procedure, target database library file
4902 @subsubheading add_board_info Procedure
4903 @findex add_board_info
4905 This treats @code{board_info} array's field @emph{entry} as a TCL list
4906 and adds @emph{value} at the end.
4909 @t{@b{add_board_info} @i{entry} @i{value}}
4915 The name of a @code{board_info} field to operate on.
4918 The value to add to the field.
4921 @node set_currtarget_info procedure, target_info procedure, add_board_info procedure, target database library file
4922 @subsubheading set_currtarget_info Procedure
4923 @findex set_currtarget_info
4926 @t{@b{set_currtarget_info} @i{entry} @i{value}}
4934 @node target_info procedure, unset_board_info procedure, set_currtarget_info procedure, target database library file
4935 @subsubheading target_info Procedure
4939 @t{@b{target_info} @i{op} @i{args}}
4947 @node unset_board_info procedure, unset_currtarget_info procedure, target_info procedure, target database library file
4948 @subsubheading unset_board_info Procedure
4949 @findex unset_board_info
4951 This checks if @code{board_info} array's field @emph{entry} has been
4952 set and if so, then removes it.
4955 @t{@b{unset_board_info} @i{entry}}
4960 The name of a @code{board_info} field to operate on.
4963 @node unset_currtarget_info procedure, push_target procedure, unset_board_info procedure, target database library file
4964 @subsubheading unset_currtarget_info Procedure
4965 @findex unset_currtarget_info
4968 @t{@b{unset_currtarget_info} @i{entry}}
4975 @node push_target procedure, pop_target procedure, unset_currtarget_info procedure, target database library file
4976 @subsubheading push_target Procedure
4979 This makes the target named @emph{name} be the current target
4983 @t{@b{push_target} @i{name}}
4988 Name of the target to make the current connection.
4991 @node pop_target procedure, push_host procedure, push_target procedure, target database library file
4992 @subsubheading pop_target Procedure
4995 This unsets the current target connection.
5001 @node push_host procedure, pop_host procedure, pop_target procedure, target database library file
5002 @subsubheading push_host Procedure
5005 This procedure makes the host named @emph{name} be the current remote
5009 @t{@b{push_host} @i{name}}
5014 Name of the host to make the current connection.
5017 @node pop_host procedure, , push_host procedure, target database library file
5018 @subsubheading pop_host Procedure
5021 This unsets the current host connection.
5027 @node platform dependent procedures, Utility Procedures, target database library file, Built-in Procedures
5028 @section Platform Dependent Procedures
5030 Each combination of target and tool requires some target-dependent
5031 procedures. The names of these procedures have a common form: the
5032 tool name, followed by an underscore @emph{_}, and finally a suffix
5033 describing the procedure's purpose. For example, a procedure to
5034 extract the version from GDB is called @code{gdb_version}.
5036 @code{runtest} itself calls only two of these procedures,
5037 @code{$@{tool@}_exit} and @code{$@{tool@}_version}; these procedures
5040 The other two procedures, @code{$@{tool@}_start} and
5041 @code{$@{tool@}_load}, are only called by the test suites themselves
5042 (or by testsuite-specific initialization code); they may take
5043 arguments or not, depending on the conventions used within each
5046 The usual convention for return codes from any of these procedures
5047 (although it is not required by @code{runtest}) is to return @emph{0}
5048 if the procedure succeeded, @emph{1} if it failed, and @emph{-1} if
5049 there was a communication error.
5052 * $@{tool@}_start Procedure: $@{tool@}_start procedure
5053 * $@{tool@}_load Procedure: $@{tool@}_load procedure
5054 * $@{tool@}_exit Procedure: $@{tool@}_exit procedure
5055 * $@{tool@}_version Procedure: $@{tool@}_version procedure
5058 @node $@{tool@}_start procedure, $@{tool@}_load procedure, , platform dependent procedures
5059 @subsubheading $@{tool@}_start Procedure
5060 @findex $@{tool@}_start
5062 Starts a particular tool. For an interactive tool,
5063 @code{$@{tool@}_start} starts and initializes the tool, leaving the
5064 tool up and running for the test cases; an example is
5065 @code{gdb_start}, the start function for GDB. For a batch-oriented
5066 tool, @code{$@{tool@}_start} is optional; the recommended convention
5067 is to let @code{$@{tool@}_start} run the tool, leaving the output in a
5068 variable called @code{comp_output}. Test scripts can then analyze
5069 @code{$comp_output} to determine the test results. An example of this
5070 second kind of start function is @code{gcc_start}, the start function
5073 DejaGnu itself does not call @code{$@{tool@}_start}. The
5074 initialization module @code{$@{tool@}_init.exp} must call
5075 @code{$@{tool@}_start} for interactive tools; for batch-oriented
5076 tools, each individual test script calls @code{$@{tool@}_start} (or
5077 makes other arrangements to run the tool).
5080 @t{@b{$@{tool@}_start}}
5083 @node $@{tool@}_load procedure, $@{tool@}_exit procedure, $@{tool@}_start procedure, platform dependent procedures
5084 @subsubheading $@{tool@}_load Procedure
5085 @findex $@{tool@}_load
5087 Loads something into a tool. For an interactive tool, this conditions
5088 the tool for a particular test case; for example, @code{gdb_load}
5089 loads a new executable file into the debugger. For batch-oriented
5090 tools, @code{$@{tool@}_load} may do nothing---though, for example, the
5091 GCC support uses @code{gcc_load} to load and run a binary on the
5092 target environment. Conventionally, @code{$@{tool@}_load} leaves the
5093 output of any program it runs in a variable called
5094 @code{$exec_output}. Writing @code{$@{tool@}_load} can be the most
5095 complex part of extending DejaGnu to a new tool or a new target, if it
5096 requires much communication coding or file downloading. Test scripts
5097 call @code{$@{tool@}_load}.
5100 @t{@b{$@{tool@}_load}}
5103 @node $@{tool@}_exit procedure, $@{tool@}_version procedure, $@{tool@}_load procedure, platform dependent procedures
5104 @subsubheading $@{tool@}_exit Procedure
5105 @findex $@{tool@}_exit
5107 Cleans up (if necessary) before DejaGnu exits. For interactive tools,
5108 this usually ends the interactive session. You can also use
5109 @code{$@{tool@}_exit} to remove any temporary files left over from the
5110 tests. @code{runtest} calls @code{$@{tool@}_exit}.
5113 @t{@b{$@{tool@}_exit}}
5116 @node $@{tool@}_version procedure, , $@{tool@}_exit procedure, platform dependent procedures
5117 @subsubheading $@{tool@}_version Procedure
5118 @findex $@{tool@}_version
5120 Prints the version label and number for @code{$@{tool@}}. This is
5121 called by the DejaGnu procedure that prints the final summary report.
5122 The output should consist of the full path name used for the tested
5123 tool, and its version number.
5126 @t{@b{$@{tool@}_version}}
5129 @node Utility Procedures, Libgloss, platform dependent procedures, Built-in Procedures
5130 @section Utility Procedures
5133 * getdirs Procedure: getdirs procedure
5134 * relative_filename Procedure: relative_filename procedure
5135 * find Procedure: find procedure
5136 * which Procedure: which procedure
5137 * grep Procedure: grep procedure
5138 * prune Procedure: prune procedure
5139 * runtest_file_p Procedure: runtest_file_p procedure
5140 * diff Procedure: diff procedure
5141 * setenv Procedure: setenv procedure
5142 * unsetenv Procedure: unsetenv procedure
5143 * getenv Procedure: getenv procedure
5146 @node getdirs procedure, relative_filename procedure, Utility Procedures, Utility Procedures
5147 @subsubheading getdirs Procedure
5150 Returns a list of all the subdirectories in a single directory that
5151 match a glob pattern. If no directories match the pattern, then an
5152 empty list is returned.
5154 This procedure is specialized as a search for tests in testsuites:
5155 @code{getdirs} ignores directories named @samp{testsuite},
5156 @samp{config}, or @samp{lib}, and also ignores directories associated
5157 with a few revision control systems, specifically Git (@samp{.git}),
5158 Subversion (@samp{.svn}), CVS (@samp{CVS}), RCS (@samp{RCS}), and SCCS
5159 (@samp{SCCS}). These ignored directories will not appear in the
5160 returned list, nor will they be examined in a recursive search.
5163 @t{@b{getdirs} @i{-all} @i{rootdir} @i{pattern}}
5169 If this option is given, then subdirectories will be matched
5172 @item @code{rootdir}
5173 The top level directory to start the search from.
5175 @item @code{pattern}
5176 The Tcl glob pattern to match. If you do not specify @code{pattern},
5177 @code{getdirs} uses a default pattern of @code{*}.
5181 @node relative_filename procedure, find procedure, getdirs procedure, Utility Procedures
5182 @subsubheading relative_filename Procedure
5183 @findex relative_filename
5185 Return a relative file name, given a starting point.
5188 @t{@b{relative_filename} @i{base} @i{destination}}
5194 The starting point for relative file name traversal.
5196 @item @code{destination}
5197 The absolute file name that should be reached by appending the return
5201 @node find procedure, which procedure, relative_filename procedure, Utility Procedures
5202 @subsubheading find Procedure
5205 Search for files whose names match a glob pattern. Search
5206 subdirectories recursively, starting at a particular root directory.
5207 The result is the list of files whose names match. Filenames in the
5208 result include all intervening subdirectory names. If no files match
5209 the pattern, then an empty string is returned.
5212 @t{@b{find} @i{rootdir} @i{pattern}}
5216 @item @code{rootdir}
5217 The top level directory to start the search from.
5219 @item @code{pattern}
5220 A glob pattern representing the files to find.
5223 @node which procedure, grep procedure, find procedure, Utility Procedures
5224 @subsubheading which Procedure
5227 Searches the execution path for an executable file like the BSD
5228 @code{which(1)} utility. This procedure uses the shell environment
5229 variable @code{PATH}. It returns @b{0} if the binary is not in the
5230 path or if the @code{PATH} environment variable is not set. If the
5231 file is in the path, this procedure returns the full path to the file.
5234 @t{@b{which} @i{file}}
5239 The executable program or shell script to look for.
5242 @node grep procedure, prune procedure, which procedure, Utility Procedures
5243 @subsubheading grep Procedure
5246 Search a named file for lines that contain a match for a regular
5247 expression. The result is a list of all the lines that match. If no
5248 lines match, the result is an empty string. All of the Tcl regular
5249 expression syntax is supported.
5252 @t{@b{grep} @i{-n} @i{filename} @i{regexp} @b{line}}
5257 The @code{-n} option prefixes matched lines in the result with the
5258 line number, just like GNU @code{grep} does. This option should be
5259 used in preference to the @code{line} keyword documented below.
5261 @item @code{filename}
5265 The Unix style regular expression (as used by the @code{grep} UNIX
5266 utility) to search for.
5269 Use the optional keyword @code{line} to prefix matched lines in the
5270 result with the line number. This usage is deprecated.
5273 @node prune procedure, runtest_file_p procedure, grep procedure, Utility Procedures
5274 @subsubheading prune Procedure
5277 This procedure is deprecated and will be removed in a future release
5278 of DejaGnu. If a testsuite uses this procedure, a copy of the
5279 procedure should be made and placed in the @file{lib} directory of the
5282 @node runtest_file_p procedure, diff procedure, prune procedure, Utility Procedures
5283 @subsubheading runtest_file_p Procedure
5284 @findex runtest_file_p
5286 Search @emph{runtest}s for @emph{testcase} and return @b{1} if found,
5287 @b{0} if not. This is used by tools like compilers where each
5291 @t{@b{runtest_file_p} @i{runtests} @i{testcase}}
5295 @item @code{runtests}
5297 @code{runtests} is a list of two elements. The second is a copy of
5298 what was on the right side of the @code{=} if @code{foo.exp="..."} was
5299 specified, or an empty string if no such argument is present.
5301 @item @code{testcase}
5302 The filename of the current testcase under consideration.
5305 @node diff procedure, setenv procedure, runtest_file_p procedure, Utility Procedures
5306 @subsubheading diff Procedure
5309 Compares two files and returns @b{1} if they match (no differences) or
5310 @b{0} if not. If @code{verbose} is set, then it will print the
5311 differences to the console.
5314 @t{@b{diff} @i{file1} @i{file2}}
5319 First file for the comparison.
5322 Second file for the comparison.
5325 @node setenv procedure, unsetenv procedure, diff procedure, Utility Procedures
5326 @subsubheading setenv Procedure
5329 Set an environment variable.
5332 @t{@b{setenv} @i{var} @i{val}}
5337 The environment variable to set.
5340 The value to set the variable to.
5343 @node unsetenv procedure, getenv procedure, setenv procedure, Utility Procedures
5344 @subsubheading unsetenv Procedure
5347 Unset an environment variable.
5350 @t{@b{unsetenv} @i{var} }
5355 The environment variable to unset.
5358 @node getenv procedure, , unsetenv procedure, Utility Procedures
5359 @subsubheading getenv Procedure
5362 Returns the value of the envrionment variable @emph{var} if it is
5363 defined, otherwise an empty string is returned.
5366 @t{@b{getenv} @i{var} }
5371 Environment variable to retrieve.
5374 @node Libgloss, Debugging Procedures, Utility Procedures, Built-in Procedures
5375 @section Libgloss, a free board support package (BSP)
5377 Libgloss is a free board support package @dfn{BSP} commonly used with
5378 GCC and G++ to produce a fully linked executable image for an embedded
5382 * libgloss_link_flags Procedure: libgloss_link_flags procedure
5383 * libgloss_include_flags Procedure: libgloss_include_flags procedure
5384 * newlib_link_flags Procedure: newlib_link_flags procedure
5385 * newlib_include_flags Procedure: newlib_include_flags procedure
5386 * libio_include_flags Procedure: libio_include_flags procedure
5387 * libio_link_flags Procedure: libio_link_flags procedure
5388 * g++_include_flags Procedure: g++_include_flags procedure
5389 * g++_link_flags Procedure: g++_link_flags procedure
5390 * libstdc++_include_flags Procedure: libstdc++_include_flags procedure
5391 * libstdc++_link_flags Procedure: libstdc++_link_flags procedure
5392 * get_multilibs Procedure: get_multilibs procedure
5393 * find_binutils_prog Procedure: find_binutils_prog procedure
5394 * find_gcc Procedure: find_gcc procedure
5395 * find_gcj Procedure: find_gcj procedure
5396 * find_g++ Procedure: find_g++ procedure
5397 * find_g77 Procedure: find_g77 procedure
5398 * find_gfortran Procedure: find_gfortran procedure
5399 * find_go Procedure: find_go procedure
5400 * find_go_linker Procedure: find_go_linker procedure
5401 * find_rustc Procedure: find_rustc procedure
5402 * process_multilib_options Procedure: process_multilib_options procedure
5403 * add_multilib_option Procedure: add_multilib_option procedure
5404 * find_gas Procedure: find_gas procedure
5405 * find_ld Procedure: find_ld procedure
5406 * build_wrapper Procedure: build_wrapper procedure
5407 * winsup_include_flags Procedure: winsup_include_flags procedure
5408 * winsup_link_flags Procedure: winsup_link_flags procedure
5411 @node libgloss_link_flags procedure, libgloss_include_flags procedure, , Libgloss
5412 @subsubheading libgloss_link_flags Procedure
5413 @findex libgloss_link_flags
5415 Finds the pieces of @code{libgloss} needed to link a set of object
5416 files into an executable. This usually means setting the @code{-L}
5417 and @code{-B} paths correctly.
5420 @t{@b{libgloss_link_flags} @i{args} }
5428 @node libgloss_include_flags procedure, newlib_link_flags procedure, libgloss_link_flags procedure, Libgloss
5429 @subsubheading libgloss_include_flags Procedure
5430 @findex libgloss_include_flags
5432 This procedure always returns an empty string. It is provided for
5436 @t{@b{libgloss_include_flags} @i{args}}
5444 @node newlib_link_flags procedure, newlib_include_flags procedure, libgloss_include_flags procedure, Libgloss
5445 @subsubheading newlib_link_flags Procedure
5446 @findex newlib_link_flags
5448 Return the options needed to link an executable with @code{newlib}.
5449 This usually means setting the @code{-L} and @code{-B} paths
5453 @t{@b{newlib_link_flags} @i{args}}
5461 @node newlib_include_flags procedure, libio_include_flags procedure, newlib_link_flags procedure, Libgloss
5462 @subsubheading newlib_include_flags Procedure
5463 @findex newlib_include_flags
5465 Return the options needed to locate the @code{newlib} header files.
5468 @t{@b{newlib_include_flags} @i{args}}
5476 @node libio_include_flags procedure, libio_link_flags procedure, newlib_include_flags procedure, Libgloss
5477 @subsubheading libio_include_flags Procedure
5478 @findex libio_include_flags
5481 @t{@b{libio_include_flags} @i{args}}
5484 Return the options needed to locate the @code{libio} header files.
5491 @node libio_link_flags procedure, g++_include_flags procedure, libio_include_flags procedure, Libgloss
5492 @subsubheading libio_link_flags Procedure
5493 @findex libio_link_flags
5496 @t{@b{libio_link_flags} @i{args}}
5499 Return the options needed to link an executable with @code{libio}.
5500 This usually means setting the @code{-L} and @code{-B} paths
5508 @node g++_include_flags procedure, g++_link_flags procedure, libio_link_flags procedure, Libgloss
5509 @subsubheading g++_include_flags Procedure
5510 @findex g++_include_flags
5512 Return the options needed to locate the C++ stnadard library header
5516 @t{@b{g++_include_flags} @i{args}}
5524 @node g++_link_flags procedure, libstdc++_include_flags procedure, g++_include_flags procedure, Libgloss
5525 @subsubheading g++_link_flags Procedure
5526 @findex g++_link_flags
5529 @t{@b{g++_link_flags} @i{args}}
5532 Return the options needed to link an executable with @code{libg++}.
5533 This usually means setting the @code{-L} and @code{-B} paths
5541 @node libstdc++_include_flags procedure, libstdc++_link_flags procedure, g++_link_flags procedure, Libgloss
5542 @subsubheading libstdc++_include_flags Procedure
5543 @findex libstdc++_include_flags
5546 @t{@b{libstdc++_include_flags} @i{args}}
5549 Return the options needed to locate the C++ stnadard library header
5557 @node libstdc++_link_flags procedure, get_multilibs procedure, libstdc++_include_flags procedure, Libgloss
5558 @subsubheading libstdc++_link_flags Procedure
5559 @findex libstdc++_link_flags
5562 @t{@b{libstdc++_link_flags} @i{args}}
5569 @node get_multilibs procedure, find_binutils_prog procedure, libstdc++_link_flags procedure, Libgloss
5570 @subsubheading get_multilibs Procedure
5571 @findex get_multilibs
5574 @t{@b{get_multilibs} @i{args}}
5581 @node find_binutils_prog procedure, find_gcc procedure, get_multilibs procedure, Libgloss
5582 @subsubheading find_binutils_prog Procedure
5583 @findex find_binutils_prog
5586 @t{@b{find_binutils_prog} @i{name}}
5593 @node find_gcc procedure, find_gcj procedure, find_binutils_prog procedure, Libgloss
5594 @subsubheading find_gcc Procedure
5597 Looks for a copy of the GNU C compiler in the build tree and in the
5598 @code{PATH}. This will also return the proper transformed name for a
5599 cross-compiler if the build tree is configured for one.
5605 @node find_gcj procedure, find_g++ procedure, find_gcc procedure, Libgloss
5606 @subsubheading find_gcj Procedure
5609 Looks for a copy of the GNU Java compiler in the build tree and in the
5610 @code{PATH}. This will also return the proper transformed name for a
5611 cross-compiler if the build tree is configured for one.
5617 @node find_g++ procedure, find_g77 procedure, find_gcj procedure, Libgloss
5618 @subsubheading find_g++ Procedure
5621 Looks for a copy of the GNU C++ compiler in the build tree and in the
5622 @code{PATH}. This will also return the proper transformed name for a
5623 cross-compiler if the build tree is configured for one.
5629 @node find_g77 procedure, find_gfortran procedure, find_g++ procedure, Libgloss
5630 @subsubheading find_g77 Procedure
5633 Looks for a copy of the GNU Fortran 77 compiler in the build tree and
5634 in the @code{PATH}. This will also return the proper transformed name
5635 for a cross-compiler if the build tree is configured for one.
5641 @node find_gfortran procedure, find_go procedure, find_g77 procedure, Libgloss
5642 @subsubheading find_gfortran Procedure
5643 @findex find_gfortran
5645 Looks for a copy of the GNU Fortran compiler in the build tree and in
5646 the @code{PATH}. This will also return the proper transformed name
5647 for a cross-compiler if the build tree is configured for one.
5650 @t{@b{find_gfortran}}
5653 @node find_go procedure, find_go_linker procedure, find_gfortran procedure, Libgloss
5654 @subsubheading find_go Procedure
5657 Looks for a copy of the GNU compiler for the Go language in the build
5658 tree and in the @code{PATH}. This will also return the proper
5659 transformed name for a cross-compiler if the build tree is configured
5666 @node find_go_linker procedure, find_rustc procedure, find_go procedure, Libgloss
5667 @subsubheading find_go_linker Procedure
5668 @findex find_go_linker
5670 Looks for a copy of the special linker associated with the GNU
5671 compiler for the Go language in the build tree and in the @code{PATH}.
5672 This will also return the proper transformed name for a cross-compiler
5673 if the build tree is configured for one.
5676 @t{@b{find_go_linker}}
5679 @node find_rustc procedure, process_multilib_options procedure, find_go_linker procedure, Libgloss
5680 @subsubheading find_rustc Procedure
5683 Looks for a copy of a compiler for the Rust language in the build tree
5684 and in the @code{PATH}. The Rust compiler is different and this
5685 procedure also ensures that it will be called with options to suppress
5692 @node process_multilib_options procedure, add_multilib_option procedure, find_rustc procedure, Libgloss
5693 @subsubheading process_multilib_options Procedure
5694 @findex process_multilib_options
5697 @t{@b{process_multilib_options} @i{args}}
5704 @node add_multilib_option procedure, find_gas procedure, process_multilib_options procedure, Libgloss
5705 @subsubheading add_multilib_option Procedure
5706 @findex add_multilib_option
5709 @t{@b{add_multilib_option} @i{args}}
5716 @node find_gas procedure, find_ld procedure, add_multilib_option procedure, Libgloss
5717 @subsubheading find_gas Procedure
5724 @node find_ld procedure, build_wrapper procedure, find_gas procedure, Libgloss
5725 @subsubheading find_ld Procedure
5732 @node build_wrapper procedure, winsup_include_flags procedure, find_ld procedure, Libgloss
5733 @subsubheading build_wrapper Procedure
5734 @findex build_wrapper
5737 @t{@b{build_wrapper} @i{gluefile}}
5741 @item @code{gluefile}
5744 @node winsup_include_flags procedure, winsup_link_flags procedure, build_wrapper procedure, Libgloss
5745 @subsubheading winsup_include_flags Procedure
5746 @findex winsup_include_flags
5749 @t{@b{winsup_include_flags} @i{args}}
5756 @node winsup_link_flags procedure, , winsup_include_flags procedure, Libgloss
5757 @subsubheading winsup_link_flags Procedure
5758 @findex winsup_link_flags
5761 @t{@b{winsup_link_flags} @i{args}}
5768 @node Debugging Procedures, , Libgloss, Built-in Procedures
5769 @section Procedures for debugging your scripts
5772 * bt Procedure: bt procedure
5773 * dumpvars Procedure: dumpvars procedure
5774 * dumplocals Procedure: dumplocals procedure
5775 * dumprocs Procedure: dumprocs procedure
5776 * dumpwatch Procedure: dumpwatch procedure
5777 * watcharray Procedure: watcharray procedure
5778 * watchvar Procedure: watchvar procedure
5779 * watchunset Procedure: watchunset procedure
5780 * watchwrite Procedure: watchwrite procedure
5781 * watchread Procedure: watchread procedure
5782 * watchdel Procedure: watchdel procedure
5783 * print Procedure: print procedure
5784 * quit Procedure: quit procedure
5787 @node bt procedure, dumpvars procedure, Debugging Procedures, Debugging Procedures
5788 @subsubheading bt Procedure
5791 This procedure prints a backtrace using the @code{w} command from the
5798 @node dumpvars procedure, dumplocals procedure, bt procedure, Debugging Procedures
5799 @subsubheading dumpvars Procedure
5803 This procedure prints the values of the global variables that match a
5804 glob pattern. Abbreviation: @kbd{dv}.
5807 @t{@b{dumpvars} @i{pattern}}
5811 @item @code{pattern}
5812 The global variables to dump.
5815 @node dumplocals procedure, dumprocs procedure, dumpvars procedure, Debugging Procedures
5816 @subsubheading dumplocals Procedure
5820 This procedure prints the values of local variables that match a glob
5821 pattern. Abbreviation: @kbd{dl}.
5824 @t{@b{dumplocals} @i{pattern} }
5828 @item @code{pattern}
5829 The local variables to dump.
5832 @node dumprocs procedure, dumpwatch procedure, dumplocals procedure, Debugging Procedures
5833 @subsubheading dumprocs Procedure
5837 This procedure dumps the body of all procs that match a glob pattern.
5838 It is abbreviated as @kbd{dp}.
5841 @t{@b{dumprocs} @i{pattern}}
5845 @item @code{pattern}
5846 The proc bodies to dump.
5849 @node dumpwatch procedure, watcharray procedure, dumprocs procedure, Debugging Procedures
5850 @subsubheading dumpwatch Procedure
5854 This procedure prints all of the watchpoints matching a glob pattern.
5855 It is abbreviated as @kbd{dw}.
5858 @t{@b{dumpwatch} @i{pattern}}
5862 @item @code{pattern}
5863 The watchpoints to dump.
5866 @node watcharray procedure, watchvar procedure, dumpwatch procedure, Debugging Procedures
5867 @subsubheading watcharray Procedure
5871 @t{@b{watcharray} @i{array} @i{element} @i{type}}
5877 @item @code{element}
5880 The csh "glob" style pattern to look for.
5883 @node watchvar procedure, watchunset procedure, watcharray procedure, Debugging Procedures
5884 @subsubheading watchvar Procedure
5888 @t{@b{watchvar} @i{var} @i{type}}
5897 @node watchunset procedure, watchwrite procedure, watchvar procedure, Debugging Procedures
5898 @subsubheading watchunset Procedure
5902 This breaks program execution when the variable @code{var} is unset.
5903 Abbreviation: @kbd{wu}.
5906 @t{@b{watchunset} @i{pattern}}
5910 @item @code{pattern}
5913 @node watchwrite procedure, watchread procedure, watchunset procedure, Debugging Procedures
5914 @subsubheading watchwrite Procedure
5918 This breaks program execution when the variable @code{var} is written.
5919 Abbreviation: @kbd{ww}.
5922 @t{@b{watchwrite} @i{var}}
5927 The variable to watch.
5930 @node watchread procedure, watchdel procedure, watchwrite procedure, Debugging Procedures
5931 @subsubheading watchread Procedure
5935 This breaks program execution when the variable @code{var} is read.
5936 Abbreviation: @kbd{wr}.
5939 @t{@b{watchread} @i{var}}
5944 The variable to watch.
5947 @node watchdel procedure, print procedure, watchread procedure, Debugging Procedures
5948 @subsubheading watchdel Procedure
5952 This deletes a watchpoint from the watch list. Abbreviation:
5956 @t{@b{watchdel} @i{pattern}}
5960 @item @code{pattern}
5963 @node print procedure, quit procedure, watchdel procedure, Debugging Procedures
5964 @subsubheading print Procedure
5967 This prints the value of a variable. Abbreviation: @kbd{p}.
5970 @t{@b{print} @i{var}}
5975 The variable to print.
5978 @node quit procedure, , print procedure, Debugging Procedures
5979 @subsubheading quit Procedure
5982 This makes @code{runtest} exit. Abbreviation: @kbd{q}.
5988 @node GNU Free Documentation License, Concept Index, Built-in Procedures, Top
5989 @appendix GNU Free Documentation License
5992 @node Concept Index, Procedure Index, GNU Free Documentation License, Top
5993 @unnumbered Concept Index
5996 @node Procedure Index, Variable Index, Concept Index, Top
5997 @unnumbered Procedure Index
6000 @node Variable Index, , Procedure Index, Top
6001 @unnumbered Variable Index
6006 @c LocalWords: subdirectory prepend prepended testsuite filename Expect's svn
6007 @c LocalWords: DejaGnu CVS RCS SCCS prepending subcommands Tcl Awk Readline
6008 @c LocalWords: POSIX KFAIL KPASS XFAIL XPASS hostname multitable gfortran api
6009 @c LocalWords: boolean subcommand testcase eval rustc executables perror gdb
6010 @c LocalWords: interprocess lookahead