external/bsd/flex/dist/tests/README

   1 This file describes the flex test suite.
   2
   3 * WHO SHOULD USE THE TEST SUITE?
   4
   5 The test suite is intended to be used by flex developers, i.e., anyone hacking
   6 the flex distribution. If you are simply installing flex, then you can ignore
   7 this directory and its contents.
   8
   9 * STRUCTURE OF THE TEST SUITE
  10
  11 The test suite consists of several directories, each containing a
  12 scanner known to work with the most recent version of flex. In
  13 general, after you modify your copy of the flex distribution, you
  14 should re-run the test suite. Some of the tests may require certain tools
  15 to be available (e.g., bison, diff). If any test returns an error or
  16 generates an error message, then your modifications *may* have broken
  17 a feature of flex. At a minimum, you'll want to investigate the
  18 failure and determine if it's truly significant.
  19
  20 * HOW TO RUN THE TEST SUITE
  21
  22 To build and execute all tests from the top level of the flex source tree:
  23
  24   $ make check
  25
  26 To build and execute a single test:
  27
  28   $ cd tests/ # from the top level of the flex tree.
  29   $ cd test-pthread-nr # for example
  30   $ make test
  31
  32 * HOW TO ADD A NEW TEST TO THE TEST SUITE
  33
  34 **- RUN the script `create-test` found in this directory with a single
  35 argument of the name of the test you want to create.  If it fails with
  36 a message about a non-existent file `config.status', then run the
  37 configure script in the top-level directory and everything will be
  38 fine.  If it fails to work for you other than this, report it as a
  39 bug.
  40
  41 ** Modify the files in the newly created directory so that they test
  42 whatever feature of flex you are interested in.
  43
  44 ** On success, your test should return zero.
  45
  46 ** On error, your test should return 1 (one) and print a message to
  47 stderr, which will have been redirected to the file named, "OUTPUT",
  48 in your test's directory.
  49
  50 ** If your test is skipped (e.g., because bison was not found), then
  51    the test should return 2 (two). See "test-bison-nr/Makefile.am" for
  52    an example.
  53
  54 ** You must modify the last few lines of the top-level configure.in by
  55    adding the Makefile for your test directory.  (This step is
  56    done automatically by `create-test`.)
  57
  58 ** You must add the name of your test to the SUBDIRS variable in
  59    tests/Makefile.am. (This is also done automatically for you by `create-test'.)
  60
  61 ** Add a description of your new test to the end of the file
  62     `descriptions'. Remember to keep the description as brief as
  63     possible, preferably to one line.
  64
  65 ** You will have to run the autogen.sh script in the top-level
  66    directory as well as run the configure script in that
  67    directory. (Note that running config.status may prove easier or
  68    quicker.)
  69
  70 ** The easiest way for you to submit your new test to the flex
  71    maintainers is by generating a patch. The flex maintainers only
  72    need to have the Makefile.am, the flex input file, the test input
  73    file (if there is one) and any other files necessary to compile the
  74    test. You do not need to submit files generated by autoconf,
  75    automake, configure etc. It would be helpful to include the file
  76    .cvsignore which you will find in your test directory if you used
  77    the `create-test' script.