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