diff options
Diffstat (limited to 'src/isa-l/doc')
| -rw-r--r-- | src/isa-l/doc/build.md | 46 | ||||
| -rw-r--r-- | src/isa-l/doc/test.md | 49 |
2 files changed, 95 insertions, 0 deletions
diff --git a/src/isa-l/doc/build.md b/src/isa-l/doc/build.md new file mode 100644 index 000000000..db2c4f0d2 --- /dev/null +++ b/src/isa-l/doc/build.md @@ -0,0 +1,46 @@ +# ISA-L Build Details + +For x86-64 builds it is highly recommended to get an up-to-date version of +[nasm] that can understand the latest instruction sets. Building with an older +version is usually possible but the library may lack some function versions for +the best performance. + +## Windows Build Environment Details + +The windows dynamic and static libraries can be built with the nmake tool on the +windows command line when appropriate paths and tools are setup as follows. + +### Download nasm and put into path + +Download and install [nasm] and add location to path. + + set PATH=%PATH%;C:\Program Files\NASM + +### Setup compiler environment + +Install compiler and run environment setup script. + +Compilers for windows usually have a batch file to setup environment variables +for the command line called `vcvarsall.bat` or `compilervars.bat` or a link to +run these. For Visual Studio this may be as follows for Community edition. + + C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat x64 + +For the Intel compiler the path is typically as follows where yyyy, x, zzz +represent the version. + + C:\Program Files (x86)\IntelSWTools\system_studio_for_windows_yyyy.x.zzz\compilers_and_libraries_yyyy\bin\compilervars.bat intel64 + +### Build ISA-L libs and copy to appropriate place + +Run `nmake /f Makefile.nmake` + +This should build isa-l.dll, isa-l.lib and isa-l_static.lib. You may want to +copy the libs to a system directory in the dynamic linking path such as +`C:\windows\system32` or to a project directory. + +To build a simple program with a static library. + + cl /Fe: test.exe test.c isa-l_static.lib + +[nasm]: https://www.nasm.us diff --git a/src/isa-l/doc/test.md b/src/isa-l/doc/test.md new file mode 100644 index 000000000..e3a4ccda7 --- /dev/null +++ b/src/isa-l/doc/test.md @@ -0,0 +1,49 @@ +# ISA-L Testing + +Tests are divided into check tests, unit tests and fuzz tests. Check tests, +built with `make check`, should have no additional dependencies. Other unit +tests built with `make test` may have additional dependencies in order to make +comparisons of the output of ISA-L to other standard libraries and ensure +compatibility. Fuzz tests are meant to be run with a fuzzing tool such as [AFL] +or [llvm libFuzzer] fuzzing to direct the input data based on coverage. There +are a number of scripts in the /tools directory to help with automating the +running of tests. + +## Test check + +`./tools/test_autorun.sh` is a helper script for kicking off check tests, that +typically run for a few minutes, or extended tests that could run much +longer. The command `test_autorun.sh check` build and runs all check tests with +autotools and runs other short tests to ensure check tests, unit tests, +examples, install, exe stack, format are correct. Each run of `test_autorun.sh` +builds tests with a new random test seed that ensures that each run is unique to +the seed but deterministic for debugging. Tests are also built with sanitizers +and Electric Fence if available. + +## Extended tests + +Extended tests are initiated with the command `./tools/test_autorun.sh +ext`. These build and run check tests, unit tests, and other utilities that can +take much longer than check tests alone. This includes special compression tools +and some cross targets such as the no-arch build of base functions only and +mingw build if tools are available. + +## Fuzz testing + +`./tools/test_fuzz.sh` is a helper script for fuzzing to setup, build and run +the ISA-L inflate fuzz tests on multiple fuzz tools. Fuzzing with +[llvm libFuzzer] requires clang compiler tools with `-fsanitize=fuzzer` or +`libFuzzer` installed. You can invoke the default fuzz tests under llvm with + + ./tools/test_fuzz.sh -e checked + +To use [AFL], install tools and system setup for `afl-fuzz` and run + + ./tools/test_fuzz.sh -e checked --afl 1 --llvm -1 -d 1 + +This uses internal vectors as a seed. You can also specify a sample file to use +as a seed instead with `-f <file>`. One of three fuzz tests can be invoked: +checked, simple, and round_trip. + +[llvm libFuzzer]: https://llvm.org/docs/LibFuzzer.html +[AFL]: https://github.com/google/AFL |