From 5069da371ee058f9658a7cb8e72909d97d6899b2 Mon Sep 17 00:00:00 2001 From: Paul Brossier Date: Sat, 27 Aug 2016 00:23:52 +0200 Subject: [PATCH] installing.rst: split and rewrite --- doc/building.rst | 98 ++++++++++++++++++++++++++++ doc/download.rst | 4 +- doc/installing.rst | 98 ++++------------------------ doc/requirements.rst | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 290 insertions(+), 88 deletions(-) create mode 100644 doc/building.rst create mode 100644 doc/requirements.rst diff --git a/doc/building.rst b/doc/building.rst new file mode 100644 index 00000000..5c52a309 --- /dev/null +++ b/doc/building.rst @@ -0,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 diff --git a/doc/download.rst b/doc/download.rst index 581633fd..58329980 100644 --- 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 `_ for more options. @@ -18,3 +16,5 @@ To use aubio in an android project, see :ref:`android`. debian_packages xcode_frameworks android + +To compile aubio from source, read :ref:`building`. diff --git a/doc/installing.rst b/doc/installing.rst index 6df528ef..d0657bd8 100644 --- a/doc/installing.rst +++ b/doc/installing.rst @@ -1,93 +1,19 @@ -.. highlight:: bash +Installing aubio +================ -Building aubio -============== +aubio runs on Linux, Windows, macOS, iOS, Android, and probably quite a few +others operating systems. -.. note:: - To download a prebuilt version of aubio, see :ref:`download`. +To download a pre-compiled version of the library, head to :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. +To install the python extension, head to :ref:`python`. -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/ +To compile aubio form source, first check the :ref:`requirements`, then read +:ref:`building`. .. toctree:: :maxdepth: 2 + + download + requirements + building diff --git a/doc/requirements.rst b/doc/requirements.rst new file mode 100644 index 00000000..727299f2 --- /dev/null +++ b/doc/requirements.rst @@ -0,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 `_ to compute + FFTs and other vectorized operations optimally. + + - `CoreAudio `_ and + `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 `_ to compute + FFTs and other vectorized operations optimally. + + - `CoreAudio `_ and + `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 `_, 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 +failed 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 failed 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 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 `_ to build the `API documentation`. + - `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``. + -- 2.11.0