Skip to content

Compiling

Jump to bottom
James Bradbury edited this page Jan 13, 2022 · 5 revisions

These are instructions for compiling the FluCoMa package on your own machines. This may be useful if you are compiling for an unusual setup or want to compile for optimal performance.

Pre-requisites

  • CMake >= 3.11
  • A C++ 14 compliant compiler for Mac or Windows (via XCode tools on Mac, and Visual Studio 17 >= 15.9 on Windows)

Dependencies

  • Max SDK (>= 7.3.3) : this is the only dependency we don't (optionally) manage for you, so there must be a version available to point to when you run, using the CMake Variable MAX_SDK_PATH (see below). It can live anywhere on your file system, although often it is convenient to install directly into your Max packages folder.

These will be downloaded and configured automatically, unless you pass CMake a source code location on disk for each (see below):

I'm in a Hurry...

...and you already have a development environment set up, understand CMake, and have the Max SDK available? And Python 3 + DocUtils + Jinja if you want docs?

Cool:

mkdir -p build && cd build
cmake -DMAX_SDK_PATH=<location of your Max SDK> -DDOCS=<ON/OFF> ..
make install

This will assemble a Max package in release-packaging.

An alternative to setting up / running CMake directly on the command line is to install the CMake GUI, or use to use the curses GUI ccmake.

Also, with CMake you have a choice of which build system you use.

  • The default on macOS and Linux is Unix Makefiles. On macOS you can also use Xcode by passing -GXcode to CMake when you first run it.
  • The default on Windows is the latest version of Visual Studio installed. However, Visual Studio can open CMake files directly as projects, which has some upsides. When used this way, CMake variables have to be set via a JSON file that MSVC will use to configure CMake.

Generating Documentation

The documentation partially relies on a system that is shared with other wrappers of the Fluid Corpus Manipulation Project for different creative coding environments.

Pre-requisites:

  • Python 3
  • Docutils python package (ReST parsing)
  • Jinja python package (template engine)
  • PyYAML >= 5.1 (YAML parsing)

To generate maxref.xml documentation for the Max objects requires a further dependency, flucoma-docs, which we use to combine generated and human-written docs. We then pass DOCS=ON to CMake

cmake -DDOCS=ON ..

Unless we pass the location on disk of flucoma-docs, CMake will again take care of downloading this dependency.

This process:

  • has only ever been tested on Mac, so may well not work at all on Windows
  • can sometimes produce spurious warnings in Xcode, but should work

Using Manual Dependencies

In some cases you may want to use your own copies of the required libraries. Unless specified, the build system will download these automatically. To bypass this behavior, use the following cache variables:

  • FLUID_PATH: location of the Fluid Corpus Manipulation Library
  • FLUID_DOCS_PATH: location of flucoma-docs repository (e.g. for debugging documentation generation)
  • EIGEN_PATH location of the Eigen library
  • HISS_PATH location of the HISSTools library

For example, use this to use your own copy of the Fluid Corpus Manipulation Library

cmake -DMAX_SDK_PATH=<location of your Max SDK> -DFLUID_PATH=<location of Fluid Corpus Manipulation Library> ..

To find out which branches / tags / commits of these we use, look in the top level CMakeLists.txt of the Fluid Corpus Manipulation Library for the FetchContent_Declare statements for each dependency.

Setting Compiler Options for Performance or Different Platforms

Our binary releases all target 64-bit intel architectures with SSE extensions enabled. This strikes a workable balance between supporting a wide range of machines whilst enjoying some of the performance benefits of newer CPU features. If you have a newer machine that supports additional instruction sets like AVX, AVX2, FMA and so forth, you may wish to take advantage or these.Likewise, you may wish to build for an architecture we don't directly support, like 32-bit Intel or ARM.

Both GCC and Clang allow you to supply a native setting which will enable optimal settings for your particular CPU, giving possible performance benefits at the cost of portability. You can pass these in to CMake via a flag CMAKE_CXX_FLAGS or, equivalently, set the CXXFLAGS environment variable in your shell before running CMake. On x64 this could look like

cmake -DCMAKE_CXX_FLAGS=-march=native <your other stuff> ..

on ARM, you might need to use mcpu rather than march:

cmake -DCMAKE_CXX_FLAGS=-mcpu=native <your other stuff> ..

MSVC doesn't have an equivalent to this handy feature, but for 64 bit systems you can enable various extensions via the /arch flag (reference).

To build natively on newer Apple Silicon machines, you may need to explictly pass -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64" (which should produce a universal (fat) binary).

Similarly, to build for 32-bit macOS, you might need to pass -DCMAKE_OSX_ARCHITECTURES="x86;x86_64" , although we can't make any promises that 32-bit builds will always function (and you'll need an XCode version < 10).

FluCoMa Home Page

FluCoMa Learn Platform

FluCoMa Discourse

Clone this wiki locally