doc/requirements.rst: improve description of options
authorPaul Brossier <piem@piem.org>
Sun, 11 Dec 2016 20:12:14 +0000 (21:12 +0100)
committerPaul Brossier <piem@piem.org>
Sun, 11 Dec 2016 20:12:14 +0000 (21:12 +0100)
doc/requirements.rst

index b0e71c6..d2b4bde 100644 (file)
@@ -1,10 +1,96 @@
 .. _requirements:
 
-Requirements
-============
+Build options
+=============
+
+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.
 
-While aubio can be built without any external dependencies, we **recommend** to
-use at least some of the following libraries.
+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 system frameworks will be used on Mac OS X systems:
 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 @@ and on iOS Simulator:
 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,7 +183,19 @@ list of options, run:
 
 .. 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,96 +204,26 @@ To compile aubio in double precision mode, configure with ``--enable-double``.
 
 To compile aubio in single precision mode, use ``--disable-double`` (default).
 
-Fat binary
-..........
-
-To build a fat binary on Mac OS platforms, configure with ``--enable-fat``.
-
-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``
-
+Edit wscript
+............
 
-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.
+Many of the options are gathered in the file `wscript`. a good starting point
+when looking for additional options.
 
-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``
+.. _build_docs:
 
-External tools
---------------
+Building the docs
+-----------------
 
-If the following tools are found, additional documentations are built:
+If the following command line tools are found, the documentation will be built
+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.
 
 To disable the documentation, configure with ``--disable-docs``. To build with
 the documentation, configure with ``--enable-docs``.
-