ref: e15d7d0cdaf0471ebe2ee07dc5a91ab5c1039d2b
parent: e65fbec11f5e2ab3de411c84cd3a17c547eea4fe
author: Paul Brossier <piem@piem.org>
date: Sun Dec 11 16:12:14 EST 2016
doc/requirements.rst: improve description of options
--- a/doc/requirements.rst
+++ b/doc/requirements.rst
@@ -1,11 +1,97 @@
.. _requirements:
-Requirements
-============
+Build options
+=============
-While aubio can be built without any external dependencies, we **recommend** to
-use at least some of the following libraries.
+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 formas add more features to aubio, you can use one
+or all of the `following libraries <extlibs>`_.
+
+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.
+
+libav
+.....
+
+ `libav.org <https://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
+<https://libav.org/documentation/general.html#Audio-Codecs>`_.
+
+* 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 <http://www.mega-nerd.com/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 <http://www.mega-nerd.com/SRC/>`_, 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``
+
+libfftw3
+........
+
+ `FFTW <http://fftw.org/>`_, 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``
+
Platform notes
--------------
@@ -41,6 +127,9 @@
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
.......
@@ -86,7 +175,7 @@
Set ``CFLAGS`` and ``LINKFLAGS`` to change these default values, or edit
``wscript`` directly.
-Build options
+Other options
-------------
Some additional options can be passed to the configure step. For the complete
@@ -94,8 +183,20 @@
.. code:: bash
- $ ./waf configure --help
+ $ ./waf --help
+Here is an example of a custom command:
+
+.. code:: bash
+
+ $ ./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
................
@@ -103,92 +204,23 @@
To compile aubio in single precision mode, use ``--disable-double`` (default).
-Fat binary
-..........
+Edit wscript
+............
-To build a fat binary on Mac OS platforms, configure with ``--enable-fat``.
+Many of the options are gathered in the file `wscript`. a good starting point
+when looking for additional options.
-External libraries
-------------------
+.. _build_docs:
-External libraries are checked for using ``pkg-config``. Set the
-``PKG_CONFIG_PATH`` environment variable if you have them installed in an
-unusual location.
+Building the docs
+-----------------
+If the following command line tools are found, the documentation will be built
+built:
-.. note::
-
- If ``pkg-config`` is not found in ``PATH``, the configure step will
- succeed, but none of the external libraries will be used.
-
-libav
-.....
-
- `libav.org <https://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
-<https://libav.org/documentation/general.html#Audio-Codecs>`_.
-
-* 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 <http://www.mega-nerd.com/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 <http://www.mega-nerd.com/SRC/>`_, 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``
-
-libfftw3
-........
-
- `FFTW <http://fftw.org/>`_, 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``
-
-External tools
---------------
-
-If the following tools are found, additional documentations are built:
-
- `doxygen <http://doxygen.org>`_ to build the :ref:`doxygen-documentation`.
- `txt2man <https://github.com/mvertes/txt2man>`_ to build the :ref:`manpages`
+ - `sphinx <http://sphinx-doc.org>`_ 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.
@@ -195,4 +227,3 @@
To disable the documentation, configure with ``--disable-docs``. To build with
the documentation, configure with ``--enable-docs``.
-