Pamplejuce is a template lifestyle for creating and building JUCE plugins in 2022.
Out of the box, it supports:
- C++20
- JUCE 7.x as a submodule tracking develop
- CMake 3.21 for building cross-platform
- Catch2 v3.1.0 as the test framework and runner
- pluginval 1.x for plugin validation
- GitHub Actions config for building binaries, running Catch2 tests and pluginval,artifact building on the Windows, Linux and macOS platforms, including code signing and notarization on macOS and Windows EV/OV code signing via Azure Key Vault
It also contains:
- Proper
.gitignorefor all platforms - A
.clang-formatfile - A
VERSIONfile that will propagate through to JUCE and your app.
Read up about JUCE and CMmake on my blog!.
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.
For an example of a plugin that uses this repo, check out Load Monster!.
After you've created a new repo:
-
git cloneyour 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 latest JUCE by running
git submodule update --initin your repository directory. By default, this will track JUCE'sdevelopbranch, which IMO is what you want until you are at the point of releasing a plugin. -
Replace
Pamplejucewith the name of your project in CMakeLists.txt line 5, where thePROJECT_NAMEvariable is set. Make this all one word, no spaces. -
Pick which formats you want built on line 8.
-
Set the correct flags for your plugin under
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 likePLUGIN_CODEandPLUGIN_MANUFACTURER_CODE. -
Rename
AudioPluginAudioProcessorto your plugin name in the code. -
If you are packaging and code signing, you'll want to take a look at the packaging/ directory and add assets and config that match your product. Otherwise you can delete the steps which do this.
- Your tests will be in "Tests" and you can just add new .cpp files there.
- Your binary data target is called "Assets"
You can 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
I'll work on making this less awkward...
Releases are set to prerelease, which means that uploaded release assets are visible to other users, but it's not explicitly listed as the latest release until changed in the GitHub UI.
This repo codesigns Windows via Azure Key Vault, read more about how to do that on my blog.
It also code signs and notarizes macOS, blog article coming soon, but there are many more examples of this in the wild.
-
⚠️ GitHub gives you 2000 or 3000 free GitHub Actions "minutes" for private projects, but they actually bill 2x the number of minutes you use on Windows and 10x on MacOS. -
There's a
VERSIONfile in the root that you can treat as the main place to bump the version. -
You might feel disincentivized to push to a private repo due to burning minutes. You can push a commit with
[ci skip]in the message if you are doing things like updating the README. You have a few other big picture options, like doing testing/pluginval only on linux and moving everything else to release. The tradeoff is you won't be sure everything is happy on all platforms until the time you are releasing, which is the last place you really want friction. By default, multiple commits in quick succession will cancel the earlier builds.
It can be confusing, as the documentation is a big fragmented.
- Things in double curly braces like
${{ matrix.name }}are called "contexts or expressions" and can be used to get, set, or perform simple operations. - In "if" conditions you can omit the double curly braces, as the whole condition is evaluated as an expression:
if: contains(github.ref, 'tags/v') - You can set variables for the whole workflow to use in "env"
- Reading those variables is done with the env context when you are inside a
with,name, orif:${{ env.SOME_VARIABLE }} - Inside of
run, you have access to bash ENV variables in addition to contexts/expressions. That means$SOME_VARIABLEor${SOME_VARIABLE}will work but only when using bash and not while using powershell on windows. The version with curly braces (variable expansion) is often used when the variable is forming part of a larger string to avoid ambiguity. Be sure that the ENV variable was set properly in the workflow/job/step before you use it. And if you need the variable to be os-agnostic, use the env context.
- Update with the latest CMake version listed here, or the latest version supported by your toolchain like VS or Clion.
- Update JUCE with
git submodule update --remote --merge - (unfortunately) to get updates to the CMakesList.txt you'll have to manually compare, as I assume you made a bunch of changes. In the future, I may move most of the cmake magic into helpers to keep the main CMakesList.txt cleaner.
- The "Modern CMake" gitbook which also has a section on https://cliutils.gitlab.io/modern-cmake/chapters/testing/catch.html.
- Effective Modern CMake
- JUCE's announcement of native CMake support
- Eyalamir Music's JUCE / CMake prototype repository
- Christian Adam's HelloWorld CMake and ccache repo
- Maxwell Pollack's JUCE CMake + GitHub Actions repo
- Oli Larkin's PDSynth iPlug2 template
- Running pluginval in CI