Document CMake options in INSTALL

INSTALL

@@ -16,7 +16,7 @@ XZ Utils Installation
             1.2.8. DOS
             1.2.9. z/OS
        1.3. Adding support for new platforms
-    2. configure options
+    2. configure and CMake options
        2.1. Static vs. dynamic linking of liblzma
        2.2. Optimizing xzdec and lzmadec
     3. xzgrep and other scripts
@@ -213,19 +213,53 @@ XZ Utils Installation
     in C89 or C++.
 
 
-2. configure options
+2. configure and CMake options
---------------------
+------------------------------
 
     In most cases, the defaults are what you want. Many of the options
     below are useful only when building a size-optimized version of
     liblzma or command line tools.
 
+    configure options are those that begin with two dashes "--"
+    or "gl_".
+
+    CMake options begin with "XZ_", "TUKLIB_", or "CMAKE_". To use
+    them on the command line, prefix them with "-D", for example,
+    "cmake -DCMAKE_COMPILE_WARNING_AS_ERROR=ON".
+
+    CMAKE_BUILD_TYPE=TYPE
+                CMake only:
+
+                For release builds, CMAKE_BUILD_TYPE=Release is fine.
+                On targets where CMake defaults to -O3, the default
+                value is overridden to -O2.
+
+                Empty value (CMAKE_BUILD_TYPE=) is fine if using custom
+                optimization options. *In this package* the empty build
+                type also disables debugging code just like "Release"
+                does. To enable debugging code with empty build type,
+                use -UNDEBUG in the CFLAGS environment variable or in
+                the CMAKE_C_FLAGS CMake variable to override -DNDEBUG.
+
+                Non-standard build types like "None" do NOT disable
+                debugging code! Such non-standard build types should
+                be avoided for production builds!
+
     --enable-encoders=LIST
     --disable-encoders
-                Specify a comma-separated LIST of filter encoders to
+    XZ_ENCODERS=LIST
-                build. See "./configure --help" for exact list of
+                Specify a LIST of filter encoders to build. In the
-                available filter encoders. The default is to build all
+                configure option the list is comma separated.
-                supported encoders.
+                CMake lists are semicolon separated.
+
+                To see the exact list of available filter encoders:
+
+                  - Autotools: ./configure --help
+
+                  - CMake: Configure the tree normally first, then use
+                    "cmake -LH ." to list the cache variables.
+
+                The default is to build all supported encoders.
 
                 If LIST is empty or --disable-encoders is used, no filter
                 encoders will be built and also the code shared between
@@ -237,10 +271,12 @@ XZ Utils Installation
 
     --enable-decoders=LIST
     --disable-decoders
+    XZ_DECODERS=LIST
                 This is like --enable-encoders but for decoders. The
                 default is to build all supported decoders.
 
     --enable-match-finders=LIST
+    XZ_MATCH_FINDERS=LIST
                 liblzma includes two categories of match finders:
                 hash chains and binary trees. Hash chains (hc3 and hc4)
                 are quite fast but they don't provide the best compression
@@ -257,9 +293,11 @@ XZ Utils Installation
                 or LZMA2 filter encoders are being built.
 
     --enable-checks=LIST
+    XZ_CHECKS=LIST
                 liblzma support multiple integrity checks. CRC32 is
-                mandatory, and cannot be omitted. See "./configure --help"
+                mandatory, and cannot be omitted. Supported check
-                for exact list of available integrity check types.
+                types are "crc32", "crc64", and "sha256". By default
+                all supported check types are enabled.
 
                 liblzma and the command line tools can decompress files
                 which use unsupported integrity check type, but naturally
@@ -270,6 +308,7 @@ XZ Utils Installation
                 it is known to not cause problems.
 
     --enable-external-sha256
+    XZ_EXTERNAL_SHA256=ON
                 Try to use SHA-256 code from the operating system libc
                 or similar base system libraries. This doesn't try to
                 use OpenSSL or libgcrypt or such libraries.
@@ -306,6 +345,8 @@ XZ Utils Installation
                         time xz --test foo.xz
 
     --disable-microlzma
+    XZ_MICROLZMA_ENCODER=OFF
+    XZ_MICROLZMA_DECODER=OFF
                 Don't build MicroLZMA encoder and decoder. This omits
                 lzma_microlzma_encoder() and lzma_microlzma_decoder()
                 API functions from liblzma. These functions are needed
@@ -313,6 +354,7 @@ XZ Utils Installation
                 erofs-utils but they may be used by others too.
 
     --disable-lzip-decoder
+    XZ_LZIP_DECODER=OFF
                 Disable decompression support for .lz (lzip) files.
                 This omits the API function lzma_lzip_decoder() from
                 liblzma and .lz support from the xz tool.
@@ -321,6 +363,10 @@ XZ Utils Installation
     --disable-xzdec
     --disable-lzmadec
     --disable-lzmainfo
+    XZ_TOOL_XZ=OFF
+    XZ_TOOL_XZDEC=OFF
+    XZ_TOOL_LZMADEC=OFF
+    XZ_TOOL_LZMAINFO=OFF
                 Don't build and install the command line tool mentioned
                 in the option name.
 
@@ -330,29 +376,40 @@ XZ Utils Installation
                 a dangling man page symlink lzmadec.1 -> xzdec.1 is
                 created.
 
+    XZ_TOOL_SYMLINKS=OFF
+                Don't create the unxz and xzcat symlinks. (There is
+                no "configure" option to disable these symlinks.)
+
     --disable-lzma-links
+    XZ_TOOL_SYMLINKS_LZMA=OFF
                 Don't create symlinks for LZMA Utils compatibility.
                 This includes lzma, unlzma, and lzcat. If scripts are
                 installed, also lzdiff, lzcmp, lzgrep, lzegrep, lzfgrep,
                 lzmore, and lzless will be omitted if this option is used.
 
     --disable-scripts
+    XZ_TOOL_SCRIPTS=OFF
                 Don't install the scripts xzdiff, xzgrep, xzmore, xzless,
                 and their symlinks.
 
     --disable-doc
+    XZ_DOC=OFF
                 Don't install the documentation files to $docdir
                 (often /usr/doc/xz or /usr/local/doc/xz). Man pages
                 will still be installed. The $docdir can be changed
                 with --docdir=DIR.
 
     --enable-doxygen
+    XZ_DOXYGEN=ON
                 Enable generation of the HTML version of the liblzma API
                 documentation using Doxygen. The resulting files are
                 installed to $docdir/api. This option assumes that
                 the 'doxygen' tool is available.
 
+                NOTE: --disable-doc or XZ_DOC=OFF don't affect this.
+
     --disable-assembler
+    XZ_ASM_I386=OFF
                 This disables CRC32 and CRC64 assembly code on
                 32-bit x86. This option currently does nothing
                 on other architectures (not even on x86-64).
@@ -365,7 +422,16 @@ XZ Utils Installation
                 pre-i686 systems, you may want to disable the assembler
                 code.
 
+                The assembly code is compatible with only certain OSes
+                and toolchains (it's not compatible with MSVC).
+
+                Since XZ Utils 5.7.1alpha, the 32-bit x86 assembly code
+                co-exists with the modern CLMUL code: CLMUL is used if
+                support for it is detected at runtime. On old processors
+                the assembly code is used.
+
     --disable-clmul-crc
+    XZ_CLMUL_CRC=OFF
                 Disable the use of carryless multiplication for CRC
                 calculation even if compiler support for it is detected.
                 The code uses runtime detection of SSSE3, SSE4.1, and
@@ -378,6 +444,7 @@ XZ Utils Installation
                 detection isn't used and the generic code is omitted.
 
     --disable-arm64-crc32
+    XZ_ARM64_CRC32=OFF
                 Disable the use of the ARM64 CRC32 instruction extension
                 even if compiler support for it is detected. The code will
                 detect support for the instruction at runtime.
@@ -388,6 +455,7 @@ XZ Utils Installation
                 generic code is omitted.
 
     --enable-unaligned-access
+    TUKLIB_FAST_UNALIGNED_ACCESS=ON
                 Allow liblzma to use unaligned memory access for 16-bit,
                 32-bit, and 64-bit loads and stores. This should be
                 enabled only when the hardware supports this, that is,
@@ -435,6 +503,7 @@ XZ Utils Installation
                         how unaligned access is done in the C code.
 
     --enable-unsafe-type-punning
+    TUKLIB_USE_UNSAFE_TYPE_PUNNING=ON
                 This enables use of code like
 
                     uint8_t *buf8 = ...;
@@ -451,6 +520,7 @@ XZ Utils Installation
                 GCC 3 and early 4.x on x86, GCC < 6 on ARMv6 and ARMv7).
 
     --enable-small
+    XZ_SMALL=ON
                 Reduce the size of liblzma by selecting smaller but
                 semantically equivalent version of some functions, and
                 omit precomputed lookup tables. This option tends to
@@ -467,6 +537,7 @@ XZ Utils Installation
                 flag(s) to CFLAGS manually.
 
     --enable-assume-ram=SIZE
+    XZ_ASSUME_RAM=SIZE
                 On the most common operating systems, XZ Utils is able to
                 detect the amount of physical memory on the system. This
                 information is used by the options --memlimit-compress,
@@ -483,6 +554,7 @@ XZ Utils Installation
                 src/common/tuklib_physmem.c for details.
 
     --enable-threads=METHOD
+    XZ_THREADS=METHOD
                 Threading support is enabled by default so normally there
                 is no need to specify this option.
 
@@ -519,6 +591,7 @@ XZ Utils Installation
                                 one thread, something bad may happen.
 
     --enable-sandbox=METHOD
+    XZ_SANDBOX=METHOD
                 There is limited sandboxing support in the xz and xzdec
                 tools. If built with sandbox support, xz uses it
                 automatically when (de)compressing exactly one file to
@@ -554,6 +627,7 @@ XZ Utils Installation
                                 is found, configure will give an error.
 
     --enable-symbol-versions[=VARIANT]
+    XZ_SYMBOL_VERSIONING=VARIANT
                 Use symbol versioning for liblzma shared library.
                 This is enabled by default on GNU/Linux (glibc only),
                 other GNU-based systems, and FreeBSD.
@@ -598,13 +672,25 @@ XZ Utils Installation
                 run-time consistency checks. It makes the code slower, so
                 you normally don't want to have this enabled.
 
+                In CMake, the build type (CMAKE_BUILD_TYPE) controls if
+                -DNDEBUG is passed to the compiler. *In this package*,
+                an empty build type disables debugging code too.
+                Non-standard build types like "None" do NOT disable
+                debugging code!
+
+                To enable debugging code with empty build type in CMake,
+                use -UNDEBUG in the CFLAGS environment variable or in
+                the CMAKE_C_FLAGS CMake variable to override -DNDEBUG.
+
     --enable-werror
+    CMAKE_COMPILE_WARNING_AS_ERROR=ON (CMake >= 3.24)
                 If building with GCC, make all compiler warnings an error,
                 that abort the compilation. This may help catching bugs,
                 and should work on most systems. This has no effect on the
                 resulting binaries.
 
     --enable-path-for-scripts=PREFIX
+    (CMake determines this from the path of XZ_POSIX_SHELL)
                 If PREFIX isn't empty, PATH=PREFIX:$PATH will be set in
                 the beginning of the scripts (xzgrep and others).
                 The default is empty except on Solaris the default is
@@ -621,6 +707,17 @@ XZ Utils Installation
                 the PATH for the scripts. It is described in section 3.2
                 and is supported in this xz version too.
 
+    gl_cv_posix_shell=/path/to/bin/sh
+    XZ_POSIX_SHELL=/path/to/bin/sh
+                POSIX shell to use for xzgrep and other scripts.
+
+                  - configure should autodetect this well enough.
+                    Typically it's /bin/sh but in some cases, like
+                    Solaris, something else is used.
+
+                  - CMake build uses /bin/sh except on Solaris the
+                    default is /usr/xpg4/bin/sh.
+
 
 2.1. Static vs. dynamic linking of liblzma