diff --git a/README.md b/README.md index a84d579..a4c4050 100644 --- a/README.md +++ b/README.md @@ -70,13 +70,13 @@ our knowledge. See also the end of this README for detailed terms. 2. Using the Rubber Band command-line tool 3. Using the Rubber Band Library 4. Compiling Rubber Band - a. FFT and resampler selection - b. Other supported #defines - c. Building on Linux - d. Building on macOS - e. Building for iOS - f. Building on Windows with Visual C++ - g. Building for Android and Java integration + a. Building on Linux + b. Building on macOS + c. Building for iOS + d. Building on Windows + e. Building for Android and Java integration + f. FFT and resampler selection + g. Other supported #defines 5. Copyright notes for bundled libraries @@ -156,19 +156,183 @@ acquired a commercial licence from the author. ## 4. Compiling the Rubber Band Library -### 4a. FFT and resampler selection +The primary supported build system for the Rubber Band Library on all +platforms is Meson (https://mesonbuild.com). To build, ensure Meson +and Ninja are installed and run: + +``` +$ meson build && ninja -C build +``` + +This checks for necessary dependencies, reports what it finds, and if +all is well, builds the code into a subdirectory called `build`. It +will build everything it can find the requisite dependencies for: +static and dynamic libraries, LADSPA and Vamp plugins, and +command-line utility. + +Some configuration options are provided, described in the +`meson_options.txt` file. To set one of these, add a `-D` option to +Meson: + +``` +$ meson build -Dipp_path=/opt/intel/ipp +``` + +The options are documented in the library- and platform-specific +sections below. + +For those who don't wish to use Meson, some alternative build files +(Makefiles and Visual C++ projects) are included in the `otherbuilds` +directory. These build only the static library. + +If you are building this software using one of the bundled library +options (Speex or KissFFT), please be sure to review the terms for +those libraries in `src/speex/COPYING` and `src/kissfft/COPYING` as +applicable. + + +### 4a. Building on Linux + +For best results, and to make sure the command-line tool and plugins +are built, first ensure libsamplerate, libsndfile, and the LADSPA and +Vamp plugin headers are installed and can be found using +`pkg-config`. Then + +``` +$ meson build && ninja -C build +``` + +If you only need the static library and prefer a Makefile, try + +``` +$ make -f otherbuilds/Makefile.linux +``` + + +### 4b. Building on macOS + +Ensure the Xcode command-line tools are installed, and ideally also +install libsamplerate and libsndfile. + +To build for the native architecture of the build machine: + +``` +$ meson build && ninja -C build +``` + +To build for Intel (x86_64) regardless of the native architecture: + +``` +$ meson build --cross-file cross/macos-x86_64.txt && ninja -C build +``` + +To build for Apple Silicon (arm64) regardless of the native +architecture: + +``` +$ meson build --cross-file cross/macos-arm64.txt && ninja -C build +``` + +You can build a universal binary library for both architectures like +this: + +``` +$ meson build --cross-file cross/macos-universal.txt && ninja -C build +``` + +However, the resulting binary will be marked as loadable on macOS 11+ +only, even for Intel, which is probably not what you want (ideally the +Intel slice would support older versions of the OS). A Makefile that +handles this explicitly is also provided: + +``` +$ make -f otherbuilds/Makefile.macos-universal +``` + +This produces only a static library, but as a universal binary that is +compatible with macOS 10.7 onwards on Intel. + +Note that you cannot legally distribute applications using Rubber Band +in the Mac App Store, unless you have first obtained a commercial +licence for the Rubber Band Library. GPL code is not permitted in the +app store. See https://breakfastquay.com/technology/license.html for +commercial terms. + + +### 4c. Building for iOS + +Ensure the Xcode command-line tools are installed, and + +``` +$ meson build_ios --cross-file cross/ios.txt && ninja -C build +``` + +The resulting outputs will be found in `build_ios/` + +To build for the simulator, + +``` +$ meson build_sim --cross-file cross/ios-simulator.txt && ninja -C build +``` + +The resulting outputs will be found in `build_sim/`. + +Note that you cannot legally distribute applications using Rubber Band +in the iOS App Store, unless you have a first obtained a commercial +licence for the Rubber Band Library. GPL code is not permitted in the +app store. See https://breakfastquay.com/technology/license.html for +commercial terms. + + +### 4d. Building on Windows + +A Visual Studio solution, targeted to VC 2015, with two projects is +supplied. The `rubberband-library` project builds the Rubber Band +static libraries only. The `rubberband-program` project builds the +Rubber Band command-line tool (which requires the Rubber Band Library +and libsndfile). + +You will need to adjust the project settings so as to set the compile +flags according to your preference for FFT and resampler +implementation, and set the include path and library path +appropriately. The default is to use the bundled KissFFT and the +Speex resampler. + +If you prefer to add the Rubber Band Library files to an existing +build project instead of using the supplied one, the files in `src/` +(except for `RubberBandStretcherJNI.cpp`) and the API headers in +`rubberband/` should be all you need. + + +### 4e. Building for Android and Java integration + +Currently only a very old Android NDK build file is provided, as +`otherbuilds/Android.mk`. This includes compile definitions for a +shared library built for ARM architectures which can be loaded from a +Java application using the Java native interface (i.e. the Android +NDK). + +The Java side of the interface can be found in +`com/breakfastquay/rubberband/RubberBandStretcher.java`. + +See +https://hg.sr.ht/~breakfastquay/rubberband-android-simple-sample +for a very trivial example of integration with Android Java code. + +The supplied `.mk` file uses KissFFT and the Speex resampler. + + +### 4f. FFT and resampler selection Rubber Band requires additional library code for FFT calculation and resampling. Several libraries are supported. The selection is -controlled using preprocessor flags at compile time, as detailed in -the tables below. +controlled (in Meson) using `-D` options and (in the code itself) +using preprocessor flags set by the build system. These options and +flags are detailed in the tables below. -Flags that declare that you want to use an external library begin with -`HAVE_`; flags that select from the bundled options begin with `USE_`. - -You must enable one resampler implementation and one FFT -implementation. Do not enable more than one of either unless you know -what you're doing. +At least one resampler implementation and one FFT implementation must +be enabled. It is technically possible to enable more than one, but +it's confusing and not often useful. If you are building this software using one of the bundled library options (Speex or KissFFT), please be sure to review the terms for @@ -178,44 +342,42 @@ applicable. #### FFT libraries supported ``` -Name Flags required Notes ----- -------------- ----- +Library Build option CPP define Notes +---- ------------ ---------- ----- -FFTW3 -DHAVE_FFTW3 GPL. +KissFFT -Dfft=kissfft -DUSE_KISSFFT Default except on macOS/iOS. + Bundled, can be distributed with + either the Rubber Band GPL or + commercial licence. -Accelerate -DHAVE_VDSP Platform library on macOS and iOS. +Accelerate -Dfft=vdsp -DHAVE_VDSP Default on macOS/iOS. + Best option on these platforms. -Intel IPP -DHAVE_IPP Proprietary library, can only be used with - Rubber Band commercial licence. Define - USE_IPP_STATIC as well to build with static - IPP libraries. +FFTW3 -Dfft=fftw -DHAVE_FFTW3 GPL. -KissFFT -DUSE_KISSFFT Bundled, can be distributed with either the - Rubber Band GPL or commercial licence. - Single-precision. Slower than the above - options. +Intel IPP -Dfft=ipp -DHAVE_IPP Proprietary, can only be used with + Rubber Band commercial licence. ``` #### Resampler libraries supported ``` -Name Flags required Notes ----- -------------- ----- +Library Build option CPP define Notes +---- ------------ ---------- ----- -libsamplerate -DHAVE_LIBSAMPLERATE GPL until v0.1.8, BSD for v0.1.9 and later. - This is the preferred choice in almost - all cases. +libsamplerate -DHAVE_LIBSAMPLERATE + -Dresampler=libsamplerate Best choice in most cases. -libresample -DHAVE_LIBRESAMPLE LGPL. - -Speex -DUSE_SPEEX Bundled, can be distributed with either the - Rubber Band GPL or commercial licence. +Speex -DUSE_SPEEX + -Dresampler=speex Bundled, can be distributed with + either the Rubber Band GPL or + commercial licence. ``` -### 4b. Other supported #defines +### 4g. Other supported #defines -Other symbols you may define at compile time are as follows. (Usually -the supplied build files will handle these for you.) +Other known preprocessor symbols are as follows. (Usually the supplied +build files will handle these for you.) -DLACK_BAD_ALLOC Define on systems lacking std::bad_alloc in the C++ library. @@ -250,132 +412,6 @@ the supplied build files will handle these for you.) for mobile architectures. -### 4c. Building on Linux - -A GNU-style configure script is included for use on Linux and similar -systems. - -Run `./configure`, then adjust the generated Makefile according to -your preference for FFT and resampler implementations. The default is -to use FFTW3 and libsamplerate. - -The following Makefile targets are available: - - static -- build static libraries only - dynamic -- build dynamic libraries only - library -- build static and dynamic libraries only - program -- build the command-line tool - vamp -- build Vamp plugin - ladspa -- build LADSPA plugin - all -- build everything. - -The default target is "all". - - -### 4d. Building on macOS - -Two Makefiles for macOS are provided, as `Makefile.macos` and -`Makefile.macos-universal`. `Makefile.macos` will build for your -native machine architecture; `Makefile.macos-universal` will build a -universal binary with both x86_64 and arm64 slices. The latter -requires macOS 11+, although the resulting binaries should work with -macOS 10.7 or newer if all the dependent libraries are also built -appropriately. You will also need the Xcode command-line tools -installed. - -Adjust your selected Makefile according to your preference for -compiler and platform SDK, FFT and resampler implementations. The -default is to use the Accelerate framework and the Speex resampler. -Then run e.g. `make -f Makefile.macos library` in a terminal window to -build. - -(You probably don't want to use the configure script on macOS -- just -use your preferred Makefile directly.) - -The following Makefile targets are available: - - static -- build static libraries only - dynamic -- build dynamic libraries only - library -- build static and dynamic libraries only - program -- build the command-line tool - vamp -- build Vamp plugin - ladspa -- build LADSPA plugin - all -- build everything. - -The default target is to build the static and dynamic libraries and -the command line tool. The sndfile library is required for the -command line tool. - -If you prefer to add the Rubber Band Library files to an existing -build project instead of using the Makefile, the files in `src/` -(except for `RubberBandStretcherJNI.cpp`) and the API headers in -`rubberband/` should be all you need. - -Note that you cannot legally distribute applications using Rubber Band -in the Mac App Store, unless you have first obtained a commercial -licence for the Rubber Band Library. GPL code is not permitted in the -app store. See https://breakfastquay.com/technology/license.html for -commercial terms. - - -### 4e. Building for iOS - -A Makefile for iOS (compiling on macOS) is provided as `Makefile.ios`. -It produces a single static library containing both simulator and -device binaries, in both 32- and 64-bit architectures. - -Run e.g. `make -f Makefile.ios` in a terminal window to build. You -will need the Xcode command-line tools installed. - -If you prefer to add the Rubber Band Library files to an existing -build project instead of using the Makefile, the files in `src/` -(except for `RubberBandStretcherJNI.cpp`) and the API headers in -`rubberband/` should be all you need. - -Note that you cannot legally distribute applications using Rubber Band -in the iOS App Store, unless you have a first obtained a commercial -licence for the Rubber Band Library. GPL code is not permitted in the -app store. See https://breakfastquay.com/technology/license.html for -commercial terms. - - -### 4f. Building on Windows with Visual C++ - -A Visual Studio solution, targeted to VC 2015, with two projects is -supplied. The `rubberband-library` project builds the Rubber Band -static libraries only. The `rubberband-program` project builds the -Rubber Band command-line tool (which requires the Rubber Band Library -and libsndfile). - -You will need to adjust the project settings so as to set the compile -flags according to your preference for FFT and resampler -implementation, and set the include path and library path -appropriately. The default is to use the bundled KissFFT and the -Speex resampler. - -If you prefer to add the Rubber Band Library files to an existing -build project instead of using the supplied one, the files in `src/` -(except for `RubberBandStretcherJNI.cpp`) and the API headers in -`rubberband/` should be all you need. - - -### 4g. Building for Android and Java integration - -An Android NDK build file is provided as `Android.mk`. This includes -compile definitions for a shared library built for ARM architectures -which can be loaded from a Java application using the Java native -interface (i.e. the Android NDK). - -The Java side of the interface can be found in -`com/breakfastquay/rubberband/RubberBandStretcher.java`. - -See -https://hg.sr.ht/~breakfastquay/rubberband-android-simple-sample -for a very trivial example of integration with Android Java code. - -The supplied `.mk` file uses KissFFT and the Speex resampler. - - ## 5. Copyright notes for bundled libraries ### 5a. Speex