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 Basically, a testcase contains dg-keywords (see dg.exp) indicating
   6 what to do and what kinds of behaviour are to be expected.  New
   7 testcases should be written with the new style DejaGnu framework in
   8 mind.
   9
  10 To ease transition, here is the list of dg-keyword documentation
  11 lifted from dg.exp -- eventually we should improve DejaGnu
  12 documentation, but getting checkin account currently demands Pyrrhic
  13 effort.
  14
  15 # The currently supported options are:
  16 #
  17 # dg-prms-id N
  18 #       set prms_id to N
  19 #
  20 # dg-options "options ..." [{ target selector }]
  21 #       specify special options to pass to the tool (eg: compiler)
  22 #
  23 # dg-do do-what-keyword [{ target/xfail selector }]
  24 #       `do-what-keyword' is tool specific and is passed unchanged to
  25 #       ${tool}-dg-test.  An example is gcc where `keyword' can be any of:
  26 #       preprocess|compile|assemble|link|run
  27 #       and will do one of: produce a .i, produce a .s, produce a .o,
  28 #       produce an a.out, or produce an a.out and run it (the default is
  29 #       compile).
  30 #
  31 # dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]]
  32 #       indicate an error message <regexp> is expected on this line
  33 #       (the test fails if it doesn't occur)
  34 #       Linenum=0 for general tool messages (eg: -V arg missing).
  35 #       "." means the current line.
  36 #
  37 # dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]]
  38 #       indicate a warning message <regexp> is expected on this line
  39 #       (the test fails if it doesn't occur)
  40 #
  41 # dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]]
  42 #       indicate a bogus error message <regexp> use to occur here
  43 #       (the test fails if it does occur)
  44 #
  45 # dg-build regexp comment [{ target/xfail selector }]
  46 #       indicate the build use to fail for some reason
  47 #       (errors covered here include bad assembler generated, tool crashes,
  48 #       and link failures)
  49 #       (the test fails if it does occur)
  50 #
  51 # dg-excess-errors comment [{ target/xfail selector }]
  52 #       indicate excess errors are expected (any line)
  53 #       (this should only be used sparingly and temporarily)
  54 #
  55 # dg-output regexp [{ target selector }]
  56 #       indicate the expected output of the program is <regexp>
  57 #       (there may be multiple occurrences of this, they are concatenated)
  58 #
  59 # dg-final { tcl code }
  60 #       add some tcl code to be run at the end
  61 #       (there may be multiple occurrences of this, they are concatenated)
  62 #       (unbalanced braces must be \-escaped)
  63 #
  64 # "{ target selector }" is a list of expressions that determine whether the
  65 # test succeeds or fails for a particular target, or in some cases whether the
  66 # option applies for a particular target.  If the case of `dg-do' it specifies
  67 # whether the testcase is even attempted on the specified target.
  68 #
  69 # The target selector is always optional.  The format is one of:
  70 #
  71 # { xfail *-*-* ... } - the test is expected to fail for the given targets
  72 # { target *-*-* ... } - the option only applies to the given targets
  73 #
  74 # At least one target must be specified, use *-*-* for "all targets".
  75 # At present it is not possible to specify both `xfail' and `target'.
  76 # "native" may be used in place of "*-*-*".
  77 #
  78 # Example:
  79 #
  80 #       [ ... some complicated code ... ]
  81 #       return a; /* { dg-build "fatal" "ran out of spill regs" { xfail i386-*-* } } */
  82 #
  83 # In this example, the compiler use to crash on the "return a;" for some
  84 # target and that it still does crash on i386-*-*.  Admittedly, this is a
  85 # contrived example.
  86 #
  87 # ??? It might be possible to add additional optional arguments by having
  88 # something like: { dg-error ".*syntax.*" "syntax error" { { foo 1 } ... } }
  89
  90
  91 The V3 testing framework supports additional keywords for the purpose
  92 of easing the job of writing testcases.  All V3-keywords are of the
  93 form @xxx@.  Currently supported keywords include:
  94
  95   @require@ <files>
  96       The existence of <files> is essential for the test to complete
  97       successfully.  For example, a testcase foo.C using bar.baz as
  98       input file could say
  99             // @require@ bar.baz
 100       The special variable % stands for the rootname, e.g. the
 101       file-name without its `.C' extension.  Example of use (taken
 102       verbatim from 27_io/filebuf.cc)
 103            // @require@ %-*.tst %-*.txt
 104
 105   @diff@ <first-list> <second-list>
 106       After the testcase compiles and ran successfully, diff
 107       <first-list> against <second-list>, these lists should have the
 108       same length.  The test fails if diff returns non-zero a pair of
 109       files.
 110
 111 -- Gaby