Migrating from Projucer

BeatConnect requires CMake for cloud builds. If you’re using Projucer, this guide will help you migrate.

Why Migrate?

Projucer	CMake
GUI-based configuration	Text-based, version controlled
Manual IDE project generation	Cross-platform build configuration
Not supported by CI/CD	Industry standard for automation
JUCE-specific	Works with any C++ library

Before You Start

Backup your project — Create a branch or copy
Note your settings — Export or screenshot Projucer settings
Test locally — Ensure project builds in Projucer first

Step-by-Step Migration

Step 1: Create CMakeLists.txt

Create a CMakeLists.txt file in your project root:

cmake_minimum_required(VERSION 3.22)
project(YourPlugin VERSION 1.0.0)
 
# JUCE location - update path as needed
add_subdirectory(JUCE)
 
# Your plugin configuration goes here (see Step 2)

Step 2: Translate Projucer Settings

Open your .jucer file and translate each section:

Project Settings

Projucer:

Project Name: My Plugin
Project Version: 1.0.0
Bundle Identifier: com.mycompany.myplugin
Plugin Manufacturer: My Company
Plugin Manufacturer Code: Myco
Plugin Code: Mypl

CMake:

juce_add_plugin(MyPlugin
    VERSION 1.0.0
    BUNDLE_ID "com.mycompany.myplugin"
    COMPANY_NAME "My Company"
    PLUGIN_MANUFACTURER_CODE Myco
    PLUGIN_CODE Mypl
    PRODUCT_NAME "My Plugin"
)

Plugin Characteristics

Projucer:

Plugin is a Synth: No
Plugin Midi Input: Yes
Plugin Midi Output: No
Midi Effect Plugin: No

CMake:

juce_add_plugin(MyPlugin
    # ...
    IS_SYNTH FALSE
    NEEDS_MIDI_INPUT TRUE
    NEEDS_MIDI_OUTPUT FALSE
    IS_MIDI_EFFECT FALSE
)

Plugin Formats

Projucer:

Build VST3: Yes
Build AU: Yes
Build AUv3: No
Build AAX: No
Build Standalone: Yes

CMake:

juce_add_plugin(MyPlugin
    # ...
    FORMATS VST3 AU Standalone
)

Source Files

Projucer:

Source/PluginProcessor.cpp
Source/PluginProcessor.h
Source/PluginEditor.cpp
Source/PluginEditor.h

CMake:

target_sources(MyPlugin
    PRIVATE
        Source/PluginProcessor.cpp
        Source/PluginProcessor.h
        Source/PluginEditor.cpp
        Source/PluginEditor.h
)

JUCE Modules

Projucer:

Modules:
  juce_audio_basics
  juce_audio_devices
  juce_audio_formats
  juce_audio_plugin_client
  juce_audio_processors
  juce_core
  juce_graphics
  juce_gui_basics

CMake:

target_link_libraries(MyPlugin
    PRIVATE
        juce::juce_audio_basics
        juce::juce_audio_devices
        juce::juce_audio_formats
        juce::juce_audio_plugin_client
        juce::juce_audio_processors
        juce::juce_core
        juce::juce_graphics
        juce::juce_gui_basics
)

Step 3: Add JUCE as a Submodule

# Remove existing JUCE folder if it's not a submodule
rm -rf JUCE
 
# Add as a submodule
git submodule add https://github.com/juce-framework/JUCE.git JUCE
 
# Or if JUCE is in a different location
git submodule add https://github.com/juce-framework/JUCE.git external/JUCE

Update CMakeLists.txt path:

add_subdirectory(external/JUCE)

Step 4: Handle Binary Resources

Projucer binary resources:

Resources/Background.png
Resources/Logo.svg

CMake:

juce_add_binary_data(MyPluginData
    SOURCES
        Resources/Background.png
        Resources/Logo.svg
)
 
target_link_libraries(MyPlugin PRIVATE MyPluginData)

Step 5: Preprocessor Definitions

Projucer:

Extra Preprocessor Definitions:
  MY_FEATURE=1
  DEBUG_MODE=0

CMake:

target_compile_definitions(MyPlugin
    PRIVATE
        MY_FEATURE=1
        DEBUG_MODE=0
)

Step 6: Compiler Flags

Projucer Extra Compiler Flags:

-Wall
-Wextra

CMake:

target_compile_options(MyPlugin
    PRIVATE
        $<$<CXX_COMPILER_ID:AppleClang,Clang,GNU>:-Wall -Wextra>
        $<$<CXX_COMPILER_ID:MSVC>:/W4>
)

Step 7: Linker Settings

Projucer Extra Libraries (macOS):

Accelerate
CoreAudio

CMake:

if(APPLE)
    target_link_libraries(MyPlugin
        PRIVATE
            "-framework Accelerate"
            "-framework CoreAudio"
    )
endif()

Complete Migration Example

Original Projucer Project

<!-- MyPlugin.jucer (key settings) -->
<JUCERPROJECT name="My Plugin" version="1.0.0"
              bundleIdentifier="com.mycompany.myplugin"
              pluginManufacturer="My Company"
              pluginManufacturerCode="Myco"
              pluginCode="Mypl"
              pluginIsSynth="0"
              pluginWantsMidiIn="1"
              pluginProducesMidiOut="0"
              pluginIsMidiEffectPlugin="0"
              buildVST3="1"
              buildAU="1"
              buildStandalone="1">
  <MODULES>
    <MODULE id="juce_audio_basics"/>
    <MODULE id="juce_audio_devices"/>
    <MODULE id="juce_audio_formats"/>
    <MODULE id="juce_audio_plugin_client"/>
    <MODULE id="juce_audio_processors"/>
    <MODULE id="juce_audio_utils"/>
    <MODULE id="juce_core"/>
    <MODULE id="juce_graphics"/>
    <MODULE id="juce_gui_basics"/>
  </MODULES>
</JUCERPROJECT>

Migrated CMake Project

cmake_minimum_required(VERSION 3.22)
project(MyPlugin VERSION 1.0.0)
 
add_subdirectory(external/JUCE)
 
juce_add_plugin(MyPlugin
    # Identification
    PLUGIN_MANUFACTURER_CODE Myco
    PLUGIN_CODE Mypl
    BUNDLE_ID "com.mycompany.myplugin"
 
    # Names
    PRODUCT_NAME "My Plugin"
    COMPANY_NAME "My Company"
    PLUGIN_NAME "My Plugin"
 
    # Characteristics
    IS_SYNTH FALSE
    NEEDS_MIDI_INPUT TRUE
    NEEDS_MIDI_OUTPUT FALSE
    IS_MIDI_EFFECT FALSE
 
    # Formats
    FORMATS VST3 AU Standalone
)
 
# Source files
target_sources(MyPlugin
    PRIVATE
        Source/PluginProcessor.cpp
        Source/PluginProcessor.h
        Source/PluginEditor.cpp
        Source/PluginEditor.h
)
 
# Binary resources
juce_add_binary_data(MyPluginData
    SOURCES
        Resources/Background.png
)
 
# Link everything
target_link_libraries(MyPlugin
    PRIVATE
        MyPluginData
        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_graphics
        juce::juce_gui_basics
    PUBLIC
        juce::juce_recommended_config_flags
        juce::juce_recommended_lto_flags
        juce::juce_recommended_warning_flags
)

Testing Your Migration

Build Locally

# macOS
mkdir build && cd build
cmake .. -GXcode
cmake --build . --config Release
 
# Windows (Developer Command Prompt)
mkdir build && cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release

Verify Plugin Loads

Find built plugins in build/MyPlugin_artefacts/
Copy to plugin folder:
- macOS VST3: ~/Library/Audio/Plug-Ins/VST3/
- macOS AU: ~/Library/Audio/Plug-Ins/Components/
- Windows VST3: C:\Program Files\Common Files\VST3\
Scan in your DAW
Test all functionality

Common Migration Issues

”Module not found”

Error:

CMake Error: juce::juce_audio_basics not found

Fix: Ensure JUCE is added before using it:

add_subdirectory(external/JUCE)  # Before juce_add_plugin

“Cannot find source file”

Error:

CMake Error: Cannot find source file: Source/PluginProcessor.cpp

Fix: Check paths are relative to CMakeLists.txt location:

target_sources(MyPlugin PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/Source/PluginProcessor.cpp
)

“Binary resource not found”

Error:

error: 'BinaryData.h' file not found

Fix: Link binary data target and use correct namespace:

juce_add_binary_data(MyPluginData SOURCES Resources/image.png)
target_link_libraries(MyPlugin PRIVATE MyPluginData)

“Plugin code not unique”

Warning:

Plugin code 'Plgn' is not unique

Fix: Use unique 4-character codes:

PLUGIN_MANUFACTURER_CODE Abcd  # Your company
PLUGIN_CODE Xyz1               # This specific plugin

Keeping Projucer (Optional)

You can keep both during transition:

project/
├── CMakeLists.txt          # For BeatConnect builds
├── MyPlugin.jucer          # For local Projucer use
├── Source/                 # Shared source files
└── external/JUCE/          # JUCE (submodule for CMake)

Note: Keep configurations in sync manually. We recommend fully migrating to CMake once verified.

Next Steps

Test local builds on macOS and Windows
Connect your repository
Run your first cloud build
Remove .jucer file once confident in CMake setup

BeatConnect Docs

Explorer

Migrating from Projucer

Migrating from Projucer

Why Migrate?

Before You Start

Step-by-Step Migration

Step 1: Create CMakeLists.txt

Step 2: Translate Projucer Settings

Project Settings

Plugin Characteristics

Plugin Formats

Source Files

JUCE Modules

Step 3: Add JUCE as a Submodule

Step 4: Handle Binary Resources

Step 5: Preprocessor Definitions

Step 6: Compiler Flags

Step 7: Linker Settings

Complete Migration Example

Original Projucer Project

Migrated CMake Project

Testing Your Migration

Build Locally

Verify Plugin Loads

Common Migration Issues

”Module not found”

“Cannot find source file”

“Binary resource not found”

“Plugin code not unique”

Keeping Projucer (Optional)

Next Steps

Graph View

Table of Contents

Backlinks