From e15d7d0cdaf0471ebe2ee07dc5a91ab5c1039d2b Mon Sep 17 00:00:00 2001 From: Paul Brossier Date: Sun, 11 Dec 2016 21:12:14 +0100 Subject: [PATCH] doc/requirements.rst: improve description of options --- doc/requirements.rst | 203 +++++++++++++++++++++++++++++---------------------- 1 file changed, 117 insertions(+), 86 deletions(-) diff --git a/doc/requirements.rst b/doc/requirements.rst index b0e71c6b..d2b4bde2 100644 --- a/doc/requirements.rst +++ b/doc/requirements.rst @@ -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 `_. + +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 `_, 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 +`_. + +* 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 `_, 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 `_, 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 `_, 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 `_, 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 -`_. - -* 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 `_, 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 `_, 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 `_, 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 `_ to build the :ref:`doxygen-documentation`. - `txt2man `_ to build the :ref:`manpages` + - `sphinx `_ 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``. - -- 2.11.0