| 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.
|
|---|
