# Building

You may build plugins from scratch.

The build process doesn't differ much for GNU/Linux, FreeBSD or Windows. For a build on macOS and FreeBSD you should use `gmake` instead of `make`. Build of standalone versions for Windows is yet not supported.

For successful build for Linux/FreeBSD you need the following packages to be installed:

- gcc >= 4.7 OR clang >= 10.0.1
- gcc-c++ >= 4.7 OR clang-c++ >= 10.0.1
- libgcc_s1 >= 5.2
- libstdc++-devel >= 4.7
- libsndfile-devel >= 1.0.25
- libcairo-devel >= 1.14
- php >= 5.5.14 (for documentation)
- jack-devel >= 1.9.5 (for JACK)
- libiconv (for FreeBSD)
- libGL-devel >= 11.2.2
- gstreamer >= 1.20 (for GStreamer)
- gstreamer-plugins-base >= 1.20 (for GStreamer)

For macOS build, the following software needs to be installed:

- make >= 4.4.1
- cairo >= 1.18.4
- freetype >= 2.13.3
- pkgconf >= 2.5.1
- php >= 5.5.14 (for the docs)

On some Command Line Tools 16.x installations the libc++ headers live inside the SDK (`$(xcrun --show-sdk-path)/usr/include/c++/v1`) instead of the expected `/Library/Developer/CommandLineTools/usr/include/c++/v1`, so `#include <thread>` and other standard headers fail to resolve. If the build fails with `'thread' file not found` while compiling `*.mm` translation units, export `-isystem $(xcrun --show-sdk-path)/usr/include/c++/v1` in `CXXFLAGS` (and `CFLAGS`). This is unrelated to architecture; it depends on which CLT release is installed.

For Windows build, the following software needs to be installed:

- MinGW/MinGW-W64 >= 7.0
- Git >= 2.8 (optional)
- PHP >= 5.5.14
- GNU Make >= 4.2

To perform toolchain setup for Windows, you may perform the following steps:

- Download latest Git
- Download latest MinGW-W64 GCC
- Download latest PHP x64 Thread Safe ZIP package
- Install Git
- Unpack PHP ZIP to C:\php
- Unpack MinGW to C:\mingw64
- To make all installed software accessible from command line, add to the PATH environment variable following elements:
- C:\Program Files\Git\cmd
- C:\Program Files\Git\usr\bin
- C:\mingw64\bin
- C:\php

> MacOS includes their own version of `make`, if you decide to install it from homebrew, replace all the commands with `gmake`.

To build the project from archive with source code, the following sequence of commands should be performed:

      make clean
      make config
      make
      make install

To build the project from GIT repository, the additional 'make fetch' command should be issued to obtain all source code dependencies:

      make clean
      make config
      make fetch
      make
      make install

For Windows, the `make install` command creates 'INSTALL' subdirectory and places the plugin content into desired subfolders.

By default, all supported formats of plugins for the target platform are built. The list of modules for build can be adjusted by specifying FEATURES variable at the configuration stage:

      make config FEATURES='lv2 vst2 ui doc'

Available compile options are:

- asan - build with address sanitizer enabled.
- crosscompile - build with additional debug information and debug logs enabled.
- debug - build with additional debug information and debug logs enabled.
- devel - use development (SSH) links for remote repositories instead of HTTPS.
- profile - build with gprof profiling options.
- strict - strict compilation: treat all compilation warning as errors.
- test - enable tests and build test binary.
- trace - enable output of additional trace logs.

Available options are:

- clap - CLAP plugin binaries;
- doc - HTML documentation;
- gst - GStreamer plugin binaries;
- jack - JACK backend for standalone plugins (not available under Windows);
- ladspa - LADSPA plugin binaries;
- launcher - Build launcher application for standalone JACK plugins;
- lv2 - LV2 plugin binaries;
- standalone - Standalone plugins applications (not available on Windows);
- ui - build plugins with UI support;
- vst2 - VST2/LinuxVST plugin binaries;
- vst3 - VST2 plugin binaries;
- xdg - the X11 desktop integration icons (not necessary for Windows).

By default plugins use '/usr/local' path as a target directory for installation. To override this path, the PREFIX variable can be overridden:

      make config PREFIX=/usr

To build binaries for debugging, add `debug` feature to `FEATURES` variable:

      make config ADD_FEATURES='debug'

To build binaries for testing (developers only), add `test` feature to `FEATURES` variable:

      make config ADD_FEATURES='test'

To install plugins at the desired root directory, the DESTDIR variable can be specified:

      make install DESTDIR=<installation-root>

To install only specific formats, use INSTALL_FEATURES option:

      make install FEATURES='lv2 ladspa'

To build standalone source code package, the following commands can be issued:

      make config
      make distsrc

After that, a standalone archive with source code will be created in the `.build` directory.

When cross compiling, the AS, AR, CC, CXX, LD, etc. variables should be set in the environment according to the target/cross compile toolchain. The build host machine versions of those variables- HOST_AS, HOST_AR, HOST_CC, HOST_CXX, etc. have defaults set in the makefiles but may need to be overridden. To troubleshoot, run `make config` with the VERBOSE option. Additional variables should be configured:

- set the `ARCHITECTURE` option to the target architecture.
- add the `croccompile` feature to the `FEATURES` variable.

Example cross compile procedure for aarch64 target on x86_64 build host: ```

    make clean
    make config ARCHITECTURE="aarch64" ADD_FEATURES="crosscompile"
    make fetch
    make
    make install

    After successful completion, the cross compiled artifacts should be located in the directory specified by PREFIX.

    For more build options, issue:

    make help

    Build example for macOS:

    brew install make pkgconf cairo freetype
    gmake clean
    gmake config FEATURES="vst3 ui"
    gmake fetch
    gmake
    sudo gmake install

    The bundle produced by `gmake install` is unsigned and works as-is in
    most hosts. However, if the bundle is **modified after build** — for
    example by `lipo`-merging an arm64 and an x86_64 slice into a universal
    binary, or by manually swapping a file inside it — the existing
    `_CodeSignature/CodeResources` manifest no longer matches the contents,
    and hosts that verify signatures (Ableton Live among them) reject the
    bundle with `code has no resources but signature indicates they must be
    present`. The fix is to refresh the ad-hoc signature:

    codesign --remove-signature lsp-plugins.vst3
    codesign --force --deep --sign - lsp-plugins.vst3
    codesign --verify --verbose=2 lsp-plugins.vst3