soxr-code/INSTALL

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
* SIMD



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: http://www.cmake.org/cmake/resources/software.html


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
    adminstrator.  Enter:

        nmake install               (on MS-Windows)
    or
        cd Release; make install    (on unix-like)


4. Configuration:

    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 ..



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



SIMD

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.

Example #3 can be used to determine the result of the selection on a particular
system.  E.g. (on unix-like):

    $ ./3-options-input-fn < /dev/null
    ./3-options-input-fn       no error; 0 clips; I/O: no error (single-precision-SIMD)