libstdc++-v3/docs/html/test.html

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html
   3           PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8    <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
   9    <meta name="KEYWORDS" content="c++, libstdc++, test, regression, g++" />
  10    <meta name="DESCRIPTION" content="README for the GNU libstdc++ effort." />
  11    <meta name="GENERATOR" content="vi and eight fingers" />
  12    <title>libstdc++-v3 Testing Instructions</title>
  13 <link rel="StyleSheet" href="lib3styles.css" />
  14 </head>
  15 <body>
  16
  17 <h1 class="centered"><a name="top">Testing Details</a></h1>
  18
  19 <p class="fineprint"><em>
  20    The latest version of this document is always available at
  21    <a href="http://gcc.gnu.org/onlinedocs/libstdc++/test.html">
  22    http://gcc.gnu.org/onlinedocs/libstdc++/test.html</a>.
  23 </em></p>
  24
  25 <p><em>
  26    To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
  27 </em></p>
  28
  29 <!-- ####################################################### -->
  30 <hr />
  31 <h2>Contents</h2>
  32 <ul>
  33    <li><a href="#org">Testsuite organization and naming conventions</a></li>
  34    <li><a href="#util">Utilities: abicheck and libv3test</a></li>
  35    <li><a href="#new">How to write a new test case</a></li>
  36    <li><a href="#check">Options for running the tests</a></li>
  37    <li><a href="#debug">Running debug-mode tests</a></li>
  38    <li><a href="#future">Future</a></li>
  39    <li><a href="#internals">DejaGNU internals</a></li>
  40 </ul>
  41
  42 <hr />
  43
  44 <!-- ####################################################### -->
  45
  46 <h2><a name="org">Testsuite organization and naming conventions</a></h2>
  47    <p>
  48       The directory <em>libsrcdir/testsuite</em> contains the
  49       individual test cases organized in sub-directories corresponding
  50       to chapters of the C++ standard (detailed below), the dejagnu
  51       test harness support files, and sources to various testsuite
  52       utilities that are packaged in a separate testing library.
  53    </p>
  54
  55    <p> All test cases for functionality required by the runtime
  56    components of the C++ standard (ISO 14882) are files within the
  57    following directories.
  58    </p>
  59
  60    <pre>
  61 17_intro
  62 18_support
  63 19_diagnostics
  64 20_util
  65 21_strings
  66 22_locale
  67 23_containers
  68 25_algorithms
  69 26_numerics
  70 27_io
  71    </pre>
  72
  73    <p>
  74       In addition, the following directories include test files:
  75    </p>
  76
  77    <pre>
  78 tr1               Tests for components as described by the Technical Report on Standard Library Extensions (TR1).
  79 backward          Tests for backwards compatibility and deprecated features.
  80 demangle          Tests for __cxa_demangle, the IA 64 C++ ABI demangler
  81 ext               Tests for extensions.
  82 performance       Tests for performance analysis, and performance regressions.
  83 thread            Tests for threads.
  84    </pre>
  85
  86    <p>
  87       Some directories don't have test files, but instead contain
  88       auxiliary information (<a href="#internals">more information</a>):
  89    </p>
  90
  91    <pre>
  92 config            Files for the dejagnu test harness.
  93 lib               Files for the dejagnu test harness.
  94 libstdc++*        Files for the dejagnu test harness.
  95 data              Sample text files for testing input and output.
  96    </pre>
  97
  98    <p>
  99       Within a directory that includes test files, there may be
 100       additional subdirectories, or files.  Originally, test cases
 101       were appended to one file that represented a particular section
 102       of the chapter under test, and was named accordingly. For
 103       instance, to test items related to <code> 21.3.6.1 -
 104       basic_string::find [lib.string::find]</code> in the standard,
 105       the following was used:
 106    </p>
 107    <pre>
 108 21_strings/find.cc
 109    </pre>
 110    <p>
 111       However, that practice soon became a liability as the test cases
 112       became huge and unwieldy, and testing new or extended
 113       functionality (like wide characters or named locales) became
 114       frustrating, leading to aggressive pruning of test cases on some
 115       platforms that covered up implementation errors. Now, the test
 116       suite has a policy of one file, one test case, which solves the
 117       above issues and gives finer grained results and more manageable
 118       error debugging. As an example, the test case quoted above
 119       becomes:
 120    </p>
 121    <pre>
 122 21_strings/basic_string/find/char/1.cc
 123 21_strings/basic_string/find/char/2.cc
 124 21_strings/basic_string/find/char/3.cc
 125 21_strings/basic_string/find/wchar_t/1.cc
 126 21_strings/basic_string/find/wchar_t/2.cc
 127 21_strings/basic_string/find/wchar_t/3.cc
 128    </pre>
 129
 130    <p>
 131       All new tests should be written with the policy of one test
 132       case, one file in mind.
 133    </p>
 134
 135    <p>
 136       In addition, there are some special names and suffixes that are
 137       used within the testsuite to designate particular kinds of
 138       tests.
 139    </p>
 140
 141 <ul>
 142 <li>
 143    <em>_xin.cc</em>
 144    <p>
 145       This test case expects some kind of interactive input in order
 146       to finish or pass. At the moment, the interactive tests are not
 147       run by default. Instead, they are run by hand, like:
 148    </p>
 149       <pre>
 150 g++ 27_io/objects/char/3_xin.cc
 151 cat 27_io/objects/char/3_xin.in | a.out
 152      </pre>
 153 </li>
 154 <li>
 155    <em>.in</em>
 156    <p>
 157       This file contains the expected input for the corresponding <em>
 158       _xin.cc</em> test case.
 159    </p>
 160 </li>
 161 <li>
 162    <em>_neg.cc</em>
 163    <p>
 164       This test case is expected to fail: it's a negative test. At the
 165       moment, these are almost always compile time errors.
 166    </p>
 167 </li>
 168 <li>
 169    <em>char</em>
 170    <p>
 171       This can either be a directory name or part of a longer file
 172       name, and indicates that this file, or the files within this
 173       directory are testing the <code>char</code> instantiation of a
 174       template.
 175    </p>
 176 </li>
 177 <li>
 178    <em>wchar_t</em>
 179    <p>
 180       This can either be a directory name or part of a longer file
 181       name, and indicates that this file, or the files within this
 182       directory are testing the <code>wchar_t</code> instantiation of
 183       a template. Some hosts do not support <code>wchar_t</code>
 184       functionality, so for these targets, all of these tests will not
 185       be run.
 186    </p>
 187 </li>
 188 <li>
 189    <em>thread</em>
 190    <p>
 191       This can either be a directory name or part of a longer file
 192       name, and indicates that this file, or the files within this
 193       directory are testing situations where multiple threads are
 194       being used.
 195    </p>
 196 </li>
 197 <li>
 198    <em>performance</em>
 199    <p>
 200       This can either be an enclosing directory name or part of a
 201       specific file name. This indicates a test that is used to
 202       analyze runtime performance, for performance regression testing,
 203       or for other optimization related analysis. At the moment, these
 204       test cases are not run by default.
 205    </p>
 206 </li>
 207 </ul>
 208
 209 <hr />
 210 <h2><a name="util">Utilities: abi_check and libv3test</a></h2>
 211   <p>
 212    The testsuite directory also contains some files that implement
 213    functionality that is intended to make writing test cases easier,
 214    or to avoid duplication, or to provide error checking in a way that
 215    is consistent across platforms and test harnesses. A stand-alone
 216    executable, called <em>abi_check</em>, and a static library called
 217    <em>libv3test</em> are constructed. Both of these items are not
 218    installed, and only used during testing.
 219   </p>
 220
 221   <p>
 222   These files include the following functionality:
 223   </p>
 224
 225   <ul>
 226      <li>
 227        <em>testsuite_abi.h</em>,
 228        <em>testsuite_abi.cc</em>,
 229        <em>testsuite_abi_check.cc</em>
 230        <p>
 231         Creates the executable <em>abi_check</em>.
 232         Used to check correctness of symbol versioning, visibility of
 233         exported symbols, and compatibility on symbols in the shared
 234         library, for hosts that support this feature. More information
 235         can be found in the ABI documentation <a href="abi.html"> here</a>
 236        </p>
 237      </li>
 238      <li>
 239        <em>testsuite_allocator.h</em>,
 240        <em>testsuite_allocator.cc</em>
 241        <p>
 242         Contains specialized allocators that keep track of construction
 243         and destruction. Also, support for overriding global new and
 244         delete operators, including verification that new and delete
 245         are called during execution, and that allocation over max_size
 246         fails.
 247        </p>
 248      </li>
 249      <li>
 250        <em>testsuite_character.h</em>
 251        <p>
 252         Contains <code>std::char_traits</code> and
 253         <code>std::codecvt</code> specializations for a user-defined
 254         POD.
 255        </p>
 256      </li>
 257      <li>
 258        <em>testsuite_hooks.h</em>,
 259        <em>testsuite_hooks.cc</em>
 260        <p>
 261        A large number of utilities, including:
 262        </p>
 263        <ul>
 264          <li>VERIFY</li>
 265          <li>set_memory_limits</li>
 266          <li>verify_demangle</li>
 267          <li>run_tests_wrapped_locale</li>
 268          <li>run_tests_wrapped_env</li>
 269          <li>try_named_locale</li>
 270          <li>try_mkfifo</li>
 271          <li>func_callback</li>
 272          <li>counter</li>
 273          <li>copy_tracker</li>
 274          <li>copy_constructor</li>
 275          <li>assignment_operator</li>
 276          <li>destructor</li>
 277          <li>pod_char, pod_int and associated char_traits specializations</li>
 278        </ul>
 279        <p></p>
 280      </li>
 281      <li>
 282        <em>testsuite_io.h</em>
 283        <p>
 284        Error, exception, and constraint checking for
 285        <code>std::streambuf, std::basic_stringbuf, std::basic_filebuf</code>.
 286        </p>
 287      </li>
 288      <li>
 289        <em>testsuite_iterators.h</em>
 290        <p>
 291        Wrappers for various iterators.
 292        </p>
 293      </li>
 294      <li>
 295        <em>testsuite_performance.h</em>
 296        <p>
 297        A number of class abstractions for performance counters, and
 298        reporting functions including:
 299        </p>
 300       <ul>
 301          <li>time_counter</li>
 302          <li>resource_counter</li>
 303          <li>report_performance</li>
 304       </ul>
 305        <p></p>
 306      </li>
 307   </ul>
 308
 309 <hr />
 310 <h2><a name="new">How to write a new test case</a></h2>
 311
 312    <p>
 313     The first step in making a new test case is to choose the correct
 314     directory and file name, given the organization as previously
 315     described.
 316    </p>
 317
 318    <p>
 319     All files are copyright the FSF, and GPL'd: this is very
 320     important.  The first copyright year should correspond to the date
 321     the file was checked in to CVS.
 322    </p>
 323
 324    <p>
 325      As per the dejagnu instructions, always return 0 from main to
 326      indicate success.
 327    </p>
 328
 329    <p>
 330    A bunch of utility functions and classes have already been
 331    abstracted out into the testsuite utility library, <code>
 332    libv3test</code>. To use this functionality, just include the
 333    appropriate header file: the library will automatically be linked
 334    in as part of the testsuite run.
 335    </p>
 336
 337    <p>
 338    For a test that needs to take advantage of the dejagnu test
 339    harness, what follows below is a list of special keyword that
 340    harness uses. Basically, a test case contains dg-keywords (see
 341    dg.exp) indicating what to do and what kinds of behavior are to be
 342    expected.  New test cases should be written with the new style
 343    DejaGnu framework in mind.
 344    </p>
 345
 346    <p>
 347     To ease transition, here is the list of dg-keyword documentation
 348     lifted from dg.exp.
 349    </p>
 350
 351 <pre>
 352 # The currently supported options are:
 353 #
 354 # dg-prms-id N
 355 #       set prms_id to N
 356 #
 357 # dg-options "options ..." [{ target selector }]
 358 #       specify special options to pass to the tool (eg: compiler)
 359 #
 360 # dg-do do-what-keyword [{ target/xfail selector }]
 361 #       `do-what-keyword' is tool specific and is passed unchanged to
 362 #       ${tool}-dg-test.  An example is gcc where `keyword' can be any of:
 363 #       preprocess|compile|assemble|link|run
 364 #       and will do one of: produce a .i, produce a .s, produce a .o,
 365 #       produce an a.out, or produce an a.out and run it (the default is
 366 #       compile).
 367 #
 368 # dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]]
 369 #       indicate an error message &lt;regexp&gt; is expected on this line
 370 #       (the test fails if it doesn't occur)
 371 #       Linenum=0 for general tool messages (eg: -V arg missing).
 372 #       "." means the current line.
 373 #
 374 # dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]]
 375 #       indicate a warning message &lt;regexp&gt; is expected on this line
 376 #       (the test fails if it doesn't occur)
 377 #
 378 # dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]]
 379 #       indicate a bogus error message &lt;regexp&gt; use to occur here
 380 #       (the test fails if it does occur)
 381 #
 382 # dg-build regexp comment [{ target/xfail selector }]
 383 #       indicate the build use to fail for some reason
 384 #       (errors covered here include bad assembler generated, tool crashes,
 385 #       and link failures)
 386 #       (the test fails if it does occur)
 387 #
 388 # dg-excess-errors comment [{ target/xfail selector }]
 389 #       indicate excess errors are expected (any line)
 390 #       (this should only be used sparingly and temporarily)
 391 #
 392 # dg-output regexp [{ target selector }]
 393 #       indicate the expected output of the program is &lt;regexp&gt;
 394 #       (there may be multiple occurrences of this, they are concatenated)
 395 #
 396 # dg-final { tcl code }
 397 #       add some tcl code to be run at the end
 398 #       (there may be multiple occurrences of this, they are concatenated)
 399 #       (unbalanced braces must be \-escaped)
 400 #
 401 # "{ target selector }" is a list of expressions that determine whether the
 402 # test succeeds or fails for a particular target, or in some cases whether the
 403 # option applies for a particular target.  If the case of `dg-do' it specifies
 404 # whether the test case is even attempted on the specified target.
 405 #
 406 # The target selector is always optional.  The format is one of:
 407 #
 408 # { xfail *-*-* ... } - the test is expected to fail for the given targets
 409 # { target *-*-* ... } - the option only applies to the given targets
 410 #
 411 # At least one target must be specified, use *-*-* for "all targets".
 412 # At present it is not possible to specify both `xfail' and `target'.
 413 # "native" may be used in place of "*-*-*".
 414
 415 Example 1: Testing compilation only
 416 // { dg-do compile }
 417
 418 Example 2: Testing for expected warnings on line 36, which all targets fail
 419 // { dg-warning "string literals" "" { xfail *-*-* } 36
 420
 421 Example 3: Testing for expected warnings on line 36
 422 // { dg-warning "string literals" "" { target *-*-* } 36
 423
 424 Example 4: Testing for compilation errors on line 41
 425 // { dg-do compile }
 426 // { dg-error "no match for" "" { target *-*-* } 41 }
 427
 428 Example 5: Testing with special command line settings, or without the
 429 use of pre-compiled headers, in particular the stdc++.h.gch file. Any
 430 options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set
 431 up in the normal.exp file.
 432 // { dg-options "-O0" { target *-*-* } }
 433 </pre>
 434
 435    <p>
 436     More examples can be found in the libstdc++-v3/testsuite/*/*.cc files.
 437    </p>
 438
 439 <hr />
 440 <h2><a name="check">Options for running the tests</a></h2>
 441
 442    <p> There are several options for running tests, including testing
 443    the regression tests, testing a subset of the regression tests,
 444    testing the performance tests, testing just compilation, testing
 445    installed tools, etc. In addition, there is a special rule for
 446    checking the exported symbols of the shared library.
 447    </p>
 448
 449    <p>You can check the status of the build without installing it
 450    using the dejagnu harness, much like the rest of the gcc tools.</p>
 451    <pre> make check</pre>
 452    <p>in the <em>libbuilddir</em> directory.</p>
 453    <p>or</p>
 454    <pre> make check-target-libstdc++-v3</pre>
 455    <p>in the <em>gccbuilddir</em> directory.</p>
 456
 457    <p>
 458       These commands are functionally equivalent and will create a
 459       'testsuite' directory underneath <em>libbuilddir</em> containing
 460       the results of the tests. Two results files will be generated:
 461       <em> libstdc++.sum</em>, which is a PASS/FAIL summary for each
 462       test, and <em>libstdc++.log</em> which is a log of the exact
 463       command line passed to the compiler, the compiler output, and
 464       the executable output (if any).
 465    </p>
 466
 467
 468 <p>
 469 To debug the dejagnu test harness during runs, try invoking with a
 470 specific argument to the variable RUNTESTFLAGS, as below.
 471 </p>
 472
 473 <pre>
 474 make check-target-libstdc++-v3 RUNTESTFLAGS="-v"
 475 </pre>
 476 or
 477 <pre>
 478 make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
 479 </pre>
 480
 481 <p> To run a subset of the library tests, try using a command like the
 482 following from the <em>libbuilddir/testsuite</em> directory:
 483 </p>
 484 <pre>
 485 runtest --tool libstdc++ normal.exp="`find $srcdir/17_intro -name *.cc`"
 486 </pre>
 487
 488
 489 <p>
 490 There are two ways to run on a simulator: set up DEJAGNU to point to a
 491 specially crafted site.exp, or pass down --target_board flags.
 492 </p>
 493 Example flags to pass down for various embedded builds are as follows:
 494 <pre>
 495 --target=powerpc-eabism (libgloss/sim)
 496 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
 497
 498 --target=calmrisc32 (libgloss/sid)
 499 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid"
 500
 501 --target=xscale-elf (newlib/sim)
 502 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
 503 </pre>
 504
 505 <p> Also, here is an example of how to run the libstdc++ testsuite for a
 506 multilibed build directory with different ABI settings:
 507 </p>
 508 <pre>
 509 make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"'
 510 </pre>
 511
 512 <p>
 513 You can run the tests with a compiler and library that have already
 514 been installed.  Make sure that the compiler (e.g., <code>g++</code>)
 515 is in your <code>PATH</code>.  If you are using shared libraries, then
 516 you must also ensure that the directory containing the shared version
 517 of libstdc++ is in your <code>LD_LIBRARY_PATH</code>, or equivalent.
 518 If your GCC source tree is at <code>/path/to/gcc</code>, then you can
 519 run the tests as follows:
 520 <pre>
 521 runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
 522 </pre>
 523 The testsuite will create a number of files in the directory in which you
 524 run this command,.  Some of those files might use the same name as
 525 files created by other testsuites (like the ones for GCC and G++), so
 526 you should not try to run all the testsuites in parallel from the same
 527 directory.
 528 </p>
 529
 530    <p> In addition, there are some testing options that are mostly of
 531    interest to library maintainers and system integrators. As such,
 532    these tests may not work on all cpu and host combinations, and may need to
 533    be executed in the <em>libbuilddir/testsuite</em> directory.  These options
 534    include, but are not necessarily limited to, the following:
 535    </p>
 536
 537    <pre>
 538    make testsuite_files</pre>
 539   <p>
 540     Five files are generated that determine what test files
 541     are run. These files are:
 542   </p>
 543    <ul>
 544      <li>
 545      <em>testsuite_files </em>
 546      <p> This is a list of all the test cases that will be run. Each
 547       test case is on a separate line, given with an absolute path
 548       from the <em>libsrcdir/testsuite</em> directory.
 549      </p>
 550      </li>
 551
 552      <li>
 553      <em>testsuite_files_interactive </em>
 554      <p> This is a list of all the interactive test cases, using the
 555      same format as the file list above. These tests are not run by default.
 556      </p>
 557      </li>
 558
 559      <li>
 560      <em>testsuite_files_performance</em>
 561      <p> This is a list of all the performance test cases, using the
 562      same format as the file list above. These tests are not run by default.
 563      </p>
 564      </li>
 565
 566      <li>
 567      <em>testsuite_thread</em>
 568      <p> This file indicates that the host system can run tests which
 569      incolved multiple threads.
 570      </p>
 571      </li>
 572
 573      <li>
 574      <em>testsuite_wchar_t</em>
 575      <p> This file indicates that the host system can run the wchar_t
 576      tests, and corresponds to the macro definition <code>
 577      _GLIBCXX_USE_WCHAR_T</code> in the file c++config.h.
 578      </p>
 579      </li>
 580     </ul>
 581
 582    <pre>
 583    make check-abi</pre>
 584    <p>The library ABI can be tested. This involves testing the shared
 585    library against an ABI-defining previous version of symbol exports. </p>
 586
 587   <pre>
 588    make check-compile</pre>
 589    <p>This rule compiles, but does not link or execute, the
 590    <em>testsuite_files</em> test cases and displays the output on stdout.</p>
 591
 592    <pre>
 593    make check-performance</pre>
 594    <p>This rule runs through the <em>testsuite_files_performance</em>
 595    test cases and collects information for performance analysis and
 596    can be used to spot performance regressions. Various timing
 597    information is collected, as well as number of hard page faults,
 598    and memory used. This is not run by default, and the implementation
 599    is in flux.
 600 </p>
 601
 602    <p>
 603       We are interested in any strange failures of the
 604       testsuite; please see <a href="faq/index.html#2_4">FAQ 2.4</a>
 605       for which files to examine.
 606    </p>
 607
 608 <hr/>
 609 <h2><a name="debug">Running debug-mode tests</a></h2>
 610 <p>To run the libstdc++ test suite under the <a
 611   href="debug.html#safe">debug mode</a>,
 612   edit <code>libstdc++/scripts/testsuite_flags</code> to add the
 613   compile-time flag <code>-D_GLIBCXX_DEBUG</code> to the result
 614   printed by the <code>--build-cxx</code> option. Additionally, add
 615   the <code>-D_GLIBCXX_DEBUG_PEDANTIC</code> flag to turn on pedantic
 616   checking. The libstdc++ test suite should produce precisely the same
 617   results under debug mode that it does under release mode: any
 618   deviation indicates an error in either the library or the test
 619   suite.</p>
 620
 621 <hr />
 622 <h2><a name="future">Future</a></h2>
 623
 624 <p>
 625 Shared runs need to be implemented, for targets that support shared libraries.
 626 </p>
 627
 628 <p>
 629 Diffing of expected output to standard streams needs to be finished off.
 630 </p>
 631
 632 <p>
 633 The V3 testing framework supports, or will eventually support,
 634 additional keywords for the purpose of easing the job of writing
 635 test cases.  All V3-keywords are of the form <code>@xxx@</code>.
 636 Currently plans for supported keywords include:
 637 </p>
 638
 639 <dl>
 640 <dt> <code> @require@ &lt;files&gt; </code> </dt>
 641 <dd>
 642    <p>
 643       The existence of &lt;files&gt; is essential for the test to complete
 644       successfully.  For example, a test case foo.C using bar.baz as
 645       input file could say
 646    </p>
 647    <pre>
 648             // @require@ bar.baz</pre>
 649    <p>
 650       The special variable % stands for the rootname, e.g. the
 651       file-name without its `.C' extension.  Example of use (taken
 652       verbatim from 27_io/filebuf.cc)
 653    </p>
 654    <pre>
 655            // @require@ %-*.tst %-*.txt</pre>
 656 </dd>
 657 <dt> <code> @diff@ &lt;first-list&gt; &lt;second-list&gt; </code> </dt>
 658 <dd>
 659    <p>
 660       After the test case compiles and ran successfully, diff
 661       &lt;first-list&gt; against &lt;second-list&gt;, these lists should
 662       have the same length.  The test fails if diff returns non-zero a
 663       pair of files.
 664    </p>
 665 </dd>
 666 </dl>
 667
 668 <hr />
 669 <h2><a name="internals">DejaGNU internals</a></h2>
 670
 671 <p>This is information for those looking at making changes to the testsuite
 672 structure, and/or needing to trace dejagnu's actions with --verbose.  This
 673 will not be useful to people who are "merely" adding new tests to the existing
 674 structure.
 675 </p>
 676
 677 <p>The first key point when working with dejagnu is the idea of a "tool".
 678 Files, directories, and functions are all implicitly used when they are
 679 named after the tool in use.  Here, the tool will always be "libstdc++".
 680 </p>
 681
 682 <p>The <code>lib</code> subdir contains support routines.  The
 683 <code>lib/libstdc++.exp</code> file ("support library") is loaded
 684 automagically, and must explicitly load the others.  For example, files can
 685 be copied from the core compiler's support directory into <code>lib</code>.
 686 </p>
 687
 688 <p>Some routines in <code>lib/libstdc++.exp</code> are callbacks, some are
 689 our own.  Callbacks must be prefixed with the name of the tool.  To easily
 690 distinguish the others, by convention our own routines are named "v3-*".
 691 </p>
 692
 693 <p>The next key point when working with dejagnu is "test files".  Any
 694 directory whose name starts with the tool name will be searched for test files.
 695 (We have only one.)  In those directories, any <code>.exp</code> file is
 696 considered a test file, and will be run in turn.  Our main test file is called
 697 <code>normal.exp</code>; it runs all the tests in testsuite_files using the
 698 callbacks loaded from the support library.
 699 </p>
 700
 701 <p>The <code>config</code> directory is searched for any particular "target
 702 board" information unique to this library.  This is currently unused and sets
 703 only default variables.
 704 </p>
 705
 706
 707 <!-- ####################################################### -->
 708
 709 <hr />
 710 <p class="fineprint"><em>
 711 See <a href="17_intro/license.html">license.html</a> for copying conditions.
 712 Comments and suggestions are welcome, and may be sent to
 713 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 714 </em></p>
 715
 716
 717 </body>
 718 </html>