184 lines
5.4 KiB
Plaintext
184 lines
5.4 KiB
Plaintext
SoX Resampler Library Copyright (c) 2007-16 robs@users.sourceforge.net
|
||
|
||
INSTALLATION GUIDE CONTENTS
|
||
|
||
* Standard build
|
||
* Build customisation
|
||
* Cross-compilation
|
||
* Integration with other build systems
|
||
* Run-time configuration
|
||
|
||
|
||
|
||
STANDARD BUILD
|
||
|
||
1. Prerequisites:
|
||
|
||
Before you can build this library, you need to have available on your
|
||
system:
|
||
|
||
* A C-compiler with 64-bit integer support and, optionally, OpenMP, SIMD.
|
||
|
||
* A 'make' utility (most compiler installations already have one of these).
|
||
|
||
* CMake v3.0 or newer: https://cmake.org/download/
|
||
|
||
|
||
2. Build:
|
||
|
||
At a command prompt, change directory (`cd') to the one containing this
|
||
file, then enter:
|
||
|
||
go (on MS-Windows with nmake)
|
||
or
|
||
./go (on Unix-like systems)
|
||
|
||
This should build the library and run a few sanity tests.
|
||
|
||
|
||
3. Installation:
|
||
|
||
Note that this step may need to be performed by a system
|
||
administrator. Enter:
|
||
|
||
nmake install (on MS-Windows)
|
||
or
|
||
cd Release; make install (on Unix-like)
|
||
|
||
|
||
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.
|
||
|
||
|
||
5. Installation test
|
||
|
||
To test the installation, build and run some of the example programmes
|
||
(see examples/README).
|
||
|
||
|
||
|
||
BUILD CUSTOMISATION
|
||
|
||
If it is necessary to customise the build, then steps 2 and 3 above should be
|
||
substituted as follows: change directory to the one containing this file, then
|
||
enter commands along the lines:
|
||
|
||
mkdir build
|
||
cd build
|
||
cmake -Wno-dev -DCMAKE_BUILD_TYPE=Release [OPTIONS] ..
|
||
make
|
||
make test
|
||
sudo make install
|
||
|
||
N.B. The CMAKE_BUILD_TYPE to use for library deployment is Release.
|
||
|
||
To list help on the available options, enter:
|
||
|
||
cmake -LH ..
|
||
|
||
Options, if given, should be preceded with '-D', e.g.
|
||
|
||
-DBUILD_SHARED_LIBS:BOOL=OFF
|
||
|
||
|
||
|
||
Resampling engines
|
||
|
||
As available on a given system, options for including up-to five resampling
|
||
‘engines’ are available (per above) as follows:
|
||
|
||
WITH_CR32: for constant-rate HQ resampling,
|
||
WITH_CR32S: SIMD variant of previous,
|
||
WITH_CR64: for constant-rate VHQ resampling,
|
||
WITH_CR64S: SIMD variant of previous,
|
||
WITH_VR32: for variable-rate HQ resampling.
|
||
|
||
By default, these options are all set to ON.
|
||
|
||
When both SIMD and non-SIMD engine variants 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. Which engine has been selected for a specific configuration and
|
||
invocation of the library can be checked using example #3, which reports it.
|
||
See also Run-time Configuration, below.
|
||
|
||
|
||
|
||
CROSS-COMPILATION
|
||
|
||
E.g. targeting a Linux ARM system:
|
||
|
||
mkdir build
|
||
cd build
|
||
cmake -DCMAKE_SYSTEM_NAME=Linux \
|
||
-DCMAKE_C_COMPILER=arm-linux-gnueabi-gcc \
|
||
..
|
||
or, also building the examples (one of which uses C++):
|
||
|
||
cmake -DCMAKE_SYSTEM_NAME=Linux \
|
||
-DCMAKE_C_COMPILER=arm-linux-gnueabi-gcc \
|
||
-DCMAKE_CXX_COMPILER=arm-linux-gnueabi-g++ \
|
||
-DBUILD_EXAMPLES=1 \
|
||
..
|
||
|
||
E.g. with Mingw (Linux host), using a tool-chain file:
|
||
|
||
mkdir build
|
||
cd build
|
||
cmake -DCMAKE_TOOLCHAIN_FILE=~/Toolchain-x86_64-mingw-w64-mingw32.cmake \
|
||
-DCMAKE_INSTALL_PREFIX=install \
|
||
..
|
||
make
|
||
|
||
where ~/Toolchain-x86_64-mingw-w64-mingw32.cmake might contain:
|
||
|
||
SET(CMAKE_SYSTEM_NAME Windows)
|
||
SET(CMAKE_C_COMPILER /usr/bin/x86_64-w64-mingw32-gcc)
|
||
SET(CMAKE_CXX_COMPILER /usr/bin/x86_64-w64-mingw32-g++)
|
||
SET(CMAKE_RC_COMPILER /usr/bin/x86_64-w64-mingw32-windres)
|
||
SET(CMAKE_Fortran_COMPILER /usr/bin/x86_64-w64-mingw32-gfortran)
|
||
SET(CMAKE_AR:FILEPATH /usr/bin/x86_64-w64-mingw32-ar)
|
||
SET(CMAKE_RANLIB:FILEPATH /usr/bin/x86_64-w64-mingw32-ranlib)
|
||
SET(CMAKE_FIND_ROOT_PATH /usr/x86_64-w64-mingw32)
|
||
SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
|
||
SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
|
||
SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
|
||
SET(QT_BINARY_DIR /usr/x86_64-w64-mingw32/bin /usr/bin)
|
||
SET(Boost_COMPILER -gcc47)
|
||
|
||
|
||
|
||
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 .
|
||
(or with other build options as required).
|
||
|
||
For MS Visual Studio, see msvc/README.
|
||
|
||
|
||
|
||
RUN-TIME CONFIGURATION
|
||
|
||
The libsoxr API structure ‘soxr_runtime_spec_t’ allows application developers
|
||
to optimise some aspects of libsoxr’s operation for a particular application.
|
||
Optimal performance however, might depend on an individual end-user’s run-
|
||
time system and the end-user’s preferences. Hence environment variables are
|
||
available to set (override) run-time parameters as follows:
|
||
|
||
Env. variable Equivalent soxr_runtime_spec_t item (see soxr.h)
|
||
------------------ -----------------------------------
|
||
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
|
||
|
||
Additionally, the SOXR_USE_SIMD32 and SOXR_USE_SIMD64 boolean environment
|
||
variables can be used to override automatic selection (or to provide manual
|
||
selection where automatic selection is not available) between SIMD and
|
||
non-SIMD engine variants.
|