libstdc++-v3/testsuite/README

   1 We're in the process of converting the existing testsuite machinery to
   2 use the new style DejaGnu framework.  Eventually, we'll abandon
   3 ../mkcheck.in in favor of this new testsuite framework.
   4
   5 // 1: Thoughts on naming test cases, and structuring them.
   6 The testsuite directory has been divided into 11 directories, directly
   7 correlated to the relevant chapters in the standard. For example, the
   8 directory testsuite/21_strings contains tests related to "Chapter 21,
   9 Strings library" in the C++ standard.
  10
  11 So, the first step in making a new test case is to choose the correct
  12 directory. The second item is seeing if a test file exists that tests
  13 the item in question. Generally, within chapters test files are named
  14 after the section headings in ISO 14882, the C++ standard. For instance,
  15
  16 21.3.7.9 Inserters and Extractors
  17
  18 Has a related test case:
  19 21_strings/inserters_extractors.cc
  20
  21 Not so hard. Some time, the words "ctor" and "dtor" are used instead
  22 of "construct", "constructor", "cons", "destructor", etc. Other than
  23 that, the naming seems mostly consistent. If the file exists, add a
  24 test to it. If it does not, then create a new file. All files are
  25 copyright the FSF, and GPL'd: this is very important.
  26
  27 Inside a test file, the plan is to test the relevant parts of the
  28 standard, and then add specific regressions as additional test
  29 functions, ie test04() can represent a specific regression noted in
  30 GNATS. Once test files get unwieldy or too big, then they should be
  31 broken up into multiple sub-categories, hopefully intelligently named
  32 after the relevant (and more specific) part of the standard.
  33
  34
  35 // 2: How to write a test case, from a dejagnu perspective
  36 As per the dejagnu instructions, always return 0 from main to indicate
  37 success.
  38
  39 Basically, a test case contains dg-keywords (see dg.exp) indicating
  40 what to do and what kinds of behaviour are to be expected.  New
  41 testcases should be written with the new style DejaGnu framework in
  42 mind.
  43
  44 To ease transition, here is the list of dg-keyword documentation
  45 lifted from dg.exp -- eventually we should improve DejaGnu
  46 documentation, but getting checkin account currently demands Pyrrhic
  47 effort.
  48
  49 # The currently supported options are:
  50 #
  51 # dg-prms-id N
  52 #       set prms_id to N
  53 #
  54 # dg-options "options ..." [{ target selector }]
  55 #       specify special options to pass to the tool (eg: compiler)
  56 #
  57 # dg-do do-what-keyword [{ target/xfail selector }]
  58 #       `do-what-keyword' is tool specific and is passed unchanged to
  59 #       ${tool}-dg-test.  An example is gcc where `keyword' can be any of:
  60 #       preprocess|compile|assemble|link|run
  61 #       and will do one of: produce a .i, produce a .s, produce a .o,
  62 #       produce an a.out, or produce an a.out and run it (the default is
  63 #       compile).
  64 #
  65 # dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]]
  66 #       indicate an error message <regexp> is expected on this line
  67 #       (the test fails if it doesn't occur)
  68 #       Linenum=0 for general tool messages (eg: -V arg missing).
  69 #       "." means the current line.
  70 #
  71 # dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]]
  72 #       indicate a warning message <regexp> is expected on this line
  73 #       (the test fails if it doesn't occur)
  74 #
  75 # dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]]
  76 #       indicate a bogus error message <regexp> use to occur here
  77 #       (the test fails if it does occur)
  78 #
  79 # dg-build regexp comment [{ target/xfail selector }]
  80 #       indicate the build use to fail for some reason
  81 #       (errors covered here include bad assembler generated, tool crashes,
  82 #       and link failures)
  83 #       (the test fails if it does occur)
  84 #
  85 # dg-excess-errors comment [{ target/xfail selector }]
  86 #       indicate excess errors are expected (any line)
  87 #       (this should only be used sparingly and temporarily)
  88 #
  89 # dg-output regexp [{ target selector }]
  90 #       indicate the expected output of the program is <regexp>
  91 #       (there may be multiple occurrences of this, they are concatenated)
  92 #
  93 # dg-final { tcl code }
  94 #       add some tcl code to be run at the end
  95 #       (there may be multiple occurrences of this, they are concatenated)
  96 #       (unbalanced braces must be \-escaped)
  97 #
  98 # "{ target selector }" is a list of expressions that determine whether the
  99 # test succeeds or fails for a particular target, or in some cases whether the
 100 # option applies for a particular target.  If the case of `dg-do' it specifies
 101 # whether the testcase is even attempted on the specified target.
 102 #
 103 # The target selector is always optional.  The format is one of:
 104 #
 105 # { xfail *-*-* ... } - the test is expected to fail for the given targets
 106 # { target *-*-* ... } - the option only applies to the given targets
 107 #
 108 # At least one target must be specified, use *-*-* for "all targets".
 109 # At present it is not possible to specify both `xfail' and `target'.
 110 # "native" may be used in place of "*-*-*".
 111
 112 Example 1: Testing compilation only
 113 (to just have a testcase do compile testing, without linking and executing)
 114 // { dg-do compile }
 115
 116 Example 2: Testing for expected warings on line 36
 117 // { dg-warning "string literals" "" { xfail *-*-* } 36
 118
 119 Example 3: Testing for compilation errors on line 41
 120 // { dg-do compile }
 121 // { dg-error "no match for" "" { xfail *-*-* } 41 }
 122
 123 More examples can be found in the libstdc++-v3/testsuite/*/*.cc files.
 124
 125
 126 // 3: Test harness notes, invocation, and debugging.
 127 Configuring the dejagnu harness to work with libstdc++-v3 in a cross
 128 compilation environment has been maddening. However, it does work now,
 129 and on a variety of platforms. Including solaris, linux, and cygwin.
 130
 131 To debug the test harness during runs, try invoking with
 132
 133 make check-target-libstdc++-v3 RUNTESTFLAGS="-v"
 134 or
 135 make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
 136
 137 There are two ways to run on a simulator: set up DEJAGNU to point to a
 138 specially crafted site.exp, or pass down --target_board flags.
 139
 140 Example flags to pass down for various embedded builds are as follows:
 141
 142 --target=powerpc-eabism (libgloss/sim)
 143 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
 144
 145 --target=calmrisc32 (libgloss/sid)
 146 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid"
 147
 148 --target=xscale-elf (newlib/sim)
 149 make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
 150
 151
 152 // 4: Future plans, to be done
 153 Shared runs need to be implemented, for targets that support shared libraries.
 154
 155 Diffing of expected output to standard streams needs to be finished off.
 156
 157 The V3 testing framework supports, or will eventually support,
 158 additional keywords for the purpose of easing the job of writing
 159 testcases.  All V3-keywords are of the form @xxx@.  Currently plans
 160 for supported keywords include:
 161
 162   @require@ <files>
 163       The existence of <files> is essential for the test to complete
 164       successfully.  For example, a testcase foo.C using bar.baz as
 165       input file could say
 166             // @require@ bar.baz
 167       The special variable % stands for the rootname, e.g. the
 168       file-name without its `.C' extension.  Example of use (taken
 169       verbatim from 27_io/filebuf.cc)
 170            // @require@ %-*.tst %-*.txt
 171
 172   @diff@ <first-list> <second-list>
 173       After the testcase compiles and ran successfully, diff
 174       <first-list> against <second-list>, these lists should have the
 175       same length.  The test fails if diff returns non-zero a pair of
 176       files.
 177
 178 Current testing problems with cygwin-hosted tools:
 179
 180 There are two known problems which I have not addressed.  The first is
 181 that when testing cygwin hosted tools from the unix build dir, it does
 182 the wrong thing building the wrapper program (testglue.c) because host
 183 and target are the same in site.exp (host and target are the same from
 184 the perspective of the target libraries)
 185
 186 Problem number two is a little more annoying.  In order for me to make
 187 v3 testing work on Windows, I had to tell dejagnu to copy over the
 188 debug_assert.h file to the remote host and then set the includes to
 189 -I./.  This is how all the other tests like this are done so I didn't
 190 think much of it.  However, this had some unfortunate results due to
 191 gcc having a testcase called "limits" and C++ having an include file
 192 called "limits".  The gcc "limits" binary was in the temporary dir
 193 when the v3 tests were being built.  As a result, the gcc "limits"
 194 binary was being #included rather than the intended one.  The only way
 195 to fix this is to go through the testsuites and make sure binaries are
 196 deleted on the remote host when testing is done with them.  That is a
 197 lot more work than I want to do so I worked around it by cleaning out
 198 D:\kermit on compsognathus and rerunning tests.