source: doc/requirements.rst @ 46b065d1

feature/autosinkfeature/cnnfeature/cnn_orgfeature/constantqfeature/crepefeature/crepe_orgfeature/pitchshiftfeature/pydocstringsfeature/timestretchfix/ffmpeg5
Last change on this file since 46b065d1 was 46b065d1, checked in by Paul Brossier <piem@piem.org>, 6 years ago

doc/requirements.rst: add some blas documentation

  • Property mode set to 100644
File size: 9.6 KB
RevLine 
[5069da3]1.. _requirements:
2
[e15d7d0]3Build options
4=============
5
6If built without any external dependencies aubio can be somewhat useful, for
7instance to read, process, and write simple wav files.
8
[8f1b354]9To support more media input formats and add more features to aubio, you can use
10one or all of the following `external libraries`_.
[e15d7d0]11
12You may also want to know more about the `other options`_ and the `platform
13notes`_
14
15The configure script will automatically for these extra libraries. To make sure
16the library or feature is used, pass the `--enable-flag` to waf. To disable
17this feature, use `--disable-feature`.
18
19To find out more about the build commands, use the `--verbose` option.
[5069da3]20
[e15d7d0]21External libraries
22------------------
23
24External libraries are checked for using ``pkg-config``. Set the
25``PKG_CONFIG_PATH`` environment variable if you have them installed in an
26unusual 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
[b45af44]34Media libraries
35---------------
36
[e15d7d0]37libav
38.....
39
40  `libav.org <https://libav.org/>`_, open source audio and video processing
41  tools.
42
43If 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
45from all formats supported by `libav
46<https://libav.org/documentation/general.html#Audio-Codecs>`_.
47
48* libavcodec
49* libavformat
50* libavutil
51* libavresample
52
53To enable this option, configure with ``--enable-avcodec``. The build will then
54failed if the required libraries are not found. To disable this option,
55configure with ``--disable-avcodec``
56
57
58libsndfile
59..........
60
61  `libsndfile <http://www.mega-nerd.com/libsndfile/>`_, a C library for reading
62  and writing sampled sound files.
63
64With libsndfile built in, ``aubio_source_sndfile`` will be built in and used by
65``aubio_source``.
66
67To enable this option, configure with ``--enable-sndfile``. The build will then
68fail if the required library is not found. To disable this option, configure
69with ``--disable-sndfile``
70
71libsamplerate
72.............
73
74  `libsamplerate <http://www.mega-nerd.com/SRC/>`_, a sample rate converter for
75  audio.
76
77With libsamplerate built in, ``aubio_source_sndfile`` will support resampling,
78and ``aubio_resample`` will be fully functional.
79
80To enable this option, configure with ``--enable-samplerate``. The build will
81then fail if the required library is not found. To disable this option,
82configure with ``--disable-samplerate``
83
[b45af44]84Optimisation libraries
85----------------------
86
[e15d7d0]87libfftw3
88........
89
90  `FFTW <http://fftw.org/>`_, a C subroutine for computing the discrete Fourier
91  transform
92
93With libfftw3 built in, ``aubio_fft`` will use `FFTW`_ to
94compute Fast Fourier Transform (FFT), allowing aubio to compute FFT on length
95that are not a power of 2.
96
97To enable this option, configure with ``--enable-fftw3``. The build will
98then fail if the required library is not found. To disable this option,
99configure with ``--disable-fftw3``
[5069da3]100
[46b065d1]101blas
102....
103
104On macOs/iOS, `blas
105<https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms>`_ are made
106available through the Accelerate framework.
107
108On Linux, they can be enabled with ``--enable-blas``.  On Debian (etch),
109`atlas`_, `openblas`_, and `libblas`_ have been successfully tested.
110
111When 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
134atlas
135.....
136
137`ATLAS BLAS APIs <http://math-atlas.sourceforge.net/>`_ will be used the path
138returned by ``pkg-config --libs blas`` contains ``atlas``.
139
140..
141  ``<atlas/cblas.h>`` will be included.
142
143Example:
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
154openblas
155........
156
157`OpenBlas libraries <https://www.openblas.net/>`_ will be used when the output
158of ``pkg-config --libs blas`` contains 'openblas',
159
160..
161  ``<openblas/cblas.h>`` will be included.
162
163Example:
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
174libblas
175.......
176
177`Netlib's libblas (LAPACK) <https://www.netlib.org/lapack/>`_ will be used if
178no specific library path is specified by ``pkg-config``
179
180..
181  ``<cblas.h>`` will be included.
182
183Example:
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
[5069da3]195Platform notes
196--------------
197
[a9a1e79]198On 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
[5069da3]204Linux
205.....
206
207The following `External libraries`_ will be used if found: `libav`_,
208`libsamplerate`_, `libsndfile`_, `libfftw3`_.
209
210macOS
211.....
212
213The 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
227The following `External libraries`_ will also be checked: `libav`_,
228`libsamplerate`_, `libsndfile`_, `libfftw3`_.
229
[e15d7d0]230To build a fat binary on a darwin like system (macOS, tvOS, appleOS, ...)
231platforms, configure with ``--enable-fat``.
232
[5069da3]233Windows
234.......
235
[7b3668c]236To use a specific version of the compiler, ``--msvc_version``. To build for a
237specific architecture, use ``--msvc_target``. For instance, to build aubio
238for ``x86`` using ``msvc 12.0``, use:
239
240.. code:: bash
241
242    waf configure --msvc_version='msvc 12.0' --msvc_target='x86'
243
244
[5069da3]245The following `External libraries`_ will be used if found: `libav`_,
246`libsamplerate`_, `libsndfile`_, `libfftw3`_.
247
248iOS
249...
250
251The 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
260To build aubio for iOS, configure with ``--with-target-platform=ios``. For the
261iOS Simulator, use ``--with-target-platform=iosimulator`` instead.
262
263By 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
269and on iOS Simulator:
270
271.. code::
272
[6f29fe3]273    CFLAGS="-arch i386 -arch x86_64 -mios-simulator-version-min=6.1"
[5069da3]274
275Set ``CFLAGS`` and ``LINKFLAGS`` to change these default values, or edit
276``wscript`` directly.
277
[e15d7d0]278Other options
[5069da3]279-------------
280
[a9a1e79]281Some additional options can be passed to the configure step. For the complete
282list of options, run:
283
[385a9c1e]284.. code:: bash
285
[e15d7d0]286    $ ./waf --help
287
288Here 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
[5069da3]299
300Double precision
301................
302
303To compile aubio in double precision mode, configure with ``--enable-double``.
304
305To compile aubio in single precision mode, use ``--disable-double`` (default).
306
[9682d9d]307Disabling the tests
308...................
309
310In some case, for instance when cross-compiling, unit tests should not be run.
311Option ``--notests`` can be used for this purpose. The tests will not be
312executed, but the binaries will be compiled, ensuring that linking against
313libaubio works as expected.
314
315.. note::
316
317  The ``--notests`` option should be passed to both ``build`` and ``install``
318  targets, otherwise waf will try to run them.
319
[e15d7d0]320Edit wscript
321............
[5069da3]322
[e15d7d0]323Many of the options are gathered in the file `wscript`. a good starting point
324when looking for additional options.
[5069da3]325
[e15d7d0]326.. _build_docs:
[5069da3]327
[e15d7d0]328Building the docs
329-----------------
[5069da3]330
[e15d7d0]331If the following command line tools are found, the documentation will be built
332built:
[5069da3]333
[7a8a07e]334 - `doxygen <http://doxygen.org>`_ to build the :ref:`doxygen-documentation`.
[5069da3]335 - `txt2man <https://github.com/mvertes/txt2man>`_ to build the :ref:`manpages`
[e15d7d0]336 - `sphinx <http://sphinx-doc.org>`_ to build this document
[5069da3]337
338These tools are searched for in the current ``PATH`` environment variable.
339By default, the documentation is built only if the tools are found.
340
341To disable the documentation, configure with ``--disable-docs``. To build with
342the documentation, configure with ``--enable-docs``.
Note: See TracBrowser for help on using the repository browser.