The YUP CMake API#

System Requirements#

All project types require CMake 3.31 or higher.
Android and Emscripten targets are not currently supported for audio plugins.

Most system package managers have packages for CMake, but we recommend using the most recent release from https://cmake.org/download.

Getting Started#

Using FetchContent#

The recommended way to include YUP in your project:

cmake_minimum_required (VERSION 3.31)

set (target_name my_plugin)
set (target_version "0.0.1")
project (${target_name} VERSION ${target_version})

include (FetchContent)

FetchContent_Declare (
    yup
    GIT_REPOSITORY https://github.com/kunitoki/yup.git
    GIT_TAG main)

set (YUP_BUILD_EXAMPLES OFF)
set (YUP_BUILD_TESTS OFF)
FetchContent_MakeAvailable (yup)

yup_audio_plugin (
    TARGET_NAME ${target_name}
    TARGET_VERSION ${target_version}
    TARGET_APP_ID "com.mycompany.${target_name}"
    TARGET_APP_NAMESPACE "com.mycompany"
    PLUGIN_CREATE_CLAP ON
    PLUGIN_CREATE_VST3 ON
    MODULES yup::yup_gui yup::yup_audio_processors)

file (GLOB sources "${CMAKE_CURRENT_LIST_DIR}/*.cpp")
target_sources (${target_name}_shared PUBLIC ${sources})

Platform-Specific Build Commands#

macOS:

cmake -G "Xcode" . -B build
cmake --build build --config Release

Windows:

cmake -G "Visual Studio 17 2022" -A x64 . -B build
cmake --build build --config Release

Linux:

cmake -G "Ninja" . -B build
cmake --build build --config Release

Building universal binaries for macOS#

cmake -B build -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"

CMake Cache Options#

These flags can be enabled or disabled to change the behaviour of parts of the YUP build. They would normally be configured by supplying an option in the form -DNAME=ON/OFF to the initial CMake configuration call, or by calling set(NAME ON/OFF) before including YUP via FetchContent.

`YUP_BUILD_EXAMPLES`#

Controls whether targets are added for the example projects. OFF by default.

`YUP_BUILD_TESTS`#

Controls whether targets are added for test projects. OFF by default.

`YUP_BUILD_BENCHMARKS`#

Controls whether targets are added for benchmark projects. OFF by default.

`YUP_ENABLE_COVERAGE`#

Enables code coverage instrumentation. OFF by default.

`YUP_ENABLE_PLUGINVAL`#

Enables pluginval validation as a post-build step for plugin targets. OFF by default.

`YUP_ENABLE_CLAP_VALIDATOR`#

Enables CLAP validator as a post-build step for CLAP plugin targets. OFF by default.

`YUP_ENABLE_VST3_VALIDATOR`#

Enables the SMTG VST3 validator as a post-build step for VST3 targets. OFF by default.

`YUP_ENABLE_AUVAL_VALIDATOR`#

Enables auval validation as a post-build step for AU/AUv3 targets. OFF by default.

Functions#

`yup_audio_plugin`#

yup_audio_plugin(
    [KEY value]...
)

Adds a shared code static library target with name <TARGET_NAME>_shared, along with extra targets for each of the specified plugin formats. All arguments are optional unless noted otherwise. Keys that are not specified will fall back to sensible defaults.

Target Globals#

Key	Type	Default	Description
`TARGET_NAME`	string	(required)	Base name for all generated targets.
`TARGET_VERSION`	string	(required)	Version in `major.minor.patch` format.
`TARGET_IDE_GROUP`	string	-	IDE folder group name (e.g. “Examples”).
`TARGET_APP_ID`	string	-	Bundle identifier (e.g. `com.mycompany.MyPlugin`). Used as the macOS bundle id.
`TARGET_APP_NAMESPACE`	string	-	App namespace (e.g. `com.mycompany`).
`TARGET_CXX_STANDARD`	integer	`20`	C++ standard version.

Format Toggles#

Key	Type	Default	Description
`PLUGIN_CREATE_CLAP`	ON\|OFF	OFF	Build a CLAP plugin target.
`PLUGIN_CREATE_VST3`	ON\|OFF	OFF	Build a VST3 plugin target.
`PLUGIN_CREATE_AU`	ON\|OFF	OFF	Build an AUv2 plugin target (macOS only).
`PLUGIN_CREATE_AUv3`	ON\|OFF	OFF	Build an AUv3 plugin target (macOS only).
`PLUGIN_CREATE_AAX`	ON\|OFF	OFF	Build an AAX plugin target. Requires AAX SDK.
`PLUGIN_CREATE_LV2`	ON\|OFF	OFF	Build an LV2 plugin target (in progress).
`PLUGIN_CREATE_STANDALONE`	ON\|OFF	OFF	Build a standalone executable.

At least one format must be enabled, otherwise configuration fails with an error.

Plugin Metadata#

Key	Type	Default	Description
`PLUGIN_ID`	string	-	Globally-unique plugin identifier (e.g. `com.mycompany.MyPlugin`).
`PLUGIN_NAME`	string	`<TARGET_NAME>`	Display name shown in DAWs.
`PLUGIN_VENDOR`	string	-	Vendor/company name.
`PLUGIN_EMAIL`	string	-	Contact email address.
`PLUGIN_VERSION`	string	`1`	Plugin version string.
`PLUGIN_DESCRIPTION`	string	-	Short description of the plugin.
`PLUGIN_URL`	string	-	Website URL for the plugin.
`PLUGIN_IS_SYNTH`	ON\|OFF	OFF	Whether the plugin is a synthesizer (affects format-specific defaults).
`PLUGIN_IS_MONO`	ON\|OFF	OFF	Whether the plugin is mono (affects CLAP feature defaults).
`PLUGIN_COPYRIGHT`	string	-	Copyright string added to Info.plist on macOS.

AU-Specific#

Key	Type	Default	Description
`PLUGIN_AU_SUBTYPE`	4-char	`Dflt`	AudioUnit subtype code. Must be exactly 4 characters.
`PLUGIN_AU_MANUFACTURER`	4-char	`Yup!`	AudioUnit manufacturer code. Must be exactly 4 characters.
`PLUGIN_AU_SANDBOX_SAFE`	ON\|OFF	ON	Sets `sandboxSafe` in the AU Info.plist. Set OFF if your plugin needs IOKit or other unsandboxed resources.

AAX-Specific#

Required when PLUGIN_CREATE_AAX is ON. If not provided, configuration fails with a fatal error.

Key	Type	Default	Description
`PLUGIN_AAX_MANUFACTURER_ID`	4-char	(required)	AAX manufacturer ID (e.g. `YUPP`).
`PLUGIN_AAX_PRODUCT_ID`	4-char	(required)	AAX product ID (e.g. `YpSy`).
`PLUGIN_AAX_PLUGIN_ID_NATIVE`	4-char	(required)	AAX native plugin ID (e.g. `YpSN`).
`PLUGIN_AAX_PLUGIN_ID_AUDIOSUITE`	4-char	(required)	AAX AudioSuite plugin ID (e.g. `YpSA`).
`PLUGIN_AAX_CATEGORY`	string	(auto)	AAX plugin category (e.g. `AAX_ePlugInCategory_Example`). If omitted, auto-derived from `PLUGIN_IS_SYNTH`.
`PLUGIN_AAX_PAGE_TABLE_FILE`	path	-	Path to an AAX page table resource file.

CLAP-Specific#

Key	Type	Default	Description
`PLUGIN_CLAP_FEATURES`	list	(auto)	Space-separated list of CLAP plugin features. If omitted, auto-derived from `IS_SYNTH` and `IS_MONO`.

Supported feature names:

Value	CLAP Constant
`instrument`	`CLAP_PLUGIN_FEATURE_INSTRUMENT`
`audio-effect`	`CLAP_PLUGIN_FEATURE_AUDIO_EFFECT`
`note-effect`	`CLAP_PLUGIN_FEATURE_NOTE_EFFECT`
`note-detector`	`CLAP_PLUGIN_FEATURE_NOTE_DETECTOR`
`analyzer`	`CLAP_PLUGIN_FEATURE_ANALYZER`
`synthesizer`	`CLAP_PLUGIN_FEATURE_SYNTHESIZER`
`mono`	`CLAP_PLUGIN_FEATURE_MONO`
`stereo`	`CLAP_PLUGIN_FEATURE_STEREO`
`surround`	`CLAP_PLUGIN_FEATURE_SURROUND`
`utility`	`CLAP_PLUGIN_FEATURE_UTILITY`

VST3-Specific#

Key	Type	Default	Description
`PLUGIN_VST3_CATEGORIES`	list	(auto)	Space-separated list of VST3 subcategories. Pipe-joined at compile time. If omitted, auto-derived from `IS_SYNTH` (`Instrument
`PLUGIN_VST3_AUTO_MANIFEST`	ON\|OFF	ON	Generate `moduleinfo.json` as a post-build step. Set OFF if the plugin needs custom post-processing before it can be loaded.

Common VST3 categories: Fx, Instrument, Analyzer, Delay, Distortion, Drum, Dynamics, EQ, Filter, Generator, Mastering, Modulation, Reverb, Sampler, Spatial, Stereo, Surround, Synth, Tools.

Multiple categories are pipe-joined automatically. Example: PLUGIN_VST3_CATEGORIES Fx Stereo produces "Fx|Stereo".

Codesigning & Entitlements#

All codesigning options are macOS-only and have no effect on other platforms.

Key	Type	Default	Description
`PLUGIN_CODESIGN_IDENTITY`	string	`-`	Codesigning identity. Default `-` means ad-hoc signing. Set to `"Developer ID Application: ..."` for distribution.
`PLUGIN_CODESIGN_TEAM`	string	-	10-character Apple Developer Team ID. When set, configures `DEVELOPMENT_TEAM` Xcode attribute.
`PLUGIN_APPLE_ENTITLEMENTS`	path	(built-in)	Path to a custom entitlements plist file. If omitted, the built-in AUv3 entitlements are used for AUv3 targets; other formats have no entitlements by default.
`PLUGIN_HARDENED_RUNTIME`	ON\|OFF	OFF	Enable macOS hardened runtime (required for notarization). Adds `--options runtime` to codesign.
`PLUGIN_HARDENED_RUNTIME_OPTIONS`	list	-	Space-separated list of entitlement keys to add to the entitlements plist when hardened runtime is enabled (e.g. `com.apple.security.device.audio-input`).

Copy & Install#

Key	Type	Default	Description
`PLUGIN_COPY_AFTER_BUILD`	ON\|OFF	ON	Automatically copy/symlink the built plugin to the system plugin directory after building.

Icons#

Key	Type	Default	Description
`PLUGIN_ICON_BIG`	path	-	Path to a large icon image file.
`PLUGIN_ICON_SMALL`	path	-	Path to a small icon image file.

Custom Plist Injection#

Key	Type	Default	Description
`PLUGIN_CUSTOM_PLIST`	list	-	Additional plist key-value strings to merge into the target’s Info.plist.

Dependencies#

Key	Type	Default	Description
`MODULES`	list	(required)	YUP module dependencies (e.g. `yup::yup_gui yup::yup_audio_processors`).
`DEFINITIONS`	list	-	Additional compile definitions applied to all format targets.
`OPTIONS`	list	-	Additional compile options applied to all format targets.
`LINK_OPTIONS`	list	-	Additional linker options applied to all format targets.
`ADDITIONAL_LIBRARIES`	list	-	Extra libraries to link into all format targets (in addition to `MODULES`).

`yup_standalone_app`#

yup_standalone_app(
    [KEY value]...
)

Creates a standalone executable application. Used internally by PLUGIN_CREATE_STANDALONE but can also be used independently for non-plugin GUI applications.

Arguments#

Key	Type	Default	Description
`TARGET_NAME`	string	(required)	Target name for the executable.
`TARGET_VERSION`	string	(required)	Version in `major.minor.patch` format.
`TARGET_CONSOLE`	ON\|OFF	OFF	Build a console app (no windowing/SDL, no macOS bundle).
`TARGET_IDE_GROUP`	string	-	IDE folder group name.
`TARGET_APP_NAMESPACE`	string	-	App namespace; the bundle id is `<namespace>.<TARGET_NAME>`.
`TARGET_CXX_STANDARD`	integer	`20`	C++ standard version.
`TARGET_ICON`	path	(built-in)	Path to an application icon image.
`TARGET_WHEEL`	ON\|OFF	OFF	Build as a loadable module (e.g. a Python wheel) instead of an executable.
`DEFINITIONS`	list	-	Additional compile definitions.
`COMPILE_OPTIONS`	list	-	Additional compile options.
`MODULES`	list	-	YUP module dependencies.
`SOURCES`	list	-	Additional source files.
`LINK_OPTIONS`	list	-	Additional linker options.
`BUNDLE_RESOURCES`	list	-	Files to bundle for runtime access via `File::getSpecialLocation (File::bundleDirectory)`, as `"local/path@relative/dest"` pairs. See `yup_add_bundled_resources()` below.

Note

yup_standalone_app derives the macOS/app bundle identifier from TARGET_APP_NAMESPACE (as <namespace>.<TARGET_NAME>). Unlike yup_audio_plugin it has no TARGET_APP_ID argument.

Emscripten / WebAssembly#

These arguments only affect the Emscripten build and are ignored elsewhere.

Key	Type	Default	Description
`INITIAL_MEMORY`	integer	`65536000`	Initial WASM heap size in bytes (`-sINITIAL_MEMORY`).
`MAXIMUM_MEMORY`	integer	(unset)	Maximum WASM heap size in bytes (`-sMAXIMUM_MEMORY`). Only applied when set; use with `ALLOW_MEMORY_GROWTH` to cap unbounded growth.
`PTHREAD_POOL_SIZE`	integer	`8`	Size of the pthread pool (`-sPTHREAD_POOL_SIZE`).
`STACK_SIZE`	integer	`2097152`	Stack size in bytes (`-sSTACK_SIZE`).
`CUSTOM_SHELL`	path	(built-in)	Custom Emscripten shell HTML (`--shell-file`).
`PRELOAD_FILES`	list	-	Files to preload into the virtual filesystem (`--preload-file`), e.g. `"local/path@/vfs/path"`.
`ENABLE_EMSCRIPTEN_WEBGPU`	boolean	`ON`	Enable the native WebGPU rendering backend via the Emdawnwebgpu port (`--use-port=emdawnwebgpu`). Per-target parameter on `yup_standalone_app`. Requires Emscripten 4.0.22+.
`ENABLE_EMSCRIPTEN_GL_DEBUGGING`	boolean	`OFF`	Enable OpenGL debugging assertions (`-sGL_ASSERTIONS=1 -sGL_DEBUG=1`). Per-target parameter on `yup_standalone_app`.

Apple#

Key	Type	Default	Description
`CUSTOM_PLIST`	path	(built-in)	Custom `Info.plist` template for the app bundle.

`yup_add_bundled_resources`#

yup_add_bundled_resources(<target_name>
    RESOURCES <path>@<relative-dest>...)

Bundles arbitrary files next to a target so they are read back at runtime through the normal File/FileInputStream API - via File::getSpecialLocation (File::bundleDirectory) - rather than compiled into the binary. Unlike yup_add_embedded_binary_resources, this does real file I/O at runtime (backed by AAssetManager on Android, with no first-run copy to disk), so bundled files stay read-only and are best suited to large or user-replaceable assets rather than tiny config blobs.

Each entry is a <source-path>@<relative-dest> pair, using the same convention as the PRELOAD_FILES argument above. relative-dest is the path getSpecialLocation (File::bundleDirectory).getChildFile (relative-dest) must be given to find the file again, and it may rename the file relative to its source name.

Arguments#

Key	Type	Default	Description
`<target_name>`	string	(required)	Target to bundle the resources with (first positional argument).
`RESOURCES`	list	(required)	`<source-path>@<relative-dest>` pairs.

Platform behavior#

Platform	Effect
macOS	`MACOSX_PACKAGE_LOCATION` is set to `Resources/<relative-dest-dir>`, so the file lands in the app/plugin bundle’s `Contents/Resources` folder, preserving the destination’s subdirectory structure.
iOS	`MACOSX_PACKAGE_LOCATION` is set to `<relative-dest-dir>` (no `Resources/` prefix) - iOS app bundles are flat and `[NSBundle resourcePath]` resolves to the bundle root itself, not a `Resources` subfolder.
Android	Copied into `${CMAKE_CURRENT_BINARY_DIR}/app/src/main/assets/<relative-dest>`, which the Android Gradle Plugin packages into the APK automatically - no manifest or `build.gradle` changes needed.
Emscripten	Bridged to `--preload-file=<source>@<relative-dest>`, the same mechanism `PRELOAD_FILES` uses.
Other desktop platforms	No-op - `bundleDirectory` there is the directory next to the executable, and desktop code typically reads assets straight from the source tree instead.

Normally called through yup_standalone_app’s BUNDLE_RESOURCES argument rather than directly; call it directly only when bundling resources with a target yup_standalone_app doesn’t own.

Example#

yup_standalone_app(
    # ...
    BUNDLE_RESOURCES
        "${CMAKE_CURRENT_LIST_DIR}/data/config.json@data/config.json"
        "${CMAKE_CURRENT_LIST_DIR}/data/logo.png@images/logo.png")

auto config = yup::File::getSpecialLocation (yup::File::bundleDirectory).getChildFile ("data/config.json");
auto stream = config.createInputStream();

`yup_add_embedded_binary_resources`#

yup_add_embedded_binary_resources(<library_name>
    OUT_DIR        <subdir>
    HEADER         <header_file_name>
    [NAMESPACE     <namespace>]
    RESOURCE_NAMES <symbol>...
    RESOURCES      <path>...)

Embeds one or more arbitrary binary files directly into the executable, with no runtime file I/O. It generates C++ source at configure time and produces a linkable OBJECT library that exposes each resource as a byte array. This is the portable way to ship assets - images, fonts, .riv/.lottie files, shader bundles, config blobs - including on platforms without a conventional filesystem (Android, WebAssembly).

For each entry, a matching pair of symbols is emitted into the given namespace:

extern const uint8_t     <RESOURCE_NAME>_data[];
extern const std::size_t <RESOURCE_NAME>_size;

Arguments#

Key	Type	Default	Description
`<library_name>`	string	(required)	Name of the generated `OBJECT` library target (first positional argument).
`OUT_DIR`	string	(required)	Subdirectory under the build tree where the generated `.cpp`/`.inc`/header are written.
`HEADER`	string	(required)	File name of the generated header declaring the symbols.
`NAMESPACE`	string	-	C++ namespace wrapping the declarations. Omit for the global namespace.
`RESOURCE_NAMES`	list	(required)	Symbol base names, one per resource. Paired positionally with `RESOURCES`.
`RESOURCES`	list	(required)	Source file paths to embed. Paired positionally with `RESOURCE_NAMES`.

RESOURCE_NAMES and RESOURCES are parallel lists: the n-th name is bound to the n-th file. The library is regenerated only when a resource’s bytes change, so incremental builds stay fast. The target is placed in the EmbeddedResources IDE folder.

Example#

yup_add_embedded_binary_resources(
    "${target_name}_binary_data"
    OUT_DIR BinaryData
    HEADER  BinaryData.h
    NAMESPACE MyApp
    RESOURCE_NAMES
        Settings
        Logo
    RESOURCES
        "resources/config/settings.json"
        "resources/images/logo.png")

# Link the object library into your target.
yup_standalone_app(
    # ...
    MODULES
        yup::yup_gui
        libpng
        "${target_name}_binary_data")   # << add the resources library

Consume the bytes at runtime through the generated header:

#include <BinaryData.h>

yup::MemoryInputStream stream (MyApp::Settings_data, MyApp::Settings_size, false);

auto result = yup::Image::loadFromData (
    yup::Span<const uint8_t> (MyApp::Logo_data, MyApp::Logo_size));

Tip

To compile and embed GPU shaders offline, use the higher-level yup_add_shader_bundle() helper, which builds a .ysl bundle at configure time and embeds it through this function. See Offline shader compilation.

Plugin Format-Specific Notes#

CLAP Features#

When PLUGIN_CLAP_FEATURES is not specified, features are auto-derived:

If PLUGIN_IS_SYNTH ON: instrument, synthesizer
If PLUGIN_IS_SYNTH OFF: audio-effect
If PLUGIN_IS_MONO ON: mono
If PLUGIN_IS_MONO OFF: stereo

When PLUGIN_CLAP_FEATURES IS specified, the auto-derived features are bypassed entirely and only the specified features are used.

VST3 Categories#

When PLUGIN_VST3_CATEGORIES is not specified, the category is auto-derived:

If PLUGIN_IS_SYNTH ON: Instrument|Synth
If PLUGIN_IS_SYNTH OFF: Fx

When PLUGIN_VST3_CATEGORIES IS specified, the auto-derived category is bypassed.

AAX SDK & IDs#

AAX plugin support requires the AAX SDK. Set YUP_AAX_SDK_ROOT (CMake variable or environment variable) to the root of the AAX SDK installation. If YUP_AAX_SDK_ROOT is not set, AAX targets are silently skipped.

All four AAX ID values (PLUGIN_AAX_MANUFACTURER_ID, PLUGIN_AAX_PRODUCT_ID, PLUGIN_AAX_PLUGIN_ID_NATIVE, PLUGIN_AAX_PLUGIN_ID_AUDIOSUITE) are required when AAX is enabled. If any is missing, configuration fails with a fatal error.

AU Subtype & Manufacturer#

The AU subtype and manufacturer codes must be exactly 4 characters each. These are used in the AudioComponents Info.plist entry for AUv2 and in the NSExtensionAttributes for AUv3.

AUv3 Entitlements#

AUv3 plugins require an entitlements plist. By default, YUP provides a built-in entitlements file at cmake/platforms/mac/AudioUnitV3_Entitlements.plist with:

App Sandbox enabled
Audio input access
MIDI access

Override with PLUGIN_APPLE_ENTITLEMENTS pointing to a custom .plist file.

Codesigning for Distribution#

For local development, ad-hoc signing (-) is sufficient. For distribution (notarization, App Store), you must set:

PLUGIN_CODESIGN_IDENTITY "Developer ID Application: Your Name (TEAMID)"
PLUGIN_CODESIGN_TEAM "ABCDE12345"
PLUGIN_HARDENED_RUNTIME ON

On macOS, PLUGIN_CODESIGN_TEAM also sets the DEVELOPMENT_TEAM Xcode attribute on the target.

Plugin Install Locations#

Plugins are automatically copied/symlinked after building when PLUGIN_COPY_AFTER_BUILD is ON (the default).

Format	macOS
CLAP	`~/Library/Audio/Plug-Ins/CLAP/`
VST3	`~/Library/Audio/Plug-Ins/VST3/`
AU	`~/Library/Audio/Plug-Ins/Components/`
AUv3	`~/Library/Audio/Plug-Ins/AppExtensions/`
AAX	`~/Library/Application Support/Avid/Audio/Plug-Ins/`

The YUP CMake API#

System Requirements#

Getting Started#

Using FetchContent#

Platform-Specific Build Commands#

Building universal binaries for macOS#

CMake Cache Options#

YUP_BUILD_EXAMPLES#

YUP_BUILD_TESTS#

YUP_BUILD_BENCHMARKS#

YUP_ENABLE_COVERAGE#

YUP_ENABLE_PLUGINVAL#

YUP_ENABLE_CLAP_VALIDATOR#

YUP_ENABLE_VST3_VALIDATOR#

YUP_ENABLE_AUVAL_VALIDATOR#

Functions#

yup_audio_plugin#

Target Globals#

Format Toggles#

Plugin Metadata#

AU-Specific#

AAX-Specific#

CLAP-Specific#

VST3-Specific#

Codesigning & Entitlements#

Copy & Install#

Icons#

Custom Plist Injection#

Dependencies#

yup_standalone_app#

Arguments#

Emscripten / WebAssembly#

Apple#

yup_add_bundled_resources#

Arguments#

Platform behavior#

Example#

yup_add_embedded_binary_resources#

Arguments#

Example#

Plugin Format-Specific Notes#

CLAP Features#

VST3 Categories#

AAX SDK & IDs#

AU Subtype & Manufacturer#

AUv3 Entitlements#

Codesigning for Distribution#

Plugin Install Locations#

`YUP_BUILD_EXAMPLES`#

`YUP_BUILD_TESTS`#

`YUP_BUILD_BENCHMARKS`#

`YUP_ENABLE_COVERAGE`#

`YUP_ENABLE_PLUGINVAL`#

`YUP_ENABLE_CLAP_VALIDATOR`#

`YUP_ENABLE_VST3_VALIDATOR`#

`YUP_ENABLE_AUVAL_VALIDATOR`#

`yup_audio_plugin`#

`yup_standalone_app`#

`yup_add_bundled_resources`#

`yup_add_embedded_binary_resources`#