Existing JUCE Developers
Already have a JUCE project? Here’s how to integrate it with BeatConnect’s build infrastructure for automated signing, notarization, and distribution.
Prerequisites
- JUCE 7.0+ (earlier versions may work but are untested)
- CMake-based project (or migrate from Projucer)
- Git repository on GitHub
Integration Checklist
- CMake project structure is correct
- All dependencies are self-contained or fetchable
- JUCE is accessible (submodule, FetchContent, or system)
- Project builds locally without errors
- GitHub App installed and repository linked
CMake Project Requirements
Minimum CMakeLists.txt
cmake_minimum_required(VERSION 3.22)
project(YourPlugin VERSION 1.0.0)
# Find or include JUCE
add_subdirectory(external/JUCE)
# OR
# find_package(JUCE CONFIG REQUIRED)
# Define the plugin
juce_add_plugin(YourPlugin
PLUGIN_MANUFACTURER_CODE Xxxx # 4-char unique code
PLUGIN_CODE Yyyy # 4-char unique code
FORMATS VST3 AU Standalone
PRODUCT_NAME "Your Plugin"
COMPANY_NAME "Your Company"
BUNDLE_ID "com.yourcompany.yourplugin"
PLUGIN_NAME "Your Plugin"
PLUGIN_MANUFACTURER_NAME "Your Company"
NEEDS_MIDI_INPUT FALSE
NEEDS_MIDI_OUTPUT FALSE
IS_SYNTH FALSE
IS_MIDI_EFFECT FALSE
)
# Add sources
target_sources(YourPlugin PRIVATE
Source/PluginProcessor.cpp
Source/PluginProcessor.h
Source/PluginEditor.cpp
Source/PluginEditor.h
)
# Link JUCE modules
target_link_libraries(YourPlugin
PRIVATE
juce::juce_audio_basics
juce::juce_audio_devices
juce::juce_audio_formats
juce::juce_audio_plugin_client
juce::juce_audio_processors
juce::juce_audio_utils
juce::juce_core
juce::juce_data_structures
juce::juce_events
juce::juce_graphics
juce::juce_gui_basics
juce::juce_gui_extra
PUBLIC
juce::juce_recommended_config_flags
juce::juce_recommended_lto_flags
juce::juce_recommended_warning_flags
)JUCE Configuration Options
Plugin Codes
Every plugin needs unique 4-character codes:
PLUGIN_MANUFACTURER_CODE Btcn # Your company code (register with Steinberg for VST3)
PLUGIN_CODE Mypl # Unique per-pluginVST3 Categories
Help DAWs categorize your plugin:
VST3_CATEGORIES "Fx" "Dynamics"
# Options: Fx, Instrument, Analyzer, Delay, Distortion, Dynamics,
# EQ, Filter, Generator, Mastering, Modulation, Network,
# Pitch Shift, Restoration, Reverb, Sampler, Spatial,
# Stereo, Surround, Synth, Tools, Up-DownmixAU Properties
For Audio Units on macOS:
AU_MAIN_TYPE "kAudioUnitType_Effect"
# Options: kAudioUnitType_Effect, kAudioUnitType_MusicDevice,
# kAudioUnitType_Generator, kAudioUnitType_MIDIProcessorHandling Dependencies
Option 1: Git Submodules (Recommended)
# Add JUCE as a submodule
git submodule add https://github.com/juce-framework/JUCE.git external/JUCE
# Add other dependencies
git submodule add https://github.com/other/lib.git external/libCMakeLists.txt:
add_subdirectory(external/JUCE)
add_subdirectory(external/lib)Option 2: FetchContent
include(FetchContent)
FetchContent_Declare(
juce
GIT_REPOSITORY https://github.com/juce-framework/JUCE.git
GIT_TAG 7.0.9
)
FetchContent_MakeAvailable(juce)Note: FetchContent adds to build time but ensures version consistency.
Option 3: Pre-installed JUCE
find_package(JUCE CONFIG REQUIRED)Warning: This requires JUCE to be installed on the build machine. Not recommended for cloud builds.
Build Configuration
Compiler Flags
BeatConnect uses these default flags:
# Release builds
CMAKE_BUILD_TYPE=Release
# macOS specific
CMAKE_OSX_ARCHITECTURES="x86_64;arm64" # Universal Binary
CMAKE_OSX_DEPLOYMENT_TARGET="10.13" # Minimum macOS version
# Windows specific
CMAKE_GENERATOR="Visual Studio 17 2022"
CMAKE_GENERATOR_PLATFORM="x64"Custom Flags
Override defaults in your CMakeLists.txt:
# Minimum macOS version
set(CMAKE_OSX_DEPLOYMENT_TARGET "11.0" CACHE STRING "")
# Disable specific warnings
target_compile_options(YourPlugin PRIVATE
$<$<CXX_COMPILER_ID:AppleClang>:-Wno-deprecated-declarations>
$<$<CXX_COMPILER_ID:MSVC>:/wd4996>
)Resource Files
Icons and Images
# Add binary resources
juce_add_binary_data(YourPluginData
SOURCES
Resources/logo.png
Resources/background.jpg
)
target_link_libraries(YourPlugin PRIVATE YourPluginData)Presets and Data
For bundled presets:
juce_add_binary_data(YourPluginPresets
NAMESPACE Presets
SOURCES
Presets/Default.xml
Presets/Warm.xml
Presets/Bright.xml
)Common Integration Issues
Issue: “JUCE not found”
Cause: JUCE path incorrect or submodule not initialized.
Fix:
git submodule update --init --recursiveIssue: “Unknown CMake command juce_add_plugin”
Cause: JUCE not properly included before use.
Fix: Ensure add_subdirectory(external/JUCE) comes before juce_add_plugin().
Issue: “Universal binary fails to build”
Cause: Some dependencies don’t support arm64.
Fix:
# Build Intel-only if needed
set(CMAKE_OSX_ARCHITECTURES "x86_64" CACHE STRING "")Or fix the dependency to support arm64.
Issue: “Link errors on Windows”
Cause: Missing Windows libraries or wrong runtime.
Fix:
# Ensure static runtime for Windows
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")Recommended Project Structure
your-plugin/
├── CMakeLists.txt
├── CMakePresets.json # Optional: build presets
├── .gitmodules # Submodule definitions
├── .github/
│ └── workflows/ # Optional: your own CI
├── external/
│ └── JUCE/ # JUCE as submodule
├── Source/
│ ├── PluginProcessor.h
│ ├── PluginProcessor.cpp
│ ├── PluginEditor.h
│ ├── PluginEditor.cpp
│ └── DSP/ # Your DSP code
│ ├── Filter.h
│ ├── Filter.cpp
│ └── ...
├── Resources/
│ ├── logo.png
│ └── presets/
├── Tests/ # Unit tests (optional)
│ └── PluginTests.cpp
└── README.md
Version Numbering
BeatConnect uses semantic versioning:
project(YourPlugin VERSION 1.2.3)| Release Type | Version Change |
|---|---|
| Major | 1.0.0 → 2.0.0 |
| Minor | 1.0.0 → 1.1.0 |
| Patch | 1.0.0 → 1.0.1 |
| Development | 1.0.0-dev.1 |
Configure in the build trigger:
Release Type: patch
Result: 1.0.0 → 1.0.1
Testing Before Cloud Build
Always test locally first:
# macOS
mkdir build && cd build
cmake .. -GXcode -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
cmake --build . --config Release
# Windows (in Visual Studio Developer Command Prompt)
mkdir build && cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config ReleaseMulti-Plugin Repositories
For repositories with multiple plugins:
# Root CMakeLists.txt
cmake_minimum_required(VERSION 3.22)
project(MyPlugins)
add_subdirectory(external/JUCE)
add_subdirectory(plugins/PluginA)
add_subdirectory(plugins/PluginB)
add_subdirectory(plugins/PluginC)Each plugin has its own CMakeLists.txt:
# plugins/PluginA/CMakeLists.txt
juce_add_plugin(PluginA
PLUGIN_CODE PlgA
...
)Note: Multi-plugin repos build all plugins in a single build. Contact us for separate builds per plugin.
Optimization Tips
1. Reduce Build Time
# Disable unused formats
FORMATS VST3 AU # Not Standalone, AAX unless needed
# Use precompiled headers
target_precompile_headers(YourPlugin PRIVATE
<juce_audio_processors/juce_audio_processors.h>
<juce_gui_basics/juce_gui_basics.h>
)2. Reduce Plugin Size
# Enable LTO
set_target_properties(YourPlugin PROPERTIES INTERPROCEDURAL_OPTIMIZATION TRUE)
# Strip symbols (handled by code signing, but you can do it early)
target_compile_options(YourPlugin PRIVATE $<$<CONFIG:Release>:-g0>)3. Faster Debug Builds
# For local development only
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
set(CMAKE_OSX_ARCHITECTURES "arm64") # Build only for your Mac
endif()