ghc/compiler/tests/README

   1 Installing a new compiler test
   2 ==============================
   3
   4 [If the test if for the driver, the parser, the runtime system, the
   5 std prelude, ... in short _not_ the compiler, it belongs elsewhere.]
   6
   7 1.  Copy your Haskell program into an appropriately named file in the
   8     appropriate directory, e.g., "typecheck/tc093.hs" for the 93rd
   9     typechecker test.
  10
  11 2.  Edit the Jmakefile in that dir to add your test: almost certainly
  12     just a line of the form...
  13
  14 RunStdTest(tc093,$(TESTGHC), "-ddump-tc tc093.hs", 0, /dev/null, tc093.stderr)
  15            ^^^^^
  16 name of test||||
  17                  ^^^^^^^^^^
  18 driver to use----||||||||||
  19                              ^^^^^^^^^^^^^^^^^^^^
  20 driver command line----------||||||||||||||||||||
  21                                                   ^^
  22 expected exit status (0=success, 1=failure)-------||
  23                                                      ^^^^^^^^^
  24 file holding expected standard output----------------|||||||||
  25                                                                 ^^^^^^^^^^^^^
  26 file holding expected output on standard error------------------|||||||||||||
  27
  28     The example above is typical.  The command-line stuff may vary,
  29     but it's likely to be "dump pass <foo> output" (e.g., -ddump-tc)
  30     and the input file name.  Dump output is on stderr, hence the
  31     expected-output files.
  32
  33     The current best documentation of the flags to use is in
  34     $(TOP)/driver/ghc (invoke w/ -help option).
  35
  36 3.  Create the expected-output files.  I'm usually lazy and just
  37     "touch" them (creating an empty file), then update them (section
  38     below) after the test has "failed".
  39
  40 4.  "make Makefile", to make a Makefile from the Jmakefile.
  41
  42 5.  "make runtest_<testname>" (e.g., make runtest_tc093) to run the
  43     one test.
  44
  45     IF "make" FALLS OVER, THEN IMMEDIATEDLY "mv Makefile.bak Makefile"!!
  46     You probably had a typo in the Jmakefile; fix it and resume from
  47     step 4.
  48
  49
  50 Running tests
  51 =============
  52
  53 * You may run all tests by typing "make runtests" (or, if you expect
  54   or don't mind errors, "make -k runtests").
  55
  56 * You may run one test <foo> with "make runtest_<foo>".
  57
  58 * You may run tests <foo> to <bar> with a simple script,
  59   "dotests <foo> <bar>".  You may pass "make" arguments to it as well,
  60   as in:
  61         dotests -k tc019 tc028
  62
  63
  64 Updating the "expected output" files
  65 ====================================
  66
  67 Sometimes, it will happen that the differences between expected and
  68 actual output of the tests will not mean failure but that the actual
  69 output is "more correct".
  70
  71 If you save the output of "make runtests" (mainly from "diff"), you
  72 may automatically update the expected-output files by using
  73
  74     patch -p0 < saved-output
  75
  76 (You should probably ^C out of the "patch" if it doesn't do exactly
  77 what you expect.)