From ba177057643dae6e9c167ee26471181c199c8a00 Mon Sep 17 00:00:00 2001 From: Jia Tan Date: Fri, 14 Jul 2023 23:20:33 +0800 Subject: [PATCH] Docs: Add a new section to INSTALL for Tests. The new Tests section describes basic information about the tests, how to run them, and important details when cross compiling. We have had a few questions about how to compile the tests without running them, so hopefully this information will help others with the same question in the future. Fixes: https://github.com/tukaani-project/xz/issues/54 --- INSTALL | 81 +++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 64 insertions(+), 17 deletions(-) diff --git a/INSTALL b/INSTALL index 7fb41fa6..b2b3c8e8 100644 --- a/INSTALL +++ b/INSTALL @@ -22,13 +22,16 @@ XZ Utils Installation 3. xzgrep and other scripts 3.1. Dependencies 3.2. PATH - 4. Troubleshooting - 4.1. "No C99 compiler was found." - 4.2. "No POSIX conforming shell (sh) was found." - 4.3. configure works but build fails at crc32_x86.S - 4.4. Lots of warnings about symbol visibility - 4.5. "make check" fails - 4.6. liblzma.so (or similar) not found when running xz + 4. Tests + 4.1 Testing in parallel + 4.2 Cross compiling + 5. Troubleshooting + 5.1. "No C99 compiler was found." + 5.2. "No POSIX conforming shell (sh) was found." + 5.3. configure works but build fails at crc32_x86.S + 5.4. Lots of warnings about symbol visibility + 5.5. "make check" fails + 5.6. liblzma.so (or similar) not found when running xz 0. Preface @@ -100,7 +103,7 @@ XZ Utils Installation XZ Utils doesn't have code to detect the amount of physical RAM and number of CPU cores on MINIX 3. - See section 4.4 in this file about symbol visibility warnings (you + See section 5.4 in this file about symbol visibility warnings (you may want to pass gl_cv_cc_visibility=no to configure). @@ -127,14 +130,14 @@ XZ Utils Installation missing from PATH (/usr/xpg4/bin or /usr/xpg6/bin). Nowadays /usr/xpg4/bin is added to the script PATH by default on Solaris (see --enable-path-for-scripts=PREFIX in section 2), but old xz - releases needed extra steps. See sections 4.5 and 3.2 for more + releases needed extra steps. See sections 5.5 and 3.2 for more information. 1.2.6. Tru64 If you try to use the native C compiler on Tru64 (passing CC=cc to - configure), you may need the workaround mention in section 4.1 in + configure), you may need the workaround mention in section 5.1 in this file (pass also ac_cv_prog_cc_c99= to configure). @@ -624,10 +627,54 @@ XZ Utils Installation src/scripts/xz*.in -4. Troubleshooting +4. Tests +-------- + + The test framework can be built and run by executing "make check" in + the build directory. The tests are a mix of executables and POSIX + shell scripts (sh). All tests should pass if the default configuration + is used. Disabling features through the configure options may cause + some tests to be skipped. If any tests do not pass, see section 5.5. + + +4.1. Testing in parallel + + The tests can be run in parallel using the "-j" make option on systems + that support it. For instance, "make -j4 check" will run up to four + tests simultaneously. + + +4.2. Cross compiling + + The tests can be built without running them: + + make check TESTS= + + The TESTS variable is the list of tests you wish to run. Leaving it + empty will compile the tests without running any. + + If the tests are copied to a target machine to execute, the test data + files in the directory tests/files must also be copied. The tests + search for the data files using the environment variable $srcdir, + expecting to find the data files under $srcdir/files/. If $srcdir + isn't set then it defaults to the current directory. + + The shell script tests can be copied from the source directory to the + target machine to execute. In addition to the test files, these tests + will expect the following relative file paths to execute properly: + + ./create_compress_files + ../config.h + ../src/xz/xz + ../src/xzdec/xzdec + ../src/scripts/xzdiff + ../src/scripts/xzgrep + + +5. Troubleshooting ------------------ -4.1. "No C99 compiler was found." +5.1. "No C99 compiler was found." You need a C99 compiler to build XZ Utils. If the configure script cannot find a C99 compiler and you think you have such a compiler @@ -642,7 +689,7 @@ XZ Utils Installation support enough C99. -4.2. "No POSIX conforming shell (sh) was found." +5.2. "No POSIX conforming shell (sh) was found." xzgrep and other scripts need a shell that (roughly) conforms to POSIX. The configure script tries to find such a shell. If @@ -652,7 +699,7 @@ XZ Utils Installation this error by passing --disable-scripts to configure. -4.3. configure works but build fails at crc32_x86.S +5.3. configure works but build fails at crc32_x86.S The easy fix is to pass --disable-assembler to the configure script. @@ -669,7 +716,7 @@ XZ Utils Installation (see INSTALL.generic). -4.4. Lots of warnings about symbol visibility +5.4. Lots of warnings about symbol visibility On some systems where symbol visibility isn't supported, GCC may still accept the visibility options and attributes, which will make @@ -681,7 +728,7 @@ XZ Utils Installation using --enable-werror. -4.5. "make check" fails +5.5. "make check" fails If the other tests pass but test_scripts.sh fails, then the problem is in the scripts in src/scripts. Comparing the contents of @@ -707,7 +754,7 @@ XZ Utils Installation information. -4.6. liblzma.so (or similar) not found when running xz +5.6. liblzma.so (or similar) not found when running xz If you installed the package with "make install" and get an error about liblzma.so (or a similarly named file) being missing, try