NameDateSize

..09-Jul-20209

archives/09-May-20167

basic/09-May-20168

common.sh15-May-20149.3 KiB

execution/09-May-20168

Makefile09-May-2016302

Makefile.depend10-Mar-2016176

Makefile.inc17-Feb-201632

README15-May-20145.5 KiB

shell/09-May-201610

suffixes/09-May-20167

syntax/09-May-20168

sysmk/09-May-20167

test-new.mk15-May-2014188

variables/09-May-20168

README

1$FreeBSD$
2
3This directory contains regression tests for make(1).
4
5To invoke the tests, please refer to tests(7).
6
7----------------------------------------------------------------------------
8
9The rest of this file is intended for developers.
10
11The tests are invoked via the test.sh script or prove(1) from p5-Test-Harness.
12Tests are normally executed in a special test directory that is built under
13/tmp. The reason for this is, that make tests are generally influenced by
14all file in a directory, by files in one of make's obscure object directories
15as well as in other directories make happens to look into. Therefor the
16test scripts build a clean environment in the temp directory and the
17tests are executed by cd-ing into that directory and invoking make. The
18output of the make run (standard output, standard error and the exit status)
19are written into files that are created in another directory. So the layout
20for the shell/builtin test looks like:
21
22	./shell/builtin/			- directory with test stuff
23	/tmp/make.${USER}/shell/builtin		- actual test directory
24	/tmp/make.${USER}/shell/builtin.OUTPUT	- output files
25
26So a full test consists of the following steps:
27
28	setup	- Set up the test environment by creating the test directory
29		  and populating it with the needed files. If the test
30		  directory already exists an error is printed.
31
32	run	- Run the test and produce the output into the output
33		  directory.
34
35	show	- Show the result files on the screen.
36
37	compare	- Compare the results in the output directory with those
38		  in the test source directory. This just prints whether
39		  the test was ok or not in the format used by prove(1).
40
41	diff	- Diff the output files and the expected output files.
42
43	reset	- Reset the test to its initial state.
44
45	clean	- Remove both the test directory and the output directory.
46
47Each of these steps can independently be invoked with the test script
48contained in each directory. These test scripts are called test.t.
49Additionally the scripts understand the following commands:
50
51	test	- Run setup, run and compare.
52
53	prove	- Run setup, run, compare and clean. This is identically
54		  to invoking the script without an argument.
55
56	desc	- Print a short test description.
57
58	update	- Update the expected results from the actual results.
59
60The test script has the following syntax:
61
62	% test.t [-v] [-m path_to_make_binary] command
63
64To invoke it via prove(1) use:
65
66	% [MAKE_PROG=path_to_make_binary] prove [options] [files/directories]
67
68Example:
69	% sh test.t -m `pwd`/../obj/make run
70	% MAKE_PROG=/usr/obj/usr/src/usr.bin/make/make prove -r
71
72The test scripts use the following environment variables that can be set
73by the user in the test script's environment:
74
75	WORK_BASE
76		- Base directory for working files. If not set
77		  /tmp/make.${USER} is used.
78
79	MAKE_PROG
80		- Path to the make program to test. If not set
81		  /usr/bin/make is used.
82
83The following variables are available to test scripts:
84
85	SRC_BASE
86		- test source base directory. This is determined by
87		  repeatedly doing cd .. and checking for common.sh.
88		  Therefor this can fail if a test source directory is 
89		  actually a symbolic link and is physically not located
90		  below the directory containing common.sh.
91
92	SUBDIR	
93		- subdirectory below WORK_BASE and SRC_BASE for current test
94
95	WORK_DIR
96		- ${WORK_BASE}/${SUBDIR}
97
98	SRC_DIR
99		- ${SRC_BASE}/${SUBDIR}
100
101The following variables and functions may be defined by the test script.
102This also lists special filenames.
103
104	DESC
105		A one-line description of the test.
106
107	TEST_MAKE_DIRS
108		A list of pairs of directory names and modes. These
109		directories are created during setup and reset. When
110		the directory already exists (during reset) only the
111		mode change is applied.
112
113		TEST_MAKE_DIRS="subdir 775 subdir/sub 555"
114
115	TEST_COPY_FILES
116		A list of pairs of file names and modes. These files
117		are copied from the source to the working directory
118		during setup and reset. When the file already exists
119		(during reset) only the mode change is applied. Files
120		may be copied from/to sub-directories. The sub-directory
121		in the working directory must already exists (see
122		TEST_MAKE_DIRS).
123
124		TEST_COPY_FILES="libtest.a 444 subdir/libfoo.a 444"
125
126	TEST_TOUCH
127		List of pairs of file names and arguments to touch(1).
128		During setup and reset for each list element touch(1)
129		is executed.
130
131		TEST_TOUCH="file1 '-t 200501011257'"
132
133	TEST_LINK
134		List of pairs of filenames. Each pair is passed to ln(1).
135		All names are prefixed with the working directory.
136
137	Makefile
138		If a file with this name exists in the source directory
139		it is automatically copied to the working directory.
140
141	setup_test()
142		If this function exists it is executed at the end of the
143		setup.
144
145	reset_test()
146		If this function exists it is executed at the end of the
147		reset.
148
149	TEST_CLEAN_FILES
150		A list of file to be deleted when resetting.
151
152	TEST_N
153		Number of tests in this script. If not set this is assumed
154		to be 1.
155
156	TEST_<number>
157		Arguments to make for test number <number>. If not set
158		the default argument of test<number> is used. To run a test
159		without argument to make, set TEST_<number> to the empty string.
160
161	TEST_<number>_SKIP
162		To skip a test (for whatever reason) this should be set
163		to a string explaining the reason for skipping the test.
164
165	TEST_<number>_TODO
166		For a test that should fail this is a short string describing
167		what the problem in make(1) is that should be fixed.
168
169	run_test()
170		Function to run a test. This function gets a single argument
171		which is the number of the test to executed. The default
172		function evaluates the variable TEST_<number> and calls
173		make with the arguments in this variable.
174
175