doc: Add details on build and test

Change-Id: I58401ed26ba8a0a7fad0191b4c1bbb461d0311e6
Signed-off-by: Greg Tucker <greg.b.tucker@intel.com>

Doxyfile

@@ -13,7 +13,9 @@ INPUT                  = isa-l.h \
 			 include \
 			 README.md \
 			 CONTRIBUTING.md \
-			 Release_notes.txt
+			 Release_notes.txt \
+			 doc/test.md \
+			 doc/build.md
 
 EXCLUDE                = include/test.h include/types.h include/unaligned.h
 EXCLUDE_PATTERNS       = */include/*_multibinary.h

README.md

@@ -62,6 +62,8 @@ On Windows use nmake to build dll and static lib:
 
     nmake -f Makefile.nmake
 
+or see [details on setting up environment here](doc/build.md).
+
 ### Other make targets
 Other targets include:
 * `make check` : create and run tests

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

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