source:
doc/requirements.rst
@
88b301a
Last change on this file since 88b301a was 8924bdf, checked in by , 6 years ago | |
---|---|
|
|
File size: 10.6 KB |
Build options
If built without any external dependencies aubio can be somewhat useful, for instance to read, process, and write simple wav files.
To support more media input formats and add more features to aubio, you can use one or all of the following external libraries.
You may also want to know more about the other options and the platform notes
The configure script will automatically for these extra libraries. To make sure the library or feature is used, pass the --enable-flag to waf. To disable this feature, use --disable-feature.
To find out more about the build commands, use the --verbose option.
External libraries
External libraries are checked for using pkg-config. Set the PKG_CONFIG_PATH environment variable if you have them installed in an unusual location.
Note
If pkg-config is not found in PATH, the configure step will succeed, but none of the external libraries will be used.
Media libraries
libav
libav.org, open source audio and video processing tools.
If all of the following libraries are found, they will be used to compile aubio_source_avcodec. so that aubio_source will be able to decode audio from all formats supported by libav.
- libavcodec
- libavformat
- libavutil
- libavresample
To enable this option, configure with --enable-avcodec. The build will then failed if the required libraries are not found. To disable this option, configure with --disable-avcodec
libsndfile
libsndfile, a C library for reading and writing sampled sound files.
With libsndfile built in, aubio_source_sndfile will be built in and used by aubio_source.
To enable this option, configure with --enable-sndfile. The build will then fail if the required library is not found. To disable this option, configure with --disable-sndfile
libsamplerate
libsamplerate, a sample rate converter for audio.
With libsamplerate built in, aubio_source_sndfile will support resampling, and aubio_resample will be fully functional.
To enable this option, configure with --enable-samplerate. The build will then fail if the required library is not found. To disable this option, configure with --disable-samplerate
Optimisation libraries
libfftw3
FFTW, a C subroutine for computing the discrete Fourier transform
With libfftw3 built in, aubio_fft will use FFTW to compute Fast Fourier Transform (FFT), allowing aubio to compute FFT on length that are not a power of 2.
To enable this option, configure with --enable-fftw3. The build will then fail if the required library is not found. To disable this option, configure with --disable-fftw3
blas
On macOs/iOS, blas are made available through the Accelerate framework.
On Linux, they can be enabled with --enable-blas. On Debian (etch), atlas, openblas, and libblas have been successfully tested.
When enabled, waf will check for the current blas configuration by running pkg-config --libs blas. Depending of the library path returned by pkg-config, different headers will be searched for.
Note
On Debian systems, multiple versions of BLAS and LAPACK can be installed. To configure which libblas is being used:
$ sudo update-alternatives --config libblas.so
atlas
ATLAS BLAS APIs will be used the path returned by pkg-config --libs blas contains atlas.
Example:
$ pkg-config --libs blas -L/usr/lib/atlas-base/atlas -lblas $ ./waf configure --enable-atlas [...] Checking for 'blas' : yes Checking for header atlas/cblas.h : yes
openblas
OpenBlas libraries will be used when the output of pkg-config --libs blas contains 'openblas',
Example:
$ pkg-config --libs blas -L/usr/lib/openblas-base -lblas $ ./waf configure --enable-atlas [...] Checking for 'blas' : yes Checking for header openblas/cblas.h : yes
libblas
Netlib's libblas (LAPACK) will be used if no specific library path is specified by pkg-config
Example:
$ pkg-config --libs blas -lblas $ ./waf configure --enable-atlas [...] Checking for 'blas' : yes Checking for header cblas.h : yes
Platform notes
On all platforms, you will need to have installed:
- a compiler (gcc, clang, msvc, ...)
- python (any version >= 2.7, including 3.x)
- a terminal to run command lines in
Linux
The following External libraries will be used if found: libav, libsamplerate, libsndfile, libfftw3.
macOS
The following system frameworks will be used on Mac OS X systems:
- Accelerate to compute FFTs and other vectorized operations optimally.
- CoreAudio and AudioToolbox to decode audio from files and network streams.
Note
To build a fat binary for both i386 and x86_64, use ./waf configure --enable-fat.
The following External libraries will also be checked: libav, libsamplerate, libsndfile, libfftw3.
To build a fat binary on a darwin like system (macOS, tvOS, appleOS, ...) platforms, configure with --enable-fat.
Windows
To use a specific version of the compiler, --msvc_version. To build for a specific architecture, use --msvc_target. For instance, to build aubio for x86 using msvc 12.0, use:
waf configure --msvc_version='msvc 12.0' --msvc_target='x86'
The following External libraries will be used if found: libav, libsamplerate, libsndfile, libfftw3.
iOS
The following system frameworks will be used on iOS and iOS Simulator.
- Accelerate to compute FFTs and other vectorized operations optimally.
- CoreAudio and AudioToolbox to decode audio from files and network streams.
To build aubio for iOS, configure with --with-target-platform=ios. For the iOS Simulator, use --with-target-platform=iosimulator instead.
By default, aubio is built with the following flags on iOS:
CFLAGS="-fembed-bitcode -arch arm64 -arch armv7 -arch armv7s -miphoneos-version-min=6.1"
and on iOS Simulator:
CFLAGS="-arch i386 -arch x86_64 -mios-simulator-version-min=6.1"
Set CFLAGS and LINKFLAGS to change these default values, or edit wscript directly.
Other options
Some additional options can be passed to the configure step. For the complete list of options, run:
$ ./waf --help
Here is an example of a custom command:
$ ./waf --verbose configure build install \ --enable-avcodec --enable-wavread --disable-wavwrite \ --enable-sndfile --enable-samplerate --enable-docs \ --destdir $PWD/build/destdir --testcmd="echo %s" \ --prefix=/opt --libdir=/opt/lib/multiarch \ --manpagesdir=/opt/share/man \ uninstall clean distclean dist distcheck
Double precision
The datatype used to store real numbers in aubio is named smpl_t. By default, smpl_t is defined as float, a single-precision format (32-bit). Some algorithms require a floating point representation with a higher precision, for instance to prevent arithmetic underflow in recursive filters. In aubio, these special samples are named lsmp_t and defined as double by default (64-bit).
Sometimes it may be useful to compile aubio in double-precision, for instance to reproduce numerical results obtained with 64-bit routines. In this case, smpl_t will be defined as double.
The following table shows how smpl_t and lsmp_t are defined in single- and double-precision modes:
single | double | |
smpl_t | float | double |
lsmp_t | double | long double |
To compile aubio in double precision mode, configure with --enable-double.
To compile in single-precision mode (default), use --disable-double (or simply none of these two options).
Disabling the tests
In some case, for instance when cross-compiling, unit tests should not be run. Option --notests can be used for this purpose. The tests will not be executed, but the binaries will be compiled, ensuring that linking against libaubio works as expected.
Note
The --notests option should be passed to both build and install targets, otherwise waf will try to run them.
Edit wscript
Many of the options are gathered in the file wscript. a good starting point when looking for additional options.
Building the docs
If the following command line tools are found, the documentation will be built built:
doxygen to build the :ref:`doxygen-documentation`.
txt2man to build the :ref:`manpages`
sphinx to build this document
These tools are searched for in the current PATH environment variable. By default, the documentation is built only if the tools are found.
To disable the documentation, configure with --disable-docs. To build with the documentation, configure with --enable-docs.