1This is /home/jacob/projects/GNU/dejagnu/doc/dejagnu.info, produced by 2makeinfo version 4.8 from 3/home/jacob/projects/GNU/dejagnu/doc/dejagnu.texi. 4 5 Copyright (C) 1992-2020 Free Software Foundation, Inc. 6 7 Permission is granted to copy, distribute and/or modify this document 8under the terms of the GNU Free Documentation License, Version 1.3 or 9any later version published by the Free Software Foundation; with no 10Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 11Texts. A copy of the license is included in the section entitled "GNU 12Free Documentation License". 13 14INFO-DIR-SECTION Software development 15START-INFO-DIR-ENTRY 16* DejaGnu: (dejagnu). The GNU testing framework. 17END-INFO-DIR-ENTRY 18 19 20File: dejagnu.info, Node: Top, Next: Introduction, Up: (dir) 21 22DejaGnu 23******* 24 25* Menu: 26 27* Introduction:: 28* Running tests:: 29* Running other DejaGnu commands:: 30* Customizing DejaGnu:: 31* Extending DejaGnu:: 32* Unit testing:: 33* Built-in Procedures:: 34* GNU Free Documentation License:: 35* Concept Index:: 36* Procedure Index:: 37* Variable Index:: 38 39 40Introduction 41 42* What is DejaGnu?:: 43* New in this release: Release Notes 44* Design goals:: 45* A POSIX conforming test framework: A POSIX Conforming Test Framework. 46* Installation:: 47 48Running tests 49 50* Running 'make check': Make Check. 51* Running runtest: Runtest. 52* Output files: Output Files. 53 54Running other DejaGnu commands 55 56* Invoking dejagnu:: Command line options for the launcher itself. 57* Invoking dejagnu help:: Reading man pages for dejagnu subcommands. 58* Invoking dejagnu report card:: Summarizing test results from many tools. 59 60Customizing DejaGnu 61 62* Global configuration file:: 63* Local configuration file:: 64* Board configuration file:: 65* Remote host testing:: 66* Configuration file values:: 67 68Extending DejaGnu 69 70* Adding a new testsuite:: 71* Adding a new tool:: 72* Adding a new target:: 73* Adding a new board:: 74* Board file values:: 75* Writing a test case:: 76* Debugging a test case:: 77* Adding a test case to a testsuite:: 78* Test case special variables: Test case variables. 79 80Unit testing 81 82* What is unit testing?:: Unit testing and system testing. 83* Running unit tests:: 84* DejaGnu unit test protocol:: DejaGnu native unit testing protocol. 85* C unit testing API:: 86* C++ unit testing API:: 87 88Reference 89 90* Built-in Procedures:: 91 92Indices 93 94* Concept Index:: 95* Procedure Index:: 96* Variable Index:: 97 98 99File: dejagnu.info, Node: Introduction, Next: Running tests, Prev: Top, Up: Top 100 1011 Introduction 102************** 103 104* Menu: 105 106* What is DejaGnu?:: 107* New in this release: Release Notes. 108* Design goals:: 109* A POSIX compliant test framework: A POSIX Conforming Test Framework. 110* Installation:: 111 112 113File: dejagnu.info, Node: What is DejaGnu?, Next: Release Notes, Up: Introduction 114 1151.1 What is DejaGnu? 116==================== 117 118DejaGnu is a framework for testing other programs, providing a single 119front-end for all tests. You can think of it as a library of Tcl 120procedures to help with writing a test harness. A _test harness_ is 121the infrastructure that is created to test a specific program or tool. 122Each program can have multiple testsuites, all supported by a single 123test harness. DejaGnu is written in Expect, which in turn uses Tcl, 124the Tool command language. There is more information on Tcl at the 125Tcl/Tk web site (http://www.tcl.tk) and the Expect web site 126(http://expect.nist.gov). 127 128 Julia Menapace first coined the term _DejaGnu_ to describe an 129earlier testing framework she wrote at Cygnus Support for testing GDB. 130When we replaced it with the Expect-based framework, it was like 131DejaGnu all over again. More importantly, it was also named after my 132daughter, Deja Snow Savoye, who was a toddler during DejaGnu's 133beginnings. 134 135 DejaGnu offers several advantages for testing: 136 137 * The flexibility and consistency of the DejaGnu framework make it 138 easy to write tests for any program, with either batch-oriented, 139 or interactive programs. 140 141 * DejaGnu provides a layer of abstraction which allows you to write 142 tests that are portable to any host or target where a program must 143 be tested. For instance, a test for `GDB' can run from any 144 supported host system on any supported target system. DejaGnu runs 145 tests on many single board computers, whose operating software 146 ranges from a simple boot monitor to a real-time OS. 147 148 * All tests have the same output format. This makes it easy to 149 integrate testing into other software development processes. 150 DejaGnu's output is designed to be parsed by other filtering script 151 and it is also human readable. 152 153 * Using Tcl and Expect, it's easy to create wrappers for existing 154 testsuites. By incorporating existing tests under DejaGnu, it's 155 easier to have a single set of report analyse programs.. 156 157 Running tests requires two things: the testing framework and the 158testsuites themselves. Tests are usually written in Expect using Tcl, 159but you can also use a Tcl script to run a testsuite that is not based 160on Expect. Expect script filenames conventionally use `.exp' as a 161suffix. For example, the main implementation of the DejaGnu test 162driver is in the file `runtest.exp'. 163 164 165File: dejagnu.info, Node: Release Notes, Next: Design goals, Prev: What is DejaGnu?, Up: Introduction 166 1671.2 New in this release 168======================= 169 170The following major, user-visible changes have been introduced since 171version 1.5.3. 172 173 1. Support for target communication via SSH has been added. 174 175 2. A large number of very old config and baseboard files have been 176 removed. If you need to resurrect these, you can get them from 177 version 1.5.3. If you can show that a board is still in use, it 178 can be put back in the distribution. 179 180 3. The `--status' command line option is now the default. This means 181 that any error in the testsuite Tcl scripts will cause runtest to 182 abort with exit status code 2. The `--status' option has been 183 removed from the documentation, but will continue to be accepted 184 for backward compatibility. 185 186 4. `runtest' now exits with exit code 0 if the testsuite "passed", 1 187 if something unexpected happened (eg, FAIL, XPASS or UNRESOLVED), 188 and 2 if an exception is raised by the Tcl interpreter. 189 190 5. `runtest' now exits with the standard exit codes of programs that 191 are terminated by the SIGINT, SIGTERM and SIGQUIT signals. 192 193 6. The user-visible utility procedures `absolute', `psource' and 194 `slay' have been removed. If a testsuite uses any of these 195 procedures, a copy of the procedure should be made and placed in 196 the lib directory of the testsuite. 197 198 7. Support was added for testing the D compiler. 199 200 8. `~/.dejagnurc' is now loaded last, not first. This allows the 201 user to have the ability to override anything in their environment 202 (even the `site.exp' file specified by `$DEJAGNU'). 203 204 9. The user-visible utility procedure `unsetenv' is *deprecated* and 205 will be removed in the next release. If a testsuite uses this 206 procedure, a copy should be made and placed in the lib directory 207 of the testsuite. 208 209 210 211File: dejagnu.info, Node: Design goals, Next: A POSIX Conforming Test Framework, Prev: Release Notes, Up: Introduction 212 2131.3 Design goals 214================ 215 216DejaGnu grew out of the internal needs of Cygnus Solutions (formerly 217Cygnus Support). Cygnus maintained and enhanced a variety of free 218programs in many different environments and needed a testing tool that: 219 220 * was useful to developers while fixing bugs; 221 222 * automated running many tests during a software release process; 223 224 * was portable among a variety of host computers; 225 226 * supported a cross-development environment; 227 228 * permitted testing of interactive programs like `GDB'; and 229 230 * permitted testing of batch-oriented programs like `GCC'. 231 232 Some of the requirements proved challenging. For example, 233interactive programs do not lend themselves very well to automated 234testing. But all the requirements are important. For instance, it is 235imperative to make sure that `GDB' works as well when cross-debugging 236as it does in a native configuration. 237 238 Probably the greatest challenge was testing in a cross-development 239environment. Most cross-development environments are customized by 240each developer. Even when buying packaged boards from vendors there 241are many differences. The communication interfaces vary from a serial 242line to Ethernet. DejaGnu was designed with a modular communication 243setup, so that each kind of communication can be added as required and 244supported thereafter. Once a communication procedure is written, any 245test can use it. Currently DejaGnu can use `ssh', `rsh', `rlogin', 246`telnet', `tip', and `kermit' for remote communications. 247 248 249File: dejagnu.info, Node: A POSIX Conforming Test Framework, Next: Installation, Prev: Design goals, Up: Introduction 250 2511.4 A POSIX compliant test framework 252==================================== 253 254DejaGnu conforms to the POSIX 1003.3 standard for test frameworks. Rob 255Savoye was a member of that committee. 256 257 POSIX standard 1003.3 defines what a testing framework needs to 258provide to create a POSIX compliant testsuite. This standard is 259primarily oriented to checking POSIX conformance, but its requirements 260also support testing of features not related to POSIX conformance. 261POSIX 1003.3 does not specify a particular testing framework, but at 262this time there is only one other POSIX conforming test framework. TET 263was created by Unisoft for a consortium comprised of X/Open, Unix 264International and the Open Software Foundation. 265 266 The POSIX documentation refers to "assertions". An assertion is a 267description of behavior. For example, if a standard says "The sun 268shall shine", a corresponding assertion might be "The sun is shining." 269A test based on this assertion would pass or fail depending on whether 270it is day or night. It is important to note that the standard being 271tested is never 1003.3; the standard being tested is some other 272standard, for which the assertions were written. 273 274 As there is no testsuite to verify that testing frameworks are POSIX 2751003.3 compliant, this is done by repeatedly reading the standard and 276experimenting. One of the main things POSIX 1003.3 does specify is the 277set of allowed output messages and their definitions. Four messages 278are supported for a required feature of POSIX conforming systems and a 279fifth for a conditional feature. DejaGnu supports all five output 280messages. In this sense a testsuite that uses exactly these messages 281can be considered POSIX compliant. These definitions specify the 282output of a test case: 283 284PASS 285 A test has succeeded. That is, it demonstrated that the assertion 286 is true. 287 288FAIL 289 A test has not succeeded - the assertion is false. The _FAIL_ 290 message is based on this test case only. Other messages are used 291 to indicate a failure of the framework. As with _PASS_, POSIX 292 tests must return _FAIL_ rather than _XFAIL_ even if a failure was 293 expected. 294 295XFAIL 296 POSIX 1003.3 does not incorporate the notion of expected failures, 297 so _PASS_, instead of _XPASS_, must also be returned for test 298 cases which were expected to fail and did not. This means that 299 _PASS_ is in some sense more ambiguous than if _XPASS_ is also 300 used. 301 302UNRESOLVED 303 A test produced indeterminate results. Usually, this means the 304 test executed in an unexpected fashion. This outcome requires a 305 human to go over results to determine if the test should have 306 passed or failed. This message is also used for any test that 307 requires human intervention because it is beyond the abilities of 308 the testing framework. Any unresolved test should resolved to 309 _PASS_ or _FAIL_ before a test run can be considered finished. 310 311 Note that for POSIX, each assertion must produce a test result 312 code. If the test isn't actually run, it must produce _UNRESOLVED_ 313 rather than just leaving that test out of the output. This means 314 that you have to be careful when writing tests to not carelessly 315 use Tcl commands like _return_--if you alter the flow of control 316 of the Tcl code you must insure that every test still produces 317 some result code. 318 319 Here are some of the ways a test may wind up _UNRESOLVED_: 320 321 * Execution of a test is interrupted. 322 323 * A test does not produce a clear result. This is usually because 324 there was an _ERROR_ from DejaGnu while processing the test, or 325 because there were three or more _WARNING_ messages. Any _WARNING_ 326 or _ERROR_ messages can invalidate the output of the test. This 327 usually requires a human to examine the output to determine what 328 really happened - and to improve the test case. 329 330 * A test depends on a previous test, which has failed. 331 332 * The test was set up incorrectly. 333 334 * A test script aborts due to a Tcl error. In this case, the DejaGnu 335 framework inserts an _UNRESOLVED_ result as a placeholder for an 336 unknown number of tests that were not run because the script 337 crashed. 338 339UNTESTED 340 A test was not run. This is a placeholder used when there is no 341 real test case yet. 342 343UNSUPPORTED 344 There is no support for the tested case. This may mean that a 345 conditional feature of an operating system, or of a compiler, is 346 not implemented. DejaGnu also uses this message when a testing 347 environment (often a "bare board" target) lacks basic support for 348 compiling or running the test case. For example, a test for the 349 system subroutine _gethostname_ would never work on a target board 350 running only a boot monitor. 351 352 DejaGnu uses the same output procedures to produce these messages for 353all testsuites and these procedures are already known to conform to 354POSIX 1003.3. For a DejaGnu testsuite to conform to POSIX 1003.3, you 355must avoid the _setup_xfail_ procedure as described in the _PASS_ 356section above and you must be careful to return _UNRESOLVED_ where 357appropriate, as described in the _UNRESOLVED_ section above. 358 359 360File: dejagnu.info, Node: Installation, Prev: A POSIX Conforming Test Framework, Up: Introduction 361 3621.5 Installation 363================ 364 365Refer to the `INSTALL' in the source distribution for detailed 366installation instructions. Note that there is no compilation step as 367with many other GNU packages, as DejaGnu consists of interpreted code 368only. 369 370 Save for its own small testsuite, the DejaGnu distribution does not 371include any testsuites. Testsuites for the various GNU development 372tools are included with those packages. After configuring the 373top-level DejaGnu directory, unpack and configure the test directories 374for the tools you want to test; then, in each test directory, run _make 375check_ to build auxiliary programs required by some of the tests, and 376run the test suites. 377 378 379File: dejagnu.info, Node: Running tests, Next: Running other DejaGnu commands, Prev: Introduction, Up: Top 380 3812 Running tests 382*************** 383 384There are two ways to execute a testsuite. The most common way is when 385there is existing support in the `Makefile' of the tool being tested. 386This usually consists of a _check_ target. The other way is to execute 387the `runtest' program directly. To run `runtest' directly from the 388command line requires either all of the correct command line options, 389or a *Note Local configuration file:: must be set up correctly. 390 391* Menu: 392 393* Running 'make check': Make Check. 394* Running runtest: Runtest. 395* Output files: Output Files. 396 397 398File: dejagnu.info, Node: Make Check, Next: Runtest, Up: Running tests 399 4002.1 Running 'make check' 401======================== 402 403To run tests from an existing collection, first use `configure' as 404usual to set up the build directory. Then type `make check'. If the 405_check_ target exists, it usually saves you some trouble. For 406instance, it can set up any auxiliary programs or other files needed by 407the tests. The most common file the _check_ target depends on is the 408`site.exp' file. The `site.exp' contains various variables that 409DejaGnu uses to determine the configuration of the program being tested. 410 411 Once you have run _make check_ to build any auxiliary files, you can 412invoke the test driver `runtest' directly to repeat the tests. You 413will also have to execute `runtest' directly for test collections with 414no _check_ target in the `Makefile'. 415 416 GNU Automake has built-in support for DejaGnu. To add DejaGnu 417support to your generated `Makefile.in', just add the keyword `dejagnu' 418to the AUTOMAKE_OPTIONS variable in `Makefile.am'. This will ensure 419that the generated `Makefile.in' has a `check' target that invokes 420DejaGnu correctly. *Note DejaGnu Tests: (automake)Tests. 421 422 423File: dejagnu.info, Node: Runtest, Next: Output Files, Prev: Make Check, Up: Running tests 424 4252.2 Running runtest 426=================== 427 428`runtest' is the test driver for DejaGnu. You can specify two kinds of 429things on the `runtest' command line: command line options, and Tcl 430variables that are passed to the test scripts. The options are listed 431alphabetically below. 432 433 `runtest' returns one of the following exit codes: 434 4350 436 if all tests passed including expected failures and unsupported 437 tests. 438 4391 440 if any test failed, passed unexpectedly, or was unresolved. 441 4422 443 if Expect encountered any error in the test scripts. 444 445* Menu: 446 447* Output States:: 448* Invoking runtest:: 449* Common Options: Common Operations. 450 451 452File: dejagnu.info, Node: Output States, Next: Invoking runtest, Up: Runtest 453 4542.2.1 Output States 455------------------- 456 457`runtest' flags the outcome of each test as one of these cases. See 458*Note A POSIX Conforming Test Framework:: for a discussion of how POSIX 459specifies the meanings of these cases. 460 461PASS 462 The most desirable outcome: the test was expected to succeed and 463 did succeed. 464 465XPASS 466 A pleasant kind of failure: a test was expected to fail, but 467 succeeded. This may indicate progress; inspect the test case to 468 determine whether you should amend it to stop expecting failure. 469 470FAIL 471 A test failed, although it was expected to succeed. This may 472 indicate regress; inspect the test case and the failing software 473 to locate the bug. 474 475XFAIL 476 A test failed, but it was expected to fail. This result indicates 477 no change in a known bug. If a test fails because the operating 478 system where the test runs lacks some facility required by the 479 test, the outcome is _UNSUPPORTED_ instead. 480 481UNRESOLVED 482 Output from a test requires manual inspection; the testsuite could 483 not automatically determine the outcome. For example, your tests 484 can report this outcome is when a test does not complete as 485 expected. 486 487UNTESTED 488 A test case is not yet complete, and in particular cannot yet 489 produce a _PASS_ or _FAIL_. You can also use this outcome in dummy 490 "tests" that note explicitly the absence of a real test case for a 491 particular property. 492 493UNSUPPORTED 494 A test depends on a conditionally available feature that does not 495 exist (in the configured testing environment). For example, you 496 can use this outcome to report on a test case that does not work 497 on a particular target because its operating system support does 498 not include a required subroutine. 499 500 `runtest' may also display the following messages: 501 502ERROR 503 Indicates a major problem (detected by the test case itself) in 504 running the test. This is usually an unrecoverable error, such as 505 a missing file or loss of communication to the target. POSIX 506 testsuites should not emit this message; use _UNSUPPORTED_, 507 _UNTESTED_, or _UNRESOLVED_ instead, as appropriate. 508 509WARNING 510 Indicates a possible problem in running the test. Usually warnings 511 correspond to recoverable errors, or display an important message 512 about the following tests. 513 514NOTE 515 An informational message about the test case. 516 517 518File: dejagnu.info, Node: Invoking runtest, Next: Common Operations, Prev: Output States, Up: Runtest 519 5202.2.2 Invoking runtest 521---------------------- 522 523This is the full set of command line options that `runtest' recognizes. 524Option names may be abbreviated to the shortest unique string. 525 526`-a', `--all' 527 Display all test output. By default, _runtest_ shows only the 528 output of tests that produce unexpected results; that is, tests 529 with status _FAIL_ (unexpected failure), _XPASS_ (unexpected 530 success), or _ERROR_ (a severe error in the test case itself). 531 Specify `--all' to see output for tests with status _PASS_ 532 (success, as expected) _XFAIL_ (failure, as expected), or 533 _WARNING_ (minor error in the test case itself). 534 535`--build [triplet]' 536 _triplet_ is a system triplet of the form _cpu-manufacturer-os_. 537 This is the type of machine DejaGnu and the tools to be tested are 538 built on. For a normal cross environment this is the same as the 539 host, but for a Canadian cross, they are different. 540 541`-D0', `-D1' 542 Start the internal Tcl debugger. The Tcl debugger supports 543 breakpoints, single stepping, and other common debugging 544 activities. See the document Debugger for Tcl Applications 545 (http://expect.sourceforge.net/doc/tcl-debug.ps) by Don Libes. If 546 you specify _-D1_, the _expect_ shell stops at a breakpoint as 547 soon as DejaGnu invokes it. If you specify _-D0_, DejaGnu starts 548 as usual, but you can enter the debugger by sending an interrupt 549 (e.g. by typing <Ctrl>-<c>). 550 551`--debug' 552 Turns on the Expect internal debugging output. Debugging output is 553 displayed as part of the _runtest_ output, and logged to a file 554 called `dbg.log'. The extra debugging output does _not_ appear on 555 standard output, unless the verbose level is greater than 2 (for 556 instance, to see debug output immediately, specify `--debug -v 557 -v'). The debugging output shows all attempts at matching the test 558 output of the tool with the scripted patterns describing expected 559 output. The output generated with `--strace' also goes into 560 `dbg.log'. 561 562`--global_init [name]' 563 Use _name_ as the global init file instead of `site.exp' in 564 _libdir_. The default is, of course, `site.exp'. Note that this 565 option accepts a relative file name, interpreted starting at 566 _libdir_, so a file in a subdirectory may be used. This is 567 probably less useful for most sites, but is orthogonal with the 568 `--local_init' option and may be useful in large testing labs. 569 570`--help' 571 Prints out a short summary of the _runtest_ options, then exits 572 (even if you specify other options). 573 574`--host [triplet]' 575 _triplet_ is a system triplet of the form _cpu-manufactuer-os_. 576 Use this option to override the default string recorded by your 577 configuration's choice of host. This choice does not change how 578 anything is actually configured unless -build is also specified; 579 it affects _only_ DejaGnu procedures that compare the host string 580 with particular values. The procedures _ishost_, _istarget_, 581 _isnative_, and _setup_xfail_ are affected by `--host'. In this 582 usage, _host_ refers to the machine that the tests are to be run 583 on, which may not be the same as the _build_ machine. If 584 `--build' is also specified, then `--host' refers to the machine 585 that the tests will be run on, not the machine DejaGnu is run on. 586 587`--host_board [name]' 588 The host board to use. 589 590`--ignore [tests(s)] ' 591 The name(s) of specific tests to ignore. 592 593`--local_init [name]' 594 Use _name_ as the testsuite local init file instead of `site.exp' 595 in the current directory and in _objdir_. The default is, of 596 course, `site.exp'. Note that this option accepts a relative file 597 name, so a file in a subdirectory may be used. 598 599`--log_dialog' 600 Emit Expect output to stdout. The Expect output is usually only 601 written to the `.log' file. By enabling this option, they are 602 also printed to standard output. 603 604`--mail [address(es)]' 605 Send test results to one or more email addresses. 606 607`--objdir [path]' 608 Use _path_ as the top directory containing any auxiliary compiled 609 test code. The default is '.'. Use this option to locate 610 pre-compiled test code. You can normally prepare any auxiliary 611 files needed with _make_. 612 613`--outdir [path]' 614 Write log files in directory `path'. The default is '.', the 615 directory where you start _runtest_. This option affects only the 616 summary (`.sum') and the detailed log files (`.log'). The DejaGnu 617 debug log `dbg.log' always appears (when requested) in the local 618 directory. 619 620`--reboot [name]' 621 Reboot the target board when `runtest' starts. When running tests 622 on a separate target board, it is safer to reboot the target to be 623 certain of its state. However, when developing test scripts, 624 rebooting can take a lot of time. 625 626`--srcdir [path]' 627 Use `path' as the top directory for test scripts to run. 628 _runtest_ looks in this directory for any subdirectory whose name 629 begins with the toolname (specified with `--tool'). For instance, 630 with `--tool gdb', _runtest_ uses tests in subdirectories `gdb.*' 631 (with the usual shell-like filename expansion). If you do not use 632 `--srcdir', _runtest_ looks for test directories under the current 633 working directory. 634 635`--strace [n]' 636 Turn on internal tracing for _expect_, to n levels deep. By 637 adjusting the level, you can control the extent to which your 638 output expands multi-level Tcl statements. This allows you to 639 ignore some levels of _case_ or _if_ statements. Each procedure 640 call or control structure counts as one "level". The output is 641 recorded in the same file, `dbg.log', used for output from 642 `--debug'. 643 644`--target [triplet]' 645 Use this option to override the default setting (native testing). 646 _triplet_ is a system triplet of the form _cpu-manufacturer-os_. 647 This option changes the configuration `runtest' uses for the 648 default tool names, and other setup information. 649 650`--target_board [name(s)]' 651 The list of target boards to run tests on. 652 653`--tool [name(s)]' 654 Specifies which testsuite to run, and what initialization module to 655 use. `--tool' is used _only_ for these two purposes. It is _not_ 656 used to name the executable program to test. Executable tool 657 names (and paths) are recorded in `site.exp' and you can override 658 them by specifying Tcl variables on the command line. 659 660 For example, including `--tool' gcc on the command line runs tests 661 from all test subdirectories whose names match `gcc.*', and uses 662 one of the initialization modules named `config/*-gcc.exp'. To 663 specify the name of the compiler (perhaps as an alternative path to 664 what _runtest_ would use by default), use _GCC=path-to-gcc_ on the 665 _runtest_ command line. 666 667`--tool_exec [name]' 668 The path to the tool executable to test. 669 670`--tool_opts [options]' 671 A list of additional options to pass to the tool. 672 673`-v', `--verbose' 674 Turns on more output. Repeating this option increases the amount 675 of output displayed. Level one (_-v_) is simply test output. 676 Level two (_-v -v_) shows messages on options, configuration, and 677 process control. Verbose messages appear in the detailed 678 (`*.log') log file, but not in the summary (`*.sum') log file. 679 680`-V', `--version' 681 Prints out the version numbers of DejaGnu, Expect, and Tcl. 682 683`-x', `--xml' 684 Generate XML output. The output file is named after the tool with 685 an .xml extension. 686 687`testfile'.exp[=arg(s)] 688 Specify the names of testsuites to run. By default, _runtest_ 689 runs all tests for the tool, but you can restrict it to particular 690 testsuites by giving the names of the _.exp_ scripts that control 691 them. _testsuite_.exp cannot include directory names, only plain 692 filenames. 693 694 `arg(s)' specifies a subset of test cases to run. For compiler or 695 assembler tests, which often use a single _.exp_ script covering 696 many different test case files, this option allows you to further 697 restrict the tests by listing particular test cases. For larger 698 testsuites such as that included in GCC, this can save a lot of 699 time. Some tools support wildcards here, but this varies from 700 tool to tool. Typically the wildcards _?_, _*_, and _[chars]_ are 701 recognized. 702 703`tclvar'=value 704 You can define Tcl variables for use by your test scripts in the 705 same style used with _make_ for environment variables. For 706 example, _runtest GDB=gdb.old_ defines a variable called `GDB'; 707 when your scripts refer to `$GDB' in this run, they use the value 708 _gdb.old_. 709 710 The default Tcl variables used for most tools are defined in the 711 main DejaGnu _Makefile_; their values are captured in the 712 `site.exp' file. 713 714 715File: dejagnu.info, Node: Common Operations, Prev: Invoking runtest, Up: Runtest 716 7172.2.3 Common Options 718-------------------- 719 720Typically, you don't need to use any command line options. The 721`--tool' option is only required when there is more than one testsuite 722in the same directory. The default options are in the local `site.exp' 723file, created by `make site.exp'. 724 725 For example, if the directory `gdb/testsuite' contains a collection 726of DejaGnu tests for GDB, you can run them like this: 727 728 $ cd gdb/testsuite 729 $ runtest --tool gdb 730 731 The test output follows, then ends with: 732 733 === gdb Summary === 734 735 # of expected passes 508 736 # of expected failures 103 737 /usr/latest/bin/gdb version 4.14.4 -nx 738 739 You can use the option `--srcdir' to point to some other directory 740containing a collection of tests: 741 742 $ runtest --srcdir /devo/gdb/testsuite 743 744 By default, `runtest' prints only the names of the tests it runs, 745output from any tests that have unexpected results, and a summary 746showing how many tests passed and how many failed. To display output 747from all tests (whether or not they behave as expected), use the `-a' 748(all) option. For more verbose output about processes being run, 749communication, and so on, use `-v' (verbose). To see even more output, 750use multiple `-v' options. See *Note Invoking runtest:: for a more 751detailed explanation of each `runtest' option. 752 753 754File: dejagnu.info, Node: Output Files, Prev: Runtest, Up: Running tests 755 7562.3 Output files 757================ 758 759DejaGnu always writes two kinds of output files. Summary output is 760written to the `.sum' file, and detailed output is written to the 761`.log' file. The tool name determines the prefix for these files. For 762example, after running with `--tool gdb', the output files will be 763called `gdb.sum' and `gdb.log'. For troubleshooting, a debug log file 764that logs the operation of Expect is available. Each of these will be 765described in turn. 766 767* Menu: 768 769* Summary log file:: 770* Detailed log file:: 771* Debug log file:: 772 773 774File: dejagnu.info, Node: Summary log file, Next: Detailed log file, Up: Output Files 775 7762.3.1 Summary log file 777---------------------- 778 779DejaGnu always produces a summary (`.sum') output file. This summary 780lists the names of all test files run. For each test file, one line of 781output from each `pass' command (showing status _PASS_ or _XPASS_) or 782`fail' command (status _FAIL_ or _XFAIL_), trailing summary statistics 783that count passing and failing tests (expected and unexpected), the 784full pathname of the tool tested, and the version number of the tool. 785All possible outcomes, and all errors, are always reflected in the 786summary output file, regardless of whether or not you specify `--all'. 787 788 If any of your tests use the procedures `unresolved', `unsupported', 789or `untested', the summary output also tabulates the corresponding 790outcomes. 791 792 For example, after running `runtest --tool binutils' a summary log 793file will be written to `binutils.sum'. Normally, DejaGnu writes this 794file in your current working directory. Use the `--outdir' option to 795select a different output directory. 796 797 *Sample summary log* 798 799 Test Run By bje on Sat Nov 14 21:04:30 AEDT 2015 800 801 === gdb tests === 802 803 Running ./gdb.t00/echo.exp ... 804 PASS: Echo test 805 Running ./gdb.all/help.exp ... 806 PASS: help add-symbol-file 807 PASS: help aliases 808 PASS: help breakpoint "bre" abbreviation 809 FAIL: help run "r" abbreviation 810 Running ./gdb.t10/crossload.exp ... 811 PASS: m68k-elf (elf-big) explicit format; loaded 812 XFAIL: mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed C types 813 814 === gdb Summary === 815 816 # of expected passes 5 817 # of expected failures 1 818 # of unexpected failures 1 819 /usr/latest/bin/gdb version 4.6.5 -q 820 821 822File: dejagnu.info, Node: Detailed log file, Next: Debug log file, Prev: Summary log file, Up: Output Files 823 8242.3.2 Detailed log file 825----------------------- 826 827DejaGnu also saves a detailed log file (`.log'), showing any output 828generated by test cases as well as the summary output. For example, 829after running `runtest --tool binutils', a detailed log file will be 830written to `binutils.log'. Normally, DejaGnu writes this file in your 831current working directory. Use the `--outdir' option to select a 832different output directory. 833 834 *Sample detailed log for g++ tests* 835 836 Test Run By bje on Sat Nov 14 21:07:23 AEDT 2015 837 838 === g++ tests === 839 840 Running ./g++.other/t01-1.exp ... 841 PASS: operate delete 842 843 Running ./g++.other/t01-2.exp ... 844 FAIL: i960 bug EOF 845 p0000646.C: In function `int warn_return_1 ()': 846 p0000646.C:109: warning: control reaches end of non-void function 847 p0000646.C: In function `int warn_return_arg (int)': 848 p0000646.C:117: warning: control reaches end of non-void function 849 p0000646.C: In function `int warn_return_sum (int, int)': 850 p0000646.C:125: warning: control reaches end of non-void function 851 p0000646.C: In function `struct foo warn_return_foo ()': 852 p0000646.C:132: warning: control reaches end of non-void function 853 Running ./g++.other/t01-4.exp ... 854 FAIL: abort 855 900403_04.C:8: zero width for bit-field `foo' 856 Running ./g++.other/t01-3.exp ... 857 FAIL: segment violation 858 900519_12.C:9: parse error before `;' 859 900519_12.C:12: Segmentation violation 860 /usr/latest/bin/gcc: Internal compiler error: program cc1plus got fatal signal 861 862 === g++ Summary === 863 864 # of expected passes 1 865 # of expected failures 3 866 /usr/latest/bin/g++ version cygnus-2.0.1 867 868 869File: dejagnu.info, Node: Debug log file, Prev: Detailed log file, Up: Output Files 870 8712.3.3 Debug log file 872-------------------- 873 874The `runtest' option `--debug' creates a file showing the output from 875Expect in debugging mode. The `dbg.log' file is created in the current 876directory. The log file shows the string sent to the tool being tested 877by each `send' command and the pattern it compares with the tool output 878by each `expect' command. 879 880 The log messages begin with a message of the form: 881 882 expect: does {tool output} (spawn_id n) 883 match pattern {expected pattern}? 884 885 For every unsuccessful match, Expect issues a _no_ after this 886message. If other patterns are specified for the same Expect command, 887they are reflected also, but without the first part of the message 888(_expect... match pattern_). 889 890 When Expect finds a match, the log for the successful match ends with 891_yes_, followed by a record of the Expect variables set to describe a 892successful match. 893 894 *Example debug log file for a GDB test* 895 896 send: sent {break gdbme.c:34\n} to spawn id 6 897 expect: does {} (spawn_id 6) match pattern {Breakpoint.*at.* file 898 gdbme.c, line 34.*\(gdb\) $}? no 899 {.*\(gdb\) $}? no 900 expect: does {} (spawn_id 0) match pattern {return} ? no 901 {\(y or n\) }? no 902 {buffer_full}? no 903 {virtual}? no 904 {memory}? no 905 {exhausted}? no 906 {Undefined}? no 907 {command}? no 908 break gdbme.c:34 909 Breakpoint 8 at 0x23d8: file gdbme.c, line 34. 910 (gdb) expect: does {break gdbme.c:34\r\nBreakpoint 8 at 0x23d8: 911 file gdbme.c, line 34.\r\n(gdb) } (spawn_id 6) match pattern 912 {Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $}? yes 913 expect: set expect_out(0,start) {18} 914 expect: set expect_out(0,end) {71} 915 expect: set expect_out(0,string) {Breakpoint 8 at 0x23d8: file 916 gdbme.c, line 34.\r\n(gdb) } 917 epect: set expect_out(spawn_id) {6} 918 expect: set expect_out(buffer) {break gdbme.c:34\r\nBreakpoint 8 919 at 0x23d8: file gdbme.c, line 34.\r\n(gdb) } 920 PASS: 70 0 breakpoint line number in file 921 922 This example exhibits three properties of Expect and DejaGnu that 923might be surprising at first glance: 924 925 * Empty output for the first attempted match. The first set of 926 attempted matches shown ran against the output _{}_ -- that is, no 927 output. Expect begins attempting to match the patterns supplied 928 immediately; often, the first pass is against incomplete output 929 (or completely before all output, as in this case). 930 931 * Interspersed tool output. The beginning of the log entry for the 932 second attempted match may be hard to spot: this is because the 933 prompt _{(gdb) }_ appears on the same line, just before the 934 _expect:_ that marks the beginning of the log entry. 935 936 * Fail-safe patterns. Many of the patterns tested are fail-safe 937 patterns provided by GDB testing utilities, to reduce possible 938 indeterminacy. It is useful to anticipate potential variations 939 caused by extreme system conditions (GDB might issue the message 940 _virtual memory exhausted_ in rare circumstances), or by changes 941 in the tested program (_Undefined command_ is the likeliest 942 outcome if the name of a tested command changes). 943 944 The pattern _{return}_ is a particularly interesting fail-safe to 945 notice; it checks for an unexpected <RET> prompt. This may 946 happen, for example, if the tested tool can filter output through a 947 pager. 948 949 These fail-safe patterns (like the debugging log itself) are 950 primarily useful while developing test scripts. Use the `error' 951 procedure to make the actions for fail-safe patterns produce 952 messages starting with _ERROR_ on standard output, and in the 953 detailed log file. 954 955 956 957File: dejagnu.info, Node: Running other DejaGnu commands, Next: Customizing DejaGnu, Prev: Running tests, Up: Top 958 9593 Running other DejaGnu commands 960******************************** 961 962DejaGnu now features auxiliary commands not directly related to running 963tests, but somehow related to the broader purpose of testing. 964 965 These commands are run via the `dejagnu' multiplex launcher, which 966locates an appropriate script and the required interpreter and then 967runs the requested command. 968 969* Menu: 970 971* Invoking dejagnu:: Command line options for the launcher itself. 972* Invoking dejagnu help:: Reading man pages for dejagnu subcommands. 973* Invoking dejagnu report card:: Summarizing test results from many tools. 974 975 976File: dejagnu.info, Node: Invoking dejagnu, Next: Invoking dejagnu help, Prev: Running other DejaGnu commands, Up: Running other DejaGnu commands 977 9783.1 Invoking `dejagnu' 979====================== 980 981The `dejagnu' launcher is primarily designed to pass most options on to 982the scripts that it runs, but does process the `--help' and `--version' 983options entirely internally, while also recognizing the `--verbose' 984option. 985 986 `dejagnu' <command> [options...] 987 `dejagnu' --help 988 `dejagnu' --version 989 990 Note that the command names may contain multiple words. In this 991case, the command can be given as separate arguments to `dejagnu' or 992combined with dashes (`-'); both forms are equivalent. 993 994 All words of the command name must appear before any options. The 995search for a command terminates when an option is found. 996 997 Note that the first valid command found is used. A longer command 998name can be shadowed by a shorter command name that happens to be a 999prefix of the longer name, if the command name is given as multiple 1000arguments. The equivalent form with the longer command name combined 1001using dashes into a single argument will correctly refer to the 1002otherwise shadowed command. 1003 1004 The `dejagnu' launcher can also be run using symbolic links, 1005provided that the shell places the name under which `dejagnu' was 1006invoked in `$0'. Any dash-separated words after "dejagnu" in the name 1007of such a link are taken to be the leading words of a command name. 1008 1009 The `dejagnu' launcher supports alternate implementations depending 1010upon available interpreters. 1011 1012 Options for the `dejagnu' launcher itself cannot be abbreviated, 1013since the launcher has no way to know which abbreviations are unique 1014and which would be ambiguous to the invoked command. 1015 1016`--help' 1017 Print a help message instead of running a command. 1018 1019`-V', `--version' 1020 Print a version banner for the launcher itself including the 1021 version of DejaGnu. Any command given is ignored. 1022 1023`-v', `--verbose' 1024 Emit additional output describing the inner workings of the 1025 `dejagnu' launcher. This option is also passed on to the invoked 1026 command. 1027 1028 1029 All arguments after the command name are passed to the invoked 1030command. 1031 1032 1033File: dejagnu.info, Node: Invoking dejagnu help, Next: Invoking dejagnu report card, Prev: Invoking dejagnu, Up: Running other DejaGnu commands 1034 10353.2 Invoking `dejagnu help' 1036=========================== 1037 1038The `dejagnu help' tool displays long-form documentation for DejaGnu 1039auxiliary commands that are invoked using the `dejagnu' launcher. 1040 1041 `dejagnu help' [options...] <command> 1042 1043 Again, command names may contain multiple words. This command forms 1044an operand by joining all words in the command name using dashes (`-') 1045and prepending `dejagnu-'. This is then used as the name of a manual 1046page and passed to the `man' command. 1047 1048 If the manual page is in a particular directory relative to the 1049script implementing this command, a full file name is produced, 1050otherwise, `man' performs its normal search. 1051 1052 The `--verbose' option causes additional output describing the inner 1053workings of the `dejagnu help' command to be produced. 1054 1055 The `--path', `-w', and `-W' options are passed to `man'. 1056 1057 1058File: dejagnu.info, Node: Invoking dejagnu report card, Prev: Invoking dejagnu help, Up: Running other DejaGnu commands 1059 10603.3 Invoking `dejagnu report card' 1061================================== 1062 1063The `dejagnu report card' tool produces a tabular summary of the 1064results from test runs by reading the summary files that DejaGnu 1065produces. 1066 1067 `dejagnu report card' [<option>|<tool>|<file>]... 1068 1069 The `--verbose' option causes additional output describing the inner 1070workings of the `dejagnu report card' command to be produced. 1071 1072 Aside from options, the command may include a list of tools or files. 1073Names ending in `.sum' are used as-is. Names ending in `.log' are 1074changed to instead refer to the summary file. Names ending with a 1075simple dot (`.') have `sum' appended, for convenience when using 1076Readline filename completion in a shell, which will complete to the 1077dot, since there are both `.sum' and `.log' files produced for each 1078tool tested. Lastly, all other names are taken as tool names and 1079`.sum' is appended to refer to the summary file produced by DejaGnu. 1080 1081 The relevant summary files are read and an ASCII-art table is 1082produced. The table has columns for counts of tests passed, failed, 1083unsupported, unresolved, and untested. Tests that are expected to pass 1084and tests that are expected to fail are counted in separate columns, 1085but known failures (`KFAIL' and `KPASS') are summarized together with 1086expected failures (`XFAIL' and `XPASS') in two additional columns: 1087`?PASS' and `?FAIL'. Additionally, if a test produced any warnings or 1088errors, tags `!W!' or `!E!' are added at the end of the row. 1089 1090 1091File: dejagnu.info, Node: Customizing DejaGnu, Next: Extending DejaGnu, Prev: Running other DejaGnu commands, Up: Top 1092 10934 Customizing DejaGnu 1094********************* 1095 1096The site configuration file, `site.exp', captures 1097configuration-dependent values and propagates them to the DejaGnu test 1098environment using Tcl variables. This ties the DejaGnu test scripts 1099into the `configure' and `make' programs. If this file is setup 1100correctly, it is possible to execute a testsuite merely by typing 1101`runtest'. 1102 1103 DejaGnu supports two `site.exp' files. The multiple instances of 1104`site.exp' are loaded in a fixed order. The first file loaded is the 1105local file `site.exp', and then the optional global `site.exp' file as 1106pointed to by the `DEJAGNU' environment variable. 1107 1108 There is an optional global `site.exp', containing configuration 1109values that apply to DejaGnu site-wide. `runtest' loads these values 1110first. The global `site.exp' contains the default values for all 1111targets and hosts supported by DejaGnu. This global file is identified 1112by setting the environment variable `DEJAGNU' to the name of the file. 1113If `DEJAGNU' is set, but the file cannot be located, an error will be 1114raised and `runtest' will abort. 1115 1116 Any directory containing a configured testsuite also has a local 1117`site.exp', capturing configuration values specific to the tool being 1118tested. Since `runtest' loads these values last, the individual test 1119configuration can either rely on and use, or override, any of the 1120global values from the global `site.exp' file. 1121 1122 You can usually generate or update the testsuite's local `site.exp' 1123by typing `make site.exp' in the testsuite directory, after the test 1124suite is configured. 1125 1126 You can also have a file in your home directory called `.dejagnurc'. 1127This gets loaded after the other config files. Usually this is used 1128for personal stuff, like setting the `all_flag' so all the output gets 1129printed, or your own verbosity levels. This file is usually restricted 1130to setting command line options. 1131 1132 You can further override the default values in a user-editable 1133section of any `site.exp', or by setting variables on the `runtest' 1134command line. 1135 1136* Menu: 1137 1138* Local configuration file:: 1139* Global configuration file:: 1140* Board configuration file:: 1141* Remote host testing:: 1142* Configuration file values:: 1143 1144 1145File: dejagnu.info, Node: Global configuration file, Next: Local configuration file, Up: Customizing DejaGnu 1146 11474.1 Global configuration file 1148============================= 1149 1150The global configuration file is where all the target specific 1151configuration variables for a site are set. For example, a centralized 1152testing lab where multiple developers have to share an embedded 1153development board. There are settings for both remote hosts and remote 1154targets. Below is an example of a global configuration file for a 1155Canadian cross environment. A Canadian cross is a toolchain that is 1156built on, runs on, and targets three different system triplets (for 1157example, building a Solaris-hosted MIPS R4000 toolchain on a GNU/Linux 1158system). This example is based on a configuration once used at Cygnus. 1159 1160 *Example global configuration file* 1161 1162 # Make sure we look in the right place for the board description files. 1163 lappend boards_dir "/nfs/cygint/s1/cygnus/dejagnu/boards" 1164 1165 verbose "Global config file: target_triplet is $target_triplet" 2 1166 global target_list 1167 1168 switch -glob -- $target_triplet { 1169 "native" { 1170 set target_list "unix" 1171 } 1172 "sparc64-*elf" { 1173 set target_list "sparc64-sim" 1174 } 1175 "mips-*elf" { 1176 set target_list "mips-sim wilma barney" 1177 } 1178 "mips-lsi-elf" { 1179 set target_list "mips-lsi-sim{,soft-float,el}" 1180 } 1181 } 1182 1183 In this case, we have support for several cross compilers, that all 1184run on this host. To run DejaGnu tests on tools hosted on operating 1185systems that do not run Expect, DejaGnu can be run on the build machine 1186and connect to the remote host to run all the tests. As you can see, 1187all one does is set the variable `target_list' to the list of targets 1188and options to test. 1189 1190 In this example, simple cases like _sparc64-elf_ only require 1191setting the name of the single board configuration file. The 1192_mips-elf_ target is more complicated and sets the list to three target 1193boards. _mips-sim_ is a symbolic name for a simulator "board" and 1194_wilma_ and _barney_ are symbolic names for physical boards. Symbolic 1195names are covered in the *Note Adding a new board:: section. The more 1196complicated example is the entry for _mips-lsi-elf_. This one runs the 1197tests with multiple iterations using all possible combinations of the 1198`--soft-float' and the `--el' (little endian) options. The braced 1199string includes an initial comma so that the set of combinations 1200includes no options at all. Needless to say, this last target example 1201is mostly specific to compiler testing. 1202 1203 1204File: dejagnu.info, Node: Local configuration file, Next: Board configuration file, Prev: Global configuration file, Up: Customizing DejaGnu 1205 12064.2 Local configuration file 1207============================ 1208 1209It is usually more convenient to keep these _manual overrides_ in the 1210`site.exp' local to each test directory, rather than in the global 1211`site.exp' in the installed DejaGnu library. This file is mostly for 1212supplying tool specific info that is required by the testsuite. 1213 1214 All local `site.exp' files have two sections, separated by comments. 1215The first section is generated by `make'. It is essentially a 1216collection of Tcl variable definitions based on `Makefile' environment 1217variables. Since they are generated by `make', they contain the values 1218as specified by `configure'. In particular, this section contains the 1219`Makefile' variables for host and target configuration data. Do not 1220edit this first section; if you do, your changes will be overwritten 1221the next time you run `make'. The first section starts with: 1222 1223 ## these variables are automatically generated by make ## 1224 # Do not edit here. If you wish to override these values 1225 # add them to the last section 1226 1227 In the second section, you can override any default values for all 1228the variables. The second section can also contain your preferred 1229defaults for all the command line options to `runtest'. This allows 1230you to easily customize `runtest' for your preferences in each 1231configured testsuite tree, so that you need not type options repeatedly 1232on the command line. The second section may also be empty if you do 1233not wish to override any defaults. 1234 1235 *The first section ends with this line* 1236 1237 ## All variables above are generated by configure. Do Not Edit ## 1238 1239 You can make any changes under this line. If you wish to redefine a 1240variable in the top section, then just put a duplicate value in this 1241second section. Usually the values defined in this configuration file 1242are related to the configuration of the test run. This is the ideal 1243place to set the variables `host_triplet', `build_triplet', 1244`target_triplet'. All other variables are tool dependent, i.e., for 1245testing a compiler, the value for `CC' might be set to a freshly built 1246binary, as opposed to one in the user's path. 1247 1248 Here's an example local site.exp file, as used for GCC/G++ testing. 1249 1250 *Local Configuration File* 1251 1252 ## these variables are automatically generated by make ## 1253 # Do not edit here. If you wish to override these values 1254 # add them to the last section 1255 set rootme "/build/devo-builds/i686-pc-linux-gnu/gcc" 1256 set host_triplet i686-pc-linux-gnu 1257 set build_triplet i686-pc-linux-gnu 1258 set target_triplet i686-pc-linux-gnu 1259 set target_alias i686-pc-linux-gnu 1260 set CFLAGS "" 1261 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++" 1262 append LDFLAGS " -L/build/devo-builds/i686-pc-linux-gnu/gcc/../ld" 1263 set tmpdir /build/devo-builds/i686-pc-linux-gnu/gcc/testsuite 1264 set srcdir "${srcdir}/testsuite" 1265 ## All variables above are generated by configure. Do Not Edit ## 1266 1267 This file defines the required fields for a local configuration file, 1268namely the three system triplets, and the srcdir. It also defines 1269several other Tcl variables that are used exclusively by the GCC 1270testsuite. For most test cases, the CXXFLAGS and LDFLAGS are supplied 1271by DejaGnu itself for cross testing, but to test a compiler, GCC needs 1272to manipulate these itself. 1273 1274 The local `site.exp' may also set Tcl variables such as 1275`test_timeout' which can control the amount of time (in seconds) to 1276wait for a remote test to complete. If not specified, `test_timeout' 1277defaults to 300 seconds. 1278 1279 1280File: dejagnu.info, Node: Board configuration file, Next: Remote host testing, Prev: Local configuration file, Up: Customizing DejaGnu 1281 12824.3 Board configuration file 1283============================ 1284 1285The board configuration file is where board-specific configuration 1286details are stored. A board configuration file contains all the 1287higher-level configuration settings. There is a rough inheritance 1288scheme, where it is possible to derive a new board description file 1289from an existing one. There are also collections of custom procedures 1290for common environments. For more information on adding a new board 1291config file, see *Note Adding a new board::. 1292 1293 An example board configuration file for a GNU simulator is as 1294follows. `set_board_info' is a procedure that sets the field name to 1295the specified value. The procedures mentioned in brackets are _helper 1296procedures_. These are used to find parts of a toolchain required to 1297build an executable image that may reside in various locations. This 1298is mostly of use when the startup code, the standard C libraries, or 1299the toolchain itself is part of your build tree. 1300 1301 *Example file* 1302 # This is a list of toolchains that are supported on this board. 1303 set_board_info target_install {sparc64-elf} 1304 1305 # Load the generic configuration for this board. This will define any 1306 # routines needed by the tool to communicate with the board. 1307 load_generic_config "sim" 1308 1309 # We need this for find_gcc and *_include_flags/*_link_flags. 1310 load_base_board_description "basic-sim" 1311 1312 # Use long64 by default. 1313 process_multilib_options "long64" 1314 1315 setup_sim sparc64 1316 1317 # We only support newlib on this target. We assume that all multilib 1318 # options have been specified before we get here. 1319 1320 set_board_info compiler "[find_gcc]" 1321 set_board_info cflags "[libgloss_include_flags] [newlib_include_flags]" 1322 set_board_info ldflags "[libgloss_link_flags] [newlib_link_flags]" 1323 # No linker script. 1324 set_board_info ldscript "" 1325 1326 # Used by a few gcc.c-torture testcases to delimit how large the 1327 # stack can be. 1328 set_board_info gcc,stack_size 16384 1329 # The simulator doesn't return exit status and we need to indicate this 1330 # the standard GCC wrapper will work with this target. 1331 set_board_info needs_status_wrapper 1 1332 # We can't pass arguments to programs. 1333 set_board_info noargs 1 1334 1335 There are five helper procedures used in this example: 1336 1337 * `find_gcc' looks for a copy of the GNU compiler in your build 1338 tree, or it uses the one in your path. This will also return the 1339 proper transformed name for a cross compiler if you whole build 1340 tree is configured for one. DejaGnu will use this procedure to 1341 locate a compiler if the `compiler' field is not set. 1342 1343 * `libgloss_include_flags' returns the flags to compile using *Note 1344 libgloss: Libgloss, the GNU board support package (BSP). 1345 1346 * `libgloss_link_flags' returns the flags to link an executable 1347 using *Note libgloss: Libgloss. 1348 1349 * `newlib_include_flags' returns the flags to compile using newlib 1350 (https://sourceware.org/newlib), a re-entrant standard C library 1351 for embedded systems comprising of non-GPL'd code 1352 1353 * `newlib_link_flags' returns the flags to link an executable with 1354 newlib (https://sourceware.org/newlib). 1355 1356 1357 1358File: dejagnu.info, Node: Remote host testing, Next: Configuration file values, Prev: Board configuration file, Up: Customizing DejaGnu 1359 13604.4 Remote host testing 1361======================= 1362 1363DejaGnu also supports running the tests on a remote host. To set this 1364up, the remote host needs an FTP server, and a telnet server. 1365Currently foreign operating systems used as remote hosts are VxWorks, 1366VRTX, DOS/Windows 3.1, MacOS and Windows. 1367 1368 The recommended source for a Windows-based FTP server is to get IIS 1369(either IIS 1 or Personal Web Server) from http://www.microsoft.com 1370(http://www.microsoft.com). When you install it, make sure you install 1371the FTP server - it's not selected by default. Go into the IIS manager 1372and change the FTP server so that it does not allow anonymous FTP. Set 1373the home directory to the root directory (i.e. c:\) of a suitable 1374drive. Allow writing via FTP. 1375 1376 It will create an account like IUSR_FOOBAR where foobar is the name 1377of your machine. Go into the user editor and give that account a 1378password that you don't mind hanging around in the clear (i.e. not the 1379same as your admin or personal passwords). Also, add it to all the 1380various permission groups. 1381 1382 You'll also need a telnet server. For Windows, go to the Ataman 1383(http://ataman.com) web site, pick up the Ataman Remote Logon Services 1384for Windows, and install it. You can get started on the eval period 1385anyway. Add IUSR_FOOBAR to the list of allowed users, set the HOME 1386directory to be the same as the FTP default directory. Change the Mode 1387prompt to simple. 1388 1389 Now you need to pick a directory name to do all the testing in. For 1390the sake of this example, we'll call it piggy (i.e. c:\piggy). Create 1391this directory. 1392 1393 You'll need a Unix machine. Create a directory for the scripts 1394you'll need. For this example, we'll use /usr/local/swamp/testing. 1395You'll need to have a source tree somewhere, say /usr/src/devo. Now, 1396copy some files from releng's area in SV to your machine: 1397 1398 *Remote host setup* 1399 1400 cd /usr/local/swamp/testing 1401 mkdir boards 1402 scp darkstar.welcomehome.org:/dejagnu/cst/bin/MkTestDir . 1403 scp darkstar.welcomehome.org:/dejagnu/site.exp . 1404 scp darkstar.welcomehome.org:/dejagnu/boards/useless98r2.exp boards/foobar.exp 1405 export DEJAGNU=/usr/local/swamp/testing/site.exp 1406 1407 You must edit the boards/foobar.exp file to reflect your machine; 1408change the hostname (foobar.com), username (iusr_foobar), password, and 1409ftp_directory (c:/piggy) to match what you selected. 1410 1411 Edit the global ` site.exp' to reflect your boards directory: 1412 1413 *Add The Board Directory* 1414 1415 lappend boards_dir "/usr/local/swamp/testing/boards" 1416 1417 Now run MkTestDir, which is in the contrib directory. The first 1418parameter is the toolchain prefix, the second is the location of your 1419devo tree. If you are testing a cross compiler (ex: you have 1420sh-hms-gcc.exe in your PATH on the PC), do something like this: 1421 1422 *Setup Cross Remote Testing* 1423 1424 ./MkTestDir sh-hms /usr/dejagnu/src/devo 1425 1426 If you are testing a native PC compiler (ex: you have gcc.exe in your 1427PATH on the PC), do this: 1428 1429 *Setup Native Remote Testing* 1430 1431 ./MkTestDir '' /usr/dejagnu/src/devo 1432 1433 To test the setup, `ftp' to your PC using the username (iusr_foobar) 1434and password you selected. CD to the test directory. Upload a file to 1435the PC. Now telnet to your PC using the same username and password. 1436CD to the test directory. Make sure the file is there. Type "set" 1437and/or "gcc -v" (or sh-hms-gcc -v) and make sure the default PATH 1438contains the installation you want to test. 1439 1440 *Run Test Remotely* 1441 1442 cd /usr/local/swamp/testing 1443 make -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1 1444 1445 To run a specific test, use a command like this (for this example, 1446you'd run this from the gcc directory that MkTestDir created): 1447 1448 *Run a Test Remotely* 1449 1450 make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c" 1451 1452 Note: if you are testing a cross-compiler, put in the correct target 1453board. You'll also have to download more .exp files and modify them 1454for your local configuration. The -v's are optional. 1455 1456 1457File: dejagnu.info, Node: Configuration file values, Prev: Remote host testing, Up: Customizing DejaGnu 1458 14594.5 Configuration file values 1460============================= 1461 1462DejaGnu uses a Tcl associative array to hold all the info for each 1463machine. In the case of a Canadian cross, this means host information 1464as well as target information. The named array is called 1465`target_info', and it has two indices. The following fields are part 1466of the array. 1467 1468* Menu: 1469 1470* Command line option variables:: 1471* User configuration file:: 1472 1473 1474File: dejagnu.info, Node: Command line option variables, Next: User configuration file, Up: Configuration file values 1475 14764.5.1 Command line option variables 1477----------------------------------- 1478 1479In the user editable second section of the *Note User configuration 1480file:: you can not only override the configuration variables captured 1481in the first section, but also specify default values for all of the 1482`runtest' command line options. Excepting `--debug', `--help', and 1483`--version', each command line option has an associated Tcl variable. 1484Use the Tcl `set' command to specify a new default value (as for the 1485configuration variables). The following table describes the 1486correspondence between command line options and variables you can set 1487in `site.exp'. Refer to *Note Invoking runtest::, for explanations of 1488the command-line options. 1489 1490Option Tcl variable Description 1491------------------------------------------------------------------------------- 1492-a, -all all_flag display all test results if set 1493-build build_triplet system triplet for the build host 1494-dir cmdline_dir_to_runrun only tests in the specified directory 1495-global_init global_init_file file name for global init file in `libdir' 1496-host host_triplet system triplet for the host 1497-host_board host_board host board definition to use 1498-ignore ignoretests do not run the specified tests 1499-local_init local_init_file file name for local init file in `objdir' 1500-log_dialog log_dialog emit Expect output to standard output 1501-outdir outdir directory for `.sum' and `.log' files 1502-objdir objdir directory for pre-compiled binaries 1503-reboot reboot reboot the target if set to 1 1504-srcdir srcdir directory of test subdirectories 1505-target target_triplet system triplet for the target 1506-target_board target_list list of target boards to run tests on 1507-tool tool name of tool to test (selects tests to run) 1508-tool_exec TOOL_EXECUTABLE path to the executable to test 1509-tool_opts TOOL_OPTIONS additional options to pass to the tool 1510-tool_root_dir tool_root_dir tool root directory 1511-v, -verbose verbose verbosity level greater than or equal to 0 1512 1513 1514File: dejagnu.info, Node: User configuration file, Prev: Command line option variables, Up: Configuration file values 1515 15164.5.2 Per-user configuration file (.dejagnurc) 1517---------------------------------------------- 1518 1519The per-user configuration file is named `.dejagnurc' in the user's 1520home directory. It is used to customize the behaviour of `runtest' for 1521each user - typically the user's preference for log verbosity, and for 1522storing any experimental Tcl procedures. An example `~/.dejagnurc' 1523file looks like: 1524 1525 *Example .dejagnurc* 1526 1527 set all_flag 1 1528 set RLOGIN /usr/ucb/rlogin 1529 set RSH /usr/local/sbin/ssh 1530 1531 Here `all_flag' is set so that I see all the test cases that PASS 1532along with the ones that FAIL. I also set `RLOGIN' to the BSD 1533(non-Kerberos) version. I also set `RSH' to the SSH secure shell, as 1534rsh is mostly used to test Unix machines within a local network. 1535 1536 1537File: dejagnu.info, Node: Extending DejaGnu, Next: Unit testing, Prev: Customizing DejaGnu, Up: Top 1538 15395 Extending DejaGnu 1540******************* 1541 1542This chapter describes how to extend DejaGnu with new testsuites, new 1543tools, new targets and new boards. 1544 1545* Menu: 1546 1547* Adding a new testsuite:: 1548* Adding a new tool:: 1549* Adding a new target:: 1550* Adding a new board:: 1551* Board file values:: 1552* Writing a test case:: 1553* Debugging a test case:: 1554* Adding a test case to a testsuite:: 1555* Test case special variables: Test case variables. 1556 1557 1558File: dejagnu.info, Node: Adding a new testsuite, Next: Adding a new tool, Up: Extending DejaGnu 1559 15605.1 Adding a new testsuite 1561========================== 1562 1563The testsuite for a new package should always be located in the source 1564directory of that package. DejaGnu requires this directory to be named 1565`testsuite'. Under this directory, the test cases go in various 1566subdirectories whose name begins with the tool name. The organization 1567of the various testsuite subdirectories is up to you. For a tool named 1568`gdb', for instance, each subdirectory containing tests must start with 1569`gdb.'. 1570 1571 1572File: dejagnu.info, Node: Adding a new tool, Next: Adding a new target, Prev: Adding a new testsuite, Up: Extending DejaGnu 1573 15745.2 Adding a new tool 1575===================== 1576 1577In general, the best way to learn how to write code, or even prose, is 1578to read something similar. This principle applies to test cases and to 1579testsuites. Unfortunately, well-established testsuites have a way of 1580developing their own conventions: as test writers become more 1581experienced with DejaGnu and with Tcl, they accumulate more utilities, 1582and take advantage of more and more features of Expect and Tcl in 1583general. Inspecting such established testsuites may make the prospect 1584of creating an entirely new testsuite appear overwhelming. 1585Nevertheless, it is straightforward to start a new testsuite. 1586 1587 To help orient you further in this task, here is an outline of the 1588steps to begin building a testsuite for a program example. 1589 1590 Create or select a directory to contain your new collection of tests. 1591Change into that directory (shown here as `testsuite'): 1592 1593 Create a `configure.in' file in this directory, to control 1594configuration-dependent choices for your tests. So far as DejaGnu is 1595concerned, the important thing is to set a value for the variable 1596`target_abbrev'; this value is the link to the init file you will write 1597soon. (For simplicity, we assume the environment is Unix, and use 1598_unix_ as the value.) 1599 1600 What else is needed in `configure.in' depends on the requirements of 1601your tool, your intended test environments, and which configure system 1602you use. This example is a minimal `configure.ac' for use with GNU 1603Autoconf. 1604 16055.2.1 Sample Makefile.in Fragment 1606--------------------------------- 1607 1608Create `Makefile.in' (if using Autoconf), or `Makefile.am' (if using 1609Automake), the source file used by configure to build your `Makefile'. 1610If you are using GNU Automake.just add the keyword _dejagnu_ to the 1611_AUTOMAKE_OPTIONS_ variable in your `Makefile.am' file. This will add 1612all the `Makefile' support needed to run DejaGnu, and support the *Note 1613make check: Make Check. target. 1614 1615 You also need to include two targets important to DejaGnu: _check_, 1616to run the tests, and _site.exp_, to set up the Tcl copies of 1617configuration-dependent values. This is called the *Note Local 1618configuration file:: The _check_ target must invoke the `runtest' 1619program to run the tests. 1620 1621 The _site.exp_ target should usually set up (among other things) the 1622_$tool_ variable for the name of your program. If the local `site.exp' 1623file is setup correctly, it is possible to execute the tests by merely 1624typing `runtest' on the command line. 1625 1626 # Look for a local version of DejaGnu, otherwise use one in the path 1627 RUNTEST = `if test -f $(top_srcdir)/../dejagnu/runtest; then \ 1628 echo $(top_srcdir) ../dejagnu/runtest; \ 1629 else \ 1630 echo runtest; \ 1631 fi` 1632 1633 # Flags to pass to runtest 1634 RUNTESTFLAGS = 1635 1636 # Execute the tests 1637 check: site.exp all 1638 $(RUNTEST) $(RUNTESTFLAGS) --tool ${example} --srcdir $(srcdir) 1639 1640 # Make the local config file 1641 site.exp: ./config.status Makefile 1642 @echo "Making a new config file..." 1643 -@rm -f ./tmp? 1644 @touch site.exp 1645 1646 -@mv site.exp site.bak 1647 @echo "## these variables are automatically generated by make ##" > ./tmp0 1648 @echo "# Do not edit here. If you wish to override these values" >> ./tmp0 1649 @echo "# add them to the last section" >> ./tmp0 1650 @echo "set host_os ${host_os}" >> ./tmp0 1651 @echo "set host_alias ${host_alias}" >> ./tmp0 1652 @echo "set host_cpu ${host_cpu}" >> ./tmp0 1653 @echo "set host_vendor ${host_vendor}" >> ./tmp0 1654 @echo "set target_os ${target_os}" >> ./tmp0 1655 @echo "set target_alias ${target_alias}" >> ./tmp0 1656 @echo "set target_cpu ${target_cpu}" >> ./tmp0 1657 @echo "set target_vendor ${target_vendor}" >> ./tmp0 1658 @echo "set host_triplet ${host_canonical}" >> ./tmp0 1659 @echo "set target_triplet ${target_canonical}">>./tmp0 1660 @echo "set tool binutils" >> ./tmp0 1661 @echo "set srcdir ${srcdir}" >> ./tmp0 1662 @echo "set objdir `pwd`" >> ./tmp0 1663 @echo "set ${examplename} ${example}" >> ./tmp0 1664 @echo "## All variables above are generated by configure. Do Not Edit ##" >> ./tmp0 1665 @cat ./tmp0 > site.exp 1666 @sed < site.bak \ 1667 -e '1,/^## All variables above are.*##/ d' \ 1668 >> site.exp 1669 -@rm -f ./tmp? 1670 16715.2.2 Simple tool init file for batch programs 1672---------------------------------------------- 1673 1674The tool init file may be placed in `testsuite/lib' or in 1675`testsuite/lib/tool' and must be named `TOOL.exp', where TOOL is the 1676name of the tool to be tested. For this example, we will use the name 1677`example' for the tool name, which means that the tool init file must 1678be named `example.exp'. If the program being tested is not 1679interactive, you can get away with this minimal tool init file to begin 1680with: 1681 1682 proc example_exit {} {} 1683 proc example_version {} {} 1684 1685 By convention, the file name for the executable for a tool should be 1686stored in a global variable with the same name as the tool, but in all 1687uppercase. For our example program `example', the name of the program 1688under test should be stored in `EXAMPLE'. 1689 16905.2.3 Simple tool init file for interactive programs 1691---------------------------------------------------- 1692 1693If the program being tested is interactive, however, you might as well 1694define a _start_ routine and invoke it by using a tool init file like 1695this: 1696 1697 proc example_exit {} {} 1698 proc example_version {} {} 1699 1700 proc example_start {} { 1701 global EXAMPLE 1702 spawn $EXAMPLE 1703 expect { 1704 -re "" {} 1705 } 1706 } 1707 1708 # Start the program running we want to test 1709 example_start 1710 1711 Create a directory whose name begins with your tool's name, to 1712contain tests. For example, if the tool name is `example', then the 1713directories all need to start with `example.'. Create a sample test 1714file ending in `.exp'. You can name the file `first-try.exp'. To 1715begin with, just write one line of Tcl code to issue a message: 1716 1717 send_user "Testing: one, two...\n" 1718 17195.2.4 Testing A New Tool Config 1720------------------------------- 1721 1722Back in the `testsuite' (top level) directory, run `configure'. 1723Typically you do this while in the build directory. You are now ready 1724to type `make check' or `runtest'. You should see something like this: 1725 1726 Test Run By bje on Sat Nov 14 15:08:54 AEDT 2015 1727 1728 === example tests === 1729 1730 Running ./example.0/first-try.exp ... 1731 Testing: one, two... 1732 1733 === example Summary === 1734 1735 There is no output in the summary, because so far the example does 1736not call any of the procedures that report a test outcome. 1737 1738 Write some real tests. For an interactive tool, you should probably 1739write a real exit routine in fairly short order. In any case, you 1740should also write a real version routine soon. 1741 1742 1743File: dejagnu.info, Node: Adding a new target, Next: Adding a new board, Prev: Adding a new tool, Up: Extending DejaGnu 1744 17455.3 Adding a new target 1746======================= 1747 1748DejaGnu has some additional requirements for target support, beyond the 1749general-purpose provisions of a `configure' script. DejaGnu must 1750actively communicate with the target, rather than simply generating or 1751managing code for the target architecture. Therefore, each tool 1752requires an initialization module for each target. For new targets, 1753you must supply a few Tcl procedures to adapt DejaGnu to the target. 1754 1755 Usually the best way to write a new initialization module is to edit 1756an existing initialization module; some trial and error will be 1757required. If necessary, you can use the `--debug' option to see what 1758is really going on. 1759 1760 When you code an initialization module, be generous in printing 1761information using the `verbose' procedure. In cross-development 1762environments, most of the work is in getting the communications right. 1763Code for communicating via TCP/IP networks or serial lines is available 1764in a DejaGnu library files such as `lib/telnet.exp'. 1765 1766 If you suspect a communication problem, try running the connection 1767interactively from Expect. (There are three ways of running Expect as 1768an interactive interpreter. You can run Expect with no arguments, and 1769control it completely interactively; or you can use `expect -i' 1770together with other command-line options and arguments; or you can run 1771the command `interpreter' from any Expect procedure. Use `return' to 1772get back to the calling procedure (if any), or `return -tcl' to make 1773the calling procedure itself return to its caller; use `exit' or 1774end-of-file to leave Expect altogether.) Run the program whose name is 1775recorded in `$connectmode', with the arguments in `$targetname', to 1776establish a connection. You should at least be able to get a prompt 1777from any target that is physically connected. 1778 1779 1780File: dejagnu.info, Node: Adding a new board, Next: Board file values, Prev: Adding a new target, Up: Extending DejaGnu 1781 17825.4 Adding a new board 1783====================== 1784 1785Adding a new board consists of creating a new board configuration file. 1786Examples are in `dejagnu/baseboards'. Usually to make a new board 1787file, it's easiest to copy an existing one. It is also possible to 1788have your file be based on a _baseboard_ file with only one or two 1789changes needed. Typically, this can be as simple as just changing the 1790linker script. Once the new baseboard file is done, add it to the 1791`boards_DATA' list in the `dejagnu/baseboards/Makefile.am', and 1792regenerate the Makefile.in using automake. Then just rebuild and 1793install DejaGnu. You can test it by: 1794 1795 There is a crude inheritance scheme going on with board files, so you 1796can include one board file into another, The two main procedures used 1797to do this are `load_generic_config' and `load_base_board_description'. 1798The generic configuration file contains other procedures used for a 1799certain class of target. The board description file is where the board 1800specific settings go. Commonly there are similar target environments 1801with just different processors. 1802 1803 *Testing a New Board Configuration File* 1804 1805 make check RUNTESTFLAGS="--target_board=newboardfile". 1806 1807 Here's an example of a board configuration file. There are several 1808_helper procedures_ used in this example. A helper procedure is one 1809that look for a tool of files in commonly installed locations. These 1810are mostly used when testing in the build tree, because the executables 1811to be tested are in the same tree as the new DejaGnu files. The helper 1812procedures are the ones in brackets, which indicates a Tcl procedure 1813call. 1814 1815 *Example Board Configuration File* 1816 1817 # Load the generic configuration for this board. This will define a basic 1818 # set of routines needed by the tool to communicate with the board. 1819 load_generic_config "sim" 1820 1821 # basic-sim.exp is a basic description for the standard Cygnus simulator. 1822 load_base_board_description "basic-sim" 1823 1824 # The compiler used to build for this board. This has *nothing* to do 1825 # with what compiler is tested if we're testing gcc. Further, this is 1826 # the default, so this line is optional for most boards. 1827 set_board_info compiler "[find_gcc]" 1828 1829 # We only support newlib on this target. 1830 # However, we include libgloss so we can find the linker scripts. 1831 set_board_info cflags "[newlib_include_flags] [libgloss_include_flags]" 1832 set_board_info ldflags "[newlib_link_flags]" 1833 1834 # No linker script for this board. 1835 set_board_info ldscript "-Tsim.ld" 1836 1837 # The simulator doesn't return exit statuses and we need to indicate this. 1838 set_board_info needs_status_wrapper 1 1839 1840 # Can't pass arguments to this target. 1841 set_board_info noargs 1 1842 1843 # No signals. 1844 set_board_info gdb,nosignals 1 1845 1846 # And it can't call functions. 1847 set_board_info gdb,cannot_call_functions 1 1848 1849 1850File: dejagnu.info, Node: Board file values, Next: Writing a test case, Prev: Adding a new board, Up: Extending DejaGnu 1851 18525.5 Board configuration file values 1853=================================== 1854 1855The following fields are in the `board_info' array. These are set by 1856the `set_board_info' procedure (or `add_board_info' procedure for 1857appending to lists). Both procedures take a field name and a value for 1858the field (or is added to the field), respectively. Some common board 1859info fields are shown below. 1860 1861*Field* *Example *Description* 1862 value* 1863compiler `[find_gcc]' The path to the compiler to use. 1864cflags `-mca' Compilation flags for the compiler. 1865ldflags `[libgloss_link_flags]Linking flags for the compiler. 1866 [newlib_link_flags]' 1867ldscript `-Wl,-Tidt.ld' The linker script to use when cross 1868 compiling. 1869libs `-lgcc' Any additional libraries to link in. 1870shell_prompt `cygmon>' The command prompt of the remote shell. 1871hex_startaddr `0xa0020000' The Starting address as a string. 1872start_addr 0xa0008000 The starting address as a value. 1873startaddr `a0020000' 1874exit_statuses_bad1 Whether there is an accurate exit status. 1875reboot_delay 10 The delay between power off and power on. 1876unreliable 1 Whether communication with the board is 1877 unreliable. 1878sim [find_sim] The path to the simulator to use. 1879objcopy $tempfil The path to the `objcopy' program. 1880support_libs `${prefix_dir}/i386-coff/'Support libraries needed for cross 1881 compiling. 1882addl_link_flags`-N' Additional link flags, rarely used. 1883remotedir `/tmp/runtest.[pid]'Directory on the remote target in which 1884 executables are downloaded and executed. 1885 1886 These fields are used by the GCC and GDB tests, and are mostly only 1887useful to somewhat trying to debug a new board file for one of these 1888tools. Many of these are used only by a few testcases, and their 1889purpose is esoteric. These are listed with sample values as a guide to 1890better guessing if you need to change any of these. 1891 1892 *Board Info Fields For GCC & GDB* 1893 1894Field Sample Value Description 1895strip $tempfile Strip the executable of 1896 symbols. 1897gdb_load_offset "0x40050000" 1898gdb_protocol "remote" The GDB debugging 1899 protocol to use. 1900gdb_sect_offset "0x41000000"; 1901gdb_stub_ldscript "-Wl,-Teva-stub.ld" The linker script to 1902 use with a GDB stub. 1903gdb,noargs 1 Whether the target can 1904 take command line 1905 arguments. 1906gdb,nosignals 1 Whether there are 1907 signals on the target. 1908gdb,short_int 1 1909gdb,target_sim_options "-sparclite" Special options to pass 1910 to the simulator. 1911gdb,timeout 540 Timeout value to use 1912 for remote 1913 communication. 1914gdb_init_command "set mipsfpu none" A single command to 1915 send to GDB before the 1916 program being debugged 1917 is started. 1918gdb_init_commands "print/x \$fsr = 0x0" Same as 1919 _gdb_init_command_, 1920 except that this is a 1921 list, more commands can 1922 be added. 1923gdb_load_offset "0x12020000" 1924gdb_opts "-command gdbinit" 1925gdb_prompt "\\(gdb960\\)" The prompt GDB is using. 1926gdb_run_command "jump start" 1927gdb_stub_offset "0x12010000" 1928use_gdb_stub 1 Whether to use a GDB 1929 stub. 1930wrap_m68k_aout 1 1931gcc,no_label_values 1 1932gcc,no_trampolines 1 1933gcc,no_varargs 1 1934gcc,stack_size 16384 Stack size to use with 1935 some GCC testcases. 1936ieee_multilib_flags "-mieee" 1937is_simulator 1 1938needs_status_wrapper 1 1939no_double 1 1940no_long_long 1 1941noargs 1 1942target_install {sh-hms} 1943 1944 1945File: dejagnu.info, Node: Writing a test case, Next: Debugging a test case, Prev: Board file values, Up: Extending DejaGnu 1946 19475.6 Writing a test case 1948======================= 1949 1950The easiest way to prepare a new test case is to base it on an existing 1951one for a similar situation. There are two major categories of tests: 1952batch-oriented and interactive. Batch-oriented tests are usually 1953easier to write. 1954 1955 The GCC tests are a good example of batch-oriented tests. All GCC 1956tests consist primarily of a call to a single common procedure, since 1957all the tests either have no output, or only have a few warning 1958messages when successfully compiled. Any non-warning output 1959constitutes a test failure. All the C code needed is kept in the test 1960directory. The test driver, written in Tcl, need only get a listing of 1961all the C files in the directory, and compile them all using a generic 1962procedure. This procedure and a few others supporting for these tests 1963are kept in the library module `lib/c-torture.exp' of the GCC 1964testsuite. Most tests of this kind use very few Expect features, and 1965are coded almost purely in Tcl. 1966 1967 Writing the complete suite of C tests, then, consisted of these 1968steps: 1969 1970 * Copying all the C code into the test directory. These tests were 1971 based on the C-torture test created by Torbjorn Granlund (on 1972 behalf of the Free Software Foundation) for GCC development. 1973 1974 * Writing (and debugging) the generic Tcl procedures for compilation. 1975 1976 * Writing the simple test driver: its main task is to search the 1977 directory (using the Tcl procedure _glob_ for filename expansion 1978 with wildcards) and call a Tcl procedure with each filename. It 1979 also checks for a few errors from the testing procedure. 1980 1981 Testing interactive programs is intrinsically more complex. Tests 1982for most interactive programs require some trial and error before they 1983are complete. 1984 1985 However, some interactive programs can be tested in a simple fashion 1986reminiscent of batch tests. For example, prior to the creation of 1987DejaGnu, the GDB distribution already included a wide-ranging testing 1988procedure. This procedure was very robust, and had already undergone 1989much more debugging and error checking than many recent DejaGnu test 1990cases. Accordingly, the best approach was simply to encapsulate the 1991existing GDB tests, for reporting purposes. Thereafter, new GDB tests 1992built up a family of Tcl procedures specialized for GDB testing. 1993 19945.6.1 Hints on writing a test case 1995---------------------------------- 1996 1997To preserve basic sanity, no should test ever pass if there was any 1998kind of problem in the test case. To take an extreme case, tests that 1999pass even when the tool will not spawn are misleading. Ideally, a test 2000in this sort of situation should not fail either. Instead, print an 2001error message by calling one of the DejaGnu procedures `perror' or 2002`warning'. Note that using `perror' will cause the next text result to 2003be reported as `UNRESOLVED', so printing an error and allowing the test 2004to fail is a good option. 2005 2006 If you have trouble understanding why a pattern does not match the 2007program output, try using the `--debug' option to `runtest', and 2008examine the debug log carefully. 2009 2010 If you use glob patterns, you will need to escape any `*', `?', `[', 2011`]', and `\' characters that are meant to match literally. If you use 2012regular expressions, see the `re_syntax(n)' manual page from Tcl for 2013the syntax details, and be sure to understand what punctuation 2014characters match literally and what characters have special meanings in 2015regular expressions. 2016 2017 Tcl has a few options for quoting; the most notable are `{}' and 2018`""'. These quotes behave differently: `{}' must balance, while `""' 2019performs various interpolations. In `{}' quotes, unbalanced `{' or `}' 2020characters must be escaped with `\' and these escapes are _not_ removed; 2021fortunately, backslash-escaped braces match literal braces in Tcl 2022regular expressions. In `""' quotes, any embedded `"' characters must 2023be escaped, a literal `$' begins a variable substitution, and unescaped 2024`[]' introduce a Tcl command substitution. 2025 2026Synchronization with the tested program 2027....................................... 2028 2029A DejaGnu testsuite executes concurrently with the programs that it 2030tests. As a result, DejaGnu may see parts of the tested program's 2031output while the tested program is still producing more output. Expect 2032patterns must be written to handle the possibility that incomplete 2033output from the tested program will be considered for matching. 2034 2035 Expect reads the output from the tested program into an internal 2036matching buffer and removes everything from the start of the buffer to 2037the end of the match when a match is found. Any given character can be 2038matched at most once, or skipped if a match is found starting later in 2039the buffer or the buffer reaches its capacity. Anything left in the 2040buffer after the end of the match remains in the buffer and is 2041considered for the next `expect' command. If `expect' is invoked and 2042no patterns match, Expect waits for more text to arrive. New text is 2043appended to the buffer as it is read. If the buffer reaches its 2044capacity, the entire contents of the buffer are discarded and Expect 2045resumes reading. 2046 2047 In Expect patterns, the regular expression anchors `^' and `$' match 2048at the beginning and end of the _buffer_, not at line boundaries. The 2049`$' anchor must be used with care because it will match at the end of 2050what Expect _has_ read, but the program may have produced more output 2051that Expect _has not yet_ read. Similarly, regular expressions ending 2052with the `*' quantifier can potentially match a prefix of the intended 2053text, only for the rest to arrive shortly thereafter. 2054 2055 Maintaining synchronization with the tested program is easier if the 2056patterns match all of the output generated by the tested program; this 2057is called closure. 2058 2059 For interactive programs, a prompt is usually a good synchronization 2060point, provided that the program's prompt can be uniquely recognized. 2061Since the prompt is usually the last output until the program receives 2062further input, the `$' anchor can be useful here. 2063 2064 If the output from the tested program is organized into lines, 2065matching end-of-line using `\n' is usually a good way to process one 2066line at a time. Note that terminal settings may result in the 2067insertion of additional `\r' characters, usually translating `\n' to 2068`\r\n'. 2069 2070 Be careful not to neglect output generated by setup rather than by 2071the interesting parts of a test case. For example, while testing GDB, a 2072`set height 0\n' command is issued. The purpose is simply to make sure 2073GDB never calls a paging program. The `set height' command in GDB does 2074not generate any output; but running any command makes GDB issue a new 2075`(gdb) ' prompt. If there were no `expect' command to match this 2076prompt, the `(gdb) ' prompt will remain in the buffer and begin the 2077text seen by the next `expect' command--which might make that pattern 2078fail to match. 2079 2080Priority of Expect patterns 2081........................... 2082 2083Be particularly careful about how you write the patterns. Expect 2084attempts to match each pattern in the order that they are written in 2085the `expect' command. Unless a regexp pattern is anchored at the 2086beginning of the buffer, Expect can search ahead for a match for a 2087pattern that appears earlier in the `expect' command and skip over text 2088that would match a later pattern. _The text thus skipped is 2089discarded._ This is a source of very hard to trace bugs, especially 2090when reading input from batch-oriented unit tests. 2091 2092 For example, consider a simple model once used by the DejaGnu 2093testsuite for unit testing. In this example, a test has failed, but 2094the tests before and after it have passed. First the relevant input to 2095DejaGnu: 2096 2097 PASSED: foo 2098 FAILED: bar 2099 PASSED: baz 2100 2101 The test script is reading this with two Expect patterns, simplified 2102for this example by omitting handling of the actual messages and other 2103possible results: 2104 2105 expect { 2106 -re {PASSED: [^\r\n]+[\r\n]+} { pass ... } 2107 -re {FAILED: [^\r\n]+[\r\n]+} { fail ... } 2108 } 2109 2110 At every cycle, Expect attempts to match each pattern in the order 2111that they are written against the available input. If DejaGnu is 2112processing the input as quickly as it arrives, this example will 2113actually work. However, if the system scheduler sets DejaGnu aside for 2114a bit, or the external program produces output in a burst, Expect can 2115find that its input buffer contains the text in the first example above 2116all at once as the cycle begins. 2117 2118 If this occurs, Expect will first attempt to match `{PASSED: 2119[^\r\n]+[\r\n]+}' against the input and will succeed, since the input 2120begins with `PASSED: foo'. The `pass' procedure is called and the test 2121result recorded. Expect then starts a new matching cycle. 2122 2123 If the input had been presented one line at a time, the expected 2124result would occur: the `{FAILED: [^\r\n]+[\r\n]+}' pattern would match 2125and the test driver would work correctly. But we are considering the 2126case where all three lines arrived "at once" so we must examine what 2127Expect will do in this case. After the first line has been processed, 2128the Expect buffer now contains: 2129 2130 FAILED: bar 2131 PASSED: baz 2132 2133 Expect again attempts to match each pattern in order. Expect will 2134attempt to match `{PASSED: [^\r\n]+[\r\n]+}' before attempting to match 2135`{FAILED: [^\r\n]+[\r\n]+}' and the first attempt succeeds because the 2136pattern is not anchored. The `FAILED: bar' message is simply discarded 2137when Expect finds the later `PASSED:baz' message in the buffer. 2138 2139 How to prevent this? There are two ways: either group all of your 2140test matches into a single regexp using alternation, or ensure that all 2141patterns can match only at the start of Expect's buffer. Both options 2142can be made to work. Grouping all status results into a single regexp 2143allows some other unspecified text to still be silently discarded, 2144while ensuring that all patterns are anchored absolutely requires 2145closure, as any unmatched text will cause Expect to run out of buffer 2146space. Expect discards the entire buffer when this occurs. 2147 2148 2149File: dejagnu.info, Node: Debugging a test case, Next: Adding a test case to a testsuite, Prev: Writing a test case, Up: Extending DejaGnu 2150 21515.7 Debugging a test case 2152========================= 2153 2154These are the kinds of debugging information available from DejaGnu: 2155 2156 * Output controlled by test scripts themselves, explicitly allowed 2157 for by the test author. This kind of debugging output appears in 2158 the detailed output recorded in the DejaGnu log file. To do the 2159 same for new tests, use the `verbose' procedure (which in turn 2160 uses the Tcl variable `verbose') to control how much output to 2161 generate. This will make it easier for other people running the 2162 test to debug it if necessary. If `verbose' is zero, there should 2163 be no output other than the output from the framework (eg. FAIL). 2164 Then, to whatever extent is appropriate for the particular test, 2165 allow successively higher values of `verbose' to generate more 2166 information. Be kind to other programmers who use your tests - 2167 provide plenty of debugging information. 2168 2169 * Output from the internal debugging functions of Tcl and Expect. 2170 There is a command line options for each; both forms of debugging 2171 output are recorded in the file `dbg.log' in the current directory. 2172 2173 Use `--debug' for information from Expect. It logs how Expect 2174 attempts to match the tool output with the patterns specified. 2175 This can be very helpful while developing test scripts, since it 2176 shows precisely the characters received. Iterating between the 2177 latest attempt at a new test script and the corresponding 2178 `dbg.log' can allow you to create the final patterns by "cut and 2179 paste". This is sometimes the best way to write a test case. 2180 2181 * Use `--strace' to see more detail from Tcl. This logs how Tcl 2182 procedure definitions are expanded as they execute. The trace 2183 level argument controls the depth of definitions expanded. 2184 2185 * If the value of `verbose' is 3 or greater (`runtest -v -v -v'), 2186 DejaGnu activates the Expect command `log_user'. This command 2187 prints all Expect actions to standard output, to the `.log' file 2188 and, if `--debug' is given, to `dbg.log'. 2189 2190 2191File: dejagnu.info, Node: Adding a test case to a testsuite, Next: Test case variables, Prev: Debugging a test case, Up: Extending DejaGnu 2192 21935.8 Adding a test case to a testsuite 2194===================================== 2195 2196There are two slightly different ways to add a test case. One is to 2197add the test case to an existing directory. The other is to create a 2198new directory to hold your test. The existing test directories 2199represent several styles of testing, all of which are slightly 2200different. Examine the testsuite subdirectories for the tool of 2201interest to see which approach is most suitable. 2202 2203 Adding a GCC test may be very simple: just add the source file to any 2204test directory beginning with `gcc.' and it will be tested on the next 2205test run. 2206 2207 Adding a test by creating a new directory involves: 2208 2209 1. Create the new directory. All subdirectory names begin with the 2210 name of the tool to test; e.g. G++ tests might be in a directory 2211 called `g++.other'. There can be multiple testsuite 2212 subdirectories with the same tool name prefix. 2213 2214 2. Add the new test case to the directory, as above. 2215 2216 2217File: dejagnu.info, Node: Test case variables, Prev: Adding a test case to a testsuite, Up: Extending DejaGnu 2218 22195.9 Test case special variables 2220=============================== 2221 2222There are special variables that contain other information from 2223DejaGnu. Your test cases can inspect these variables, as well as the 2224variables saved in `site.exp'. These variables should never be changed. 2225 2226`$prms_id' 2227 The bug tracking system (eg. PRMS/GNATS) number identifying a 2228 corresponding bug report (_0_ if you do not specify it). 2229 2230`$bug_id' 2231 An optional bug ID, perhaps a bug identification number from 2232 another organization (_0_ if you do not specify it). 2233 2234`$subdir' 2235 The subdirectory for the current test case. 2236 2237`$exec_output' 2238 This is the output from a `${tool}_load' command. This only 2239 applies to tools like GCC and GAS which produce an object file that 2240 must in turn be executed to complete a test. 2241 2242`$comp_output' 2243 This is the output from a `${tool}_start' command. This is 2244 conventionally used for batch-oriented programs, like GCC and GAS, 2245 that may produce interesting output (warnings, errors) without 2246 further interaction. 2247 2248`$expect_out(buffer)' 2249 The output from the last command. This is an internal variable 2250 set by Expect. More information can be found in the Expect manual. 2251 2252 2253File: dejagnu.info, Node: Unit testing, Next: Built-in Procedures, Prev: Extending DejaGnu, Up: Top 2254 22556 Unit testing 2256************** 2257 2258* Menu: 2259 2260* What is unit testing?:: Unit testing and system testing. 2261* Running unit tests:: 2262* DejaGnu unit test protocol:: DejaGnu native unit testing protocol. 2263* C unit testing API:: 2264* C++ unit testing API:: 2265 2266 2267File: dejagnu.info, Node: What is unit testing?, Next: Running unit tests, Prev: Unit testing, Up: Unit testing 2268 22696.1 What is unit testing? 2270========================= 2271 2272Most regression testing as done by DejaGnu is system testing: the 2273complete application is tested all at once. Unit testing is for 2274testing single files, or small libraries. In this case, each file is 2275linked with a test case in C or C++, and each function or class and 2276method is tested in turn, with the test case having to check private 2277data or global variables to see if the function or method worked. 2278 2279 This works particularly well for testing APIs at a level where it is 2280easier to debug them, than by needing to trace through the entire 2281application. Also if there is a specification for the API to be 2282tested, the testcase can also function as a compliance test. 2283 2284 2285File: dejagnu.info, Node: Running unit tests, Next: DejaGnu unit test protocol, Prev: What is unit testing?, Up: Unit testing 2286 22876.2 Running unit tests 2288====================== 2289 2290The native DejaGnu unit testing support is provided by a library module 2291`dejagnu.exp' and the procedure `host_execute' is called by testsuite 2292code to run unit tests. 2293 2294 host_execute program arguments 2295 2296 The `host_execute' procedure runs program, passing arguments on the 2297command line, and examines the output for test result messages 2298according to the DejaGnu unit testing protocol. 2299 2300 If successful, the return value is an empty string. Otherwise, an 2301error message is returned. 2302 2303 2304File: dejagnu.info, Node: DejaGnu unit test protocol, Next: C unit testing API, Prev: Running unit tests, Up: Unit testing 2305 23066.3 DejaGnu unit test protocol 2307============================== 2308 2309DejaGnu spawns a unit test program and reads that program's output. 2310Arguments for the unit test program can be specified in the testsuite. 2311 2312 Unit test programs may produce any output for the benefit of a 2313developer running them directly or reading the DejaGnu log, but output 2314matching the Tcl regexp `{\n\t[][[:upper:]]*:}' (a tab character at the 2315beginning of a line, followed by any sequence of uppercase letters and 2316square brackets, followed by a colon) should be considered reserved for 2317future extension. Future versions of DejaGnu will interpret more lines 2318matching this pattern as additional unit test information. 2319 2320 -| NOTE: text 2321 2322 This will cause text to be printed at verbose levels 2 and higher. 2323 2324 -| PASSED: name 2325 2326 -| FAILED: name 2327 2328 -| XPASSED: name 2329 2330 -| XFAILED: name 2331 2332 -| UNTESTED: name 2333 2334 -| UNRESOLVED: name 2335 2336 These indicate simple test results. 2337 2338 Note that all output from a unit test program, including the lines 2339recognized and interpreted by DejaGnu, appears in the log. 2340 2341 2342File: dejagnu.info, Node: C unit testing API, Next: C++ unit testing API, Prev: DejaGnu unit test protocol, Up: Unit testing 2343 23446.4 C unit testing API 2345====================== 2346 2347The C API is provided in the `dejagnu.h' header file. This header 2348provides a self-contained implementation. For convenience, the 2349`totals()' function can be called at the end of the unit test program 2350to output summary totals. DejaGnu counts the test results 2351independently and will operate correctly even if `totals()' is never 2352invoked. 2353 2354 All of the functions that take a `msg' parameter use a C `char *' 2355that is the message to be displayed. All of the functions that display 2356a message accept a `printf'-style format string and variable arguments. 2357 2358 * `note' emits a note that will be displayed at verbose level 2 or 2359 higher. 2360 2361 note(msg, ...); 2362 2363 * `pass' prints a message for a successful test completion. 2364 2365 pass(msg, ...); 2366 2367 * `fail' prints a message for an unsuccessful test completion. 2368 2369 fail(msg, ...); 2370 2371 * `xfail' prints a message for an expected unsuccessful test 2372 completion. 2373 2374 xfail(msg, ...); 2375 2376 * `xpass' prints a message for an unexpected successful test 2377 completion. 2378 2379 xpass(msg, ...); 2380 2381 * `untested' prints a placeholder message for a test case that is 2382 not yet implemented or that could not be run for some reason. 2383 2384 untested(msg, ...); 2385 2386 * `unresolved' prints a message for a test case that was run, but 2387 did not produce a clear result. These output states require a 2388 human to look over the results to determine what happened. 2389 2390 unresolved(msg, ...); 2391 2392 * `totals' prints out the total counts of all of the test results as 2393 a convenience when running the unit test program directly. DejaGnu 2394 does not use this information and instead counts the results 2395 independently. 2396 2397 totals(); 2398 2399 2400 2401File: dejagnu.info, Node: C++ unit testing API, Prev: C unit testing API, Up: Unit testing 2402 24036.5 C++ unit testing API 2404======================== 2405 2406The C++ API is also provided in the `dejagnu.h' header file. This 2407header provides a self-contained implementation. For convenience, the 2408`totals()' method outputs summary totals to be used at the end of unit 2409test program. DejaGnu does not depend on this summary and counts the 2410test results independently. 2411 2412 All of the methods that take a `msg' parameter use a STL string as 2413the message to be displayed. There currently is no support for 2414formatted output in the C++ API; build the desired string before 2415passing it to these functions. 2416 2417 Note that the C API is also available in C++ unit test programs; 2418using both will cause confusion because each `TestState' object carries 2419its own set of summary counters, while the C API has an independent 2420global set of summary counters. 2421 2422 The `TestState' class supports the following instance methods: 2423 2424 * `pass' prints a message for a successful test completion. 2425 2426 TestState::pass(msg); 2427 2428 * `fail' prints a message for an unsuccessful test completion. 2429 2430 TestState::fail(msg); 2431 2432 * `xfail' prints a message for an expected unsuccessful test 2433 completion. 2434 2435 TestState::xfail(msg); 2436 2437 * `xpass' prints a message for an unexpected successful test 2438 completion. 2439 2440 TestState::xpass(msg); 2441 2442 * `untested' prints a placeholder message for a test case that is 2443 not yet implemented or that could not be run for some reason. 2444 2445 TestState::untested(msg); 2446 2447 * `unresolved' prints a message for a test case that was run, but 2448 did not produce a clear result. These output states require a 2449 human to look over the results to determine what happened. 2450 2451 TestState::unresolved(msg); 2452 2453 * `totals' prints out the total counts of all of the test results as 2454 a convenience when running the unit test program directly. DejaGnu 2455 does not use this information and instead counts the results 2456 independently. 2457 2458 In the C++ API, this method is automatically called when a 2459 `TestState' instance is destroyed. 2460 2461 TestState::totals(); 2462 2463 2464 2465File: dejagnu.info, Node: Built-in Procedures, Next: GNU Free Documentation License, Prev: Unit testing, Up: Top 2466 2467Appendix A Built-in Procedures 2468****************************** 2469 2470DejaGnu provides these Tcl procedures. 2471 2472* Menu: 2473 2474* Core Internal Procedures:: 2475* Procedures For Remote Communication:: 2476* Procedures For Using Utilities to Connect: connprocs. 2477* Procedures For Target Boards:: 2478* Target Database Procedures: target database library file. 2479* Platform Dependent Procedures: platform dependent procedures. 2480* Utility Procedures:: 2481* Libgloss, a free board support package (BSP): Libgloss. 2482* Debugging Procedures:: 2483 2484 2485File: dejagnu.info, Node: Core Internal Procedures, Next: Procedures For Remote Communication, Up: Built-in Procedures 2486 2487A.1 Core Internal Procedures 2488============================ 2489 2490* Menu: 2491 2492* open_logs Procedure: open_logs procedure 2493* close_logs Procedure: close_logs procedure 2494* isbuild Procedure: isbuild procedure 2495* isremote Procedure: isremote procedure 2496* is_remote Procedure: is_remote procedure 2497* is3way Procedure: is3way procedure 2498* ishost Procedure: ishost procedure 2499* istarget Procedure: istarget procedure 2500* isnative Procedure: isnative procedure 2501* log_and_exit Procedure: log_and_exit procedure 2502* log_summary Procedure: log_summary procedure 2503* setup_xfail Procedure: setup_xfail procedure 2504* pass Procedure: pass procedure 2505* fail Procedure: fail procedure 2506* xpass Procedure: xpass procedure 2507* xfail Procedure: xfail procedure 2508* set_warning_threshold Procedure: set_warning_threshold procedure 2509* get_warning_threshold Procedure: get_warning_threshold procedure 2510* warning Procedure: warning procedure 2511* perror Procedure: perror procedure 2512* note Procedure: note procedure 2513* untested Procedure: untested procedure 2514* unresolved Procedure: unresolved procedure 2515* unsupported Procedure: unsupported procedure 2516* transform Procedure: transform procedure 2517* check_conditional_xfail Procedure: check_conditional_xfail procedure 2518* clear_xfail Procedure: clear_xfail procedure 2519* verbose Procedure: verbose procedure 2520* load_lib Procedure: load_lib procedure 2521* testsuite Procedure: testsuite procedure 2522* testcase procedure: testcase procedure 2523 2524 2525File: dejagnu.info, Node: open_logs procedure, Next: close_logs procedure, Up: Core Internal Procedures 2526 2527open_logs Procedure 2528................... 2529 2530Open the output logs. 2531 2532 open_logs 2533 2534 2535File: dejagnu.info, Node: close_logs procedure, Next: isbuild procedure, Prev: open_logs procedure, Up: Core Internal Procedures 2536 2537close_logs Procedure 2538.................... 2539 2540Close the output logs. 2541 2542 close_logs 2543 2544 2545File: dejagnu.info, Node: isbuild procedure, Next: isremote procedure, Prev: close_logs procedure, Up: Core Internal Procedures 2546 2547isbuild Procedure 2548................. 2549 2550Tests for a particular build host environment. If the currently 2551configured host matches the `pattern' argument, the result is _1_; 2552otherwise the result is _0_. _pattern_ must be a full three-part 2553configure triplet; in particular, you may not use the shorter aliases 2554supported by `configure' (but you can use Tcl globbing to specify a 2555range of triplets). If called with no arguments or an empty pattern, 2556this procedure returns the build system triplet. 2557 2558 isbuild pattern 2559 2560 2561File: dejagnu.info, Node: isremote procedure, Next: is_remote procedure, Prev: isbuild procedure, Up: Core Internal Procedures 2562 2563isremote Procedure 2564.................. 2565 2566Is board remote? Return a non-zero value, if so. 2567 2568 isremote board 2569 2570 This procedure is to be used instead of `is_remote'. 2571 2572 2573File: dejagnu.info, Node: is_remote procedure, Next: is3way procedure, Prev: isremote procedure, Up: Core Internal Procedures 2574 2575is_remote Procedure 2576................... 2577 2578Is board remote? Return a non-zero value, if so. 2579 2580 is_remote board 2581 2582 Note that this procedure is now deprecated. Use `isremote' instead. 2583 2584 2585File: dejagnu.info, Node: is3way procedure, Next: ishost procedure, Prev: is_remote procedure, Up: Core Internal Procedures 2586 2587is3way Procedure 2588................ 2589 2590Tests for a Canadian cross. This is when the tests will be run on a 2591remotely hosted cross-compiler. If it is a Canadian cross, then the 2592result is _1_; otherwise _0_. 2593 2594 is3way 2595 2596 2597File: dejagnu.info, Node: ishost procedure, Next: istarget procedure, Prev: is3way procedure, Up: Core Internal Procedures 2598 2599ishost Procedure 2600................ 2601 2602Tests for a particular host environment. If the currently configured 2603host matches the argument string, the result is _1_; otherwise the 2604result is _0_. _pattern_ must be a full three-part configure triplet; 2605in particular, you may not use the shorter aliases supported by 2606`configure' (but you can use Tcl globbing to specify a range of 2607triplets). If called with no arguments or an empty pattern, this 2608procedure returns the host triplet. 2609 2610 ishost pattern 2611 2612 2613File: dejagnu.info, Node: istarget procedure, Next: isnative procedure, Prev: ishost procedure, Up: Core Internal Procedures 2614 2615istarget Procedure 2616.................. 2617 2618Tests for a particular target environment. If the currently configured 2619target matches the argument string, the result is _1_ ; otherwise the 2620result is _0_. _pattern_ must be a full three-part configure triplet; 2621in particular, you may not use the shorter aliases supported by 2622`configure' (but you can use Tcl globbing to specify a range of 2623triplets). If called with no arguments or an empty pattern, this 2624procedure returns the target triplet. 2625 2626 istarget pattern 2627 2628 2629File: dejagnu.info, Node: isnative procedure, Next: log_and_exit procedure, Prev: istarget procedure, Up: Core Internal Procedures 2630 2631isnative Procedure 2632.................. 2633 2634This procedure returns _1_ if the current configuration has the same 2635host and target (ie. it is a native configuration). Otherwise it 2636returns _0_. 2637 2638 isnative 2639 2640 2641File: dejagnu.info, Node: log_and_exit procedure, Next: log_summary procedure, Prev: isnative procedure, Up: Core Internal Procedures 2642 2643log_and_exit Procedure 2644...................... 2645 2646 log_and_exit 2647 2648 This procedure writes out the end of the test log and terminates 2649`runtest'. 2650 2651 2652File: dejagnu.info, Node: log_summary procedure, Next: setup_xfail procedure, Prev: log_and_exit procedure, Up: Core Internal Procedures 2653 2654log_summary Procedure 2655..................... 2656 2657 log_summary args 2658 2659`args' 2660 2661 2662File: dejagnu.info, Node: setup_xfail procedure, Next: pass procedure, Prev: log_summary procedure, Up: Core Internal Procedures 2663 2664setup_xfail Procedure 2665..................... 2666 2667Declares that the test is expected to fail on a particular set of 2668configurations. The config argument must be a list of full three-part 2669configure target name; in particular, you may not use the shorter 2670nicknames supported by configure (but you can use the common shell 2671wildcard characters to specify a range of triplets). The _bugid_ 2672argument is optional, and used only in the logging file output; use it 2673as a link to a bug-tracking system such as GNATS. 2674 2675 Once you use `setup_xfail', the `fail' and `pass' procedures produce 2676the messages _XFAIL_ and _XPASS_ respectively, allowing you to 2677distinguish expected failures (and unexpected success!) from other test 2678outcomes. 2679 2680 *Warning* 2681 2682 Warning you must clear the expected failure after using 2683 setup_xfail in a test case. Any call to `pass 'or `fail' clears 2684 the expected failure implicitly; if the test has some other 2685 outcome, e.g. an error, you can call `clear_xfail' to clear the 2686 expected failure explicitly. Otherwise, the expected-failure 2687 declaration applies to whatever test runs next, leading to 2688 surprising results. 2689 2690 setup_xfail config bugid 2691 2692`config' 2693 The config triplet to trigger whether this is an unexpected or 2694 expect failure. 2695 2696`bugid' 2697 The optional bugid, used to tie this test case to a bug tracking 2698 system. 2699 2700 2701File: dejagnu.info, Node: pass procedure, Next: fail procedure, Prev: setup_xfail procedure, Up: Core Internal Procedures 2702 2703pass Procedure 2704.............. 2705 2706Declares a test to have passed. `pass' writes in the log files a 2707message beginning with _PASS_ (or _XPASS_, if failure was expected), 2708appending the `message' argument. 2709 2710 pass message 2711 2712 2713File: dejagnu.info, Node: fail procedure, Next: xpass procedure, Prev: pass procedure, Up: Core Internal Procedures 2714 2715fail Procedure 2716.............. 2717 2718Declares a test to have failed. `fail' writes in the log files a 2719message beginning with _FAIL_ (or _XFAIL_, if failure was expected), 2720appending the `message' argument. 2721 2722 fail message 2723 2724 2725File: dejagnu.info, Node: xpass procedure, Next: xfail procedure, Prev: fail procedure, Up: Core Internal Procedures 2726 2727xpass Procedure 2728............... 2729 2730Declares a test to have passed when it was expected to fail. `xpass' 2731writes in the log files a message beginning with _XPASS_ (or _XFAIL_ if 2732failure was expected) and the `message' argument. 2733 2734 xpass message 2735 2736 2737File: dejagnu.info, Node: xfail procedure, Next: set_warning_threshold procedure, Prev: xpass procedure, Up: Core Internal Procedures 2738 2739xfail Procedure 2740............... 2741 2742Declares a test to have expectedly failed. `xfail' writes in the log 2743files a message beginning with _XFAIL_ (or _PASS_, if success was 2744expected), appending the `message' argument. 2745 2746 xpass message 2747 2748 2749File: dejagnu.info, Node: set_warning_threshold procedure, Next: get_warning_threshold procedure, Prev: xfail procedure, Up: Core Internal Procedures 2750 2751set_warning_threshold Procedure 2752............................... 2753 2754Sets the value of `warning_threshold'. A value of _0_ disables it: 2755calls to `warning' will not turn a _PASS_ or _FAIL_ into an 2756_UNRESOLVED_. 2757 2758 set_warning_threshold threshold 2759 2760`threshold' 2761 This is the value of the new warning threshold. 2762 2763 2764File: dejagnu.info, Node: get_warning_threshold procedure, Next: warning procedure, Prev: set_warning_threshold procedure, Up: Core Internal Procedures 2765 2766get_warning_threshold Procedure 2767............................... 2768 2769Returns the current value of `{warning_threshold'. The default value 2770is 3. This value controls how many `warning' procedures can be called 2771before becoming _UNRESOLVED_. 2772 2773 get_warning_threshold 2774 2775 2776File: dejagnu.info, Node: warning procedure, Next: perror procedure, Prev: get_warning_threshold procedure, Up: Core Internal Procedures 2777 2778warning Procedure 2779................. 2780 2781Declares detection of a minor error in the test case itself. `warning' 2782writes in the log files a message beginning with _WARNING_, appending 2783the argument `string'. Use `warning' rather than `perror' for cases 2784(such as communication failure to be followed by a retry) where the 2785test case can recover from the error. If the optional `number' is 2786supplied, then this is used to set the internal count of warnings to 2787that value. 2788 2789 As a side effect, `warning_threshold' or more calls to warning in a 2790single test case also changes the effect of the next `pass' or `fail' 2791command: the test outcome becomes _UNRESOLVED_ since an automatic 2792_PASS_ or _FAIL_ may not be trustworthy after many warnings. If the 2793optional numeric value is _0_, then there are no further side effects 2794to calling this function, and the following test outcome doesn't become 2795_UNRESOLVED_. This can be used for errors with no known side effects. 2796 2797 warning messsage number 2798 2799`message' 2800 The warning message. 2801 2802`number' 2803 The optional number to set the error counter. This is only used to 2804 fake out the counter when using the `xfail' procedure to control 2805 when it flips the output over to _UNRESOLVED_ state. 2806 2807 2808File: dejagnu.info, Node: perror procedure, Next: note procedure, Prev: warning procedure, Up: Core Internal Procedures 2809 2810perror Procedure 2811................ 2812 2813Declares a severe error in the testing framework itself. `perror' 2814writes in the log files a message beginning with _ERROR_, appending the 2815argument `string'. 2816 2817 As a side effect, perror also changes the effect of the next `pass' 2818or `fail' command: the test outcome becomes _UNRESOLVED_, since an 2819automatic _PASS_ or _FAIL_ cannot be trusted after a severe error in 2820the test framework. If the optional numeric value is _0_, then there 2821are no further side effects to calling this function, and the following 2822test outcome doesn't become _UNRESOLVED_. This can be used for errors 2823with no known side effects. 2824 2825 perror message number 2826 2827`message' 2828 The message to be logged. 2829 2830`number' 2831 The optional number to set the error counter. This is only used to 2832 fake out the counter when using the `xfail' procedure to control 2833 when it flips the output over to _UNRESOLVED_ state. 2834 2835 2836File: dejagnu.info, Node: note procedure, Next: untested procedure, Prev: perror procedure, Up: Core Internal Procedures 2837 2838note Procedure 2839.............. 2840 2841Appends an informational message to the log file. `note' writes in the 2842log files a message beginning with _NOTE_, appending the `message' 2843argument. Use `note' sparingly. The `verbose' should be used for most 2844such messages, but in cases where a message is needed in the log file 2845regardless of the verbosity level use `note'. 2846 2847 note messsage 2848 2849 2850File: dejagnu.info, Node: untested procedure, Next: unresolved procedure, Prev: note procedure, Up: Core Internal Procedures 2851 2852untested Procedure 2853.................. 2854 2855Declares a test was not run. `untested' writes in the log file a 2856message beginning with _UNTESTED_, appending the `message' argument. 2857For example, you might use this in a dummy test whose only role is to 2858record that a test does not yet exist for some feature. 2859 2860 untested message 2861 2862 2863File: dejagnu.info, Node: unresolved procedure, Next: unsupported procedure, Prev: untested procedure, Up: Core Internal Procedures 2864 2865unresolved Procedure 2866.................... 2867 2868Declares a test to have an unresolved outcome. `unresolved' writes in 2869the log file a message beginning with _UNRESOLVED_, appending the 2870`message' argument. This usually means the test did not execute as 2871expected, and a human being must go over results to determine if it 2872passed or failed (and to improve the test case). 2873 2874 unresolved message 2875 2876 2877File: dejagnu.info, Node: unsupported procedure, Next: transform procedure, Prev: unresolved procedure, Up: Core Internal Procedures 2878 2879unsupported Procedure 2880..................... 2881 2882Declares that a test case depends on some facility that does not exist 2883in the testing environment. `unsupported' writes in the log file a 2884message beginning with _UNSUPPORTED_, appending the `message' argument. 2885 2886 unsupported message 2887 2888 2889File: dejagnu.info, Node: transform procedure, Next: check_conditional_xfail procedure, Prev: unsupported procedure, Up: Core Internal Procedures 2890 2891transform Procedure 2892................... 2893 2894Generates a string for the name of a tool as it was configured and 2895installed, given its native name (as the argument `toolname'). This 2896makes the assumption that all tools are installed using the same naming 2897conventions: For example, for a cross compiler supporting the 2898_m68k-vxworks_ configuration, the result of transform `gcc' is 2899`m68k-vxworks-gcc'. 2900 2901 transform toolname 2902 2903`toolname' 2904 The name of the cross-development program to transform. 2905 2906 2907File: dejagnu.info, Node: check_conditional_xfail procedure, Next: clear_xfail procedure, Prev: transform procedure, Up: Core Internal Procedures 2908 2909check_conditional_xfail Procedure 2910................................. 2911 2912This procedure adds a conditional xfail, based on compiler options used 2913to create a test case executable. If an include options is found in 2914the compiler flags, and it's the right architecture, it'll trigger an 2915_XFAIL_. Otherwise it'll produce an ordinary _FAIL_. You can also 2916specify flags to exclude. This makes a result be a _FAIL_, even if the 2917included options are found. To set the conditional, set the variable 2918`compiler_conditional_xfail_data' to the fields 2919 2920 "[message string] [targets list] [includes list] [excludes list]" 2921 2922 (descriptions below). This is the checked at pass/fail decision 2923time, so there is no need to call the procedure yourself, unless you 2924wish to know if it gets triggered. After a pass/fail, the variable is 2925reset, so it doesn't effect other tests. It returns _1_ if the 2926conditional is true, or _0_ if the conditional is false. 2927 2928 check_conditional_xfail message targets includes excludes 2929 2930`message' 2931 This is the message to print with the normal test result. 2932 2933`targets' 2934 This is a string with the list targets to activate this conditional 2935 on. 2936 2937`includes' 2938 This is a list of sets of options to search for in the compiler 2939 options to activate this conditional. If the list of sets of 2940 options is empty or if any set of the options matches, then this 2941 conditional is true. (It may be useful to specify an empty list 2942 of include sets if the conditional is always true unless one of 2943 the exclude sets matches.) 2944 2945`excludes' 2946 This is a list of sets of options to search for in the compiler 2947 options to activate this conditional. If any set of the options 2948 matches, (regardless of whether any of the include sets match) then 2949 this conditional is de-activated. 2950 2951 *Specifying the conditional xfail data* 2952 2953 set compiler_conditional_xfail_data { \ 2954 "I sure wish I knew why this was hosed" \ 2955 "sparc*-sun*-* *-pc-*-*" \ 2956 {"-Wall -v" "-O3"} \ 2957 {"-O1" "-Map"} \ 2958 } 2959 2960 What this does is it matches only for these two targets if `-Wall 2961-v' or `-O3' is set, but neither `-O1' or `-Map' is set. For a set to 2962match, the options specified are searched for independently of each 2963other, so a `-Wall -v' matches either `-Wall -v' or `-v -Wall'. A 2964space separates the options in the string. Glob patterns are also 2965permitted. 2966 2967 2968File: dejagnu.info, Node: clear_xfail procedure, Next: verbose procedure, Prev: check_conditional_xfail procedure, Up: Core Internal Procedures 2969 2970clear_xfail Procedure 2971..................... 2972 2973Cancel an expected failure (previously declared with `setup_xfail') for 2974a particular set of configurations. The `config' argument is a list of 2975configuration target names. It is only necessary to call `clear_xfail' 2976if a test case ends without calling either `pass' or `fail', after 2977calling `setup_xfail'. 2978 2979 clear_xfail config 2980 2981`config' 2982 The system triplets to clear. 2983 2984 2985File: dejagnu.info, Node: verbose procedure, Next: load_lib procedure, Prev: clear_xfail procedure, Up: Core Internal Procedures 2986 2987verbose Procedure 2988................. 2989 2990Test cases can use this procedure to issue helpful messages depending 2991on the number of `-v'/`--verbose' options passed on the command line to 2992`runtest'. It prints message if the value of the number of `-v' 2993options passed is greater than or equal to the loglevel argument. The 2994default log level is 1. 2995 2996 verbose -log -x -n message loglevel 2997 2998`-log' 2999 Always write message to the log file, even if it won't be printed 3000 on the console. 3001 3002`-x' 3003 Log the message into an XML file. 3004 3005`-n' 3006 Print message without a trailing newline. 3007 3008`--' 3009 Use this option if message begins with `-'. 3010 3011`message' 3012 The log messsage. 3013 3014`loglevel' 3015 The specified log level. The default level is 1. 3016 3017 3018File: dejagnu.info, Node: load_lib procedure, Next: testsuite procedure, Prev: verbose procedure, Up: Core Internal Procedures 3019 3020load_lib Procedure 3021.................. 3022 3023`load_lib' loads a DejaGnu library file by searching the default fixed 3024paths built into DejaGnu. If DejaGnu has been installed, it looks in a 3025path starting with the installed library directory. If you are running 3026DejaGnu directly from a source directory, without first running `make 3027install', this path defaults to the current directory. In either case, 3028it then looks in the current directory for a directory called `lib'. 3029If there are duplicate definitions, the last one loaded takes 3030precedence over the earlier ones. 3031 3032 load_lib filespec 3033 3034`filespec' 3035 The name of the DejaGnu library file to load. 3036 3037 The global variable `libdirs', handled as a list, is appended to the 3038default fixed paths built into DejaGnu. 3039 3040 *Additional search directories for load_lib* 3041 3042 # append a non-standard search path 3043 global libdirs 3044 lappend libdirs $srcdir/../../gcc/testsuite/lib 3045 # now loading $srcdir/../../gcc/testsuite/lib/foo.exp works 3046 load_lib foo.exp 3047 3048 3049File: dejagnu.info, Node: testsuite procedure, Next: testcase procedure, Prev: load_lib procedure, Up: Core Internal Procedures 3050 3051testsuite Procedure 3052................... 3053 3054The `testsuite' procedure is a multiplex call for retrieving or 3055providing information about the current testsuite. 3056 3057testsuite file 3058.............. 3059 3060The `testsuite file' command returns an absolute file name specified 3061relative to either the testsuite source or object trees. 3062 3063 testsuite file ?-source|-object? -top|-test ?-hypothetical? 3064 ?-? name... 3065 3066 Any number of names are accepted and combined as if by `file join' 3067with a directory relevant to the testsuite prepended. 3068 3069`-object' 3070 Return a file name in the object tree. 3071 3072`-source' 3073 Return a file name in the source tree. 3074 3075`-top' 3076 Prepend the `testsuite' directory itself. 3077 3078`-test' 3079 Prepend the directory containing the current test script. 3080 3081`-hypothetical' 3082 Allow the returned value to imply directories that do not exist. 3083 3084`--' 3085 Use this option if the first name could begin with `-'. 3086 3087 3088 One of `-top' or `-test' must be given; an error is raised otherwise. 3089 3090 Unless the `-hypothetical' option is given, any directories implied 3091by the returned value will exist upon return. Implied directories are 3092created in the object tree if needed. An error is raised if an implied 3093directory does not exist in the source tree. 3094 3095testsuite can call 3096.................. 3097 3098The `testsuite can call' command is a feature test and returns a 3099boolean value indicating if a subcommand under a multiplex point is 3100available. This API call is needed because only the multiplex points 3101themselves are visible to the Tcl info command. 3102 3103 testsuite can call feature... 3104 3105 Any number of words are joined together into a single name, beginning 3106with a multiplex entry point and forming the full name of an API call 3107as documented in this manual. 3108 3109 3110File: dejagnu.info, Node: testcase procedure, Prev: testsuite procedure, Up: Core Internal Procedures 3111 3112testcase Procedure 3113.................. 3114 3115The `testcase' procedure is a multiplex call for retrieving or 3116providing information about the state of the testing process. 3117 3118testcase group 3119.............. 3120 3121The `testcase group' command provides support for grouping tests into 3122hierarchical groups within a test script. 3123 3124 Group names are internally tracked as Tcl lists, but are reported as 3125strings delimited using forward slash (`/') characters. Individual 3126name elements may not contain whitespace, but may contain forward 3127slash. A group entered by traversing intermediate levels must be left 3128by traversing those same levels. Groups must properly nest. 3129 3130 There are three uses: 3131 3132 testcase group 3133 3134 Return the current group as a string delimited with forward slash 3135(`/') characters. 3136 3137 testcase group begin name 3138 3139 testcase group end name 3140 3141 These forms allow a group to be explicitly entered and left. The 3142name parameter must be identical across a pair of these calls, and both 3143the `begin' and `end' calls must be in the same file. 3144 3145 testcase group eval name {code} 3146 3147 This form is available to wrap the `begin' and `end' calls around 3148the execution of the provided code. This form is preferred for 3149convenience in top-level scripts, but the `begin' and `end' calls are 3150preferred in helper procedures for performance. 3151 3152 3153File: dejagnu.info, Node: Procedures For Remote Communication, Next: connprocs, Prev: Core Internal Procedures, Up: Built-in Procedures 3154 3155A.2 Procedures For Remote Communication 3156======================================= 3157 3158The file `lib/remote.exp' defines procedures for establishing and 3159managing communications. Each of these procedures tries to establish 3160the connection up to three times before returning. Warnings (if 3161retries will continue) or errors (if the attempt is abandoned) report 3162on communication failures. The result for any of these procedures is 3163either _-1_, when the connection cannot be established, or the spawn ID 3164returned by the Expect command `spawn'. 3165 3166 It use the value of the `connect' field in the `target_info' array 3167as the type of connection to make. Current supported connection types 3168are ssh, tip, kermit, telnet, rsh, and rlogin. If the `--reboot' 3169option was used on the `runtest' command line, then the target is 3170rebooted before the connection is made. 3171 3172* Menu: 3173 3174* call_remote Procedure: call_remote procedure 3175* check_for_board_status Procedure: check_for_board_status procedure 3176* file_on_build Procedure: file_on_build procedure 3177* file_on_host Procedure: file_on_host procedure 3178* local_exec Procedure: local_exec procedure 3179* remote_binary Procedure: remote_binary procedure 3180* remote_close Procedure: remote_close procedure 3181* remote_download Procedure: remote_download procedure 3182* remote_exec Procedure: remote_exec procedure 3183* remote_expect Procedure: remote_expect procedure 3184* remote_file Procedure: remote_file procedure 3185* remote_ld Procedure: remote_ld procedure 3186* remote_load Procedure: remote_load procedure 3187* remote_open Procedure: remote_open procedure 3188* remote_pop_conn Procedure: remote_pop_conn procedure 3189* remote_push_conn Procedure: remote_push_conn procedure 3190* remote_raw_binary Procedure: remote_raw_binary procedure 3191* remote_raw_close Procedure: remote_raw_close procedure 3192* remote_raw_file Procedure: remote_raw_file procedure 3193* remote_raw_ld Procedure: remote_raw_ld procedure 3194* remote_raw_load Procedure: remote_raw_load procedure 3195* remote_raw_open Procedure: remote_raw_open procedure 3196* remote_raw_send Procedure: remote_raw_send procedure 3197* remote_raw_spawn Procedure: remote_raw_spawn procedure 3198* remote_raw_transmit Procedure: remote_raw_transmit procedure 3199* remote_raw_wait Procedure: remote_raw_wait procedure 3200* remote_reboot Procedure: remote_reboot procedure 3201* remote_send Procedure: remote_send procedure 3202* remote_spawn Procedure: remote_spawn procedure 3203* remote_swap_conn Procedure: remote_swap_conn procedure 3204* remote_transmit Procedure: remote_transmit procedure 3205* remote_upload Procedure: remote_upload procedure 3206* remote_wait Procedure: remote_wait procedure 3207* standard_close Procedure: standard_close procedure 3208* standard_download Procedure: standard_download procedure 3209* standard_exec Procedure: standard_exec procedure 3210* standard_file Procedure: standard_file procedure 3211* standard_load Procedure: standard_load procedure 3212* standard_reboot Procedure: standard_reboot procedure 3213* standard_send Procedure: standard_send procedure 3214* standard_spawn Procedure: standard_spawn procedure 3215* standard_transmit Procedure: standard_transmit procedure 3216* standard_upload Procedure: standard_upload procedure 3217* standard_wait Procedure: standard_wait procedure 3218* unix_clean_filename Procedure: unix_clean_filename procedure 3219 3220 3221File: dejagnu.info, Node: call_remote procedure, Next: check_for_board_status procedure, Up: Procedures For Remote Communication 3222 3223call_remote Procedure 3224..................... 3225 3226A standard procedure to call the appropriate proc. This proceure first 3227looks for a board-specific version, then a protocol-specific version, 3228and finally `call_remote' will call `standard_$proc'. 3229 3230 call_remote type proc dest args 3231 3232`proc' 3233 3234`dest' 3235 3236`args' 3237 3238 3239File: dejagnu.info, Node: check_for_board_status procedure, Next: file_on_build procedure, Prev: call_remote procedure, Up: Procedures For Remote Communication 3240 3241check_for_board_status Procedure 3242................................ 3243 3244This procedure inspected the named variable within the calling 3245procedure for the expected output from the status wrapper. A 3246non-negative value is returned if it exists. Otherwise, it returns -1. 3247The output from the status wrapper is removed from the variable. 3248 3249 check_for_board_status variable 3250 3251`variable' 3252 The name of the variable to check in the calling procedure. Be 3253 sure to pass the name of the variable (`var') and not the value of 3254 the variable (`$var'). 3255 3256 3257File: dejagnu.info, Node: file_on_build procedure, Next: file_on_host procedure, Prev: check_for_board_status procedure, Up: Procedures For Remote Communication 3258 3259file_on_build Procedure 3260....................... 3261 3262 file_on_build op file args 3263 3264`op' 3265 3266`file' 3267 3268`args' 3269 3270 3271File: dejagnu.info, Node: file_on_host procedure, Next: local_exec procedure, Prev: file_on_build procedure, Up: Procedures For Remote Communication 3272 3273file_on_host Procedure 3274...................... 3275 3276 file_on_host op file args 3277 3278`op' 3279 3280`file' 3281 3282`args' 3283 3284 3285File: dejagnu.info, Node: local_exec procedure, Next: remote_binary procedure, Prev: file_on_host procedure, Up: Procedures For Remote Communication 3286 3287local_exec Procedure 3288.................... 3289 3290Run the specified command on the local machine, redirecting input from 3291file `inp' (if non-empty), redirecting output to file `outp' (if 3292non-empty), and waiting `timeout' seconds for the command to complete 3293before killing it. A two-element list is returned: the exit status of 3294the command and any output produced by the command. If output is 3295redirected, this may or may not be empty. If output is redirected, 3296both stdout and stderr will appear in the specified file. 3297 3298 local_exec commandline inp outp timeout 3299 3300`inp' 3301 Redirect input into the input filename if not set to `""'. 3302 3303`outp' 3304 Redirect output into the output filename if not set to `""'. 3305 3306`timeout' 3307 Timeout in seconds. 3308 3309 3310 3311File: dejagnu.info, Node: remote_binary procedure, Next: remote_close procedure, Prev: local_exec procedure, Up: Procedures For Remote Communication 3312 3313remote_binary Procedure 3314....................... 3315 3316This procedure sets the connection into binary mode. That is, there is 3317no processing of input characters. 3318 3319 remote_binary host 3320 3321`host' 3322 The host on which to set a binary connection. 3323 3324 3325File: dejagnu.info, Node: remote_close procedure, Next: remote_download procedure, Prev: remote_binary procedure, Up: Procedures For Remote Communication 3326 3327remote_close Procedure 3328...................... 3329 3330 remote_close shellid 3331 3332`shellid' 3333 This is the value returned by a call to `remote_open'. This 3334 closes the connection to the target so resources can be used by 3335 others. This parameter can be left off if the `fileid' field in 3336 the `target_info' array is set. 3337 3338 3339File: dejagnu.info, Node: remote_download procedure, Next: remote_exec procedure, Prev: remote_close procedure, Up: Procedures For Remote Communication 3340 3341remote_download Procedure 3342......................... 3343 3344Download a file to a destination machine. This procedure returns 3345either an empty string (indicating failure) or the name of the file on 3346the destination macine. 3347 3348 remote_download dest file args 3349 3350`dest' 3351 Destination machine name. 3352 3353`file' 3354 Filename. 3355 3356`args' 3357 If the optional destination filename is specified, that filename 3358 will be used on the destination machine. 3359 3360 3361File: dejagnu.info, Node: remote_exec procedure, Next: remote_expect procedure, Prev: remote_download procedure, Up: Procedures For Remote Communication 3362 3363remote_exec Procedure 3364..................... 3365 3366Execute the supplied program on a remote host. A two-element list is 3367returned. The first element is the exit status of the program or -1 if 3368execution failed. The second element is any output produced by the 3369program. This may be an empty string if output from the program was 3370redirected. 3371 3372 remote_exec hostname program ?options? ?input? ?output? ?timeout? 3373 3374`hostname' 3375 Name of the host to execute the command on. 3376 3377`program' 3378 Command to execute. 3379 3380`options' 3381 Arguments to pass to the program. 3382 3383`input' 3384 Input filename to feed to standard input of the command. 3385 3386`output' 3387 Output filename where the output from the command should be 3388 written. 3389 3390`timeout' 3391 Timeout value in seconds. 3392 3393 3394 All of the optional positional arguments accept an empty string as a 3395neutral value. 3396 3397 3398File: dejagnu.info, Node: remote_expect procedure, Next: remote_file procedure, Prev: remote_exec procedure, Up: Procedures For Remote Communication 3399 3400remote_expect Procedure 3401....................... 3402 3403 remote_expect board timeout args 3404 3405`board' 3406 3407`timeout' 3408 3409`args' 3410 3411 3412File: dejagnu.info, Node: remote_file procedure, Next: remote_ld procedure, Prev: remote_expect procedure, Up: Procedures For Remote Communication 3413 3414remote_file Procedure 3415..................... 3416 3417 remote_file dest args 3418 3419`dest' 3420 3421`args' 3422 3423 3424File: dejagnu.info, Node: remote_ld procedure, Next: remote_load procedure, Prev: remote_file procedure, Up: Procedures For Remote Communication 3425 3426remote_ld Procedure 3427................... 3428 3429 remote_ld dest prog 3430 3431`dest' 3432 3433`prog' 3434 3435 3436File: dejagnu.info, Node: remote_load procedure, Next: remote_open procedure, Prev: remote_ld procedure, Up: Procedures For Remote Communication 3437 3438remote_load Procedure 3439..................... 3440 3441 remote_load dest prog args 3442 3443`dest' 3444 3445`prog' 3446 3447`args' 3448 3449 3450File: dejagnu.info, Node: remote_open procedure, Next: remote_pop_conn procedure, Prev: remote_load procedure, Up: Procedures For Remote Communication 3451 3452remote_open Procedure 3453..................... 3454 3455Open connection to a remote host or target. This requires the 3456`target_info' array be filled in with the proper information to work. 3457It returns the spawn id of the process that is the connection. 3458 3459 remote_open type 3460 3461`type' 3462 This is passed `host' or `target'. Host or target refers to 3463 whether it is a connection to a remote target, or a remote host. 3464 This opens the connection to the desired target or host using the 3465 default values in the configuration system. It returns that 3466 `spawn_id' of the process that manages the connection. This value 3467 can be used in Expect or `exp_send' statements, or passed to other 3468 procedures that need the connection process's id. This also sets 3469 the `fileid' field in the `target_info' array. 3470 3471 3472File: dejagnu.info, Node: remote_pop_conn procedure, Next: remote_push_conn procedure, Prev: remote_open procedure, Up: Procedures For Remote Communication 3473 3474remote_pop_conn Procedure 3475......................... 3476 3477Pop a previously-pushed connection from the stack. You should have 3478closed the current connection before calling this procedure. Returns 3479`pass' or `fail'. 3480 3481 remote_pop_conn host 3482 3483`host' 3484 3485 3486File: dejagnu.info, Node: remote_push_conn procedure, Next: remote_raw_binary procedure, Prev: remote_pop_conn procedure, Up: Procedures For Remote Communication 3487 3488remote_push_conn Procedure 3489.......................... 3490 3491Pushes the current connection onto a stack. Returns `pass' or `fail'. 3492 3493 remote_push_conn host 3494 3495`host' 3496 3497 3498File: dejagnu.info, Node: remote_raw_binary procedure, Next: remote_raw_close procedure, Prev: remote_push_conn procedure, Up: Procedures For Remote Communication 3499 3500remote_raw_binary Procedure 3501........................... 3502 3503 remote_raw_binary host 3504 3505`host' 3506 3507 3508File: dejagnu.info, Node: remote_raw_close procedure, Next: remote_raw_file procedure, Prev: remote_raw_binary procedure, Up: Procedures For Remote Communication 3509 3510remote_raw_close Procedure 3511.......................... 3512 3513 remote_raw_close host 3514 3515`host' 3516 3517 3518File: dejagnu.info, Node: remote_raw_file procedure, Next: remote_raw_ld procedure, Prev: remote_raw_close procedure, Up: Procedures For Remote Communication 3519 3520remote_raw_file Procedure 3521......................... 3522 3523 remote_raw_file dest args 3524 3525`dest' 3526 3527`args' 3528 3529 3530File: dejagnu.info, Node: remote_raw_ld procedure, Next: remote_raw_load procedure, Prev: remote_raw_file procedure, Up: Procedures For Remote Communication 3531 3532remote_raw_ld Procedure 3533....................... 3534 3535 remote_raw_ld dest prog 3536 3537`dest' 3538 3539`prog' 3540 3541 3542File: dejagnu.info, Node: remote_raw_load procedure, Next: remote_raw_open procedure, Prev: remote_raw_ld procedure, Up: Procedures For Remote Communication 3543 3544remote_raw_load Procedure 3545......................... 3546 3547 remote_raw_load dest prog args 3548 3549`dest' 3550 3551`prog' 3552 3553`args' 3554 3555 3556File: dejagnu.info, Node: remote_raw_open procedure, Next: remote_raw_send procedure, Prev: remote_raw_load procedure, Up: Procedures For Remote Communication 3557 3558remote_raw_open Procedure 3559......................... 3560 3561 remote_raw_open args 3562 3563`args' 3564 3565 3566File: dejagnu.info, Node: remote_raw_send procedure, Next: remote_raw_spawn procedure, Prev: remote_raw_open procedure, Up: Procedures For Remote Communication 3567 3568remote_raw_send Procedure 3569......................... 3570 3571 remote_raw_send dest string 3572 3573`dest' 3574 3575`string' 3576 3577 3578File: dejagnu.info, Node: remote_raw_spawn procedure, Next: remote_raw_transmit procedure, Prev: remote_raw_send procedure, Up: Procedures For Remote Communication 3579 3580remote_raw_spawn Procedure 3581.......................... 3582 3583 remote_raw_spawn dest commandline 3584 3585`dest' 3586 3587`commandline' 3588 3589 3590File: dejagnu.info, Node: remote_raw_transmit procedure, Next: remote_raw_wait procedure, Prev: remote_raw_spawn procedure, Up: Procedures For Remote Communication 3591 3592remote_raw_transmit Procedure 3593............................. 3594 3595 remote_raw_transmit dest file 3596 3597`dest' 3598 3599`file' 3600 3601 3602File: dejagnu.info, Node: remote_raw_wait procedure, Next: remote_reboot procedure, Prev: remote_raw_transmit procedure, Up: Procedures For Remote Communication 3603 3604remote_raw_wait Procedure 3605......................... 3606 3607 remote_raw_wait dest timeout 3608 3609`dest' 3610 3611`timeout' 3612 3613 3614File: dejagnu.info, Node: remote_reboot procedure, Next: remote_send procedure, Prev: remote_raw_wait procedure, Up: Procedures For Remote Communication 3615 3616remote_reboot Procedure 3617....................... 3618 3619Reboot the host. The return value of this procedure depends on the 3620actual implementation of reboot that will be used, in practice it is 3621expected that `remote_reboot' returns 1 on success and 0 on failure. 3622 3623 remote_reboot host 3624 3625`host' 3626 3627 3628File: dejagnu.info, Node: remote_send procedure, Next: remote_spawn procedure, Prev: remote_reboot procedure, Up: Procedures For Remote Communication 3629 3630remote_send Procedure 3631..................... 3632 3633 remote_send dest string 3634 3635`dest' 3636 3637`string' 3638 3639 3640File: dejagnu.info, Node: remote_spawn procedure, Next: remote_swap_conn procedure, Prev: remote_send procedure, Up: Procedures For Remote Communication 3641 3642remote_spawn Procedure 3643...................... 3644 3645Start a command on the destination. By default it is not possible to 3646redirect I/O. If the command is successfully started, a positive spawn 3647ID is returned. If the spawn fails, a negative value will be returned. 3648Once the command has started, you can interact with it using 3649`remote_expect' and `remote_wait' procedures. 3650 3651 remote_spawn dest commandline args 3652 3653`dest' 3654 The destination. 3655 3656`commandline' 3657 The command to execute. 3658 3659`args' 3660 If the optional keyword `readonly' is specified, input to the 3661 command may be redirected. 3662 3663 3664File: dejagnu.info, Node: remote_swap_conn procedure, Next: remote_transmit procedure, Prev: remote_spawn procedure, Up: Procedures For Remote Communication 3665 3666remote_swap_conn Procedure 3667.......................... 3668 3669Swap the current connection with the topmost one on the stack. Returns 3670`pass' or `fail'. 3671 3672 remote_swap_conn host 3673 3674`' 3675 3676 3677File: dejagnu.info, Node: remote_transmit procedure, Next: remote_upload procedure, Prev: remote_swap_conn procedure, Up: Procedures For Remote Communication 3678 3679remote_transmit Procedure 3680......................... 3681 3682 remote_transmit dest file 3683 3684`dest' 3685 3686`file' 3687 3688 3689File: dejagnu.info, Node: remote_upload procedure, Next: remote_wait procedure, Prev: remote_transmit procedure, Up: Procedures For Remote Communication 3690 3691remote_upload Procedure 3692....................... 3693 3694 remote_upload dest srcfile arg 3695 3696`dest' 3697 3698`srcfile' 3699 3700`arg' 3701 3702 3703File: dejagnu.info, Node: remote_wait procedure, Next: standard_close procedure, Prev: remote_upload procedure, Up: Procedures For Remote Communication 3704 3705remote_wait Procedure 3706..................... 3707 3708Wait for the last spawned command on the destination to complete. A 3709list of two values is returned: the exit status (-1 if the program 3710timed out) and any output produced by the command. 3711 3712 remote_wait dest timeout 3713 3714`dest' 3715 The destination board. 3716 3717`timeout' 3718 The timeout in seconds. 3719 3720 3721File: dejagnu.info, Node: standard_close procedure, Next: standard_download procedure, Prev: remote_wait procedure, Up: Procedures For Remote Communication 3722 3723standard_close Procedure 3724........................ 3725 3726This procedure closes a connection. 3727 3728 standard_close host 3729 3730`host' 3731 The host to close the connection to. 3732 3733 3734File: dejagnu.info, Node: standard_download procedure, Next: standard_exec procedure, Prev: standard_close procedure, Up: Procedures For Remote Communication 3735 3736standard_download Procedure 3737........................... 3738 3739Downloads a file to a destination. It returns either the empty string 3740(indicating failure) or the name of the file on the destination. 3741 3742 standard_download dest file destfile 3743 3744`dest' 3745 Destination board. 3746 3747`file' 3748 The name of the file to download. 3749 3750`destfile' 3751 If the optional destile is specified, that filename will be used 3752 on the destination board. 3753 3754 3755File: dejagnu.info, Node: standard_exec procedure, Next: standard_file procedure, Prev: standard_download procedure, Up: Procedures For Remote Communication 3756 3757standard_exec Procedure 3758....................... 3759 3760 standard_exec hostname args 3761 3762`hostname' 3763 3764`args' 3765 3766 3767File: dejagnu.info, Node: standard_file procedure, Next: standard_load procedure, Prev: standard_exec procedure, Up: Procedures For Remote Communication 3768 3769standard_file Procedure 3770....................... 3771 3772 standard_file dest op args 3773 3774`' 3775 3776 3777File: dejagnu.info, Node: standard_load procedure, Next: standard_reboot procedure, Prev: standard_file procedure, Up: Procedures For Remote Communication 3778 3779standard_load Procedure 3780....................... 3781 3782 standard_load dest prog args 3783 3784`dest' 3785 3786`prog' 3787 3788`args' 3789 3790 3791File: dejagnu.info, Node: standard_reboot procedure, Next: standard_send procedure, Prev: standard_load procedure, Up: Procedures For Remote Communication 3792 3793standard_reboot Procedure 3794......................... 3795 3796It looks like that this procedure is never called, instead 3797`${board}_reboot' defined in `base-config.exp' will be used because it 3798has higher priority and `base-config.exp' is always imported by 3799`runtest'. 3800 3801 standard_reboot host 3802 3803`host' 3804 3805 3806File: dejagnu.info, Node: standard_send procedure, Next: standard_spawn procedure, Prev: standard_reboot procedure, Up: Procedures For Remote Communication 3807 3808standard_send Procedure 3809....................... 3810 3811 standard_send dest string 3812 3813`dest' 3814 3815`string' 3816 3817 3818File: dejagnu.info, Node: standard_spawn procedure, Next: standard_transmit procedure, Prev: standard_send procedure, Up: Procedures For Remote Communication 3819 3820standard_spawn Procedure 3821........................ 3822 3823 standard_spawn dest commandline 3824 3825`dest' 3826 3827`commandline' 3828 3829 3830File: dejagnu.info, Node: standard_transmit procedure, Next: standard_upload procedure, Prev: standard_spawn procedure, Up: Procedures For Remote Communication 3831 3832standard_transmit Procedure 3833........................... 3834 3835The default transmit procedure if none other exists. This feeds the 3836file directly into the connection. 3837 3838 standard_transmit dest file 3839 3840`dest' 3841 3842`file' 3843 File to transmit. 3844 3845 3846File: dejagnu.info, Node: standard_upload procedure, Next: standard_wait procedure, Prev: standard_transmit procedure, Up: Procedures For Remote Communication 3847 3848standard_upload Procedure 3849......................... 3850 3851 standard_upload dest srcfile destfile 3852 3853`dest' 3854 3855`srcfile' 3856 3857`destfile' 3858 3859 3860File: dejagnu.info, Node: standard_wait procedure, Next: unix_clean_filename procedure, Prev: standard_upload procedure, Up: Procedures For Remote Communication 3861 3862standard_wait Procedure 3863....................... 3864 3865 standard_wait dest timeout 3866 3867`dest' 3868 3869`timeout' 3870 3871 3872File: dejagnu.info, Node: unix_clean_filename procedure, Prev: standard_wait procedure, Up: Procedures For Remote Communication 3873 3874unix_clean_filename Procedure 3875............................. 3876 3877This procedure returns an absolute version of the filename argument 3878with `.' and `..' removed. 3879 3880 unix_clean_filename dest file 3881 3882`dest' 3883 3884`file' 3885 The filename. 3886 3887 3888File: dejagnu.info, Node: connprocs, Next: Procedures For Target Boards, Prev: Procedures For Remote Communication, Up: Built-in Procedures 3889 3890A.3 Procedures For Using Utilities to Connect 3891============================================= 3892 3893* Menu: 3894 3895* kermit_open Procedure: kermit_open procedure 3896* kermit_command Procedure: kermit_command procedure 3897* kermit_send Procedure: kermit_send procedure 3898* kermit_transmit Procedure: kermit_transmit procedure 3899* telnet_open Procedure: telnet_open procedure 3900* telnet_binary Procedure: telnet_binary procedure 3901* tip_open Procedure: tip_open procedure 3902* rlogin_open Procedure: rlogin_open procedure 3903* rlogin_spawn Procedure: rlogin_spawn procedure 3904* rsh_open Procedure: rsh_open procedure 3905* rsh_download Procedure: rsh_download procedure 3906* rsh_upload Procedure: rsh_upload procedure 3907* rsh_exec Procedure: rsh_exec procedure 3908* ssh_close Procedure: ssh_close procedure 3909* ssh_exec Procedure: ssh_exec procedure 3910* ssh_download Procedure: ssh_download procedure 3911* ssh_upload Procedure: ssh_upload procedure 3912* ftp_open Procedure: ftp_open procedure 3913* ftp_upload Procedure: ftp_upload procedure 3914* ftp_download Procedure: ftp_download procedure 3915* ftp_close Procedure: ftp_close procedure 3916* tip_download Procedure: tip_download procedure 3917 3918 3919File: dejagnu.info, Node: kermit_open procedure, Next: kermit_command procedure, Prev: connprocs, Up: connprocs 3920 3921kermit_open Procedure 3922..................... 3923 3924 kermit_open dest args 3925 3926`dest' 3927 3928`args' 3929 3930 3931File: dejagnu.info, Node: kermit_command procedure, Next: kermit_send procedure, Prev: kermit_open procedure, Up: connprocs 3932 3933kermit_command Procedure 3934........................ 3935 3936 kermit_command dest args 3937 3938`dest' 3939 3940`args' 3941 3942 3943File: dejagnu.info, Node: kermit_send procedure, Next: kermit_transmit procedure, Prev: kermit_command procedure, Up: connprocs 3944 3945kermit_send Procedure 3946..................... 3947 3948 kermit_send dest string args 3949 3950`dest' 3951 3952`string' 3953 3954`args' 3955 3956 3957File: dejagnu.info, Node: kermit_transmit procedure, Next: telnet_open procedure, Prev: kermit_send procedure, Up: connprocs 3958 3959kermit_transmit Procedure 3960......................... 3961 3962 kermit_transmit dest file args 3963 3964`dest' 3965 3966`file' 3967 3968`args' 3969 3970 3971File: dejagnu.info, Node: telnet_open procedure, Next: telnet_binary procedure, Prev: kermit_transmit procedure, Up: connprocs 3972 3973telnet_open Procedure 3974..................... 3975 3976This procedure opens a connection to a remote host using TELNET. This 3977procedure sets the `fileid' field in the `board_info' array and returns 3978the spawn id (or -1 for error). 3979 3980 telnet_open hostname args 3981 3982`hostname' 3983 The host to connect to with TELNET. 3984 3985`args' 3986 A list of options. Currently the only supported option is `raw'. 3987 3988 3989File: dejagnu.info, Node: telnet_binary procedure, Next: tip_open procedure, Prev: telnet_open procedure, Up: connprocs 3990 3991telnet_binary Procedure 3992....................... 3993 3994Puts an existing TELNET connection into binary mode. 3995 3996 telnet_binary hostname 3997 3998`hostname' 3999 Hostname for the connection. 4000 4001 4002File: dejagnu.info, Node: tip_open procedure, Next: rlogin_open procedure, Prev: telnet_binary procedure, Up: connprocs 4003 4004tip_open Procedure 4005.................. 4006 4007Connect to a host using `tip(1)'. This procedure sets the board 4008`fileid' field with the `spawn_id' on success and, otherwise, returns 4009-1. 4010 4011 tip_open hostname 4012 4013`hostname' 4014 Hostname to connect to. 4015 4016 4017File: dejagnu.info, Node: rlogin_open procedure, Next: rlogin_spawn procedure, Prev: tip_open procedure, Up: connprocs 4018 4019rlogin_open Procedure 4020..................... 4021 4022 rlogin_open arg 4023 4024`arg' 4025 4026 4027File: dejagnu.info, Node: rlogin_spawn procedure, Next: rsh_open procedure, Prev: rlogin_open procedure, Up: connprocs 4028 4029rlogin_spawn Procedure 4030...................... 4031 4032 rlogin_spawn dest cmdline 4033 4034`dest' 4035 4036`cmdline' 4037 4038 4039File: dejagnu.info, Node: rsh_open procedure, Next: rsh_download procedure, Prev: rlogin_spawn procedure, Up: connprocs 4040 4041rsh_open Procedure 4042.................. 4043 4044 rsh_open hostname 4045 4046`hostname' 4047 4048 4049File: dejagnu.info, Node: rsh_download procedure, Next: rsh_upload procedure, Prev: rsh_open procedure, Up: connprocs 4050 4051rsh_download Procedure 4052...................... 4053 4054 rsh_download desthost srcfile destfile 4055 4056`desthost' 4057 4058`srcfile' 4059 4060`destfile' 4061 4062 4063File: dejagnu.info, Node: rsh_upload procedure, Next: rsh_exec procedure, Prev: rsh_download procedure, Up: connprocs 4064 4065rsh_upload Procedure 4066.................... 4067 4068 rsh_upload desthost srcfile destfile 4069 4070`desthost' 4071 4072`srcfile' 4073 4074`destfile' 4075 4076 4077File: dejagnu.info, Node: rsh_exec procedure, Next: ssh_close procedure, Prev: rsh_upload procedure, Up: connprocs 4078 4079rsh_exec Procedure 4080.................. 4081 4082 rsh_exec boardname cmd args 4083 4084`boardname' 4085 4086`cmd' 4087 4088`args' 4089 4090 4091File: dejagnu.info, Node: ssh_close procedure, Next: ssh_exec procedure, Prev: rsh_exec procedure, Up: connprocs 4092 4093ssh_close procedure 4094................... 4095 4096 ssh_close desthost 4097 4098`desthost' 4099 4100 4101File: dejagnu.info, Node: ssh_exec procedure, Next: ssh_download procedure, Prev: ssh_close procedure, Up: connprocs 4102 4103ssh_exec procedure 4104.................. 4105 4106 ssh_exec boardname program pargs inp outp 4107 4108`boardname' 4109 4110`program' 4111 4112`pargs' 4113 4114`inp' 4115 4116`outp' 4117 4118 4119File: dejagnu.info, Node: ssh_download procedure, Next: ssh_upload procedure, Prev: ssh_exec procedure, Up: connprocs 4120 4121ssh_download procedure 4122...................... 4123 4124 ssh_download desthost srcfile destfile 4125 4126`desthost' 4127 4128`srcfile' 4129 4130`destfile' 4131 4132 4133File: dejagnu.info, Node: ssh_upload procedure, Next: ftp_open procedure, Prev: ssh_download procedure, Up: connprocs 4134 4135ssh_upload procedure 4136.................... 4137 4138 ssh_upload desthost srcfile destfile 4139 4140`desthost' 4141 4142`srcfile' 4143 4144`destfile' 4145 4146 4147File: dejagnu.info, Node: ftp_open procedure, Next: ftp_upload procedure, Prev: ssh_upload procedure, Up: connprocs 4148 4149ftp_open Procedure 4150.................. 4151 4152Open an FTP connection. 4153 4154 ftp_open host 4155 4156`host' 4157 The host to open the FTP connection to. 4158 4159 4160File: dejagnu.info, Node: ftp_upload procedure, Next: ftp_download procedure, Prev: ftp_open procedure, Up: connprocs 4161 4162ftp_upload Procedure 4163.................... 4164 4165Fetches a file from a remote host using FTP. 4166 4167 ftp_upload host remotefile localfile 4168 4169`host' 4170 The host to transfer the file from. 4171 4172`remotefile' 4173 The filename at the remote end. 4174 4175`localfile' 4176 The filename to store locally. 4177 4178 4179 4180File: dejagnu.info, Node: ftp_download procedure, Next: ftp_close procedure, Prev: ftp_upload procedure, Up: connprocs 4181 4182ftp_download Procedure 4183...................... 4184 4185Sends a file to a remote host using FTP. 4186 4187 ftp_download host localfile remotefile 4188 4189`host' 4190 The host to transfer the file from. 4191 4192`localfile' 4193 The filename on the local system. 4194 4195`remotefile' 4196 The filename at the remote end. 4197 4198 4199File: dejagnu.info, Node: ftp_close procedure, Next: tip_download procedure, Prev: ftp_download procedure, Up: connprocs 4200 4201ftp_close Procedure 4202................... 4203 4204Closes the FTP connection to a host. 4205 4206 ftp_close host 4207 4208`host' 4209 The host connection to close. 4210 4211 4212File: dejagnu.info, Node: tip_download procedure, Prev: ftp_close procedure, Up: connprocs 4213 4214tip_download Procedure 4215...................... 4216 4217 tip_download spawnid file 4218 4219`spawnid' 4220 Download `file' to the process `spawnid' (the value returned when 4221 the connection was established), using the `~put' command under 4222 tip. Most often used for single board computers that require 4223 downloading programs in ASCII S-records. Returns _1_ if an error 4224 occurs, _0_ otherwise. 4225 4226`file' 4227 This is the filename to download. 4228 4229 4230File: dejagnu.info, Node: Procedures For Target Boards, Next: target database library file, Prev: connprocs, Up: Built-in Procedures 4231 4232A.4 Procedures For Target Boards 4233================================ 4234 4235* Menu: 4236 4237* default_link Procedure: default_link procedure 4238* default_target_assemble Procedure: default_target_assemble procedure 4239* default_target_compile Procedure: default_target_compile procedure 4240* pop_config Procedure: pop_config procedure 4241* prune_warnings Procedure: prune_warnings procedure 4242* push_build Procedure: push_build procedure 4243* push_config Procedure: push_config procedure 4244* reboot_target Procedure: reboot_target procedure 4245* target_assemble Procedure: target_assemble procedure 4246* target_compile Procedure: target_compile procedure 4247* target_link Procedure: target_link procedure 4248 4249 4250File: dejagnu.info, Node: default_link procedure, Next: default_target_assemble procedure, Up: Procedures For Target Boards 4251 4252default_link Procedure 4253...................... 4254 4255 default_link board objects destfile flags 4256 4257 This is the internal implementation for the *Note target_link 4258procedure::, and should not be directly called from testsuite code. 4259 4260 4261File: dejagnu.info, Node: default_target_assemble procedure, Next: default_target_compile procedure, Prev: default_link procedure, Up: Procedures For Target Boards 4262 4263default_target_assemble Procedure 4264................................. 4265 4266 default_target_assemble source destfile flags 4267 4268 This is the internal implementation for the *Note target_assemble 4269procedure::, and should not be directly called from testsuite code. 4270 4271 4272File: dejagnu.info, Node: default_target_compile procedure, Next: pop_config procedure, Prev: default_target_assemble procedure, Up: Procedures For Target Boards 4273 4274default_target_compile Procedure 4275................................ 4276 4277 default_target_compile source destfile type options 4278 4279 This is the default implementation for the *Note target_compile 4280procedure::, and is used if the current target board does not have a 4281special procedure for this purpose. *Note target_compile procedure::, 4282for API details. Calling this procedure directly from testsuite code 4283is deprecated. 4284 4285 4286File: dejagnu.info, Node: pop_config procedure, Next: prune_warnings procedure, Prev: default_target_compile procedure, Up: Procedures For Target Boards 4287 4288pop_config Procedure 4289.................... 4290 4291 pop_config type 4292 4293`type' 4294 4295 4296File: dejagnu.info, Node: prune_warnings procedure, Next: push_build procedure, Prev: pop_config procedure, Up: Procedures For Target Boards 4297 4298prune_warnings Procedure 4299........................ 4300 4301 prune_warnings text 4302 4303`text' 4304 4305 4306File: dejagnu.info, Node: push_build procedure, Next: push_config procedure, Prev: prune_warnings procedure, Up: Procedures For Target Boards 4307 4308push_build Procedure 4309.................... 4310 4311 push_build name 4312 4313`name' 4314 4315 4316File: dejagnu.info, Node: push_config procedure, Next: reboot_target procedure, Prev: push_build procedure, Up: Procedures For Target Boards 4317 4318push_config Procedure 4319..................... 4320 4321 push_config type name 4322 4323`type' 4324 4325`name' 4326 4327 4328File: dejagnu.info, Node: reboot_target procedure, Next: target_assemble procedure, Prev: push_config procedure, Up: Procedures For Target Boards 4329 4330reboot_target Procedure 4331....................... 4332 4333Reboot the target. 4334 4335 reboot_target 4336 4337 4338File: dejagnu.info, Node: target_assemble procedure, Next: target_compile procedure, Prev: reboot_target procedure, Up: Procedures For Target Boards 4339 4340target_assemble Procedure 4341......................... 4342 4343 target_assemble source destfile flags 4344 4345`source' 4346 4347`destfile' 4348 4349`flags' 4350 4351 4352File: dejagnu.info, Node: target_compile procedure, Next: target_link procedure, Prev: target_assemble procedure, Up: Procedures For Target Boards 4353 4354target_compile Procedure 4355........................ 4356 4357 target_compile source destfile type options 4358 4359`source' 4360 Source file or other arguments if TYPE is `none'. 4361 4362`destfile' 4363 Destination file or empty string to request output as return value. 4364 4365`type' 4366 Type of output that should be produced. 4367 `none' Special applications where no source is actually given. 4368 `preprocess' Run the source files through the C preprocessor. 4369 `assembly' Produce assembler source from the compiler. 4370 `object' Produce binary object files. 4371 `executable' Produce an executable program. 4372 4373`options' 4374 List of additional options: 4375 4376 Language-selection options: 4377 `ada' 4378 Use an Ada compiler. 4379 4380 `c++' 4381 Use a C++ compiler. 4382 4383 `d' 4384 Use a compiler for the D language. 4385 4386 `f77' 4387 Use a compiler for Fortran 77. 4388 4389 `f90' 4390 Use a compiler for Fortran 90. 4391 4392 `go' 4393 Use a compiler for Go. 4394 4395 `rust' 4396 Use a compiler for Rust. 4397 If none of these options are given, the C compiler is used by 4398 default. Giving multiple language-selection options is an error. 4399 4400 The `f77' option generally selects the `g77' compiler, while the 4401 `f90' option selects the newer `gfortran' frontend. Both of these 4402 can compile Fortran 77, but only `gfortran' supports Fortran 90. 4403 4404 Search path options: 4405 `incdir=DIR' 4406 Additional directory to search for preprocessor include files. 4407 Multiple uses of this option add multiple directories to the 4408 search path. 4409 4410 `libdir=DIR' 4411 Additional directory to search for libraries. Multiple uses 4412 of this option add multiple directories to the search path. 4413 4414 Target options: 4415 `debug' 4416 Compile with debugging information. Multiple uses of this 4417 option are treated as a single use. 4418 4419 `dest=TARGET' 4420 Override the current target and compile for TARGET instead. 4421 If this option is given multiple times, only the last use is 4422 significant. 4423 4424 `compiler=COMMAND' 4425 Override the defaults and use COMMAND as the compiler. If 4426 this option is given multiple times, only the last use is 4427 significant. 4428 4429 `linker=COMMAND' 4430 Override the defaults and use COMMAND to build executables. 4431 If this option is given multiple times, only the last use is 4432 significant. 4433 4434 `early_flags=FLAGS' 4435 Prepend FLAGS to the set of arguments to be passed to the 4436 compiler. Multiple uses of this option specify additional 4437 arguments. 4438 4439 `additional_flags=FLAGS' 4440 Add FLAGS to the set of arguments to be passed to the 4441 compiler. Multiple uses of this option specify additional 4442 arguments. 4443 4444 `optimize=FLAGS' 4445 Specify optimization flags to be passed to the compiler. 4446 Nothing enforces that the flags given with option must 4447 actually be related to optimization, however. If this option 4448 is given multiple times, only the last use is significant. 4449 4450 `ldflags=FLAGS' 4451 Add FLAGS to the set of arguments to be passed to the linker. 4452 Note that these are passed literally to the compiler driver, 4453 without adding a special prefix to each option. If a `-Wl,' 4454 prefix is needed with GCC, it must be included in the given 4455 FLAGS. As a group, the linker flags are only used if an 4456 executable is requested and are given special treatment with 4457 some languages. Multiple uses of this option specify 4458 additional arguments. 4459 4460 `ldscript=SCRIPT' 4461 Specify a linker script, or more precisely, the argument to 4462 pass to the linker via the compiler driver to select a linker 4463 script. The SCRIPT value is passed literally to the compiler 4464 driver. If this option is given multiple times, only the 4465 last use is significant. 4466 4467 `libs=LIBS' 4468 Specify additional libraries to be included in the link. The 4469 LIBS value is a space-separated list of libraries to include. 4470 Each element is checked, and if a file exists with that exact 4471 name, it is added to the list of sources to be given to the 4472 compiler. Otherwise, the element is passed literally to the 4473 compiler driver after any linker flags specified with the 4474 `ldflags' option. Multiple uses of this option specify 4475 additional lists, which are concatenated in the order they 4476 are given. 4477 4478 Execution options: 4479 `timeout=TIMEOUT' 4480 Abort the compile job if it is still running after TIMEOUT 4481 seconds. This is intended for compiler tests that are known 4482 to cause infinite loops upon failure. 4483 4484 `redirect=FILE' 4485 Instead of returning output emitted on `stdout', place it into 4486 FILE. 4487 4488 The `target_compile' procedure also uses several global Tcl 4489variables as overrides: 4490`CFLAGS_FOR_TARGET' 4491 If `CFLAGS_FOR_TARGET' is set, its value is prepended to the flags 4492 otherwise prepared for the compiler, even ahead of any 4493 board-specific flags inserted as a result of a language-selection 4494 option. 4495 4496`LDFLAGS_FOR_TARGET' 4497 If `LDFLAGS_FOR_TARGET' is set, the set of arguments to be passed 4498 to linker is initialized to its value instead of an empty list. 4499 The `ldflags' option appends to this list. 4500 4501`CC_FOR_TARGET' 4502 Override default compiler. If no other compiler is given and this 4503 variable is set, its value will be used instead of searching for a 4504 compiler or using the default from the target board configuration. 4505 The `compiler' option overrides this variable. 4506 4507`CXX_FOR_TARGET' 4508 Override C++ compiler. If the `c++' option is given, this 4509 compiler will be used and the `compiler' option ignored. 4510 4511`D_FOR_TARGET' 4512 Override D language compiler. If the `d' option is given, this 4513 compiler will be used and the `compiler' option ignored. 4514 4515`F77_FOR_TARGET' 4516 Override Fortran 77 compiler. If the `f77' option is given, this 4517 compiler will be used and the `compiler' option ignored. 4518 4519`F90_FOR_TARGET' 4520 Override Fortran 90 compiler. If the `f90' option is given, this 4521 compiler will be used and the `compiler' option ignored. 4522 4523`GO_FOR_TARGET' 4524 Override Go compiler. If the `go' option is given, this compiler 4525 will be used and the `compiler' option ignored. 4526 4527`GO_LD_FOR_TARGET' 4528 Override Go linker. If the `go' option is given, this linker will 4529 be used. 4530 4531`RUSTC_FOR_TARGET' 4532 Override Rust compiler. If the `rust' option is given, this 4533 compiler will be used and the `compiler' option ignored. 4534 4535`GNATMAKE_FOR_TARGET' 4536 Override Ada compiler. If the `ada' option is given, this 4537 compiler will be used and the `compiler' option ignored. 4538 4539 The `target_compile' procedure obtains most defaults from the target 4540board configuration, but additionally inserts any flags specified as 4541`cflags_for_target' on the _host_ board configuration. If no host is 4542set, the `unix' board configuration is checked for a 4543`cflags_for_target' key. If the `cflags_for_target' key exists, its 4544value is inserted into the set of arguments given to the compiler after 4545any arguments given with the `additional_flags' option. 4546 4547 In DejaGnu 1.6.2 and older, this mechanism did not work reliably and 4548the `unix' board configuration was always searched for the 4549`cflags_for_target' key, regardless of the host board selected. 4550 4551 Also in DejaGnu 1.6.2 and older, the `dest' option interacted very 4552badly with the language-selection options. There was no correct way to 4553combine these options because the language-specific defaults would be 4554read from the current target board configuration instead of the board 4555configuration specified with the `dest' option. The closest solution 4556was to always specify the language-selection option first, but this 4557results in defaults appropriate for the current target, instead of the 4558target selected with the `dest' option. 4559 4560 4561File: dejagnu.info, Node: target_link procedure, Prev: target_compile procedure, Up: Procedures For Target Boards 4562 4563target_link Procedure 4564..................... 4565 4566 target_link objects destfile flags 4567 4568`objects' 4569 4570`destfile' 4571 4572`flags' 4573 4574 4575File: dejagnu.info, Node: target database library file, Next: platform dependent procedures, Prev: Procedures For Target Boards, Up: Built-in Procedures 4576 4577A.5 Target Database Procedures 4578============================== 4579 4580* Menu: 4581 4582* board_info Procedure: board_info procedure 4583* host_info Procedure: host_info procedure 4584* set_board_info Procedure: set_board_info procedure 4585* add_board_info Procedure: add_board_info procedure 4586* set_currtarget_info Procedure: set_currtarget_info procedure 4587* target_info Procedure: target_info procedure 4588* unset_board_info Procedure: unset_board_info procedure 4589* unset_currtarget_info Procedure: unset_currtarget_info procedure 4590* push_target Procedure: push_target procedure 4591* pop_target Procedure: pop_target procedure 4592* push_host Procedure: push_host procedure 4593* pop_host Procedure: pop_host procedure 4594 4595 4596File: dejagnu.info, Node: board_info procedure, Next: host_info procedure, Up: target database library file 4597 4598board_info Procedure 4599.................... 4600 4601Searches the `board_info' array for the specified information. 4602 4603 board_info machine op args 4604 4605`machine' 4606 4607`op' 4608 4609`args' 4610 4611 4612File: dejagnu.info, Node: host_info procedure, Next: set_board_info procedure, Prev: board_info procedure, Up: target database library file 4613 4614host_info Procedure 4615................... 4616 4617 host_info op args 4618 4619`op' 4620 4621`args' 4622 4623 4624File: dejagnu.info, Node: set_board_info procedure, Next: add_board_info procedure, Prev: host_info procedure, Up: target database library file 4625 4626set_board_info Procedure 4627........................ 4628 4629This checks if the `board_info' array entry has been set already and, 4630if not, sets it to given value. 4631 4632 set_board_info entry value 4633 4634`entry' 4635 Field of the `board_info' to set. 4636 4637`value' 4638 Value to set the field to. 4639 4640 4641File: dejagnu.info, Node: add_board_info procedure, Next: set_currtarget_info procedure, Prev: set_board_info procedure, Up: target database library file 4642 4643add_board_info Procedure 4644........................ 4645 4646This treats `board_info' array's field _entry_ as a TCL list and adds 4647_value_ at the end. 4648 4649 add_board_info entry value 4650 4651`entry' 4652 The name of a `board_info' field to operate on. 4653 4654`value' 4655 The value to add to the field. 4656 4657 4658File: dejagnu.info, Node: set_currtarget_info procedure, Next: target_info procedure, Prev: add_board_info procedure, Up: target database library file 4659 4660set_currtarget_info Procedure 4661............................. 4662 4663 set_currtarget_info entry value 4664 4665`entry' 4666 4667`value' 4668 4669 4670File: dejagnu.info, Node: target_info procedure, Next: unset_board_info procedure, Prev: set_currtarget_info procedure, Up: target database library file 4671 4672target_info Procedure 4673..................... 4674 4675 target_info op args 4676 4677`op' 4678 4679`args' 4680 4681 4682File: dejagnu.info, Node: unset_board_info procedure, Next: unset_currtarget_info procedure, Prev: target_info procedure, Up: target database library file 4683 4684unset_board_info Procedure 4685.......................... 4686 4687This checks if `board_info' array's field _entry_ has been set and if 4688so, then removes it. 4689 4690 unset_board_info entry 4691 4692`entry' 4693 The name of a `board_info' field to operate on. 4694 4695 4696File: dejagnu.info, Node: unset_currtarget_info procedure, Next: push_target procedure, Prev: unset_board_info procedure, Up: target database library file 4697 4698unset_currtarget_info Procedure 4699............................... 4700 4701 unset_currtarget_info entry 4702 4703`entry' 4704 4705 4706File: dejagnu.info, Node: push_target procedure, Next: pop_target procedure, Prev: unset_currtarget_info procedure, Up: target database library file 4707 4708push_target Procedure 4709..................... 4710 4711This makes the target named _name_ be the current target connection. 4712 4713 push_target name 4714 4715`name' 4716 Name of the target to make the current connection. 4717 4718 4719File: dejagnu.info, Node: pop_target procedure, Next: push_host procedure, Prev: push_target procedure, Up: target database library file 4720 4721pop_target Procedure 4722.................... 4723 4724This unsets the current target connection. 4725 4726 pop_target 4727 4728 4729File: dejagnu.info, Node: push_host procedure, Next: pop_host procedure, Prev: pop_target procedure, Up: target database library file 4730 4731push_host Procedure 4732................... 4733 4734This procedure makes the host named _name_ be the current remote host 4735connection. 4736 4737 push_host name 4738 4739`name' 4740 Name of the host to make the current connection. 4741 4742 4743File: dejagnu.info, Node: pop_host procedure, Prev: push_host procedure, Up: target database library file 4744 4745pop_host Procedure 4746.................. 4747 4748This unsets the current host connection. 4749 4750 pop_host 4751 4752 4753File: dejagnu.info, Node: platform dependent procedures, Next: Utility Procedures, Prev: target database library file, Up: Built-in Procedures 4754 4755A.6 Platform Dependent Procedures 4756================================= 4757 4758Each combination of target and tool requires some target-dependent 4759procedures. The names of these procedures have a common form: the tool 4760name, followed by an underscore ___, and finally a suffix describing 4761the procedure's purpose. For example, a procedure to extract the 4762version from GDB is called `gdb_version'. 4763 4764 `runtest' itself calls only two of these procedures, `${tool}_exit' 4765and `${tool}_version'; these procedures use no arguments. 4766 4767 The other two procedures, `${tool}_start' and `${tool}_load', are 4768only called by the test suites themselves (or by testsuite-specific 4769initialization code); they may take arguments or not, depending on the 4770conventions used within each testsuite. 4771 4772 The usual convention for return codes from any of these procedures 4773(although it is not required by `runtest') is to return _0_ if the 4774procedure succeeded, _1_ if it failed, and _-1_ if there was a 4775communication error. 4776 4777* Menu: 4778 4779* ${tool}_start Procedure: ${tool}_start procedure 4780* ${tool}_load Procedure: ${tool}_load procedure 4781* ${tool}_exit Procedure: ${tool}_exit procedure 4782* ${tool}_version Procedure: ${tool}_version procedure 4783 4784 4785File: dejagnu.info, Node: ${tool}_start procedure, Next: ${tool}_load procedure, Up: platform dependent procedures 4786 4787${tool}_start Procedure 4788....................... 4789 4790Starts a particular tool. For an interactive tool, `${tool}_start' 4791starts and initializes the tool, leaving the tool up and running for 4792the test cases; an example is `gdb_start', the start function for GDB. 4793For a batch-oriented tool, `${tool}_start' is optional; the recommended 4794convention is to let `${tool}_start' run the tool, leaving the output 4795in a variable called `comp_output'. Test scripts can then analyze 4796`$comp_output' to determine the test results. An example of this 4797second kind of start function is `gcc_start', the start function for 4798GCC. 4799 4800 DejaGnu itself does not call `${tool}_start'. The initialization 4801module `${tool}_init.exp' must call `${tool}_start' for interactive 4802tools; for batch-oriented tools, each individual test script calls 4803`${tool}_start' (or makes other arrangements to run the tool). 4804 4805 ${tool}_start 4806 4807 4808File: dejagnu.info, Node: ${tool}_load procedure, Next: ${tool}_exit procedure, Prev: ${tool}_start procedure, Up: platform dependent procedures 4809 4810${tool}_load Procedure 4811...................... 4812 4813Loads something into a tool. For an interactive tool, this conditions 4814the tool for a particular test case; for example, `gdb_load' loads a 4815new executable file into the debugger. For batch-oriented tools, 4816`${tool}_load' may do nothing--though, for example, the GCC support 4817uses `gcc_load' to load and run a binary on the target environment. 4818Conventionally, `${tool}_load' leaves the output of any program it runs 4819in a variable called `$exec_output'. Writing `${tool}_load' can be the 4820most complex part of extending DejaGnu to a new tool or a new target, 4821if it requires much communication coding or file downloading. Test 4822scripts call `${tool}_load'. 4823 4824 ${tool}_load 4825 4826 4827File: dejagnu.info, Node: ${tool}_exit procedure, Next: ${tool}_version procedure, Prev: ${tool}_load procedure, Up: platform dependent procedures 4828 4829${tool}_exit Procedure 4830...................... 4831 4832Cleans up (if necessary) before DejaGnu exits. For interactive tools, 4833this usually ends the interactive session. You can also use 4834`${tool}_exit' to remove any temporary files left over from the tests. 4835`runtest' calls `${tool}_exit'. 4836 4837 ${tool}_exit 4838 4839 4840File: dejagnu.info, Node: ${tool}_version procedure, Prev: ${tool}_exit procedure, Up: platform dependent procedures 4841 4842${tool}_version Procedure 4843......................... 4844 4845Prints the version label and number for `${tool}'. This is called by 4846the DejaGnu procedure that prints the final summary report. The output 4847should consist of the full path name used for the tested tool, and its 4848version number. 4849 4850 ${tool}_version 4851 4852 4853File: dejagnu.info, Node: Utility Procedures, Next: Libgloss, Prev: platform dependent procedures, Up: Built-in Procedures 4854 4855A.7 Utility Procedures 4856====================== 4857 4858* Menu: 4859 4860* getdirs Procedure: getdirs procedure 4861* relative_filename Procedure: relative_filename procedure 4862* find Procedure: find procedure 4863* which Procedure: which procedure 4864* grep Procedure: grep procedure 4865* prune Procedure: prune procedure 4866* runtest_file_p Procedure: runtest_file_p procedure 4867* diff Procedure: diff procedure 4868* setenv Procedure: setenv procedure 4869* unsetenv Procedure: unsetenv procedure 4870* getenv Procedure: getenv procedure 4871 4872 4873File: dejagnu.info, Node: getdirs procedure, Next: relative_filename procedure, Prev: Utility Procedures, Up: Utility Procedures 4874 4875getdirs Procedure 4876................. 4877 4878Returns a list of all the subdirectories in a single directory that 4879match a glob pattern. If no directories match the pattern, then an 4880empty list is returned. 4881 4882 This procedure is specialized as a search for tests in testsuites: 4883`getdirs' ignores directories named `testsuite', `config', or `lib', 4884and also ignores directories associated with a few revision control 4885systems, specifically Git (`.git'), Subversion (`.svn'), CVS (`CVS'), 4886RCS (`RCS'), and SCCS (`SCCS'). These ignored directories will not 4887appear in the returned list, nor will they be examined in a recursive 4888search. 4889 4890 getdirs -all rootdir pattern 4891 4892`-all' 4893 If this option is given, then subdirectories will be matched 4894 recursively. 4895 4896`rootdir' 4897 The top level directory to start the search from. 4898 4899`pattern' 4900 The Tcl glob pattern to match. If you do not specify `pattern', 4901 `getdirs' uses a default pattern of `*'. 4902 4903 4904 4905File: dejagnu.info, Node: relative_filename procedure, Next: find procedure, Prev: getdirs procedure, Up: Utility Procedures 4906 4907relative_filename Procedure 4908........................... 4909 4910Return a relative file name, given a starting point. 4911 4912 relative_filename base destination 4913 4914`base' 4915 The starting point for relative file name traversal. 4916 4917`destination' 4918 The absolute file name that should be reached by appending the 4919 return value to base. 4920 4921 4922File: dejagnu.info, Node: find procedure, Next: which procedure, Prev: relative_filename procedure, Up: Utility Procedures 4923 4924find Procedure 4925.............. 4926 4927Search for files whose names match a glob pattern. Search 4928subdirectories recursively, starting at a particular root directory. 4929The result is the list of files whose names match. Filenames in the 4930result include all intervening subdirectory names. If no files match 4931the pattern, then an empty string is returned. 4932 4933 find rootdir pattern 4934 4935`rootdir' 4936 The top level directory to start the search from. 4937 4938`pattern' 4939 A glob pattern representing the files to find. 4940 4941 4942File: dejagnu.info, Node: which procedure, Next: grep procedure, Prev: find procedure, Up: Utility Procedures 4943 4944which Procedure 4945............... 4946 4947Searches the execution path for an executable file like the BSD 4948`which(1)' utility. This procedure uses the shell environment variable 4949`PATH'. It returns 0 if the binary is not in the path or if the `PATH' 4950environment variable is not set. If the file is in the path, this 4951procedure returns the full path to the file. 4952 4953 which file 4954 4955`file' 4956 The executable program or shell script to look for. 4957 4958 4959File: dejagnu.info, Node: grep procedure, Next: prune procedure, Prev: which procedure, Up: Utility Procedures 4960 4961grep Procedure 4962.............. 4963 4964Search a named file for lines that contain a match for a regular 4965expression. The result is a list of all the lines that match. If no 4966lines match, the result is an empty string. All of the Tcl regular 4967expression syntax is supported. 4968 4969 grep -n filename regexp line 4970 4971`-n' 4972 The `-n' option prefixes matched lines in the result with the line 4973 number, just like GNU `grep' does. This option should be used in 4974 preference to the `line' keyword documented below. 4975 4976`filename' 4977 The file to search. 4978 4979`regexp' 4980 The Unix style regular expression (as used by the `grep' UNIX 4981 utility) to search for. 4982 4983`line' 4984 Use the optional keyword `line' to prefix matched lines in the 4985 result with the line number. This usage is deprecated. 4986 4987 4988File: dejagnu.info, Node: prune procedure, Next: runtest_file_p procedure, Prev: grep procedure, Up: Utility Procedures 4989 4990prune Procedure 4991............... 4992 4993This procedure is deprecated and will be removed in a future release of 4994DejaGnu. If a testsuite uses this procedure, a copy of the procedure 4995should be made and placed in the `lib' directory of the testsuite. 4996 4997 4998File: dejagnu.info, Node: runtest_file_p procedure, Next: diff procedure, Prev: prune procedure, Up: Utility Procedures 4999 5000runtest_file_p Procedure 5001........................ 5002 5003Search _runtest_s for _testcase_ and return 1 if found, 0 if not. This 5004is used by tools like compilers where each testcase is a file. 5005 5006 runtest_file_p runtests testcase 5007 5008`runtests' 5009 `runtests' is a list of two elements. The second is a copy of 5010 what was on the right side of the `=' if `foo.exp="..."' was 5011 specified, or an empty string if no such argument is present. 5012 5013`testcase' 5014 The filename of the current testcase under consideration. 5015 5016 5017File: dejagnu.info, Node: diff procedure, Next: setenv procedure, Prev: runtest_file_p procedure, Up: Utility Procedures 5018 5019diff Procedure 5020.............. 5021 5022Compares two files and returns 1 if they match (no differences) or 0 if 5023not. If `verbose' is set, then it will print the differences to the 5024console. 5025 5026 diff file1 file2 5027 5028`file1' 5029 First file for the comparison. 5030 5031`file2' 5032 Second file for the comparison. 5033 5034 5035File: dejagnu.info, Node: setenv procedure, Next: unsetenv procedure, Prev: diff procedure, Up: Utility Procedures 5036 5037setenv Procedure 5038................ 5039 5040Set an environment variable. 5041 5042 setenv var val 5043 5044`var' 5045 The environment variable to set. 5046 5047`val' 5048 The value to set the variable to. 5049 5050 5051File: dejagnu.info, Node: unsetenv procedure, Next: getenv procedure, Prev: setenv procedure, Up: Utility Procedures 5052 5053unsetenv Procedure 5054.................. 5055 5056Unset an environment variable. 5057 5058 unsetenv var 5059 5060`var' 5061 The environment variable to unset. 5062 5063 5064File: dejagnu.info, Node: getenv procedure, Prev: unsetenv procedure, Up: Utility Procedures 5065 5066getenv Procedure 5067................ 5068 5069Returns the value of the envrionment variable _var_ if it is defined, 5070otherwise an empty string is returned. 5071 5072 getenv var 5073 5074`var' 5075 Environment variable to retrieve. 5076 5077 5078File: dejagnu.info, Node: Libgloss, Next: Debugging Procedures, Prev: Utility Procedures, Up: Built-in Procedures 5079 5080A.8 Libgloss, a free board support package (BSP) 5081================================================ 5082 5083Libgloss is a free board support package "BSP" commonly used with GCC 5084and G++ to produce a fully linked executable image for an embedded 5085systems. 5086 5087* Menu: 5088 5089* libgloss_link_flags Procedure: libgloss_link_flags procedure 5090* libgloss_include_flags Procedure: libgloss_include_flags procedure 5091* newlib_link_flags Procedure: newlib_link_flags procedure 5092* newlib_include_flags Procedure: newlib_include_flags procedure 5093* libio_include_flags Procedure: libio_include_flags procedure 5094* libio_link_flags Procedure: libio_link_flags procedure 5095* g++_include_flags Procedure: g++_include_flags procedure 5096* g++_link_flags Procedure: g++_link_flags procedure 5097* libstdc++_include_flags Procedure: libstdc++_include_flags procedure 5098* libstdc++_link_flags Procedure: libstdc++_link_flags procedure 5099* get_multilibs Procedure: get_multilibs procedure 5100* find_binutils_prog Procedure: find_binutils_prog procedure 5101* find_gcc Procedure: find_gcc procedure 5102* find_gcj Procedure: find_gcj procedure 5103* find_g++ Procedure: find_g++ procedure 5104* find_g77 Procedure: find_g77 procedure 5105* find_gfortran Procedure: find_gfortran procedure 5106* find_go Procedure: find_go procedure 5107* find_go_linker Procedure: find_go_linker procedure 5108* find_rustc Procedure: find_rustc procedure 5109* process_multilib_options Procedure: process_multilib_options procedure 5110* add_multilib_option Procedure: add_multilib_option procedure 5111* find_gas Procedure: find_gas procedure 5112* find_ld Procedure: find_ld procedure 5113* build_wrapper Procedure: build_wrapper procedure 5114* winsup_include_flags Procedure: winsup_include_flags procedure 5115* winsup_link_flags Procedure: winsup_link_flags procedure 5116 5117 5118File: dejagnu.info, Node: libgloss_link_flags procedure, Next: libgloss_include_flags procedure, Up: Libgloss 5119 5120libgloss_link_flags Procedure 5121............................. 5122 5123Finds the pieces of `libgloss' needed to link a set of object files 5124into an executable. This usually means setting the `-L' and `-B' paths 5125correctly. 5126 5127 libgloss_link_flags args 5128 5129`args' 5130 Ignored. 5131 5132 5133File: dejagnu.info, Node: libgloss_include_flags procedure, Next: newlib_link_flags procedure, Prev: libgloss_link_flags procedure, Up: Libgloss 5134 5135libgloss_include_flags Procedure 5136................................ 5137 5138This procedure always returns an empty string. It is provided for 5139consistency. 5140 5141 libgloss_include_flags args 5142 5143`args' 5144 Ignored. 5145 5146 5147File: dejagnu.info, Node: newlib_link_flags procedure, Next: newlib_include_flags procedure, Prev: libgloss_include_flags procedure, Up: Libgloss 5148 5149newlib_link_flags Procedure 5150........................... 5151 5152Return the options needed to link an executable with `newlib'. This 5153usually means setting the `-L' and `-B' paths correctly. 5154 5155 newlib_link_flags args 5156 5157`args' 5158 Ignored. 5159 5160 5161File: dejagnu.info, Node: newlib_include_flags procedure, Next: libio_include_flags procedure, Prev: newlib_link_flags procedure, Up: Libgloss 5162 5163newlib_include_flags Procedure 5164.............................. 5165 5166Return the options needed to locate the `newlib' header files. 5167 5168 newlib_include_flags args 5169 5170`args' 5171 Ignored. 5172 5173 5174File: dejagnu.info, Node: libio_include_flags procedure, Next: libio_link_flags procedure, Prev: newlib_include_flags procedure, Up: Libgloss 5175 5176libio_include_flags Procedure 5177............................. 5178 5179 libio_include_flags args 5180 5181 Return the options needed to locate the `libio' header files. 5182 5183`args' 5184 Ignored. 5185 5186 5187File: dejagnu.info, Node: libio_link_flags procedure, Next: g++_include_flags procedure, Prev: libio_include_flags procedure, Up: Libgloss 5188 5189libio_link_flags Procedure 5190.......................... 5191 5192 libio_link_flags args 5193 5194 Return the options needed to link an executable with `libio'. This 5195usually means setting the `-L' and `-B' paths correctly. 5196 5197`args' 5198 Ignored. 5199 5200 5201File: dejagnu.info, Node: g++_include_flags procedure, Next: g++_link_flags procedure, Prev: libio_link_flags procedure, Up: Libgloss 5202 5203g++_include_flags Procedure 5204........................... 5205 5206Return the options needed to locate the C++ stnadard library header 5207files. 5208 5209 g++_include_flags args 5210 5211`args' 5212 Ignored. 5213 5214 5215File: dejagnu.info, Node: g++_link_flags procedure, Next: libstdc++_include_flags procedure, Prev: g++_include_flags procedure, Up: Libgloss 5216 5217g++_link_flags Procedure 5218........................ 5219 5220 g++_link_flags args 5221 5222 Return the options needed to link an executable with `libg++'. This 5223usually means setting the `-L' and `-B' paths correctly. 5224 5225`args' 5226 Ignored. 5227 5228 5229File: dejagnu.info, Node: libstdc++_include_flags procedure, Next: libstdc++_link_flags procedure, Prev: g++_link_flags procedure, Up: Libgloss 5230 5231libstdc++_include_flags Procedure 5232................................. 5233 5234 libstdc++_include_flags args 5235 5236 Return the options needed to locate the C++ stnadard library header 5237files. 5238 5239`args' 5240 Ignored. 5241 5242 5243File: dejagnu.info, Node: libstdc++_link_flags procedure, Next: get_multilibs procedure, Prev: libstdc++_include_flags procedure, Up: Libgloss 5244 5245libstdc++_link_flags Procedure 5246.............................. 5247 5248 libstdc++_link_flags args 5249 5250`args' 5251 5252 5253File: dejagnu.info, Node: get_multilibs procedure, Next: find_binutils_prog procedure, Prev: libstdc++_link_flags procedure, Up: Libgloss 5254 5255get_multilibs Procedure 5256....................... 5257 5258 get_multilibs args 5259 5260`args' 5261 5262 5263File: dejagnu.info, Node: find_binutils_prog procedure, Next: find_gcc procedure, Prev: get_multilibs procedure, Up: Libgloss 5264 5265find_binutils_prog Procedure 5266............................ 5267 5268 find_binutils_prog name 5269 5270`name' 5271 5272 5273File: dejagnu.info, Node: find_gcc procedure, Next: find_gcj procedure, Prev: find_binutils_prog procedure, Up: Libgloss 5274 5275find_gcc Procedure 5276.................. 5277 5278Looks for a copy of the GNU C compiler in the build tree and in the 5279`PATH'. This will also return the proper transformed name for a 5280cross-compiler if the build tree is configured for one. 5281 5282 find_gcc 5283 5284 5285File: dejagnu.info, Node: find_gcj procedure, Next: find_g++ procedure, Prev: find_gcc procedure, Up: Libgloss 5286 5287find_gcj Procedure 5288.................. 5289 5290Looks for a copy of the GNU Java compiler in the build tree and in the 5291`PATH'. This will also return the proper transformed name for a 5292cross-compiler if the build tree is configured for one. 5293 5294 find_gcj 5295 5296 5297File: dejagnu.info, Node: find_g++ procedure, Next: find_g77 procedure, Prev: find_gcj procedure, Up: Libgloss 5298 5299find_g++ Procedure 5300.................. 5301 5302Looks for a copy of the GNU C++ compiler in the build tree and in the 5303`PATH'. This will also return the proper transformed name for a 5304cross-compiler if the build tree is configured for one. 5305 5306 find_g++ 5307 5308 5309File: dejagnu.info, Node: find_g77 procedure, Next: find_gfortran procedure, Prev: find_g++ procedure, Up: Libgloss 5310 5311find_g77 Procedure 5312.................. 5313 5314Looks for a copy of the GNU Fortran 77 compiler in the build tree and 5315in the `PATH'. This will also return the proper transformed name for a 5316cross-compiler if the build tree is configured for one. 5317 5318 find_g77 5319 5320 5321File: dejagnu.info, Node: find_gfortran procedure, Next: find_go procedure, Prev: find_g77 procedure, Up: Libgloss 5322 5323find_gfortran Procedure 5324....................... 5325 5326Looks for a copy of the GNU Fortran compiler in the build tree and in 5327the `PATH'. This will also return the proper transformed name for a 5328cross-compiler if the build tree is configured for one. 5329 5330 find_gfortran 5331 5332 5333File: dejagnu.info, Node: find_go procedure, Next: find_go_linker procedure, Prev: find_gfortran procedure, Up: Libgloss 5334 5335find_go Procedure 5336................. 5337 5338Looks for a copy of the GNU compiler for the Go language in the build 5339tree and in the `PATH'. This will also return the proper transformed 5340name for a cross-compiler if the build tree is configured for one. 5341 5342 find_go 5343 5344 5345File: dejagnu.info, Node: find_go_linker procedure, Next: find_rustc procedure, Prev: find_go procedure, Up: Libgloss 5346 5347find_go_linker Procedure 5348........................ 5349 5350Looks for a copy of the special linker associated with the GNU compiler 5351for the Go language in the build tree and in the `PATH'. This will 5352also return the proper transformed name for a cross-compiler if the 5353build tree is configured for one. 5354 5355 find_go_linker 5356 5357 5358File: dejagnu.info, Node: find_rustc procedure, Next: process_multilib_options procedure, Prev: find_go_linker procedure, Up: Libgloss 5359 5360find_rustc Procedure 5361.................... 5362 5363Looks for a copy of a compiler for the Rust language in the build tree 5364and in the `PATH'. The Rust compiler is different and this procedure 5365also ensures that it will be called with options to suppress output 5366coloration. 5367 5368 find_rustc 5369 5370 5371File: dejagnu.info, Node: process_multilib_options procedure, Next: add_multilib_option procedure, Prev: find_rustc procedure, Up: Libgloss 5372 5373process_multilib_options Procedure 5374.................................. 5375 5376 process_multilib_options args 5377 5378`args' 5379 5380 5381File: dejagnu.info, Node: add_multilib_option procedure, Next: find_gas procedure, Prev: process_multilib_options procedure, Up: Libgloss 5382 5383add_multilib_option Procedure 5384............................. 5385 5386 add_multilib_option args 5387 5388`args' 5389 5390 5391File: dejagnu.info, Node: find_gas procedure, Next: find_ld procedure, Prev: add_multilib_option procedure, Up: Libgloss 5392 5393find_gas Procedure 5394.................. 5395 5396 find_gas 5397 5398 5399File: dejagnu.info, Node: find_ld procedure, Next: build_wrapper procedure, Prev: find_gas procedure, Up: Libgloss 5400 5401find_ld Procedure 5402................. 5403 5404 find_ld 5405 5406 5407File: dejagnu.info, Node: build_wrapper procedure, Next: winsup_include_flags procedure, Prev: find_ld procedure, Up: Libgloss 5408 5409build_wrapper Procedure 5410....................... 5411 5412 build_wrapper gluefile 5413 5414`gluefile' 5415 5416 5417File: dejagnu.info, Node: winsup_include_flags procedure, Next: winsup_link_flags procedure, Prev: build_wrapper procedure, Up: Libgloss 5418 5419winsup_include_flags Procedure 5420.............................. 5421 5422 winsup_include_flags args 5423 5424`args' 5425 5426 5427File: dejagnu.info, Node: winsup_link_flags procedure, Prev: winsup_include_flags procedure, Up: Libgloss 5428 5429winsup_link_flags Procedure 5430........................... 5431 5432 winsup_link_flags args 5433 5434`args' 5435 5436 5437File: dejagnu.info, Node: Debugging Procedures, Prev: Libgloss, Up: Built-in Procedures 5438 5439A.9 Procedures for debugging your scripts 5440========================================= 5441 5442* Menu: 5443 5444* bt Procedure: bt procedure 5445* dumpvars Procedure: dumpvars procedure 5446* dumplocals Procedure: dumplocals procedure 5447* dumprocs Procedure: dumprocs procedure 5448* dumpwatch Procedure: dumpwatch procedure 5449* watcharray Procedure: watcharray procedure 5450* watchvar Procedure: watchvar procedure 5451* watchunset Procedure: watchunset procedure 5452* watchwrite Procedure: watchwrite procedure 5453* watchread Procedure: watchread procedure 5454* watchdel Procedure: watchdel procedure 5455* print Procedure: print procedure 5456* quit Procedure: quit procedure 5457 5458 5459File: dejagnu.info, Node: bt procedure, Next: dumpvars procedure, Prev: Debugging Procedures, Up: Debugging Procedures 5460 5461bt Procedure 5462............ 5463 5464This procedure prints a backtrace using the `w' command from the Tcl 5465debugger. 5466 5467 bt 5468 5469 5470File: dejagnu.info, Node: dumpvars procedure, Next: dumplocals procedure, Prev: bt procedure, Up: Debugging Procedures 5471 5472dumpvars Procedure 5473.................. 5474 5475This procedure prints the values of the global variables that match a 5476glob pattern. Abbreviation: `dv'. 5477 5478 dumpvars pattern 5479 5480`pattern' 5481 The global variables to dump. 5482 5483 5484File: dejagnu.info, Node: dumplocals procedure, Next: dumprocs procedure, Prev: dumpvars procedure, Up: Debugging Procedures 5485 5486dumplocals Procedure 5487.................... 5488 5489This procedure prints the values of local variables that match a glob 5490pattern. Abbreviation: `dl'. 5491 5492 dumplocals pattern 5493 5494`pattern' 5495 The local variables to dump. 5496 5497 5498File: dejagnu.info, Node: dumprocs procedure, Next: dumpwatch procedure, Prev: dumplocals procedure, Up: Debugging Procedures 5499 5500dumprocs Procedure 5501.................. 5502 5503This procedure dumps the body of all procs that match a glob pattern. 5504It is abbreviated as `dp'. 5505 5506 dumprocs pattern 5507 5508`pattern' 5509 The proc bodies to dump. 5510 5511 5512File: dejagnu.info, Node: dumpwatch procedure, Next: watcharray procedure, Prev: dumprocs procedure, Up: Debugging Procedures 5513 5514dumpwatch Procedure 5515................... 5516 5517This procedure prints all of the watchpoints matching a glob pattern. 5518It is abbreviated as `dw'. 5519 5520 dumpwatch pattern 5521 5522`pattern' 5523 The watchpoints to dump. 5524 5525 5526File: dejagnu.info, Node: watcharray procedure, Next: watchvar procedure, Prev: dumpwatch procedure, Up: Debugging Procedures 5527 5528watcharray Procedure 5529.................... 5530 5531 watcharray array element type 5532 5533`array' 5534 5535`element' 5536 5537`type' 5538 The csh "glob" style pattern to look for. 5539 5540 5541File: dejagnu.info, Node: watchvar procedure, Next: watchunset procedure, Prev: watcharray procedure, Up: Debugging Procedures 5542 5543watchvar Procedure 5544.................. 5545 5546 watchvar var type 5547 5548`var' 5549 5550`type' 5551 5552 5553File: dejagnu.info, Node: watchunset procedure, Next: watchwrite procedure, Prev: watchvar procedure, Up: Debugging Procedures 5554 5555watchunset Procedure 5556.................... 5557 5558This breaks program execution when the variable `var' is unset. 5559Abbreviation: `wu'. 5560 5561 watchunset pattern 5562 5563`pattern' 5564 5565 5566File: dejagnu.info, Node: watchwrite procedure, Next: watchread procedure, Prev: watchunset procedure, Up: Debugging Procedures 5567 5568watchwrite Procedure 5569.................... 5570 5571This breaks program execution when the variable `var' is written. 5572Abbreviation: `ww'. 5573 5574 watchwrite var 5575 5576`var' 5577 The variable to watch. 5578 5579 5580File: dejagnu.info, Node: watchread procedure, Next: watchdel procedure, Prev: watchwrite procedure, Up: Debugging Procedures 5581 5582watchread Procedure 5583................... 5584 5585This breaks program execution when the variable `var' is read. 5586Abbreviation: `wr'. 5587 5588 watchread var 5589 5590`var' 5591 The variable to watch. 5592 5593 5594File: dejagnu.info, Node: watchdel procedure, Next: print procedure, Prev: watchread procedure, Up: Debugging Procedures 5595 5596watchdel Procedure 5597.................. 5598 5599This deletes a watchpoint from the watch list. Abbreviation: `wd'. 5600 5601 watchdel pattern 5602 5603`pattern' 5604 5605 5606File: dejagnu.info, Node: print procedure, Next: quit procedure, Prev: watchdel procedure, Up: Debugging Procedures 5607 5608print Procedure 5609............... 5610 5611This prints the value of a variable. Abbreviation: `p'. 5612 5613 print var 5614 5615`var' 5616 The variable to print. 5617 5618 5619File: dejagnu.info, Node: quit procedure, Prev: print procedure, Up: Debugging Procedures 5620 5621quit Procedure 5622.............. 5623 5624This makes `runtest' exit. Abbreviation: `q'. 5625 5626 quit 5627 5628 5629File: dejagnu.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Built-in Procedures, Up: Top 5630 5631Appendix B GNU Free Documentation License 5632***************************************** 5633 5634 Version 1.3, 3 November 2008 5635 5636 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 5637 `https://fsf.org/' 5638 5639 Everyone is permitted to copy and distribute verbatim copies 5640 of this license document, but changing it is not allowed. 5641 5642 0. PREAMBLE 5643 5644 The purpose of this License is to make a manual, textbook, or other 5645 functional and useful document "free" in the sense of freedom: to 5646 assure everyone the effective freedom to copy and redistribute it, 5647 with or without modifying it, either commercially or 5648 noncommercially. Secondarily, this License preserves for the 5649 author and publisher a way to get credit for their work, while not 5650 being considered responsible for modifications made by others. 5651 5652 This License is a kind of "copyleft", which means that derivative 5653 works of the document must themselves be free in the same sense. 5654 It complements the GNU General Public License, which is a copyleft 5655 license designed for free software. 5656 5657 We have designed this License in order to use it for manuals for 5658 free software, because free software needs free documentation: a 5659 free program should come with manuals providing the same freedoms 5660 that the software does. But this License is not limited to 5661 software manuals; it can be used for any textual work, regardless 5662 of subject matter or whether it is published as a printed book. 5663 We recommend this License principally for works whose purpose is 5664 instruction or reference. 5665 5666 1. APPLICABILITY AND DEFINITIONS 5667 5668 This License applies to any manual or other work, in any medium, 5669 that contains a notice placed by the copyright holder saying it 5670 can be distributed under the terms of this License. Such a notice 5671 grants a world-wide, royalty-free license, unlimited in duration, 5672 to use that work under the conditions stated herein. The 5673 "Document", below, refers to any such manual or work. Any member 5674 of the public is a licensee, and is addressed as "you". You 5675 accept the license if you copy, modify or distribute the work in a 5676 way requiring permission under copyright law. 5677 5678 A "Modified Version" of the Document means any work containing the 5679 Document or a portion of it, either copied verbatim, or with 5680 modifications and/or translated into another language. 5681 5682 A "Secondary Section" is a named appendix or a front-matter section 5683 of the Document that deals exclusively with the relationship of the 5684 publishers or authors of the Document to the Document's overall 5685 subject (or to related matters) and contains nothing that could 5686 fall directly within that overall subject. (Thus, if the Document 5687 is in part a textbook of mathematics, a Secondary Section may not 5688 explain any mathematics.) The relationship could be a matter of 5689 historical connection with the subject or with related matters, or 5690 of legal, commercial, philosophical, ethical or political position 5691 regarding them. 5692 5693 The "Invariant Sections" are certain Secondary Sections whose 5694 titles are designated, as being those of Invariant Sections, in 5695 the notice that says that the Document is released under this 5696 License. If a section does not fit the above definition of 5697 Secondary then it is not allowed to be designated as Invariant. 5698 The Document may contain zero Invariant Sections. If the Document 5699 does not identify any Invariant Sections then there are none. 5700 5701 The "Cover Texts" are certain short passages of text that are 5702 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 5703 that says that the Document is released under this License. A 5704 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 5705 be at most 25 words. 5706 5707 A "Transparent" copy of the Document means a machine-readable copy, 5708 represented in a format whose specification is available to the 5709 general public, that is suitable for revising the document 5710 straightforwardly with generic text editors or (for images 5711 composed of pixels) generic paint programs or (for drawings) some 5712 widely available drawing editor, and that is suitable for input to 5713 text formatters or for automatic translation to a variety of 5714 formats suitable for input to text formatters. A copy made in an 5715 otherwise Transparent file format whose markup, or absence of 5716 markup, has been arranged to thwart or discourage subsequent 5717 modification by readers is not Transparent. An image format is 5718 not Transparent if used for any substantial amount of text. A 5719 copy that is not "Transparent" is called "Opaque". 5720 5721 Examples of suitable formats for Transparent copies include plain 5722 ASCII without markup, Texinfo input format, LaTeX input format, 5723 SGML or XML using a publicly available DTD, and 5724 standard-conforming simple HTML, PostScript or PDF designed for 5725 human modification. Examples of transparent image formats include 5726 PNG, XCF and JPG. Opaque formats include proprietary formats that 5727 can be read and edited only by proprietary word processors, SGML or 5728 XML for which the DTD and/or processing tools are not generally 5729 available, and the machine-generated HTML, PostScript or PDF 5730 produced by some word processors for output purposes only. 5731 5732 The "Title Page" means, for a printed book, the title page itself, 5733 plus such following pages as are needed to hold, legibly, the 5734 material this License requires to appear in the title page. For 5735 works in formats which do not have any title page as such, "Title 5736 Page" means the text near the most prominent appearance of the 5737 work's title, preceding the beginning of the body of the text. 5738 5739 The "publisher" means any person or entity that distributes copies 5740 of the Document to the public. 5741 5742 A section "Entitled XYZ" means a named subunit of the Document 5743 whose title either is precisely XYZ or contains XYZ in parentheses 5744 following text that translates XYZ in another language. (Here XYZ 5745 stands for a specific section name mentioned below, such as 5746 "Acknowledgements", "Dedications", "Endorsements", or "History".) 5747 To "Preserve the Title" of such a section when you modify the 5748 Document means that it remains a section "Entitled XYZ" according 5749 to this definition. 5750 5751 The Document may include Warranty Disclaimers next to the notice 5752 which states that this License applies to the Document. These 5753 Warranty Disclaimers are considered to be included by reference in 5754 this License, but only as regards disclaiming warranties: any other 5755 implication that these Warranty Disclaimers may have is void and 5756 has no effect on the meaning of this License. 5757 5758 2. VERBATIM COPYING 5759 5760 You may copy and distribute the Document in any medium, either 5761 commercially or noncommercially, provided that this License, the 5762 copyright notices, and the license notice saying this License 5763 applies to the Document are reproduced in all copies, and that you 5764 add no other conditions whatsoever to those of this License. You 5765 may not use technical measures to obstruct or control the reading 5766 or further copying of the copies you make or distribute. However, 5767 you may accept compensation in exchange for copies. If you 5768 distribute a large enough number of copies you must also follow 5769 the conditions in section 3. 5770 5771 You may also lend copies, under the same conditions stated above, 5772 and you may publicly display copies. 5773 5774 3. COPYING IN QUANTITY 5775 5776 If you publish printed copies (or copies in media that commonly 5777 have printed covers) of the Document, numbering more than 100, and 5778 the Document's license notice requires Cover Texts, you must 5779 enclose the copies in covers that carry, clearly and legibly, all 5780 these Cover Texts: Front-Cover Texts on the front cover, and 5781 Back-Cover Texts on the back cover. Both covers must also clearly 5782 and legibly identify you as the publisher of these copies. The 5783 front cover must present the full title with all words of the 5784 title equally prominent and visible. You may add other material 5785 on the covers in addition. Copying with changes limited to the 5786 covers, as long as they preserve the title of the Document and 5787 satisfy these conditions, can be treated as verbatim copying in 5788 other respects. 5789 5790 If the required texts for either cover are too voluminous to fit 5791 legibly, you should put the first ones listed (as many as fit 5792 reasonably) on the actual cover, and continue the rest onto 5793 adjacent pages. 5794 5795 If you publish or distribute Opaque copies of the Document 5796 numbering more than 100, you must either include a 5797 machine-readable Transparent copy along with each Opaque copy, or 5798 state in or with each Opaque copy a computer-network location from 5799 which the general network-using public has access to download 5800 using public-standard network protocols a complete Transparent 5801 copy of the Document, free of added material. If you use the 5802 latter option, you must take reasonably prudent steps, when you 5803 begin distribution of Opaque copies in quantity, to ensure that 5804 this Transparent copy will remain thus accessible at the stated 5805 location until at least one year after the last time you 5806 distribute an Opaque copy (directly or through your agents or 5807 retailers) of that edition to the public. 5808 5809 It is requested, but not required, that you contact the authors of 5810 the Document well before redistributing any large number of 5811 copies, to give them a chance to provide you with an updated 5812 version of the Document. 5813 5814 4. MODIFICATIONS 5815 5816 You may copy and distribute a Modified Version of the Document 5817 under the conditions of sections 2 and 3 above, provided that you 5818 release the Modified Version under precisely this License, with 5819 the Modified Version filling the role of the Document, thus 5820 licensing distribution and modification of the Modified Version to 5821 whoever possesses a copy of it. In addition, you must do these 5822 things in the Modified Version: 5823 5824 A. Use in the Title Page (and on the covers, if any) a title 5825 distinct from that of the Document, and from those of 5826 previous versions (which should, if there were any, be listed 5827 in the History section of the Document). You may use the 5828 same title as a previous version if the original publisher of 5829 that version gives permission. 5830 5831 B. List on the Title Page, as authors, one or more persons or 5832 entities responsible for authorship of the modifications in 5833 the Modified Version, together with at least five of the 5834 principal authors of the Document (all of its principal 5835 authors, if it has fewer than five), unless they release you 5836 from this requirement. 5837 5838 C. State on the Title page the name of the publisher of the 5839 Modified Version, as the publisher. 5840 5841 D. Preserve all the copyright notices of the Document. 5842 5843 E. Add an appropriate copyright notice for your modifications 5844 adjacent to the other copyright notices. 5845 5846 F. Include, immediately after the copyright notices, a license 5847 notice giving the public permission to use the Modified 5848 Version under the terms of this License, in the form shown in 5849 the Addendum below. 5850 5851 G. Preserve in that license notice the full lists of Invariant 5852 Sections and required Cover Texts given in the Document's 5853 license notice. 5854 5855 H. Include an unaltered copy of this License. 5856 5857 I. Preserve the section Entitled "History", Preserve its Title, 5858 and add to it an item stating at least the title, year, new 5859 authors, and publisher of the Modified Version as given on 5860 the Title Page. If there is no section Entitled "History" in 5861 the Document, create one stating the title, year, authors, 5862 and publisher of the Document as given on its Title Page, 5863 then add an item describing the Modified Version as stated in 5864 the previous sentence. 5865 5866 J. Preserve the network location, if any, given in the Document 5867 for public access to a Transparent copy of the Document, and 5868 likewise the network locations given in the Document for 5869 previous versions it was based on. These may be placed in 5870 the "History" section. You may omit a network location for a 5871 work that was published at least four years before the 5872 Document itself, or if the original publisher of the version 5873 it refers to gives permission. 5874 5875 K. For any section Entitled "Acknowledgements" or "Dedications", 5876 Preserve the Title of the section, and preserve in the 5877 section all the substance and tone of each of the contributor 5878 acknowledgements and/or dedications given therein. 5879 5880 L. Preserve all the Invariant Sections of the Document, 5881 unaltered in their text and in their titles. Section numbers 5882 or the equivalent are not considered part of the section 5883 titles. 5884 5885 M. Delete any section Entitled "Endorsements". Such a section 5886 may not be included in the Modified Version. 5887 5888 N. Do not retitle any existing section to be Entitled 5889 "Endorsements" or to conflict in title with any Invariant 5890 Section. 5891 5892 O. Preserve any Warranty Disclaimers. 5893 5894 If the Modified Version includes new front-matter sections or 5895 appendices that qualify as Secondary Sections and contain no 5896 material copied from the Document, you may at your option 5897 designate some or all of these sections as invariant. To do this, 5898 add their titles to the list of Invariant Sections in the Modified 5899 Version's license notice. These titles must be distinct from any 5900 other section titles. 5901 5902 You may add a section Entitled "Endorsements", provided it contains 5903 nothing but endorsements of your Modified Version by various 5904 parties--for example, statements of peer review or that the text 5905 has been approved by an organization as the authoritative 5906 definition of a standard. 5907 5908 You may add a passage of up to five words as a Front-Cover Text, 5909 and a passage of up to 25 words as a Back-Cover Text, to the end 5910 of the list of Cover Texts in the Modified Version. Only one 5911 passage of Front-Cover Text and one of Back-Cover Text may be 5912 added by (or through arrangements made by) any one entity. If the 5913 Document already includes a cover text for the same cover, 5914 previously added by you or by arrangement made by the same entity 5915 you are acting on behalf of, you may not add another; but you may 5916 replace the old one, on explicit permission from the previous 5917 publisher that added the old one. 5918 5919 The author(s) and publisher(s) of the Document do not by this 5920 License give permission to use their names for publicity for or to 5921 assert or imply endorsement of any Modified Version. 5922 5923 5. COMBINING DOCUMENTS 5924 5925 You may combine the Document with other documents released under 5926 this License, under the terms defined in section 4 above for 5927 modified versions, provided that you include in the combination 5928 all of the Invariant Sections of all of the original documents, 5929 unmodified, and list them all as Invariant Sections of your 5930 combined work in its license notice, and that you preserve all 5931 their Warranty Disclaimers. 5932 5933 The combined work need only contain one copy of this License, and 5934 multiple identical Invariant Sections may be replaced with a single 5935 copy. If there are multiple Invariant Sections with the same name 5936 but different contents, make the title of each such section unique 5937 by adding at the end of it, in parentheses, the name of the 5938 original author or publisher of that section if known, or else a 5939 unique number. Make the same adjustment to the section titles in 5940 the list of Invariant Sections in the license notice of the 5941 combined work. 5942 5943 In the combination, you must combine any sections Entitled 5944 "History" in the various original documents, forming one section 5945 Entitled "History"; likewise combine any sections Entitled 5946 "Acknowledgements", and any sections Entitled "Dedications". You 5947 must delete all sections Entitled "Endorsements." 5948 5949 6. COLLECTIONS OF DOCUMENTS 5950 5951 You may make a collection consisting of the Document and other 5952 documents released under this License, and replace the individual 5953 copies of this License in the various documents with a single copy 5954 that is included in the collection, provided that you follow the 5955 rules of this License for verbatim copying of each of the 5956 documents in all other respects. 5957 5958 You may extract a single document from such a collection, and 5959 distribute it individually under this License, provided you insert 5960 a copy of this License into the extracted document, and follow 5961 this License in all other respects regarding verbatim copying of 5962 that document. 5963 5964 7. AGGREGATION WITH INDEPENDENT WORKS 5965 5966 A compilation of the Document or its derivatives with other 5967 separate and independent documents or works, in or on a volume of 5968 a storage or distribution medium, is called an "aggregate" if the 5969 copyright resulting from the compilation is not used to limit the 5970 legal rights of the compilation's users beyond what the individual 5971 works permit. When the Document is included in an aggregate, this 5972 License does not apply to the other works in the aggregate which 5973 are not themselves derivative works of the Document. 5974 5975 If the Cover Text requirement of section 3 is applicable to these 5976 copies of the Document, then if the Document is less than one half 5977 of the entire aggregate, the Document's Cover Texts may be placed 5978 on covers that bracket the Document within the aggregate, or the 5979 electronic equivalent of covers if the Document is in electronic 5980 form. Otherwise they must appear on printed covers that bracket 5981 the whole aggregate. 5982 5983 8. TRANSLATION 5984 5985 Translation is considered a kind of modification, so you may 5986 distribute translations of the Document under the terms of section 5987 4. Replacing Invariant Sections with translations requires special 5988 permission from their copyright holders, but you may include 5989 translations of some or all Invariant Sections in addition to the 5990 original versions of these Invariant Sections. You may include a 5991 translation of this License, and all the license notices in the 5992 Document, and any Warranty Disclaimers, provided that you also 5993 include the original English version of this License and the 5994 original versions of those notices and disclaimers. In case of a 5995 disagreement between the translation and the original version of 5996 this License or a notice or disclaimer, the original version will 5997 prevail. 5998 5999 If a section in the Document is Entitled "Acknowledgements", 6000 "Dedications", or "History", the requirement (section 4) to 6001 Preserve its Title (section 1) will typically require changing the 6002 actual title. 6003 6004 9. TERMINATION 6005 6006 You may not copy, modify, sublicense, or distribute the Document 6007 except as expressly provided under this License. Any attempt 6008 otherwise to copy, modify, sublicense, or distribute it is void, 6009 and will automatically terminate your rights under this License. 6010 6011 However, if you cease all violation of this License, then your 6012 license from a particular copyright holder is reinstated (a) 6013 provisionally, unless and until the copyright holder explicitly 6014 and finally terminates your license, and (b) permanently, if the 6015 copyright holder fails to notify you of the violation by some 6016 reasonable means prior to 60 days after the cessation. 6017 6018 Moreover, your license from a particular copyright holder is 6019 reinstated permanently if the copyright holder notifies you of the 6020 violation by some reasonable means, this is the first time you have 6021 received notice of violation of this License (for any work) from 6022 that copyright holder, and you cure the violation prior to 30 days 6023 after your receipt of the notice. 6024 6025 Termination of your rights under this section does not terminate 6026 the licenses of parties who have received copies or rights from 6027 you under this License. If your rights have been terminated and 6028 not permanently reinstated, receipt of a copy of some or all of 6029 the same material does not give you any rights to use it. 6030 6031 10. FUTURE REVISIONS OF THIS LICENSE 6032 6033 The Free Software Foundation may publish new, revised versions of 6034 the GNU Free Documentation License from time to time. Such new 6035 versions will be similar in spirit to the present version, but may 6036 differ in detail to address new problems or concerns. See 6037 `https://www.gnu.org/licenses/'. 6038 6039 Each version of the License is given a distinguishing version 6040 number. If the Document specifies that a particular numbered 6041 version of this License "or any later version" applies to it, you 6042 have the option of following the terms and conditions either of 6043 that specified version or of any later version that has been 6044 published (not as a draft) by the Free Software Foundation. If 6045 the Document does not specify a version number of this License, 6046 you may choose any version ever published (not as a draft) by the 6047 Free Software Foundation. If the Document specifies that a proxy 6048 can decide which future versions of this License can be used, that 6049 proxy's public statement of acceptance of a version permanently 6050 authorizes you to choose that version for the Document. 6051 6052 11. RELICENSING 6053 6054 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 6055 World Wide Web server that publishes copyrightable works and also 6056 provides prominent facilities for anybody to edit those works. A 6057 public wiki that anybody can edit is an example of such a server. 6058 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 6059 site means any set of copyrightable works thus published on the MMC 6060 site. 6061 6062 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 6063 license published by Creative Commons Corporation, a not-for-profit 6064 corporation with a principal place of business in San Francisco, 6065 California, as well as future copyleft versions of that license 6066 published by that same organization. 6067 6068 "Incorporate" means to publish or republish a Document, in whole or 6069 in part, as part of another Document. 6070 6071 An MMC is "eligible for relicensing" if it is licensed under this 6072 License, and if all works that were first published under this 6073 License somewhere other than this MMC, and subsequently 6074 incorporated in whole or in part into the MMC, (1) had no cover 6075 texts or invariant sections, and (2) were thus incorporated prior 6076 to November 1, 2008. 6077 6078 The operator of an MMC Site may republish an MMC contained in the 6079 site under CC-BY-SA on the same site at any time before August 1, 6080 2009, provided the MMC is eligible for relicensing. 6081 6082 6083 6084File: dejagnu.info, Node: Concept Index, Next: Procedure Index, Prev: GNU Free Documentation License, Up: Top 6085 6086Concept Index 6087************* 6088 6089�[index�] 6090* Menu: 6091 6092* adding, board: Adding a new board. (line 6) 6093* adding, target: Adding a new target. (line 6) 6094* adding, testsuite: Adding a new testsuite. 6095 (line 6) 6096* assertions: A POSIX Conforming Test Framework. 6097 (line 18) 6098* C unit testing API: C unit testing API. (line 6) 6099* C++ unit testing API: C++ unit testing API. (line 6) 6100* configuration file, board: Board configuration file. 6101 (line 6) 6102* configuration file, global: Global configuration file. 6103 (line 6) 6104* configuration file, local: Local configuration file. 6105 (line 6) 6106* configuration values: Configuration file values. 6107 (line 6) 6108* customization: Customizing DejaGnu. (line 6) 6109* dejagnu help, invoking: Invoking dejagnu help. 6110 (line 6) 6111* dejagnu report card, invoking: Invoking dejagnu report card. 6112 (line 6) 6113* dejagnu report-card, invoking: Invoking dejagnu report card. 6114 (line 6) 6115* dejagnu, invoking: Invoking dejagnu. (line 6) 6116* design goals: Design goals. (line 6) 6117* extending DejaGnu: Extending DejaGnu. (line 6) 6118* extensions: Extending DejaGnu. (line 6) 6119* hints on writing a test case: Writing a test case. (line 53) 6120* options, common: Common Operations. (line 6) 6121* output file, debug log: Debug log file. (line 6) 6122* output file, detailed log: Detailed log file. (line 6) 6123* output file, summary log: Summary log file. (line 6) 6124* output states: Output States. (line 6) 6125* POSIX 1003.3: A POSIX Conforming Test Framework. 6126 (line 6) 6127* POSIX compliant test framework: A POSIX Conforming Test Framework. 6128 (line 6) 6129* runtest, invoking: Invoking runtest. (line 6) 6130* test cases, adding: Adding a test case to a testsuite. 6131 (line 6) 6132* test cases, debugging: Debugging a test case. 6133 (line 6) 6134* test cases, writing: Writing a test case. (line 53) 6135* testing on remote hosts: Remote host testing. (line 6) 6136* unit testing: What is unit testing?. 6137 (line 6) 6138* Writing a test case: Writing a test case. (line 6) 6139 6140 6141File: dejagnu.info, Node: Procedure Index, Next: Variable Index, Prev: Concept Index, Up: Top 6142 6143Procedure Index 6144*************** 6145 6146�[index�] 6147* Menu: 6148 6149* ${tool}_exit: ${tool}_exit procedure. 6150 (line 6) 6151* ${tool}_load: ${tool}_load procedure. 6152 (line 6) 6153* ${tool}_start: ${tool}_start procedure. 6154 (line 6) 6155* ${tool}_version: ${tool}_version procedure. 6156 (line 6) 6157* add_board_info: add_board_info procedure. 6158 (line 6) 6159* add_multilib_option: add_multilib_option procedure. 6160 (line 6) 6161* board_info: board_info procedure. (line 6) 6162* bt: bt procedure. (line 6) 6163* build_wrapper: build_wrapper procedure. 6164 (line 6) 6165* call_remote: call_remote procedure. (line 6) 6166* check_conditional_xfail: check_conditional_xfail procedure. 6167 (line 6) 6168* check_for_board_status: check_for_board_status procedure. 6169 (line 6) 6170* clear_xfail: clear_xfail procedure. (line 6) 6171* close_logs: close_logs procedure. (line 6) 6172* default_link: default_link procedure. 6173 (line 6) 6174* default_target_assemble: default_target_assemble procedure. 6175 (line 6) 6176* default_target_compile: default_target_compile procedure. 6177 (line 6) 6178* diff: diff procedure. (line 6) 6179* dumplocals: dumplocals procedure. (line 6) 6180* dumprocs: dumprocs procedure. (line 6) 6181* dumpvars: dumpvars procedure. (line 6) 6182* dumpwatch: dumpwatch procedure. (line 6) 6183* fail: fail procedure. (line 6) 6184* file_on_build: file_on_build procedure. 6185 (line 6) 6186* file_on_host: file_on_host procedure. 6187 (line 6) 6188* find: find procedure. (line 6) 6189* find_binutils_prog: find_binutils_prog procedure. 6190 (line 6) 6191* find_g++: find_g++ procedure. (line 6) 6192* find_g77: find_g77 procedure. (line 6) 6193* find_gas: find_gas procedure. (line 6) 6194* find_gcc: find_gcc procedure. (line 6) 6195* find_gcj: find_gcj procedure. (line 6) 6196* find_gfortran: find_gfortran procedure. 6197 (line 6) 6198* find_go: find_go procedure. (line 6) 6199* find_go_linker: find_go_linker procedure. 6200 (line 6) 6201* find_ld: find_ld procedure. (line 6) 6202* find_rustc: find_rustc procedure. (line 6) 6203* ftp_close: ftp_close procedure. (line 6) 6204* ftp_download: ftp_download procedure. 6205 (line 6) 6206* ftp_open: ftp_open procedure. (line 6) 6207* ftp_upload: ftp_upload procedure. (line 6) 6208* g++_include_flags: g++_include_flags procedure. 6209 (line 6) 6210* g++_link_flags: g++_link_flags procedure. 6211 (line 6) 6212* get_multilibs: get_multilibs procedure. 6213 (line 6) 6214* get_warning_threshold: get_warning_threshold procedure. 6215 (line 6) 6216* getdirs: getdirs procedure. (line 6) 6217* getenv: getenv procedure. (line 6) 6218* grep: grep procedure. (line 6) 6219* host_execute: Running unit tests. (line 6) 6220* host_info: host_info procedure. (line 6) 6221* is3way: is3way procedure. (line 6) 6222* is_remote: is_remote procedure. (line 6) 6223* isbuild: isbuild procedure. (line 6) 6224* ishost: ishost procedure. (line 6) 6225* isnative: isnative procedure. (line 6) 6226* isremote: isremote procedure. (line 6) 6227* istarget: istarget procedure. (line 6) 6228* kermit_command: kermit_command procedure. 6229 (line 6) 6230* kermit_open: kermit_open procedure. (line 6) 6231* kermit_send: kermit_send procedure. (line 6) 6232* kermit_transmit: kermit_transmit procedure. 6233 (line 6) 6234* libgloss_include_flags: libgloss_include_flags procedure. 6235 (line 6) 6236* libgloss_link_flags: libgloss_link_flags procedure. 6237 (line 6) 6238* libio_include_flags: libio_include_flags procedure. 6239 (line 6) 6240* libio_link_flags: libio_link_flags procedure. 6241 (line 6) 6242* libstdc++_include_flags: libstdc++_include_flags procedure. 6243 (line 6) 6244* libstdc++_link_flags: libstdc++_link_flags procedure. 6245 (line 6) 6246* load_lib: load_lib procedure. (line 6) 6247* local_exec: local_exec procedure. (line 6) 6248* log_and_exit: log_and_exit procedure. 6249 (line 6) 6250* log_summary: log_summary procedure. (line 6) 6251* newlib_include_flags: newlib_include_flags procedure. 6252 (line 6) 6253* newlib_link_flags: newlib_link_flags procedure. 6254 (line 6) 6255* note: note procedure. (line 6) 6256* open_logs: open_logs procedure. (line 6) 6257* pass: pass procedure. (line 6) 6258* perror: perror procedure. (line 6) 6259* pop_config: pop_config procedure. (line 6) 6260* pop_host: pop_host procedure. (line 6) 6261* pop_target: pop_target procedure. (line 6) 6262* print: print procedure. (line 6) 6263* process_multilib_options: process_multilib_options procedure. 6264 (line 6) 6265* prune: prune procedure. (line 6) 6266* prune_warnings: prune_warnings procedure. 6267 (line 6) 6268* push_build: push_build procedure. (line 6) 6269* push_config: push_config procedure. (line 6) 6270* push_host: push_host procedure. (line 6) 6271* push_target: push_target procedure. (line 6) 6272* quit: quit procedure. (line 6) 6273* reboot_target: reboot_target procedure. 6274 (line 6) 6275* relative_filename: relative_filename procedure. 6276 (line 6) 6277* remote_binary: remote_binary procedure. 6278 (line 6) 6279* remote_close: remote_close procedure. 6280 (line 6) 6281* remote_download: remote_download procedure. 6282 (line 6) 6283* remote_exec: remote_exec procedure. (line 6) 6284* remote_expect: remote_expect procedure. 6285 (line 6) 6286* remote_file: remote_file procedure. (line 6) 6287* remote_ld: remote_ld procedure. (line 6) 6288* remote_load: remote_load procedure. (line 6) 6289* remote_open: remote_open procedure. (line 6) 6290* remote_pop_conn: remote_pop_conn procedure. 6291 (line 6) 6292* remote_push_conn: remote_push_conn procedure. 6293 (line 6) 6294* remote_raw_binary: remote_raw_binary procedure. 6295 (line 6) 6296* remote_raw_close: remote_raw_close procedure. 6297 (line 6) 6298* remote_raw_file: remote_raw_file procedure. 6299 (line 6) 6300* remote_raw_ld: remote_raw_ld procedure. 6301 (line 6) 6302* remote_raw_load: remote_raw_load procedure. 6303 (line 6) 6304* remote_raw_open: remote_raw_open procedure. 6305 (line 6) 6306* remote_raw_send: remote_raw_send procedure. 6307 (line 6) 6308* remote_raw_spawn: remote_raw_spawn procedure. 6309 (line 6) 6310* remote_raw_transmit: remote_raw_transmit procedure. 6311 (line 6) 6312* remote_raw_wait: remote_raw_wait procedure. 6313 (line 6) 6314* remote_reboot: remote_reboot procedure. 6315 (line 6) 6316* remote_send: remote_send procedure. (line 6) 6317* remote_spawn: remote_spawn procedure. 6318 (line 6) 6319* remote_swap_conn: remote_swap_conn procedure. 6320 (line 6) 6321* remote_transmit: remote_transmit procedure. 6322 (line 6) 6323* remote_upload: remote_upload procedure. 6324 (line 6) 6325* remote_wait: remote_wait procedure. (line 6) 6326* rlogin_open: rlogin_open procedure. (line 6) 6327* rlogin_spawn: rlogin_spawn procedure. 6328 (line 6) 6329* rsh_download: rsh_download procedure. 6330 (line 6) 6331* rsh_exec: rsh_exec procedure. (line 6) 6332* rsh_open: rsh_open procedure. (line 6) 6333* rsh_upload: rsh_upload procedure. (line 6) 6334* runtest_file_p: runtest_file_p procedure. 6335 (line 6) 6336* set_board_info: set_board_info procedure. 6337 (line 6) 6338* set_currtarget_info: set_currtarget_info procedure. 6339 (line 6) 6340* set_warning_threshold: set_warning_threshold procedure. 6341 (line 6) 6342* setenv: setenv procedure. (line 6) 6343* setup_xfail: setup_xfail procedure. (line 6) 6344* ssh_close: ssh_close procedure. (line 6) 6345* ssh_download: ssh_download procedure. 6346 (line 6) 6347* ssh_exec: ssh_exec procedure. (line 6) 6348* ssh_upload: ssh_upload procedure. (line 6) 6349* standard_close: standard_close procedure. 6350 (line 6) 6351* standard_download: standard_download procedure. 6352 (line 6) 6353* standard_exec: standard_exec procedure. 6354 (line 6) 6355* standard_file: standard_file procedure. 6356 (line 6) 6357* standard_load: standard_load procedure. 6358 (line 6) 6359* standard_reboot: standard_reboot procedure. 6360 (line 6) 6361* standard_send: standard_send procedure. 6362 (line 6) 6363* standard_spawn: standard_spawn procedure. 6364 (line 6) 6365* standard_transmit: standard_transmit procedure. 6366 (line 6) 6367* standard_upload: standard_upload procedure. 6368 (line 6) 6369* standard_wait: standard_wait procedure. 6370 (line 6) 6371* target_assemble: target_assemble procedure. 6372 (line 6) 6373* target_compile: target_compile procedure. 6374 (line 6) 6375* target_info: target_info procedure. (line 6) 6376* target_link: target_link procedure. (line 6) 6377* telnet_binary: telnet_binary procedure. 6378 (line 6) 6379* telnet_open: telnet_open procedure. (line 6) 6380* testsuite: testsuite procedure. (line 6) 6381* tip_download: tip_download procedure. 6382 (line 6) 6383* tip_open: tip_open procedure. (line 6) 6384* transform: transform procedure. (line 6) 6385* unix_clean_filename: unix_clean_filename procedure. 6386 (line 6) 6387* unresolved: unresolved procedure. (line 6) 6388* unset_board_info: unset_board_info procedure. 6389 (line 6) 6390* unset_currtarget_info: unset_currtarget_info procedure. 6391 (line 6) 6392* unsetenv: unsetenv procedure. (line 6) 6393* unsupported: unsupported procedure. (line 6) 6394* untested: untested procedure. (line 6) 6395* verbose: verbose procedure. (line 6) 6396* warning: warning procedure. (line 6) 6397* watcharray: watcharray procedure. (line 6) 6398* watchdel: watchdel procedure. (line 6) 6399* watchread: watchread procedure. (line 6) 6400* watchunset: watchunset procedure. (line 6) 6401* watchvar: watchvar procedure. (line 6) 6402* watchwrite: watchwrite procedure. (line 6) 6403* which: which procedure. (line 6) 6404* winsup_include_flags: winsup_include_flags procedure. 6405 (line 6) 6406* winsup_link_flags: winsup_link_flags procedure. 6407 (line 6) 6408* xfail: xfail procedure. (line 6) 6409* xpass: xpass procedure. (line 6) 6410 6411 6412File: dejagnu.info, Node: Variable Index, Prev: Procedure Index, Up: Top 6413 6414Variable Index 6415************** 6416 6417�[index�] 6418* Menu: 6419 6420* bug_id: Test case variables. (line 15) 6421* comp_output: Test case variables. (line 27) 6422* exec_output: Test case variables. (line 22) 6423* expect_out(buffer): Test case variables. (line 33) 6424* prms_id: Test case variables. (line 11) 6425* subdir: Test case variables. (line 19) 6426* target_info: Configuration file values. 6427 (line 6) 6428* test_timeout: Local configuration file. 6429 (line 71) 6430 6431 6432 6433Tag Table: 6434Node: Top729 6435Node: Introduction2384 6436Node: What is DejaGnu?2676 6437Node: Release Notes5179 6438Node: Design goals7119 6439Node: A POSIX Conforming Test Framework8762 6440Node: Installation14080 6441Node: Running tests14866 6442Node: Make Check15534 6443Node: Runtest16725 6444Node: Output States17452 6445Node: Invoking runtest19949 6446Node: Common Operations28958 6447Node: Output Files30364 6448Node: Summary log file30985 6449Node: Detailed log file32822 6450Node: Debug log file34667 6451Node: Running other DejaGnu commands38451 6452Node: Invoking dejagnu39180 6453Node: Invoking dejagnu help41392 6454Node: Invoking dejagnu report card42399 6455Node: Customizing DejaGnu44017 6456Node: Global configuration file46335 6457Node: Local configuration file48953 6458Node: Board configuration file52896 6459Node: Remote host testing56245 6460Node: Configuration file values60441 6461Node: Command line option variables60965 6462Node: User configuration file63314 6463Node: Extending DejaGnu64209 6464Node: Adding a new testsuite64731 6465Node: Adding a new tool65321 6466Node: Adding a new target72466 6467Node: Adding a new board74418 6468Node: Board file values77435 6469Node: Writing a test case82771 6470Node: Debugging a test case92948 6471Node: Adding a test case to a testsuite95177 6472Node: Test case variables96299 6473Node: Unit testing97641 6474Node: What is unit testing?97995 6475Node: Running unit tests98837 6476Node: DejaGnu unit test protocol99502 6477Node: C unit testing API100755 6478Node: C++ unit testing API102660 6479Node: Built-in Procedures104869 6480Node: Core Internal Procedures105490 6481Node: open_logs procedure107031 6482Node: close_logs procedure107221 6483Node: isbuild procedure107441 6484Node: isremote procedure108091 6485Node: is_remote procedure108394 6486Node: is3way procedure108715 6487Node: ishost procedure109063 6488Node: istarget procedure109688 6489Node: isnative procedure110328 6490Node: log_and_exit procedure110669 6491Node: log_summary procedure110956 6492Node: setup_xfail procedure111176 6493Node: pass procedure112693 6494Node: fail procedure113042 6495Node: xpass procedure113385 6496Node: xfail procedure113755 6497Node: set_warning_threshold procedure114131 6498Node: get_warning_threshold procedure114600 6499Node: warning procedure115024 6500Node: perror procedure116401 6501Node: note procedure117452 6502Node: untested procedure117959 6503Node: unresolved procedure118415 6504Node: unsupported procedure118945 6505Node: transform procedure119368 6506Node: check_conditional_xfail procedure120014 6507Node: clear_xfail procedure122589 6508Node: verbose procedure123162 6509Node: load_lib procedure124035 6510Node: testsuite procedure125182 6511Node: testcase procedure127072 6512Node: Procedures For Remote Communication128519 6513Node: call_remote procedure131902 6514Node: check_for_board_status procedure132341 6515Node: file_on_build procedure133057 6516Node: file_on_host procedure133329 6517Node: local_exec procedure133586 6518Node: remote_binary procedure134483 6519Node: remote_close procedure134880 6520Node: remote_download procedure135368 6521Node: remote_exec procedure135965 6522Node: remote_expect procedure136974 6523Node: remote_file procedure137246 6524Node: remote_ld procedure137489 6525Node: remote_load procedure137724 6526Node: remote_open procedure137978 6527Node: remote_pop_conn procedure138949 6528Node: remote_push_conn procedure139357 6529Node: remote_raw_binary procedure139689 6530Node: remote_raw_close procedure139953 6531Node: remote_raw_file procedure140213 6532Node: remote_raw_ld procedure140479 6533Node: remote_raw_load procedure140738 6534Node: remote_raw_open procedure141016 6535Node: remote_raw_send procedure141270 6536Node: remote_raw_spawn procedure141542 6537Node: remote_raw_transmit procedure141831 6538Node: remote_raw_wait procedure142115 6539Node: remote_reboot procedure142390 6540Node: remote_send procedure142839 6541Node: remote_spawn procedure143089 6542Node: remote_swap_conn procedure143840 6543Node: remote_transmit procedure144182 6544Node: remote_upload procedure144448 6545Node: remote_wait procedure144720 6546Node: standard_close procedure145219 6547Node: standard_download procedure145546 6548Node: standard_exec procedure146140 6549Node: standard_file procedure146407 6550Node: standard_load procedure146653 6551Node: standard_reboot procedure146923 6552Node: standard_send procedure147379 6553Node: standard_spawn procedure147641 6554Node: standard_transmit procedure147918 6555Node: standard_upload procedure148320 6556Node: standard_wait procedure148614 6557Node: unix_clean_filename procedure148883 6558Node: connprocs149245 6559Node: kermit_open procedure150513 6560Node: kermit_command procedure150721 6561Node: kermit_send procedure150950 6562Node: kermit_transmit procedure151191 6563Node: telnet_open procedure151437 6564Node: telnet_binary procedure151956 6565Node: tip_open procedure152261 6566Node: rlogin_open procedure152632 6567Node: rlogin_spawn procedure152832 6568Node: rsh_open procedure153056 6569Node: rsh_download procedure153258 6570Node: rsh_upload procedure153510 6571Node: rsh_exec procedure153756 6572Node: ssh_close procedure153979 6573Node: ssh_exec procedure154177 6574Node: ssh_download procedure154436 6575Node: ssh_upload procedure154688 6576Node: ftp_open procedure154934 6577Node: ftp_upload procedure155194 6578Node: ftp_download procedure155601 6579Node: ftp_close procedure156013 6580Node: tip_download procedure156284 6581Node: Procedures For Target Boards156824 6582Node: default_link procedure157626 6583Node: default_target_assemble procedure157985 6584Node: default_target_compile procedure158415 6585Node: pop_config procedure159002 6586Node: prune_warnings procedure159235 6587Node: push_build procedure159468 6588Node: push_config procedure159690 6589Node: reboot_target procedure159927 6590Node: target_assemble procedure160169 6591Node: target_compile procedure160453 6592Node: target_link procedure168681 6593Node: target database library file168919 6594Node: board_info procedure169756 6595Node: host_info procedure170035 6596Node: set_board_info procedure170261 6597Node: add_board_info procedure170688 6598Node: set_currtarget_info procedure171131 6599Node: target_info procedure171406 6600Node: unset_board_info procedure171651 6601Node: unset_currtarget_info procedure172051 6602Node: push_target procedure172321 6603Node: pop_target procedure172679 6604Node: push_host procedure172927 6605Node: pop_host procedure173275 6606Node: platform dependent procedures173483 6607Node: ${tool}_start procedure174834 6608Node: ${tool}_load procedure175850 6609Node: ${tool}_exit procedure176722 6610Node: ${tool}_version procedure177178 6611Node: Utility Procedures177606 6612Node: getdirs procedure178228 6613Node: relative_filename procedure179307 6614Node: find procedure179767 6615Node: which procedure180399 6616Node: grep procedure180952 6617Node: prune procedure181857 6618Node: runtest_file_p procedure182227 6619Node: diff procedure182868 6620Node: setenv procedure183292 6621Node: unsetenv procedure183591 6622Node: getenv procedure183852 6623Node: Libgloss184159 6624Node: libgloss_link_flags procedure186015 6625Node: libgloss_include_flags procedure186397 6626Node: newlib_link_flags procedure186753 6627Node: newlib_include_flags procedure187141 6628Node: libio_include_flags procedure187472 6629Node: libio_link_flags procedure187801 6630Node: g++_include_flags procedure188181 6631Node: g++_link_flags procedure188506 6632Node: libstdc++_include_flags procedure188883 6633Node: libstdc++_link_flags procedure189239 6634Node: get_multilibs procedure189492 6635Node: find_binutils_prog procedure189719 6636Node: find_gcc procedure189949 6637Node: find_gcj procedure190321 6638Node: find_g++ procedure190686 6639Node: find_g77 procedure191050 6640Node: find_gfortran procedure191426 6641Node: find_go procedure191813 6642Node: find_go_linker procedure192200 6643Node: find_rustc procedure192640 6644Node: process_multilib_options procedure193064 6645Node: add_multilib_option procedure193326 6646Node: find_gas procedure193571 6647Node: find_ld procedure193753 6648Node: build_wrapper procedure193926 6649Node: winsup_include_flags procedure194150 6650Node: winsup_link_flags procedure194397 6651Node: Debugging Procedures194603 6652Node: bt procedure195319 6653Node: dumpvars procedure195561 6654Node: dumplocals procedure195901 6655Node: dumprocs procedure196247 6656Node: dumpwatch procedure196581 6657Node: watcharray procedure196918 6658Node: watchvar procedure197205 6659Node: watchunset procedure197417 6660Node: watchwrite procedure197715 6661Node: watchread procedure198036 6662Node: watchdel procedure198349 6663Node: print procedure198619 6664Node: quit procedure198884 6665Node: GNU Free Documentation License199070 6666Node: Concept Index222847 6667Node: Procedure Index226397 6668Node: Variable Index245235 6669 6670End Tag Table 6671