1This directory contains the test suite for the 'etags' and 'ctags'
2programs.
3
4The input files, which include source files in various languages
5supported by the programs, are in the *-src/ directories (e.g., c-src
6for C sources, ada-src for Ada, tex-src for TeX, etc.).
7
8The expected results are slightly different for each of the 7 commands
9(see below) run by the test suite, and are on files ETAGS.good_N
10(where N is between 1 and 6) and CTAGS.good.
11
12To run the tests, say
13
14   make check
15
16in this directory.  This should run the programs 7 times with various
17command line switches, and should not show any differences between the
18produced file ETAGS/CTAGS and the corresponding expected results.  Any
19diffs shown by the 'diff' utility should be examined for potential
20regressions in 'etags' or 'ctags'.
21
22In some cases, diffs should be expected.  These include:
23
24  . adding new input files in the *-src/ directories
25  . routine changes in the existing input files, such as the yearly
26    update of copyright years, spelling changes, etc.
27  . adding new features to etags.c
28
29When the diffs are expected, they should be examined to make sure
30there are no regressions.  To do so, compare the line numbers and byte
31offsets shown in the new ETAGS/CTAGS files against the up-to-date
32input files, and make sure the new values match, whereas the old one
33don't.  Also make sure there no new or missing entries in the
34ETAGS/CTAGS files as compared with the expected results.  (When new
35input files are added, there obviously will be new entries -- these
36should be compared to the input files to verify correctness.)
37
38Once the differences are deemed to be justified, i.e. you decide that
39the new ETAGS/CTAGS file should become the new expected result, you
40should copy the ETAGS/CTAGS files produced by the test run to the
41corresponding "good" files, one by one.  Like this:
42
43  $ make check
44  $ cp ETAGS ETAGS.good_1
45  $ make check
46  $ cp ETAGS ETAGS.good_2
47  $ make check
48  $ cp ETAGS ETAGS.good_3
49  ...
50  $ make check
51  $ cp ETAGS ETAGS.good_6
52  $ make check
53  $ cp CTAGS CTAGS.good
54
55This uses the fact that "make check" will stop after the first
56failure, i.e. after the first time 'diff' reports any diffs, and then
57the ETAGS/CTAGS file from the last invocation is available for
58becoming the new expected-result file.  Alternatively, you can see the
59name of the expected-result file which needs to be updated in the
60output of the 'diff' utility.
61