doc update; make an lsr-test conditional as appropriate

INSTALL

@@ -6,7 +6,7 @@ INSTALLATION GUIDE CONTENTS
 * Build customisation
 * Cross-compilation
 * Integration with other build systems
-* SIMD
+* Run-time configuration
 
 
 
@@ -21,7 +21,7 @@ STANDARD BUILD
 
     * A 'make' utility (most compiler installations already have one of these).
 
-    * CMake: http://www.cmake.org/cmake/resources/software.html
+    * CMake: https://cmake.org/download/
 
 
 2. Build:
@@ -31,7 +31,7 @@ STANDARD BUILD
 
         go                          (on MS-Windows with nmake)
     or
-        ./go                        (on unix-like systems)
+        ./go                        (on Unix-like systems)
 
     This should build the library and run a few sanity tests.
 
@@ -39,14 +39,14 @@ STANDARD BUILD
 3. Installation:
 
     Note that this step may need to be performed by a system
-    adminstrator.  Enter:
+    administrator.  Enter:
 
         nmake install               (on MS-Windows)
     or
-        cd Release; make install    (on unix-like)
+        cd Release; make install    (on Unix-like)
 
 
-4. Configuration:
+4. Preparation for use:
 
     To use the library you may need to set up appropriate paths to the
     library and its header file in your development environment.
@@ -82,6 +82,31 @@ Options, if given, should be preceded with '-D', e.g.
 
 
 
+Resampling engines
+
+As available on a given system, the library may include up to four resampling
+‘engines’, as follows:
+
+    cr32: for constant-rate resampling with precision up to 20 bits,
+    cr32s: SIMD variant of cr32,
+    cr64: for constant-rate resampling with precision greater than 20 bits,
+    vr32: for variable-rate resampling.
+
+Engine inclusion is controlled (as above) by the following cmake option
+variables:
+
+    cr32: WITH_SINGLE_PRECISION
+    cr32s: WITH_SINGLE_PRECISION, WITH_SIMD
+    cr32: WITH_DOUBLE_PRECISION
+
+By default, these variables are all set to ON.
+
+When both cr32 and cr32s engines are included, run-time selection is automatic
+(based on CPU capability) for x86 CPUs, and can be automatic for ARM CPUs if
+the 3rd-party library `libavutil' is available at libsoxr build-time.
+
+
+
 CROSS-COMPILATION
 
 E.g. targeting a Linux ARM system:
@@ -130,23 +155,31 @@ INTEGRATION WITH OTHER BUILD SYSTEMS
 
 Autotools-based systems might find it useful to create a file called
 `configure' in the directory containing this file, consisting of the line:
-  cmake -DBUILD_SHARED_LIBS=OFF .
+    cmake -DBUILD_SHARED_LIBS=OFF .
 (or with other build options as required).
 
-For MS visual studio, see msvc/README
+For MS visual studio, see msvc/README.
 
 
 
-SIMD
+RUN-TIME CONFIGURATION
 
-A single build of the library can support both SIMD and non-SIMD variants of a
-particular CPU via run-time selection of which instruction-set to use.  The
-SOXR_USE_SIMD boolean environment provides manual selection; otherwise,
-selection is automatic for x86 CPUs, and can be automatic for ARM CPUs if the
-3rd-party library `libavutil' is available when libsoxr is built.
+The libsoxr API structure ‘soxr_runtime_spec_t’ allows application developers
+to optimise some aspects of libsoxr’s operation for a particular application.
+However, since optimal performance might depend on an individual end-user’s
+run-time system and the end-user’s preferences, environment variables are
+available to set (override) the run-time parameters:
 
-Example #3 can be used to determine the result of the selection on a particular
-system.  E.g. (on unix-like):
+    Env. variable        Equivalent soxr_runtime_spec_t item
+    ------------------   -----------------------------------
+    SOXR_COEFS_SIZE      coef_size_kbytes
+    SOXR_COEF_INTERP     SOXR_COEF_INTERP_xxx
+    SOXR_LARGE_DFT_SIZE  log2_large_dft_size
+    SOXR_MIN_DFT_SIZE    log2_min_dft_size
+    SOXR_NUM_THREADS     num_threads
 
-    $ ./3-options-input-fn < /dev/null
-    ./3-options-input-fn       no error; 0 clips; I/O: no error (single-precision-SIMD)
+Additionally, the SOXR_USE_SIMD environment variable may be used to override
+automatic selection (or to provide manual selection where automatic selection
+is not available) between the cr32 and cr32s resampling engines. (Which engine
+is selected for a specific configuration of libsoxr can be checked using
+example #3, which reports it.)

lsr-tests/CMakeLists.txt

@@ -34,7 +34,10 @@ enable_testing ()
 set (tests
   callback_hang_test callback_test downsample_test
   float_short_test misc_test multi_channel_test
-  reset_test simple_test snr_bw_test termination_test varispeed_test)
+  reset_test simple_test termination_test varispeed_test)
+if (WITH_DOUBLE_PRECISION)
+  set (tests ${tests} snr_bw_test)
+endif ()
 
 foreach (test ${tests})
   add_executable (${test} ${test})

src/rate32.c

@@ -5,5 +5,5 @@
 #define RATE_SIMD  0
 #define RDFT_CB    _soxr_rdft32_cb
 #define RATE_CB    _soxr_rate32_cb
-#define RATE_ID    "single-precision"
+#define RATE_ID    "cr32"
 #include "rate.h"

src/rate32s.c

@@ -5,5 +5,5 @@
 #define RATE_SIMD  1
 #define RDFT_CB    _soxr_rdft32s_cb
 #define RATE_CB    _soxr_rate32s_cb
-#define RATE_ID    "single-precision-SIMD"
+#define RATE_ID    "cr32s"
 #include "rate.h"

src/rate64.c

@@ -5,5 +5,5 @@
 #define RATE_SIMD  0
 #define RDFT_CB    _soxr_rdft64_cb
 #define RATE_CB    _soxr_rate64_cb
-#define RATE_ID    "double-precision"
+#define RATE_ID    "cr64"
 #include "rate.h"

src/vr32.c

@@ -639,7 +639,7 @@ static char const * vr_create(void * channel, void * shared,double max_io_ratio,
 
 static char const * vr_id(void)
 {
-  return "single-precision variable-rate";
+  return "vr32";
 }
 
 typedef void (* fn_t)(void);