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="#future">Future</a></li>
  38 </ul>
  39
  40 <hr />
  41
  42 <!-- ####################################################### -->
  43
  44 <h2><a name="org">Testsuite organization and naming conventions</a></h2>
  45    <p>
  46       The directory <em>libsrcdir/testsuite</em> contains the test
  47       files, test harness, and utility information for verifying the
  48       correctness of C++ library on a given host. It includes the
  49       following directories, each named after a specific chapter of
  50       the C++ standard, and each containing test files or
  51       subdirectories of test files that test for that particular part
  52       of the standard.
  53    </p>
  54
  55    <pre>
  56 17_intro
  57 18_support
  58 19_diagnostics
  59 20_util
  60 21_strings
  61 22_locale
  62 23_containers
  63 25_algorithms
  64 26_numerics
  65 27_io
  66    </pre>
  67
  68    <p>
  69       In addition, the following directories include test files:
  70    </p>
  71
  72    <pre>
  73 backward          Tests for backwards compatibility and deprecated features.
  74 demangle          Tests for __cxa_demangle, the IA 64 C++ ABI demangler
  75 ext               Tests for extensions.
  76 performance       Tests for performance analysis, and performance regressions.
  77 thread            Tests for threads.
  78    </pre>
  79
  80    <p>
  81       Some directories don't have test files, but instead contain
  82       auxiliary information:
  83    </p>
  84
  85    <pre>
  86 config            Files for the dejagnu test harness.
  87 lib               Files for the dejagnu test harness.
  88 libstdc++-v3.dg   Files for the dejagnu test harness.
  89 data              Sample text files for testing input and output.
  90    </pre>
  91
  92    <p>
  93       Within a directory that includes test files, there may be
  94       additional subdirectories, or files: this particular point is in
  95       flux. Originally, test cases were appended to one file that
  96       represented a particular section of the chapter under test, and
  97       was named accordingly. For instance, to test items related to
  98       <code> 21.3.6.1 - basic_string::find [lib.string::find]</code>
  99       in the standard, the following was used:
 100    </p>
 101    <pre>
 102 21_strings/find.cc
 103    </pre>
 104    <p>
 105       However, that practice soon became a liability as the test cases
 106       became huge and unwieldy, and testing new or extended
 107       functionality (like wide characters or named locales) became
 108       frustrating, leading to aggressive pruning of test cases on some
 109       platforms that covered up implementation errors. Now, the test
 110       suite is converging on a policy of one file, one test case,
 111       which solves the above issues and gives finer grained results
 112       and more manageable error debugging. As an example, the test case
 113       quoted above becomes:
 114    </p>
 115    <pre>
 116 21_strings/basic_string/find/char/1.cc
 117 21_strings/basic_string/find/char/2.cc
 118 21_strings/basic_string/find/char/3.cc
 119 21_strings/basic_string/find/wchar_t/1.cc
 120 21_strings/basic_string/find/wchar_t/2.cc
 121 21_strings/basic_string/find/wchar_t/3.cc
 122    </pre>
 123
 124    <p>
 125       All new tests should be written with the policy of one test
 126       case, one file in mind. At some point the entire testsuite will
 127       be converted: the current status is that the 21_string,
 128       22_locale, 27_io, and demangle directories have all been
 129       transitioned.
 130    </p>
 131
 132    <p>
 133       In addition, there are some special names and suffixes that are
 134       used within the testsuite to designate particular kinds of
 135       tests.
 136    </p>
 137
 138 <ul>
 139 <li>
 140    <em>_xin.cc</em>
 141    <p>
 142       This test case expects some kind of interactive input in order
 143       to finish or pass. At the moment, the interactive tests are not
 144       run by default. Instead, they are run by hand, like:
 145    </p>
 146       <pre>
 147 g++ 27_io/objects/char/3_xin.cc
 148 cat 27_io/objects/char/3_xin.in | a.out
 149      </pre>
 150 </li>
 151 <li>
 152    <em>.in</em>
 153    <p>
 154       This file contains the expected input for the corresponding <em>
 155       _xin.cc</em> test case.
 156    </p>
 157 </li>
 158 <li>
 159    <em>_neg.cc</em>
 160    <p>
 161       This test case is expected to fail: it's a negative test. At the
 162       moment, these are almost always compile time errors.
 163    </p>
 164 </li>
 165 <li>
 166    <em>char</em>
 167    <p>
 168       This can either be a directory name or part of a longer file
 169       name, and indicates that this file, or the files within this
 170       directory are testing the <code>char</code> instantiation of a
 171       template.
 172    </p>
 173 </li>
 174 <li>
 175    <em>wchar_t</em>
 176    <p>
 177       This can either be a directory name or part of a longer file
 178       name, and indicates that this file, or the files within this
 179       directory are testing the <code>wchar_t</code> instantiation of
 180       a template. Some hosts do not support <code>wchar_t</code>
 181       functionality, so for these targets, all of these tests will not
 182       be run.
 183    </p>
 184 </li>
 185 <li>
 186    <em>performance</em>
 187    <p>
 188       This can either be an enclosing directory name or part of a
 189       specific file name. This indicates a test that is used to
 190       analyze runtime performance, for performance regression testing,
 191       or for other optimization related analysis. At the moment, these
 192       test cases are not run by default.
 193    </p>
 194 </li>
 195 </ul>
 196
 197 <hr />
 198 <h2><a name="util">Utilities: abicheck and libv3test</a></h2>
 199   <p>
 200    The testsuite directory also contains some files that implement
 201    functionality that is intended to make writing test cases easier,
 202    or to avoid duplication, or to provide error checking in a way that
 203    is consistent across platforms and test harnesses. A stand-alone
 204    executable, called <em>abi_check</em>, and a static library called
 205    <em>libv3test</em> are constructed during the build. Both of these
 206    items are not installed, and only used during testing.
 207   </p>
 208
 209   <p>
 210   These files include the following functionality:
 211   </p>
 212
 213   <ul>
 214      <li>
 215        <em>abi_check.cc</em>
 216        <p>
 217         Creates the executable <em>abi_check</em>.
 218         Used to check correctness of symbol versioning, visibility of
 219         exported symbols, and compatibility on symbols in the shared
 220         library, for hosts that support this feature. More information
 221         can be found in the ABI documentation <a href="abi.txt"> here</a>
 222        </p>
 223      </li>
 224      <li>
 225        <em>testsuite_allocator.h and </em>
 226        <em>testsuite_allocator.cc</em>
 227        <p>
 228         Specialized allocators that keep track of construction and destruction
 229        </p>
 230      </li>
 231      <li>
 232        <em>testsuite_hooks.h and </em>
 233        <em>testsuite_hooks.cc</em>
 234        <p>
 235        A large number of utilities, including:
 236        </p>
 237        <ul>
 238          <li>VERIFY</li>
 239          <li>set_memory_limits</li>
 240          <li>verify_demangle</li>
 241          <li>run_tests_wrapped_locale</li>
 242          <li>run_tests_wrapped_env</li>
 243          <li>try_named_locale</li>
 244          <li>counter</li>
 245          <li>copy_constructor</li>
 246          <li>assignment_operator</li>
 247          <li>destructor</li>
 248          <li>copy_tracker</li>
 249          <li>pod_char, pod_int and associated char_traits specializations</li>
 250        </ul>
 251        <p></p>
 252      </li>
 253      <li>
 254        <em>testsuite_performance.h</em>
 255        <p>
 256        A number of class abstractions for performance counters, and
 257        reporting functions including:
 258        </p>
 259       <ul>
 260          <li>time_counter</li>
 261          <li>resource_counter</li>
 262          <li>report_performance</li>
 263       </ul>
 264        <p></p>
 265      </li>
 266      <li>
 267        <em>printnow.c</em>
 268        <p>
 269         A cross-platform timer for use in one of the older harnesses
 270         to determine compilation and link time.
 271        </p>
 272      </li>
 273   </ul>
 274
 275 <hr />
 276 <h2><a name="new">How to write a new test case</a></h2>
 277
 278    <p>
 279     The first step in making a new test case is to choose the correct
 280     directory and file name, given the organization as previously
 281     described.
 282    </p>
 283
 284    <p>
 285     All files are copyright the FSF, and GPL'd: this is very
 286     important.  The first copyright year should correspond to the date
 287     the file was checked in to CVS.
 288    </p>
 289
 290    <p>
 291      As per the dejagnu instructions, always return 0 from main to
 292      indicate success.
 293    </p>
 294
 295    <p>
 296    A bunch of utility functions and classes have already been
 297    abstracted out into the testsuite utility library, <code>
 298    libv3test</code>. To use this functionality, just include the
 299    appropriate header file: the library will automatically be linked
 300    in as part of the testsuite run.
 301    </p>
 302
 303    <p>
 304    For a test that needs to take advantage of the dejagnu test
 305    harness, what follows below is a list of special keyword that
 306    harness uses. Basically, a test case contains dg-keywords (see
 307    dg.exp) indicating what to do and what kinds of behavior are to be
 308    expected.  New test cases should be written with the new style
 309    DejaGnu framework in mind.
 310    </p>
 311
 312    <p>
 313     To ease transition, here is the list of dg-keyword documentation
 314     lifted from dg.exp.
 315    </p>
 316
 317 <pre>
 318 # The currently supported options are:
 319 #
 320 # dg-prms-id N
 321 #       set prms_id to N
 322 #
 323 # dg-options "options ..." [{ target selector }]
 324 #       specify special options to pass to the tool (eg: compiler)
 325 #
 326 # dg-do do-what-keyword [{ target/xfail selector }]
 327 #       `do-what-keyword' is tool specific and is passed unchanged to
 328 #       ${tool}-dg-test.  An example is gcc where `keyword' can be any of:
 329 #       preprocess|compile|assemble|link|run
 330 #       and will do one of: produce a .i, produce a .s, produce a .o,
 331 #       produce an a.out, or produce an a.out and run it (the default is
 332 #       compile).
 333 #
 334 # dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]]
 335 #       indicate an error message &lt;regexp&gt; is expected on this line
 336 #       (the test fails if it doesn't occur)
 337 #       Linenum=0 for general tool messages (eg: -V arg missing).
 338 #       "." means the current line.
 339 #
 340 # dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]]
 341 #       indicate a warning message &lt;regexp&gt; is expected on this line
 342 #       (the test fails if it doesn't occur)
 343 #
 344 # dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]]
 345 #       indicate a bogus error message &lt;regexp&gt; use to occur here
 346 #       (the test fails if it does occur)
 347 #
 348 # dg-build regexp comment [{ target/xfail selector }]
 349 #       indicate the build use to fail for some reason
 350 #       (errors covered here include bad assembler generated, tool crashes,
 351 #       and link failures)
 352 #       (the test fails if it does occur)
 353 #
 354 # dg-excess-errors comment [{ target/xfail selector }]
 355 #       indicate excess errors are expected (any line)
 356 #       (this should only be used sparingly and temporarily)
 357 #
 358 # dg-output regexp [{ target selector }]
 359 #       indicate the expected output of the program is &lt;regexp&gt;
 360 #       (there may be multiple occurrences of this, they are concatenated)
 361 #
 362 # dg-final { tcl code }
 363 #       add some tcl code to be run at the end
 364 #       (there may be multiple occurrences of this, they are concatenated)
 365 #       (unbalanced braces must be \-escaped)
 366 #
 367 # "{ target selector }" is a list of expressions that determine whether the
 368 # test succeeds or fails for a particular target, or in some cases whether the
 369 # option applies for a particular target.  If the case of `dg-do' it specifies
 370 # whether the test case is even attempted on the specified target.
 371 #
 372 # The target selector is always optional.  The format is one of:
 373 #
 374 # { xfail *-*-* ... } - the test is expected to fail for the given targets
 375 # { target *-*-* ... } - the option only applies to the given targets
 376 #
 377 # At least one target must be specified, use *-*-* for "all targets".
 378 # At present it is not possible to specify both `xfail' and `target'.
 379 # "native" may be used in place of "*-*-*".
 380
 381 Example 1: Testing compilation only
 382 // { dg-do compile }
 383
 384 Example 2: Testing for expected warnings on line 36, which all targets fail
 385 // { dg-warning "string literals" "" { xfail *-*-* } 36
 386
 387 Example 3: Testing for expected warnings on line 36
 388 // { dg-warning "string literals" "" { target *-*-* } 36
 389
 390 Example 4: Testing for compilation errors on line 41
 391 // { dg-do compile }
 392 // { dg-error "no match for" "" { target *-*-* } 41 }
 393 </pre>
 394
 395    <p>
 396     More examples can be found in the libstdc++-v3/testsuite/*/*.cc files.
 397    </p>
 398
 399 <hr />
 400 <h2><a name="check">Options for running the tests</a></h2>
 401
 402    <p> There are several ways to run the testsuite. There are two
 403    harnesses, one using dejagnu and one using bash. In addition, there
 404    is a special rule for checking the ABI of the shared library.
 405    </p>
 406
 407    <p>You can check the status of the build without installing it
 408    using the dejagnu harness, much like the rest of the gcc tools.</p>
 409    <pre> make check</pre>
 410    <p>in the <em>libbuilddir</em> directory.</p>
 411    <p>or</p>
 412    <pre> make check-target-libstdc++-v3</pre>
 413    <p>in the <em>gccbuilddir</em> directory.</p>
 414
 415    <p>
 416       These commands are equivalent and will create a 'testsuite'
 417       directory underneath <em>libbuilddir</em> containing the results
 418       of the tests. Two results files will be generated: <em>
 419       libstdc++-v3.sum</em>, which is a PASS/FAIL summary for each
 420       test, and <em>libstdc++.log</em> which is a log of the exact
 421       command line passed to the compiler, the compiler output, and
 422       the executable output (if any). In addition, four files are
 423       generated that determine what test files are run. These files
 424       are:
 425    </p>
 426
 427    <ul>
 428      <li>
 429      <em>testsuite_files </em>
 430      <p> This is a list of all the test cases that will be run. Each
 431       test case is on a separate line, given with an absolute path
 432       from the <em>libsrcdir/testsuite</em> directory.
 433      </p>
 434      </li>
 435
 436      <li>
 437      <em>testsuite_files_interactive </em>
 438      <p> This is a list of all the interactive test cases, using the
 439      same format as the file list above. These tests are not run by default.
 440      </p>
 441      </li>
 442
 443      <li>
 444      <em>testsuite_files_performance</em>
 445      <p> This is a list of all the performance test cases, using the
 446      same format as the file list above. These tests are not run by default.
 447      </p>
 448      </li>
 449
 450      <li>
 451      <em>testsuite_wchar_t </em>
 452      <p> This file indicates that the host system can run the wchar_t
 453      tests, and corresponds to the macro definition <code>
 454      _GLIBCPP_USE_WCHAR_T</code> in the file c++config.h.
 455      </p>
 456      </li>
 457     </ul>
 458
 459 <p>
 460 To debug the dejagnu test harness during runs, try invoking with a
 461 specific argument to the variable RUNTESTFLAGS, as below.
 462 </p>
 463
 464 <pre>
 465 make check-target-libstdc++-v3 RUNTESTFLAGS="-v"
 466 </pre>
 467 or
 468 <pre>
 469 make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
 470 </pre>
 471
 472 There are two ways to run on a simulator: set up DEJAGNU to point to a
 473 specially crafted site.exp, or pass down --target_board flags.
 474
 475 Example flags to pass down for various embedded builds are as follows:
 476
 477 <pre>
 478 --target=powerpc-eabism (libgloss/sim)
 479 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
 480
 481 --target=calmrisc32 (libgloss/sid)
 482 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid"
 483
 484 --target=xscale-elf (newlib/sim)
 485 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
 486 </pre>
 487
 488    <p> In addition, there are some testing options that are mostly of
 489    interest to library maintainers and system integrators. As such,
 490    these tests may not work on all cpu and host combinations, and must
 491    be executed in the <em>libbuilddir/testsuite</em> directory.  These options
 492    include, but are not necessarily limited to, the following:
 493    </p>
 494
 495    <p>
 496    The library can also be tested using a bash script, instead of
 497    the default dejagnu test harness.
 498    </p>
 499    <pre>
 500    make check-script</pre>
 501    <p>
 502       These commands use the generated test_file lists as above, but
 503       run all the tests using both shared and static linking, and in
 504       addition provide some additional diffing of expected output
 505       files for the input/output tests. (This added diff may or may
 506       not be useful or necessary at the moment.) In addition, these
 507       tests provide size information for all the generated test cases,
 508       so that size data for new compiler or linker features can be
 509       collected. At one time timing information was attempted, so that
 510       compile speeds, link speeds, etc. could be measured, however at
 511       the moment all timing information is currently disabled.
 512    </p>
 513
 514    <pre>
 515    make check-script-install</pre>
 516    <p> As directly above, but tests an installed library, not the
 517       library and compiler in the build tree.
 518    </p>
 519
 520    <pre>
 521    make check-abi</pre>
 522    <p>The library ABI can be tested. This involves testing the shared
 523    library against an ABI-defining previous version. </p>
 524
 525    <pre>
 526    make check-performance</pre>
 527    <p>This rule runs through the <em>testsuite_files_performance</em>
 528    test cases and collects information for performance analysis and
 529    can be used to spot performance regressions. Various timing
 530    information is collected, as well as number of hard page faults,
 531    and memory used. This is not run by default, and the implementation
 532    is in flux.
 533 </p>
 534
 535    <p>
 536       We are interested in any strange failures of the
 537       testsuite; please see <a href="faq/index.html#2_4">FAQ 2.4</a>
 538       for which files to examine.
 539    </p>
 540
 541 <hr />
 542 <h2><a name="future">Future</a></h2>
 543
 544 <p>
 545 Shared runs need to be implemented, for targets that support shared libraries.
 546 </p>
 547
 548 <p>
 549 Diffing of expected output to standard streams needs to be finished off.
 550 </p>
 551
 552 <p>
 553 The V3 testing framework supports, or will eventually support,
 554 additional keywords for the purpose of easing the job of writing
 555 test cases.  All V3-keywords are of the form <code>@xxx@</code>.
 556 Currently plans for supported keywords include:
 557 </p>
 558
 559 <dl>
 560 <dt> <code> @require@ &lt;files&gt; </code> </dt>
 561 <dd>
 562    <p>
 563       The existence of &lt;files&gt; is essential for the test to complete
 564       successfully.  For example, a test case foo.C using bar.baz as
 565       input file could say
 566    </p>
 567    <pre>
 568             // @require@ bar.baz</pre>
 569    <p>
 570       The special variable % stands for the rootname, e.g. the
 571       file-name without its `.C' extension.  Example of use (taken
 572       verbatim from 27_io/filebuf.cc)
 573    </p>
 574    <pre>
 575            // @require@ %-*.tst %-*.txt</pre>
 576 </dd>
 577 <dt> <code> @diff@ &lt;first-list&gt; &lt;second-list&gt; </code> </dt>
 578 <dd>
 579    <p>
 580       After the test case compiles and ran successfully, diff
 581       &lt;first-list&gt; against &lt;second-list&gt;, these lists should
 582       have the same length.  The test fails if diff returns non-zero a
 583       pair of files.
 584    </p>
 585 </dd>
 586 </dl>
 587
 588 <!-- ####################################################### -->
 589
 590 <hr />
 591 <p class="fineprint"><em>
 592 See <a href="17_intro/license.html">license.html</a> for copying conditions.
 593 Comments and suggestions are welcome, and may be sent to
 594 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 595 </em></p>
 596
 597
 598 </body>
 599 </html>