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 Media libraries
  35 ---------------
  36
  37 libav
  38 .....
  39
  40   `libav.org <https://libav.org/>`_, open source audio and video processing
  41   tools.
  42
  43 If all of the following libraries are found, they will be used to compile
  44 ``aubio_source_avcodec``. so that ``aubio_source`` will be able to decode audio
  45 from all formats supported by `libav
  46 <https://libav.org/documentation/general.html#Audio-Codecs>`_.
  47
  48 * libavcodec
  49 * libavformat
  50 * libavutil
  51 * libavresample
  52
  53 To enable this option, configure with ``--enable-avcodec``. The build will then
  54 failed if the required libraries are not found. To disable this option,
  55 configure with ``--disable-avcodec``
  56
  57
  58 libsndfile
  59 ..........
  60
  61   `libsndfile <http://www.mega-nerd.com/libsndfile/>`_, a C library for reading
  62   and writing sampled sound files.
  63
  64 With libsndfile built in, ``aubio_source_sndfile`` will be built in and used by
  65 ``aubio_source``.
  66
  67 To enable this option, configure with ``--enable-sndfile``. The build will then
  68 fail if the required library is not found. To disable this option, configure
  69 with ``--disable-sndfile``
  70
  71 libsamplerate
  72 .............
  73
  74   `libsamplerate <http://www.mega-nerd.com/SRC/>`_, a sample rate converter for
  75   audio.
  76
  77 With libsamplerate built in, ``aubio_source_sndfile`` will support resampling,
  78 and ``aubio_resample`` will be fully functional.
  79
  80 To enable this option, configure with ``--enable-samplerate``. The build will
  81 then fail if the required library is not found. To disable this option,
  82 configure with ``--disable-samplerate``
  83
  84 Optimisation libraries
  85 ----------------------
  86
  87 libfftw3
  88 ........
  89
  90   `FFTW <http://fftw.org/>`_, a C subroutine for computing the discrete Fourier
  91   transform
  92
  93 With libfftw3 built in, ``aubio_fft`` will use `FFTW`_ to
  94 compute Fast Fourier Transform (FFT), allowing aubio to compute FFT on length
  95 that are not a power of 2.
  96
  97 To enable this option, configure with ``--enable-fftw3``. The build will
  98 then fail if the required library is not found. To disable this option,
  99 configure with ``--disable-fftw3``
 100
 101 blas
 102 ....
 103
 104 On macOs/iOS, `blas
 105 <https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms>`_ are made
 106 available through the Accelerate framework.
 107
 108 On Linux, they can be enabled with ``--enable-blas``.  On Debian (etch),
 109 `atlas`_, `openblas`_, and `libblas`_ have been successfully tested.
 110
 111 When enabled, ``waf`` will check for the current blas configuration by running
 112 ``pkg-config --libs blas``. Depending of the library path returned by
 113 ``pkg-config``, different headers will be searched for.
 114
 115 .. note::
 116
 117     On Debian systems, `multiple versions of BLAS and LAPACK
 118     <https://wiki.debian.org/DebianScience/LinearAlgebraLibraries>`_ can be
 119     installed. To configure which libblas is being used:
 120
 121     .. code-block:: console
 122
 123       $ sudo update-alternatives --config libblas.so
 124
 125 ..
 126   Expected pkg-config output for each alternative:
 127     /usr/lib/atlas-base/atlas/libblas.so
 128     -L/usr/lib/atlas-base/atlas -lblas
 129     /usr/lib/openblas-base/libblas.so
 130     -L/usr/lib/openblas-base -lblas
 131     /usr/lib/libblas/libblas.so
 132     -lblas
 133
 134 atlas
 135 .....
 136
 137 `ATLAS BLAS APIs <http://math-atlas.sourceforge.net/>`_ will be used the path
 138 returned by ``pkg-config --libs blas`` contains ``atlas``.
 139
 140 ..
 141   ``<atlas/cblas.h>`` will be included.
 142
 143 Example:
 144
 145 .. code-block:: console
 146
 147   $ pkg-config --libs blas
 148   -L/usr/lib/atlas-base/atlas -lblas
 149   $ ./waf configure --enable-atlas
 150   [...]
 151   Checking for 'blas'                      : yes
 152   Checking for header atlas/cblas.h        : yes
 153
 154 openblas
 155 ........
 156
 157 `OpenBlas libraries <https://www.openblas.net/>`_ will be used when the output
 158 of ``pkg-config --libs blas`` contains 'openblas',
 159
 160 ..
 161   ``<openblas/cblas.h>`` will be included.
 162
 163 Example:
 164
 165 .. code-block:: console
 166
 167   $ pkg-config --libs blas
 168   -L/usr/lib/openblas-base -lblas
 169   $ ./waf configure --enable-atlas
 170   [...]
 171   Checking for 'blas'                      : yes
 172   Checking for header openblas/cblas.h     : yes
 173
 174 libblas
 175 .......
 176
 177 `Netlib's libblas (LAPACK) <https://www.netlib.org/lapack/>`_ will be used if
 178 no specific library path is specified by ``pkg-config``
 179
 180 ..
 181   ``<cblas.h>`` will be included.
 182
 183 Example:
 184
 185 .. code-block:: console
 186
 187   $ pkg-config --libs blas
 188   -lblas
 189   $ ./waf configure --enable-atlas
 190   [...]
 191   Checking for 'blas'                      : yes
 192   Checking for header cblas.h              : yes
 193
 194
 195 Platform notes
 196 --------------
 197
 198 On all platforms, you will need to have installed:
 199
 200  - a compiler (gcc, clang, msvc, ...)
 201  - python (any version >= 2.7, including 3.x)
 202  - a terminal to run command lines in
 203
 204 Linux
 205 .....
 206
 207 The following `External libraries`_ will be used if found: `libav`_,
 208 `libsamplerate`_, `libsndfile`_, `libfftw3`_.
 209
 210 macOS
 211 .....
 212
 213 The following system frameworks will be used on Mac OS X systems:
 214
 215   - `Accelerate <https://developer.apple.com/reference/accelerate>`_ to compute
 216     FFTs and other vectorized operations optimally.
 217
 218   - `CoreAudio <https://developer.apple.com/reference/coreaudio>`_ and
 219     `AudioToolbox <https://developer.apple.com/reference/audiotoolbox>`_ to
 220     decode audio from files and network streams.
 221
 222 .. note::
 223
 224   To build a fat binary for both ``i386`` and ``x86_64``, use ``./waf configure
 225   --enable-fat``.
 226
 227 The following `External libraries`_ will also be checked: `libav`_,
 228 `libsamplerate`_, `libsndfile`_, `libfftw3`_.
 229
 230 To build a fat binary on a darwin like system (macOS, tvOS, appleOS, ...)
 231 platforms, configure with ``--enable-fat``.
 232
 233 Windows
 234 .......
 235
 236 To use a specific version of the compiler, ``--msvc_version``. To build for a
 237 specific architecture, use ``--msvc_target``. For instance, to build aubio
 238 for ``x86`` using ``msvc 12.0``, use:
 239
 240 .. code:: bash
 241
 242     waf configure --msvc_version='msvc 12.0' --msvc_target='x86'
 243
 244
 245 The following `External libraries`_ will be used if found: `libav`_,
 246 `libsamplerate`_, `libsndfile`_, `libfftw3`_.
 247
 248 iOS
 249 ...
 250
 251 The following system frameworks will be used on iOS and iOS Simulator.
 252
 253   - `Accelerate <https://developer.apple.com/reference/accelerate>`_ to compute
 254     FFTs and other vectorized operations optimally.
 255
 256   - `CoreAudio <https://developer.apple.com/reference/coreaudio>`_ and
 257     `AudioToolbox <https://developer.apple.com/reference/audiotoolbox>`_ to
 258     decode audio from files and network streams.
 259
 260 To build aubio for iOS, configure with ``--with-target-platform=ios``. For the
 261 iOS Simulator, use ``--with-target-platform=iosimulator`` instead.
 262
 263 By default, aubio is built with the following flags on iOS:
 264
 265 .. code:: bash
 266
 267     CFLAGS="-fembed-bitcode -arch arm64 -arch armv7 -arch armv7s -miphoneos-version-min=6.1"
 268
 269 and on iOS Simulator:
 270
 271 .. code::
 272
 273     CFLAGS="-arch i386 -arch x86_64 -mios-simulator-version-min=6.1"
 274
 275 Set ``CFLAGS`` and ``LINKFLAGS`` to change these default values, or edit
 276 ``wscript`` directly.
 277
 278 Other options
 279 -------------
 280
 281 Some additional options can be passed to the configure step. For the complete
 282 list of options, run:
 283
 284 .. code:: bash
 285
 286     $ ./waf --help
 287
 288 Here is an example of a custom command:
 289
 290 .. code:: bash
 291
 292     $ ./waf --verbose configure build install \
 293                 --enable-avcodec --enable-wavread --disable-wavwrite \
 294                 --enable-sndfile --enable-samplerate --enable-docs \
 295                 --destdir $PWD/build/destdir --testcmd="echo %s" \
 296                 --prefix=/opt --libdir=/opt/lib/multiarch \
 297                 --manpagesdir=/opt/share/man  \
 298                 uninstall clean distclean dist distcheck
 299
 300 .. _doubleprecision:
 301
 302 Double precision
 303 ................
 304
 305 The datatype used to store real numbers in aubio is named `smpl_t`. By default,
 306 `smpl_t` is defined as `float`, a `single-precision format
 307 <https://en.wikipedia.org/wiki/Single-precision_floating-point_format>`_
 308 (32-bit).  Some algorithms require a floating point representation with a
 309 higher precision, for instance to prevent arithmetic underflow in recursive
 310 filters.  In aubio, these special samples are named `lsmp_t` and defined as
 311 `double` by default (64-bit).
 312
 313 Sometimes it may be useful to compile aubio in `double-precision`, for instance
 314 to reproduce numerical results obtained with 64-bit routines. In this case,
 315 `smpl_t` will be defined as `double`.
 316
 317 The following table shows how `smpl_t` and `lsmp_t` are defined in single- and
 318 double-precision modes:
 319
 320 .. list-table:: Single and double-precision modes
 321    :align: center
 322
 323    * -
 324      - single
 325      - double
 326    * - `smpl_t`
 327      - ``float``
 328      - ``double``
 329    * - `lsmp_t`
 330      - ``double``
 331      - ``long double``
 332
 333 To compile aubio in double precision mode, configure with ``--enable-double``.
 334
 335 To compile in single-precision mode (default), use ``--disable-double`` (or
 336 simply none of these two options).
 337
 338 Disabling the tests
 339 ...................
 340
 341 In some case, for instance when cross-compiling, unit tests should not be run.
 342 Option ``--notests`` can be used for this purpose. The tests will not be
 343 executed, but the binaries will be compiled, ensuring that linking against
 344 libaubio works as expected.
 345
 346 .. note::
 347
 348   The ``--notests`` option should be passed to both ``build`` and ``install``
 349   targets, otherwise waf will try to run them.
 350
 351 Edit wscript
 352 ............
 353
 354 Many of the options are gathered in the file `wscript`. a good starting point
 355 when looking for additional options.
 356
 357 .. _build_docs:
 358
 359 Building the docs
 360 -----------------
 361
 362 If the following command line tools are found, the documentation will be built
 363 built:
 364
 365  - `doxygen <http://doxygen.org>`_ to build the :ref:`doxygen-documentation`.
 366  - `txt2man <https://github.com/mvertes/txt2man>`_ to build the :ref:`manpages`
 367  - `sphinx <http://sphinx-doc.org>`_ to build this document
 368
 369 These tools are searched for in the current ``PATH`` environment variable.
 370 By default, the documentation is built only if the tools are found.
 371
 372 To disable the documentation, configure with ``--disable-docs``. To build with
 373 the documentation, configure with ``--enable-docs``.