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 formas add more features to aubio, you can use one
  10 or all of the `following libraries <extlibs>`_.
  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 Edit wscript
 208 ............
 209
 210 Many of the options are gathered in the file `wscript`. a good starting point
 211 when looking for additional options.
 212
 213 .. _build_docs:
 214
 215 Building the docs
 216 -----------------
 217
 218 If the following command line tools are found, the documentation will be built
 219 built:
 220
 221  - `doxygen <http://doxygen.org>`_ to build the :ref:`doxygen-documentation`.
 222  - `txt2man <https://github.com/mvertes/txt2man>`_ to build the :ref:`manpages`
 223  - `sphinx <http://sphinx-doc.org>`_ to build this document
 224
 225 These tools are searched for in the current ``PATH`` environment variable.
 226 By default, the documentation is built only if the tools are found.
 227
 228 To disable the documentation, configure with ``--disable-docs``. To build with
 229 the documentation, configure with ``--enable-docs``.