186 lines
5.3 KiB
Plaintext
186 lines
5.3 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: 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 may be
|
||
substituted as follows. Change directory to the one containing this file,
|
||
then enter commands along the lines of:
|
||
|
||
mkdir build
|
||
cd build
|
||
cmake [OPTIONS] ..
|
||
make
|
||
make test
|
||
sudo make install
|
||
|
||
To list help on the available options, enter:
|
||
|
||
cmake -LH ..
|
||
|
||
Options, if given, should be preceded with '-D', e.g.
|
||
|
||
cmake -DWITH_SIMD:BOOL=OFF ..
|
||
|
||
|
||
|
||
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:
|
||
|
||
mkdir build
|
||
cd build
|
||
cmake -DCMAKE_SYSTEM_NAME=Linux \
|
||
-DCMAKE_C_COMPILER=arm-linux-gnueabi-gcc-5 \
|
||
..
|
||
or, also building the examples (one of which uses C++):
|
||
|
||
cmake -DCMAKE_SYSTEM_NAME=Linux \
|
||
-DCMAKE_C_COMPILER=arm-linux-gnueabi-gcc-5 \
|
||
-DCMAKE_CXX_COMPILER=arm-linux-gnueabi-g++-5 \
|
||
-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.
|
||
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:
|
||
|
||
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
|
||
|
||
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.)
|