Meter

Pamplejuce is a ~~template~~ lifestyle for creating and building JUCE plugins in 2023.

Out of the box, it:

1. Supports C++20.
2. Uses JUCE 7.x as a submodule tracking develop.
3. Relies on CMake 3.24.1 and higher for cross-platform building.
4. Has Catch2 v3.4.0 for the test framework and runner.
5. Includes a Tests target and a Benchmarks target some examples to get started quickly.
6. Has Melatonin Inspector installed as a JUCE module to help relieve headaches when building plugin UI.

It also has integration with GitHub Actions, specifically:

1. Building and testing cross-platform (linux, macOS, Windows) binaries
2. Running tests and benchmarks in CI
3. Running pluginval 1.x against the binaries for plugin validation
4. Config for installing Intel IPP
5. Code signing and notarization on macOS
6. Windows EV/OV code signing via Azure Key Vault

It also contains:

1. A .gitignore for all platforms.
2. A .clang-format file for keeping code tidy.
3. A VERSION file that will propagate through JUCE and your app.
4. A ton of useful comments and options around the CMake config.

How does this all work at a high level?

If you are new to CMake, I suggest you read up about JUCE and CMmake on my blog!.

Can I see some examples?

Lots of people have used Pamplejuce as their starting place for their private plugin projects.

Two amazing public examples (complete with signed binaries) are:

• Valentine, a compressor plugin by Jose Diaz Rohena
• Maim, an mp3 distortion plugin by Arden Butterfield

Setting up for YOUR project

This is a template repo!

That means the easiest thing to do is click "Use this template" here or at the top of the page to get your own repo with all the code here.

After you've created a new repo from the template, you have a checklist of things to do to customize for your project.

• [ ] git clone your new repo (if you make it private, see the warning below about GitHub Actions minutes)

• [ ] Download CMAKE if you aren't already using it (Clion and VS2022 both have it bundled, so you can skip this step in those cases).

• [ ] Populate the JUCE by running git submodule update --init in your repository directory. By default, this will track JUCE's develop branch, which is a good default until you are at the point of releasing a plugin. It will also pull in the CMake needed and an example module, my component inspector.

• [ ] Replace Pamplejuce with the name of your project in CMakeLists.txt where the PROJECT_NAME variable is first set. Make this all one word, no spaces.

• [ ] Adjust which plugin formats you want built as needed (VST3, AU, etc).

• [ ] Set the correct flags for your plugin juce_add_plugin. Check out the API https://github.com/juce-framework/JUCE/blob/master/docs/CMake%20API.md and be sure to change things like PLUGIN_CODE and PLUGIN_MANUFACTURER_CODE and everything that says Change me!.

• [ ] Build n' Run! If you want to generate an Xcode project, run cmake -B Builds -G Xcode. Or just open the project in CLion or VS2022. Running the standalone might be easiest, but you can also build the AudioPluginHost that comes with JUCE. Out of the box, Pamplejuce's VST3/AU targets should already be pointing to it's built location.

• [ ] If you want to package and code sign, you'll want to take a look at the packaging/ directory add assets and config that match your product. Otherwise, you can delete the GitHub Action workflow steps that handle packaging (macOS will need code signing steps to work properly).

This is what you will see when it's built, the plugin displaying its version number with a button that opens up the Melatonin Inspector:

FAQ

[!TIP] Don't see your question here? Open an issue!

Where do I put new .h / .cpp files?

New source files go in /source. All .h and .cpp files in that directory will be available to include in your plugin target and your tests.

Tests go in /tests. Just add .cpp files there and they will be available in the Tests target.

[!NOTE] If you use an overeager, CMake-aware IDE (like CLion) it might prompt you to manually add files to a CMake target. This is not needed.

I recommend not stuffing everything into the boilerplate PluginEditor/PluginProcessor files. Sure, go ahead make a mess at first. But then clean them up and just include your source from there.

How do I add another module?

Additional 3rd party JUCE modules go in /modules. You can add third party git submodules there (like the inspector is set up). Remember to not only call juce_add_module but add it to the target_link_libraries list!

I (and others, including some of the JUCE team) recommend moving as much as your application code into modules as possible. For example, if you tend to roll your own widgets, pop those into a module, you'll thank yourself later.

A few reasons to do so:

• Re-usability. You can use modules across projects.
• Testability. You can test modules in isolation from each other. When sticking test in modules, it's common to guard .cpp files with something like #ifdef RUN_MY_TESTS and set via target_compile_definitions in Tests target.
• Sanity. You can keep the root project tidy, focused on the application logic.
• Compile-friendliness. Each JUCE module is its own compilation unit. If you change a file in a module, only that one module needs to rebuild. It also means you can work on only the module in a separate CMake project, which is a very nice/fast life.

Don't worry about all of this if you are new to JUCE. Just keep it in mind as you grow.

What's the deal with BinaryData?

Your binary data CMake target is called Assets.

You need to include BinaryData.h to access it.

[!IMPORTANT] You may have to configure the project (just hit build in your IDE) to build juceaide before the header will be available.

How I get clang-format working

There are a huge number of benefits to automatic formatting of code, including the very obvious one of guaranteed consistency and therefore readability. But it also saves brain cycles and can prevent team bike-shedding.

@CrushedPixel, who prompted me to write this FAQ entry says

Formatting is a really key component and you’re providing it out of the box. I have learned to swallow my pride when it comes to my own preferences, so I’m okay as long as I can just hit save and the IDE does the deed for me

The included .clang-format file will get you very close to the JUCE style guide.

On CLion, see this guide on how to clang format on save or on key command (my preference).

On VS 2022, it's enabled by default.

On Xcode, see this plugin (disclaimer, when I was still using Xcode I couldn't find a great solution, which is part of why I switched to CLion).

What's the deal with code signing and notarization?

This repo code signs Windows via Azure Key Vault. Read more about how to set it up blog.

It also code signs and notarizes on macOS. Again, you can read my article for details.

How do I update my Pamplejuce-based project?

1. Update with the latest CMake version listed here, or the latest version supported by your toolchain like VS or Clion.
2. Update JUCE with git submodule update --remote --merge JUCE
3. Update the inspector with git submodule update --remote --merge modules/melatonin_inspector
4. Check for an IPP update from Intel.
5. If you want to update to the latest CMake config Pamplejuce uses, first check the repository's CHANGELOG to make sure you are informed of any breaking changes. Then. git submodule update --remote --merge cmake. Unfortunately, you'll have to manually compare CMakeLists.txt, but it should be pretty easy to see what changed.

How to Cut A GitHub Release

Cut a release with downloadable assets by creating a tag starting with v and pushing it to GitHub. Note that you currently must push the tag along with an actual commit.

I recommend the workflow of bumping the VERSION file and then pushing that as a release, like so:

# edit VERSION
git commit -m "Releasing v0.0.2"
git tag v0.0.2
git push --tags

[!IMPORT