ref: 5069da371ee058f9658a7cb8e72909d97d6899b2
parent: 88f7cf9218348b6d14a2421cceb680801eda0fa5
author: Paul Brossier <piem@piem.org>
date: Fri Aug 26 20:23:52 EDT 2016
installing.rst: split and rewrite
--- /dev/null
+++ b/doc/building.rst
@@ -1,0 +1,98 @@
+.. highlight:: bash
+
+.. _building:
+
+Building aubio
+==============
+
+.. note::
+ To download a prebuilt version of aubio, see :ref:`download`.
+
+aubio uses `waf`_ to configure, compile, and test the source.
+A copy of waf is included in aubio tarball, so all you need is a terminal,
+a compiler, and a recent version of python installed.
+
+.. note::
+ Make sure you have all the :ref:`requirements` you want before building.
+
+Latest release
+--------------
+
+The **latest stable release** can be downloaded from https://aubio.org/download::
+
+ $ curl -O http://aubio.org/pub/aubio-0.4.3.tar.bz2
+ $ tar xf aubio-0.4.3.tar.bz2
+ $ cd aubio-0.4.3
+
+Git repository
+--------------
+
+The **latest git branch** can be obtained with::
+
+ $ git clone git://git.aubio.org/git/aubio
+ $ cd aubio
+
+The following command will fetch the correct `waf`_ version (not included in
+aubio's git)::
+
+ $ ./scripts/get_waf.sh
+
+.. note::
+
+ Windows users without `Git Bash`_ installed will want to use the following
+ commands instead:
+
+ .. code:: bash
+
+ $ curl -fsS -o waf https://waf.io/waf-1.8.22
+ $ curl -fsS -o waf.bat https://raw.githubusercontent.com/waf-project/waf/master/utils/waf.bat
+
+
+Compiling
+---------
+
+To compile the C library, examples programs, and tests, run::
+
+ $ ./waf configure
+
+Check out the available options using ``./waf configure --help``. Once
+you are done with configuration, you can start building::
+
+ $ ./waf build
+
+To install the freshly built C library and tools, simply run the following
+command::
+
+ $ sudo ./waf install
+
+.. note::
+ Windows users should simply run ``waf``, without the leading ``./``. For
+ instance:
+
+ .. code:: bash
+
+ $ waf configure build
+
+Cleaning
+--------
+
+If you wish to uninstall the files installed by the ``install`` command, use
+``uninstall``::
+
+ $ sudo ./waf uninstall
+
+To clean the source directory, use the ``clean`` command::
+
+ $ ./waf clean
+
+To also forget the options previously passed to the last ``./waf configure``
+invocation, use the ``distclean`` command::
+
+ $ ./waf distclean
+
+.. _waf: https://waf.io/
+
+.. _Git Bash: https://git-for-windows.github.io/
+
+.. toctree::
+ :maxdepth: 2
--- a/doc/download.rst
+++ b/doc/download.rst
@@ -3,8 +3,6 @@
Downloading aubio
=================
-aubio runs on Linux, Windows, macOS, iOS, Android, and most operating systems.
-
A number of distributions already include aubio. Check your favorite package
management system, or have a look at the `aubio download page
<http://aubio.org/download>`_ for more options.
@@ -18,3 +16,5 @@
debian_packages
xcode_frameworks
android
+
+To compile aubio from source, read :ref:`building`.
--- a/doc/installing.rst
+++ b/doc/installing.rst
@@ -1,93 +1,19 @@
-.. highlight:: bash
-
-Building aubio
-==============
+Installing aubio
+================
-.. note::
- To download a prebuilt version of aubio, see :ref:`download`.
+aubio runs on Linux, Windows, macOS, iOS, Android, and probably quite a few
+others operating systems.
-aubio uses `waf`_ to configure, compile, and test the source.
-A copy of waf is included in aubio tarball, so all you need is a terminal,
-a compiler, and a recent version of python installed.
+To download a pre-compiled version of the library, head to :ref:`download`.
-Latest release
---------------
+To install the python extension, head to :ref:`python`.
-The **latest stable release** can be downloaded from https://aubio.org/download::
+To compile aubio form source, first check the :ref:`requirements`, then read
+:ref:`building`.
- $ curl -O http://aubio.org/pub/aubio-0.4.3.tar.bz2
- $ tar xf aubio-0.4.3.tar.bz2
- $ cd aubio-0.4.3
-
-Git repository
---------------
-
-The **latest git branch** can be obtained with::
-
- $ git clone git://git.aubio.org/git/aubio
- $ cd aubio
-
-The following command will fetch the correct `waf`_ version (not included in
-aubio's git)::
-
- $ ./scripts/get_waf.sh
-
-.. note::
-
- Windows users without `Git Bash`_ installed will want to use the following
- commands instead:
-
- .. code:: bash
-
- $ curl -fsS -o waf https://waf.io/waf-1.8.22
- $ curl -fsS -o waf.bat https://raw.githubusercontent.com/waf-project/waf/master/utils/waf.bat
-
-
-Compiling
----------
-
-To compile the C library, examples programs, and tests, run::
-
- $ ./waf configure
-
-Check out the available options using ``./waf configure --help``. Once
-you are done with configuration, you can start building::
-
- $ ./waf build
-
-To install the freshly built C library and tools, simply run the following
-command::
-
- $ sudo ./waf install
-
-.. note::
- Windows users should simply run ``waf``, without the leading ``./``. For
- instance:
-
- .. code:: bash
-
- $ waf configure build
-
-Cleaning
---------
-
-If you wish to uninstall the files installed by the ``install`` command, use
-``uninstall``::
-
- $ sudo ./waf uninstall
-
-To clean the source directory, use the ``clean`` command::
-
- $ ./waf clean
-
-To also forget the options previously passed to the last ``./waf configure``
-invocation, use the ``distclean`` command::
-
- $ ./waf distclean
-
-.. _waf: https://waf.io/
-
-.. _Git Bash: https://git-for-windows.github.io/
-
.. toctree::
:maxdepth: 2
+
+ download
+ requirements
+ building
--- /dev/null
+++ b/doc/requirements.rst
@@ -1,0 +1,178 @@
+.. _requirements:
+
+Requirements
+============
+
+While aubio should build without any additional external libraries, we
+**strongly recommend** to build aubio with some additional dependancies.
+
+Platform notes
+--------------
+
+Linux
+.....
+
+The following `External libraries`_ will be used if found: `libav`_,
+`libsamplerate`_, `libsndfile`_, `libfftw3`_.
+
+macOS
+.....
+
+The following system frameworks will be used on Mac OS X systems:
+
+ - `Accelerate <https://developer.apple.com/reference/accelerate>`_ to compute
+ FFTs and other vectorized operations optimally.
+
+ - `CoreAudio <https://developer.apple.com/reference/coreaudio>`_ and
+ `AudioToolbox <https://developer.apple.com/reference/audiotoolbox>`_ to
+ decode audio from files and network streams.
+
+.. note::
+
+ To build a fat binary for both ``i386`` and ``x86_64``, use ``./waf configure
+ --enable-fat``.
+
+The following `External libraries`_ will also be checked: `libav`_,
+`libsamplerate`_, `libsndfile`_, `libfftw3`_.
+
+Windows
+.......
+
+The following `External libraries`_ will be used if found: `libav`_,
+`libsamplerate`_, `libsndfile`_, `libfftw3`_.
+
+iOS
+...
+
+The following system frameworks will be used on iOS and iOS Simulator.
+
+ - `Accelerate <https://developer.apple.com/reference/accelerate>`_ to compute
+ FFTs and other vectorized operations optimally.
+
+ - `CoreAudio <https://developer.apple.com/reference/coreaudio>`_ and
+ `AudioToolbox <https://developer.apple.com/reference/audiotoolbox>`_ to
+ decode audio from files and network streams.
+
+To build aubio for iOS, configure with ``--with-target-platform=ios``. For the
+iOS Simulator, use ``--with-target-platform=iosimulator`` instead.
+
+By default, aubio is built with the following flags on iOS:
+
+.. code:: bash
+
+ CFLAGS="-fembed-bitcode -arch arm64 -arch armv7 -arch armv7s -miphoneos-version-min=6.1"
+
+and on iOS Simulator:
+
+.. code::
+
+ CFLAGS="-fembed-bitcode -arch i386 -arch x86_64 -mios-simulator-version-min=6.1"
+
+Set ``CFLAGS`` and ``LINKFLAGS`` to change these default values, or edit
+``wscript`` directly.
+
+Build options
+-------------
+
+These options can be passed to configure
+
+Double precision
+................
+
+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``
+
+
+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
+failed 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 failed 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 <http://fftw.org>`_ 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 failed 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 `API documentation`.
+ - `txt2man <https://github.com/mvertes/txt2man>`_ to build the :ref:`manpages`
+
+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``.
+