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