1This file describes the flex test suite. 2 3* WHO SHOULD USE THE TEST SUITE? 4 5The test suite is intended to be used by flex developers, i.e., anyone hacking 6the flex distribution. If you are simply installing flex, then you can ignore 7this directory and its contents. 8 9* STRUCTURE OF THE TEST SUITE 10 11The test suite consists of several directories, each containing a 12scanner known to work with the most recent version of flex. In 13general, after you modify your copy of the flex distribution, you 14should re-run the test suite. Some of the tests may require certain tools 15to be available (e.g., bison, diff). If any test returns an error or 16generates an error message, then your modifications *may* have broken 17a feature of flex. At a minimum, you'll want to investigate the 18failure and determine if it's truly significant. 19 20* HOW TO RUN THE TEST SUITE 21 22To build and execute all tests from the top level of the flex source tree: 23 24 $ make check 25 26To 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 35argument of the name of the test you want to create. If it fails with 36a message about a non-existent file `config.status', then run the 37configure script in the top-level directory and everything will be 38fine. If it fails to work for you other than this, report it as a 39bug. 40 41** Modify the files in the newly created directory so that they test 42whatever 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 47stderr, which will have been redirected to the file named, "OUTPUT", 48in 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. 78