Compiling & using Limes

Table of Contents

• Basic usage
• Compiling Limes
• CMake information
  • Options
    • limes_vecops options
  • Dependencies
  • Targets
  • Installation
    • Install components
    • Install component groups
    • Limes find_package components
• Building the Limes documentation

Basic usage

You can run cmake –install and then call find_package (Limes) from your consuming project, and everything should just work out of the box.

If your project depends on Limes, I recommend copying the FindLimes.cmake script from the scripts/ directory into your project's source tree (and adding its location to the CMAKE_MODULE_PATH before calling find_package (Limes)), so that if your project is built on a system where Limes hasn't been installed, it can still be fetched at configure-time. See the FindLimes file for more documentation on what it does.

Compiling Limes

Limes makes use of C++20, notably concepts. Limes has been tested on Mac, Windows, and Linux with Clang, GCC, and MSVC. Limes is also tested crosscompiled for iOS, tvOS and watchOS.

To build the Limes unit tests, pass -DLIMES_BUILD_TESTS=ON to the CMake configuration. This option defaults to OFF .

CMake information

Limes aims to be very CMake-aware, and modern CMake design patterns are strictly enforced in Limes CMake code and its primary CMake dependency, Oranges.

The goal of Limes's CMake scripts is to reduce the number of user-facing options, while still retaining flexibility for both users and developers of Limes.

Options

LIMES_BUILD_TESTS

Builds the Limes unit tests. Defaults to OFF if Limes is not the top-level directory CMake is invoked in.

LIMES_BUILD_DOCS

Builds the Limes documentation. Defaults to OFF if Limes is not the top-level directory CMake is invoked in.

LIMES_INTERNAL_DOCS

When building the documentation, includes extra information on internal implementation details not meant for inclusion in the public documentation. This option always defaults to OFF , and is intended for internal use only.

limes_vecops options

See also

limes_vecops

The limes_vecops library has several additional options controlling its choice of 3rd party backend (if any) to use.

The default selection of the backend follows these heuristics:

• Use vDSP if on an Apple platform
• Use IPP if on an Intel platform and it can be found on the system
• Use MIPP if on a platform that supports NEON, SSE, AVX, or AVX512
• Otherwise, use the builtin fallback implementations

However, these defaults can be overridden using the following CMake options:

LIMES_USE_VDSP

If ON , prefer to use Apple vDSP over any other backend.

LIMES_USE_IPP

If ON , prefer to use Intel IPP over any other backend.

LIMES_USE_MIPP

If ON , prefer to use MIPP over any other backend.

LIMES_USE_VECOPS_FALLBACK

If ON , prefer to use the builtin fallbacks over any third party backend.

LIMES_VECOPS_BACKEND

A string value that can be one of VDSP , IPP , MIPP , or FALLBACK . If an unrecognized value is present, a warning will be issued.

These additional options further control the behavior of the limes_vecops library:

LIMES_USE_POMMIER

If ON , Julien Pommier's sin and cosine functions for SSE and NEON will be used, if on a platform supporting those instructions. The main use case of this option is to disable these functions.

LIMES_USE_FFTW

By default, FFTW will be searched for in the system, and if found, will be used for the limes_vecops FFT class's backend. However, you can set this option to OFF to ignore FFTW. vDSP and IPP also provide FFT implementations.

Dependencies

Limes's CMake configuration depends on the Oranges package of CMake scripts.

You can set the environment or command-line variable ORANGES_PATH to direct the Limes CMake configuration to use a local copy. If no local copy is present and Oranges cannot be found on your system, invoking Limes's CMake configuration will fetch and cache a copy of the Oranges source code.

The limes_vecops library can optionally link to the following external libraries:

• Apple vDSP (Accelerate framework)
• Intel IPP
• MIPP
• FFTW

If MIPP is used, its sources will be fetched at configure time if necessary. IPP must be manually installed to the system by the developer using Intel's installer program. FFTW can be installed to your system with a simple cmake –install of their git repository.

Targets

Limes creates the following CMake targets:

Name	Kind	Description
Limes::limes_audio	Static library	Limes library of realtime audio utilities
Limes::limes_core	Static library	Limes core library of utilities
Limes::limes_data_structures	Static library	Limes library of data structures
Limes::limes_locale	Static library	Limes localization library
Limes::limes_midi	Static library	Limes library of MIDI utilities
Limes::limes_music	Static library	Limes library of music theory utilities
Limes::limes_vecops	Static library	Limes vector operations library
Limes::Limes	Interface library	Links to all Limes libraries and includes limes.h
Limes::FileUtil	Executable	OS-agnostic interface to filesystem operations
Limes::BinaryBuilder	Executable	Generates C++ sources embedding binary data files

See the documentation for each library and executable for more specific information about each of them.

Installation

Install components

Limes creates the following CPack install components:

• limes_vecops_dev
• limes_vecops_runtime
• limes_music_dev
• limes_music_runtime
• limes_core_dev
• limes_core_runtime
• limes_audio_dev
• limes_audio_runtime
• limes_midi_dev
• limes_midi_runtime
• limes_data_structures_dev
• limes_data_structures_runtime
• limes_locale_dev
• limes_locale_runtime
• limes_libs_dev
• limes_libs_runtime
• limes_binary_builder_dev
• limes_binary_builder_runtime
• limes_programs_dev
• limes_programs_runtime
• limes_dev (aggregate of all other dev components)
• limes_runtime (aggregate of all other runtime components)
• limes_doc_pdf
• limes_doc_html
• limes_doc_man
• limes_docs

Install component groups

Limes creates the following CPack install component groups:

• limes_vecops
• limes_music
• limes_core
• limes_audio
• limes_midi
• limes_data_structures
• limes_locale
• limes_libs
• limes_binary_builder
• limes_programs
• limes_sphinx_docs
• limes_doxy_docs
• limes_docs
• limes (aggregate of all Limes components)

Limes find_package components

When you call find_package(Limes) from a consuming project, you can optionally specify any of the following component names:

• All
• Libs
• Programs
• Audio
• MIDI
• Core
• DataStructures
• Locale
• Music
• Vecops
• BinaryBuilder
• FileUtil

If no component names are specified, Limes will default to importing everything.

These component names are common to the CMake package files Limes exports, and the FindLimes.cmake FindLimes.cmake script that Limes ships for convenience.

To read more about this find module, FindLimes.cmake head here.

Building the Limes documentation

The Limes documentation is built with Doxygen. Building the docs can be enabled with the LIMES_BUILD_DOCS option.

Doxygen and Graphviz's dot tool are required for building the docs. A non-fatal warning will be issued during CMake configuration if either program cannot be found.

To generate the @f(\LaTeX @f) PDF output, pdflatex and a make executable are required. If both can be found, generating the PDF will be automatically enabled. The PDF generation can fail spuriously; you can try manually running make in the doc/latex directory, and press enter if it prompts you about an error. On my Mac, I needed to run the following commands to get the @f(\LaTeX @f) build working:

brew install basictex
sudo tlmgr install latexmk collection-latexextra wasysym helvetic wasy courier
brew install gs

The CMake target that executes the build of the docs is called LimesDocs .