doc/requirements.rst

   1 .. _requirements:
   2
   3 Build options
   4 =============
   5
   6 If built without any external dependencies aubio can be somewhat useful, for
   7 instance to read, process, and write simple wav files.
   8
   9 To support more media input formats and add more features to aubio, you can use
  10 one or all of the following `external libraries`_.
  11
  12 You may also want to know more about the `other options`_ and the `platform
  13 notes`_
  14
  15 The configure script will automatically for these extra libraries. To make sure
  16 the library or feature is used, pass the `--enable-flag` to waf. To disable
  17 this feature, use `--disable-feature`.
  18
  19 To find out more about the build commands, use the `--verbose` option.
  20
  21 External libraries
  22 ------------------
  23
  24 External libraries are checked for using ``pkg-config``. Set the
  25 ``PKG_CONFIG_PATH`` environment variable if you have them installed in an
  26 unusual location.
  27
  28
  29 .. note::
  30
  31     If ``pkg-config`` is not found in ``PATH``, the configure step will
  32     succeed, but none of the external libraries will be used.
  33
  34 libav
  35 .....
  36
  37   `libav.org <https://libav.org/>`_, open source audio and video processing
  38   tools.
  39
  40 If all of the following libraries are found, they will be used to compile
  41 ``aubio_source_avcodec``. so that ``aubio_source`` will be able to decode audio
  42 from all formats supported by `libav
  43 <https://libav.org/documentation/general.html#Audio-Codecs>`_.
  44
  45 * libavcodec
  46 * libavformat
  47 * libavutil
  48 * libavresample
  49
  50 To enable this option, configure with ``--enable-avcodec``. The build will then
  51 failed if the required libraries are not found. To disable this option,
  52 configure with ``--disable-avcodec``
  53
  54
  55 libsndfile
  56 ..........
  57
  58   `libsndfile <http://www.mega-nerd.com/libsndfile/>`_, a C library for reading
  59   and writing sampled sound files.
  60
  61 With libsndfile built in, ``aubio_source_sndfile`` will be built in and used by
  62 ``aubio_source``.
  63
  64 To enable this option, configure with ``--enable-sndfile``. The build will then
  65 fail if the required library is not found. To disable this option, configure
  66 with ``--disable-sndfile``
  67
  68 libsamplerate
  69 .............
  70
  71   `libsamplerate <http://www.mega-nerd.com/SRC/>`_, a sample rate converter for
  72   audio.
  73
  74 With libsamplerate built in, ``aubio_source_sndfile`` will support resampling,
  75 and ``aubio_resample`` will be fully functional.
  76
  77 To enable this option, configure with ``--enable-samplerate``. The build will
  78 then fail if the required library is not found. To disable this option,
  79 configure with ``--disable-samplerate``
  80
  81 libfftw3
  82 ........
  83
  84   `FFTW <http://fftw.org/>`_, a C subroutine for computing the discrete Fourier
  85   transform
  86
  87 With libfftw3 built in, ``aubio_fft`` will use `FFTW`_ to
  88 compute Fast Fourier Transform (FFT), allowing aubio to compute FFT on length
  89 that are not a power of 2.
  90
  91 To enable this option, configure with ``--enable-fftw3``. The build will
  92 then fail if the required library is not found. To disable this option,
  93 configure with ``--disable-fftw3``
  94
  95 Platform notes
  96 --------------
  97
  98 On all platforms, you will need to have installed:
  99
 100  - a compiler (gcc, clang, msvc, ...)
 101  - python (any version >= 2.7, including 3.x)
 102  - a terminal to run command lines in
 103
 104 Linux
 105 .....
 106
 107 The following `External libraries`_ will be used if found: `libav`_,
 108 `libsamplerate`_, `libsndfile`_, `libfftw3`_.
 109
 110 macOS
 111 .....
 112
 113 The following system frameworks will be used on Mac OS X systems:
 114
 115   - `Accelerate <https://developer.apple.com/reference/accelerate>`_ to compute
 116     FFTs and other vectorized operations optimally.
 117
 118   - `CoreAudio <https://developer.apple.com/reference/coreaudio>`_ and
 119     `AudioToolbox <https://developer.apple.com/reference/audiotoolbox>`_ to
 120     decode audio from files and network streams.
 121
 122 .. note::
 123
 124   To build a fat binary for both ``i386`` and ``x86_64``, use ``./waf configure
 125   --enable-fat``.
 126
 127 The following `External libraries`_ will also be checked: `libav`_,
 128 `libsamplerate`_, `libsndfile`_, `libfftw3`_.
 129
 130 To build a fat binary on a darwin like system (macOS, tvOS, appleOS, ...)
 131 platforms, configure with ``--enable-fat``.
 132
 133 Windows
 134 .......
 135
 136 To use a specific version of the compiler, ``--msvc_version``. To build for a
 137 specific architecture, use ``--msvc_target``. For instance, to build aubio
 138 for ``x86`` using ``msvc 12.0``, use:
 139
 140 .. code:: bash
 141
 142     waf configure --msvc_version='msvc 12.0' --msvc_target='x86'
 143
 144
 145 The following `External libraries`_ will be used if found: `libav`_,
 146 `libsamplerate`_, `libsndfile`_, `libfftw3`_.
 147
 148 iOS
 149 ...
 150
 151 The following system frameworks will be used on iOS and iOS Simulator.
 152
 153   - `Accelerate <https://developer.apple.com/reference/accelerate>`_ to compute
 154     FFTs and other vectorized operations optimally.
 155
 156   - `CoreAudio <https://developer.apple.com/reference/coreaudio>`_ and
 157     `AudioToolbox <https://developer.apple.com/reference/audiotoolbox>`_ to
 158     decode audio from files and network streams.
 159
 160 To build aubio for iOS, configure with ``--with-target-platform=ios``. For the
 161 iOS Simulator, use ``--with-target-platform=iosimulator`` instead.
 162
 163 By default, aubio is built with the following flags on iOS:
 164
 165 .. code:: bash
 166
 167     CFLAGS="-fembed-bitcode -arch arm64 -arch armv7 -arch armv7s -miphoneos-version-min=6.1"
 168
 169 and on iOS Simulator:
 170
 171 .. code::
 172
 173     CFLAGS="-arch i386 -arch x86_64 -mios-simulator-version-min=6.1"
 174
 175 Set ``CFLAGS`` and ``LINKFLAGS`` to change these default values, or edit
 176 ``wscript`` directly.
 177
 178 Other options
 179 -------------
 180
 181 Some additional options can be passed to the configure step. For the complete
 182 list of options, run:
 183
 184 .. code:: bash
 185
 186     $ ./waf --help
 187
 188 Here is an example of a custom command:
 189
 190 .. code:: bash
 191
 192     $ ./waf --verbose configure build install \
 193                 --enable-avcodec --enable-wavread --disable-wavwrite \
 194                 --enable-sndfile --enable-samplerate --enable-docs \
 195                 --destdir $PWD/build/destdir --testcmd="echo %s" \
 196                 --prefix=/opt --libdir=/opt/lib/multiarch \
 197                 --manpagesdir=/opt/share/man  \
 198                 uninstall clean distclean dist distcheck
 199
 200 Double precision
 201 ................
 202
 203 To compile aubio in double precision mode, configure with ``--enable-double``.
 204
 205 To compile aubio in single precision mode, use ``--disable-double`` (default).
 206
 207 Disabling the tests
 208 ...................
 209
 210 In some case, for instance when cross-compiling, unit tests should not be run.
 211 Option ``--notests`` can be used for this purpose. The tests will not be
 212 executed, but the binaries will be compiled, ensuring that linking against
 213 libaubio works as expected.
 214
 215 .. note::
 216
 217   The ``--notests`` option should be passed to both ``build`` and ``install``
 218   targets, otherwise waf will try to run them.
 219
 220 Edit wscript
 221 ............
 222
 223 Many of the options are gathered in the file `wscript`. a good starting point
 224 when looking for additional options.
 225
 226 .. _build_docs:
 227
 228 Building the docs
 229 -----------------
 230
 231 If the following command line tools are found, the documentation will be built
 232 built:
 233
 234  - `doxygen <http://doxygen.org>`_ to build the :ref:`doxygen-documentation`.
 235  - `txt2man <https://github.com/mvertes/txt2man>`_ to build the :ref:`manpages`
 236  - `sphinx <http://sphinx-doc.org>`_ to build this document
 237
 238 These tools are searched for in the current ``PATH`` environment variable.
 239 By default, the documentation is built only if the tools are found.
 240
 241 To disable the documentation, configure with ``--disable-docs``. To build with
 242 the documentation, configure with ``--enable-docs``.