Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/plugdata-team/plugdata/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers building plugdata from source on all supported platforms. Building from source allows you to customize the build, add your own externals, or contribute to development.

​
Prerequisites

​
Required Tools

  • CMake 3.21 or later (required for CLAP plugin support)
  • Git with submodule support
  • Python 3 interpreter
  • Platform-specific build tools:
    • macOS: Xcode or Xcode Command Line Tools
    • Windows: Visual Studio 2019 or 2022
    • Linux: GCC or Clang, Make

​
Linux Dependencies

On Linux, JUCE framework requires specific system dependencies. You must install these before building.
Refer to the JUCE Linux Dependencies documentation and use the full command to install all required packages. Typical dependencies include:
  • libasound2-dev
  • libx11-dev
  • libxrandr-dev
  • libxinerama-dev
  • libxcursor-dev
  • libfreetype6-dev
  • libwebkit2gtk-4.0-dev
  • libglu1-mesa-dev

​
Clone the Repository

1
Step 1: Clone with Submodules
2
The --recursive flag is essential as plugdata depends on multiple git submodules:
3
git clone --recursive https://github.com/plugdata-team/plugdata.git
cd plugdata
4
Step 2: Initialize Submodules (if already cloned)
5
If you cloned without --recursive, initialize submodules manually:
6
git submodule update --init --recursive

​
Build Configuration

​
Basic Build

1
Step 1: Create Build Directory
2
mkdir build
cd build
3
Step 2: Configure with CMake
4
Choose your generator based on platform:
5
Unix Makefiles
cmake .. -G"Unix Makefiles"
Xcode (macOS)
cmake .. -G"Xcode"
Visual Studio 2022
cmake .. -G"Visual Studio 17 2022" -A x64
Visual Studio 2019
cmake .. -G"Visual Studio 16 2019" -A x64
6
Step 3: Build
7
cmake --build .
8
For faster builds on multi-core systems:
9
cmake --build . -j8

​
CMake Build Options

Customize your build with CMake options using -D<OPTION>=<VALUE>:

​
Performance Options

OptionDefaultDescription
QUICK_BUILDOFFSkip slow-to-compile features (Gem, sfizz, ffmpeg) for faster iteration
CMAKE_BUILD_TYPEReleaseBuild type: Release, Debug, RelWithDebInfo

​
Feature Toggles

OptionDefaultDescription
ENABLE_GEMONEnable Gem graphics and video library
ENABLE_SFIZZONEnable sfizz library for [sfz~] object
ENABLE_FFMPEGONEnable FFmpeg for audio/video file playback
ENABLE_PERFETTOOFFEnable Perfetto performance profiling (advanced)
ENABLE_TESTINGOFFEnable end-to-end test suite

​
Advanced Options

OptionDefaultDescription
ENABLE_ASANOFFEnable AddressSanitizer for debugging memory issues
ENABLE_WAYLANDOFFEnable native Wayland support (Linux, experimental)
MACOS_LEGACYOFFSupport older macOS versions (10.11+, x86_64 only)

​
Example Configurations

cmake .. -DQUICK_BUILD=1 -DCMAKE_BUILD_TYPE=Debug

​
Performance Profiling with Perfetto

Perfetto provides detailed performance analysis of DSP and UI operations.
1
Step 1: Enable Perfetto
2
cmake .. -DENABLE_PERFETTO=1 -DCMAKE_BUILD_TYPE=Release
3
Always profile in Release mode for accurate performance measurements.
4
Step 2: Instrument Code
5
Add tracing to functions you want to profile:
6
void myProcessingFunction() {
    TRACE_COMPONENT();  // Automatically traces this function
    // ... your code ...
}
7
Step 3: Automated Instrumentation
8
Use the Python script to automatically add trace points:
9
python3 Resources/Scripts/add_perfetto_tracepoints.py Source/**/*.cpp
10
Requires llvm >= 19.1.3 and compatible libclang Python package.
11
Step 4: Analyze Results
12
Open traces at ui.perfetto.dev or follow the Melatonin Perfetto guide.

​
Platform-Specific Notes

​
macOS

Deployment Targets:
  • Standard: macOS 10.15+ (Universal Binary: arm64 + x86_64)
  • Legacy: macOS 10.11+ (x86_64 only) with MACOS_LEGACY=ON
  • iOS: iOS 12.0+
Metal Rendering: Metal is enabled by default on macOS for better performance. Use NANOVG_METAL_IMPLEMENTATION=OFF to disable.

​
Windows

Visual Studio:
  • Tested with VS 2019 and VS 2022
  • Use x64 architecture: -A x64
  • ASIO support is automatically included
Runtime Library: Uses static runtime linking: MultiThreaded[Debug]

​
Linux

Audio Backends:
  • ALSA (enabled by default)
  • JACK (enabled by default)
Wayland Support (Experimental): 
cmake .. -DENABLE_WAYLAND=1
Requires: wayland-client, wayland-cursor, xkbcommon, libdecor-0, egl

​
BSD

On BSD systems, Gem and sfizz are automatically disabled due to compatibility issues.

​
Build Outputs

After building, plugins and standalone app are located in: 
Plugins/
├── Standalone/
│   └── plugdata          # Standalone application
├── VST3/
│   ├── plugdata.vst3     # Instrument plugin
│   └── plugdata-fx.vst3  # Effect plugin
├── AU/                   # macOS only
│   ├── plugdata.component
│   ├── plugdata-fx.component
│   └── plugdata-midi.component
├── LV2/
│   ├── plugdata.lv2
│   └── plugdata-fx.lv2
└── CLAP/
    ├── plugdata.clap
    └── plugdata-fx.clap

​
Installing

To install system-wide: 
sudo cmake --install .
Platform-specific install locations are configured in CMakeLists.txt (lines 887-932).

​
Troubleshooting

​
CMake Version Too Old

Warning: Building CLAP plugins requires at least cmake 3.21
Solution: Update CMake or disable CLAP builds (VST3/AU/LV2 still work).

​
Submodules Not Initialized

Error: Missing required dependencies
Solution: Run git submodule update --init --recursive

​
Python Not Found

FATAL_ERROR: Python3 not found - required for build scripts
Solution: Install Python 3 and ensure it’s in your PATH.

​
Linux Missing Dependencies

Solution: Install all JUCE dependencies as listed in the Linux Dependencies documentation.

​
Next Steps

Adding Externals

Learn how to add custom Pure Data externals

Performance Optimization

Optimize your patches for better performance

Build docs developers (and LLMs) love

Get started for freeTalk to us