Clean up build options and documentation

CMakeLists.txt

@@ -42,7 +42,9 @@ option(ISA_NONE "Enable builds for no SIMD")
 option(ISA_NATIVE "Enable builds for native SIMD")
 option(DECOMPRESSOR "Enable builds for decompression only")
 option(DIAGNOSTICS "Enable builds for diagnostic trace")
+option(ASAN "Enable builds width address sanitizer")
 option(UNITTEST "Enable builds for unit tests")
+option(NO_INVARIANCE "Enable builds without invariance")
 option(CLI "Enable build of CLI" ON)
 
 set(UNIVERSAL_BUILD OFF)
@@ -202,7 +204,9 @@ if("${MACOS_BUILD}")
     printopt("Universal bin  " ${UNIVERSAL_BUILD})
 endif()
 printopt("Decompressor   " ${DECOMPRESSOR})
+printopt("No invariance  " ${NO_INVARIANCE})
 printopt("Diagnostics    " ${DIAGNOSTICS})
+printopt("ASAN           " ${ASAN})
 printopt("Unit tests     " ${UNITTEST})
 
 # Subcomponents

Docs/Building.md

@@ -3,19 +3,20 @@
 This page provides instructions for building `astcenc` from the sources in
 this repository.
 
-Builds use CMake 3.15 or higher as the build system generator. The examples on
-this page only show how to use it to target NMake (Windows) and Make
-(Linux and macOS), but CMake supports other build system backends.
+Builds must use CMake 3.15 or higher as the build system generator. The
+examples on this page show how to use it to generate build systems for NMake
+(Windows) and Make (Linux and macOS), but CMake supports other build system
+backends.
 
 ## Windows
 
 Builds for Windows are tested with CMake 3.17 and Visual Studio 2019.
 
 ### Configuring the build
 
-To use CMake you must first configure the build. Create a build directory
-in the root of the `astenc` checkout, and then run `cmake` inside that
-directory to generate the build system.
+To use CMake you must first configure the build. Create a build directory in
+the root of the `astcenc` checkout, and then run `cmake` inside that directory
+to generate the build system.
 
 ```shell
 # Create a build directory
@@ -25,17 +26,18 @@ cd build
 # Configure your build of choice, for example:
 
 # x86-64 using NMake
-cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release ^
-    -DCMAKE_INSTALL_PREFIX=.\ -DISA_AVX2=ON -DISA_SSE41=ON -DISA_SSE2=ON ..
+cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=..\ ^
+    -DISA_AVX2=ON -DISA_SSE41=ON -DISA_SSE2=ON ..
 
 # x86-64 using Visual Studio solution
-cmake -G "Visual Studio 16 2019" -T ClangCL ^
-    -DCMAKE_INSTALL_PREFIX=.\ -DISA_AVX2=ON -DISA_SSE41=ON -DISA_SSE2=ON ..
+cmake -G "Visual Studio 16 2019" -T ClangCL -DCMAKE_INSTALL_PREFIX=..\ ^
+    -DISA_AVX2=ON -DISA_SSE41=ON -DISA_SSE2=ON ..
 ```
 
-This example shows all SIMD variants being enabled. It is possible to build a
-subset of the supported variants by enabling only the ones you require. At
-least one variant must be enabled.
+A single CMake configure can build multiple binaries for a single target CPU
+architecture, for example building x64 for both SSE2 and AVX2. Each binary name
+will include the build variant as a postfix. It is possible to build any set of
+the supported SIMD variants by enabling only the ones you require.
 
 Using the Visual Studio Clang-CL LLVM toolchain (`-T ClangCL`) is optional but
 produces significantly faster binaries than the default toolchain. The C++ LLVM
@@ -61,7 +63,7 @@ Builds for macOS and Linux are tested with CMake 3.17 and clang++ 9.0.
 ### Configuring the build
 
 To use CMake you must first configure the build. Create a build directory
-in the root of the astenc checkout, and then run `cmake` inside that directory
+in the root of the astcenc checkout, and then run `cmake` inside that directory
 to generate the build system.
 
 ```shell
@@ -75,32 +77,30 @@ cd build
 # Configure your build of choice, for example:
 
 # Arm arch64
-cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./ \
+cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../ \
     -DISA_NEON=ON ..
 
 # x86-64
-cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./ \
+cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../ \
     -DISA_AVX2=ON -DISA_SSE41=ON -DISA_SSE2=ON ..
 
 # macOS universal binary build
-cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./ \
+cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../ \
     -DISA_AVX2=ON -DISA_NEON=ON ..
 ```
 
-This example shows all SIMD variants being enabled. It is possible to build a
-subset of the supported variants by enabling only the ones you require.
-
-For all platforms a single CMake configure can build multiple binaries for a
-single target CPU architecture, for example building x64 for both SSE2 and
-AVX2. The binary name will include the build variant as a postfix.
-
-The macOS platform additionally supports the ability to build a universal
-binary, combining one x86 and one arm64 variant into a single output binary.
-The OS select the correct variant to run for the machine being used to run the
-binary. To build a universal binary select a single x64 variant and a single
-arm64 variant, and both will be included in a single output binary. It is not
-required, but if `CMAKE_OSX_ARCHITECTURES` is set on the command line (e.g.
-by XCode-generated build commands) it will be validated against the other
+A single CMake configure can build multiple binaries for a single target CPU
+architecture, for example building x64 for both SSE2 and AVX2. Each binary name
+will include the build variant as a postfix. It is possible to build any set of
+the supported SIMD variants by enabling only the ones you require.
+
+For macOS, we additionally support the ability to build a universal binary,
+combining one x86 and one arm64 variant into a single output binary. The OS
+will select the correct variant to run for the machine being used to run the
+built binary. To build a universal binary select a single x86 variant and a
+single arm64 variant, and both will be included in a single output binary. It
+is not required, but if `CMAKE_OSX_ARCHITECTURES` is set on the command line
+(e.g. by XCode-generated build commands) it will be validated against the other
 configuration variant settings.
 
 ### Building
@@ -116,7 +116,8 @@ make install -j16
 
 ## Advanced build options
 
-For codec developers there are a number of useful features in the build system.
+For codec developers and power users there are a number of useful features in
+the build system.
 
 ### Build Types
 
@@ -131,32 +132,39 @@ We support and test the following `CMAKE_BUILD_TYPE` options.
 Note that optimized release builds are compiled with link-time optimization,
 which can make profiling more challenging ...
 
+### Constrained block size builds
+
+All normal builds will support all ASTC block sizes, including the worst case
+6x6x6 3D block size (216 texels per block). Compressor memory footprint and
+performance can be improved by limiting the block sizes supported in the build
+by adding `-DBLOCK_MAX_TEXELS=<texel_count>` to to CMake command line when
+configuring. Legal block sizes that are unavailable in a restricted build will
+return the error `ASTCENC_ERR_NOT_IMPLEMENTED` during context creation.
+
+### Non-invariant builds
+
+All normal builds are designed to be invariant, so any build from the same git
+revision will produce bit-identical results for all compilers and CPU
+architectures. To achieve this we sacrifice some performance, so if this is
+not required you can specify `-DNO_INVARIANCE=ON` to enable additional
+optimizations.
+
 ### No intrinsics builds
 
 All normal builds will use SIMD accelerated code paths using intrinsics, as all
-target architectures (x86-64 and aarch64) guarantee SIMD availability. For
+supported target architectures (x86 and arm64) guarantee SIMD availability. For
 development purposes it is possible to build an intrinsic-free build which uses
 no explicit SIMD acceleration (the compiler may still auto-vectorize).
 
 To enable this binary variant add `-DISA_NONE=ON` to the CMake command line
 when configuring. It is NOT recommended to use this for production; it is
 significantly slower than the vectorized SIMD builds.
 
-### Constrained block sizebuilds
+### Test builds
 
-All normal builds will support all ASTC block sizes, including the worst case
-6x6x6 3D block size (216 texels per block). Compressor memory footprint and
-performance can be improved by limiting the block sizes supported in the build
-by adding `-DBLOCK_MAX_TEXELS=<texel_count>` to to CMake command line when
-configuring. Legal block sizes that are unavailable in a restricted build will
-return the error `ASTCENC_ERR_NOT_IMPLEMENTED` during context creation.
-
-### Testing
-
-We support building unit tests.
-
-These builds use the `googletest` framework, which is pulled in though a git
-submodule. On first use, you must fetch the submodule dependency:
+We support building unit tests. These use the `googletest` framework, which is
+pulled in though a git submodule. On first use, you must fetch the submodule
+dependency:
 
 ```shell
 git submodule init
@@ -174,7 +182,13 @@ cd build
 ctest --verbose
 ```
 
-### Packaging
+### Address sanitizer builds
+
+We support building with ASAN on Linux and macOS when using a compiler that
+supports it. To build binaries with ASAN checking enabled add `-DASAN=ON` to
+the CMake command line when configuring.
+
+## Packaging a release bundle
 
 We support building a release bundle of all enabled binary configurations in
 the current CMake configuration using the `package` build target

Source/cmake_core.cmake

@@ -142,7 +142,7 @@ macro(astcenc_set_properties NAME)
             # Use pthreads on Linux/macOS
             $<$<PLATFORM_ID:Linux,Darwin>:-pthread>)
 
-    if(${ENABLE_ASAN})
+    if(${ASAN})
         target_compile_options(${NAME}
             PRIVATE
                 $<$<CXX_COMPILER_ID:${CLANG_LIKE}>:-fsanitize=address>)
@@ -152,7 +152,7 @@ macro(astcenc_set_properties NAME)
                 $<$<CXX_COMPILER_ID:${CLANG_LIKE}>:-fsanitize=address>)
     endif()
 
-    if(${ENABLE_NO_INVARIANCE})
+    if(${NO_INVARIANCE})
             target_compile_definitions(${NAME}
                 PRIVATE
                     ASTCENC_NO_INVARIANCE=1)

Test/astc_test_image.py

@@ -301,9 +301,9 @@ def parse_command_line():
                  "ref-main-neon", "ref-main-sse2", "ref-main-sse4.1", "ref-main-avx2"]
 
     # All test encoders
-    testcoders = ["none", "neon", "sse2", "sse4.1", "avx2"]
-    testcodersAArch64 = ["none", "neon"]
-    testcodersX86 = ["none", "sse2", "sse4.1", "avx2"]
+    testcoders = ["none", "neon", "sse2", "sse4.1", "avx2", "native"]
+    testcodersAArch64 = ["none", "neon", "native"]
+    testcodersX86 = ["none", "sse2", "sse4.1", "avx2", "native"]
 
     coders = refcoders + testcoders + ["all-aarch64", "all-x86"]