gen~
Plugin Export
This is an example project that should help you get started with building your
own VST3 plugins and iOS applications with the help of the code-export feature
of gen~
, part of Max 8 made by
Cycling '74.
It is based on the JUCE Framework. Please be aware that the JUCE has its own license terms (mostly GPL with the availability of commercial licenses). See their website for further details.
With the release of Max 7.2.6 the licensing terms of code exported from gen also changed. This article addresses this change and will help you understand how it might affect you.
CMake
As of v2.1.0 (f2de092ea
), gen-plugin-export
uses CMake to build plugins.
If you are experiencing issues with CMake and would like to try using the
Projucer, you can check out a previous version of this project and use it
instead (e.g. git checkout v2.0.4
).
Prerequisites
- Download and install CMake. Version 3.18 or higher is required. Make sure you add it to your path.1
- (MacOS) Download and install Xcode. We have tested using Xcode 12.
- (Windows) Download and install Visual Studio 2019. Community Edition is enough!
How to use
Everything you need to build a plugin is outlined in GenPluginExport.maxpat
.
In short here are the steps:
-
Begin with a
gen~
patcher. Important! In the inspector, change the export name attribute toC74_GENPLUGIN
. -
Export the C++ code from
gen~
using thecodeexport
message. Export to themisc/exported-code
directory of this package. You should eventually see -
Open a Terminal (MacOS) or PowerShell (Windows) window. Navigate to the
gen~ Plugin Export
(orgen-plugin-export
) directory usingcd
.2 (See footnote for help if you're new to using the terminal.)
Note: Working with CMake involves two steps --- "generating" a project, and "building" the project. This is because CMake takes care of OS specific things (like figuring out where your C++ compiler is and creating any IDE projects you would like to work in, and so on). For building a simple plugin, you don't need to be a CMake expert.3
- To generate, do one of the following:
Option | Command |
---|---|
MacOS (Xcode project generator) | cmake -G "Xcode" -S misc -B misc/build |
MacOS (Makefile generator) | cmake -G "Unix Makefiles" -S misc -B misc/build" |
MacOS (Ninja generator) | cmake -G "Ninja" -S misc -B misc/build" |
Windows (Visual Studio generator) | cmake -G "Visual Studio 16 2019" -S misc -B misc/build |
If you're unsure of what option to use, Xcode
and Visual Studio
are
probably the ones to pick from. If you're on Windows using a Visual Studio
version other than 2019, you'll need to substitute the proper string for the
-G
option. You can find it by running cmake --help
and using the
appropriate string for your Visual Studio version.
-
Now you can build with
cmake --build misc/build --config Release
. -
Once the build step completes, you should be able to find your build artifact in
misc/build/C74GenPlugin_artefacts/Release
. Copy the plugin file to wherever you keep your plugins, and test your new plugin out!
File structure
Most of the code is located within the misc/
directory. So that the launch
patcher is available from the Extras
dropdown in Max, it lives in the
extras/
directory.
Some notable files/directories:
Location | Explanation |
---|---|
extras/GenPluginExport.maxpat | main Max patcher to automate building plugins |
misc/exported-code/ | the folder where gen~ will export C++ code |
misc/CoreAudioUtilityClasses/ | required for building Audio Units |
misc/Source-App/ | Source for iOS Application - feel free to edit (includes sample UI) |
misc/Source-Plugin/ | Source for Audio Plugins - feel free to edit |
misc/JUCE/ | The JUCE framework - do not edit these |
Build locations
Location | Explanation |
---|---|
misc/build/App-Builds/ | iOS projects |
misc/build/AU-Builds/ | AudioIUnit projects |
misc/build/VST3-Builds/ | VST3 projects |
Customization
Plugin building is based on the JUCE Framework. Please refer to tutorials from JUCE on building UIs, for instance.
Enjoy!
Footnotes
-
To check that CMake is on your path, you can run the command
cmake --version
. If you see a version number, all is well. If not, Google how to make sure CMake is found on your path for your OS. ↩ -
If you're new to navigating the terminal, learn about how to use the
cd
command here or here for Windows. ↩ -
It's a useful tool to become familiar with, though, so check out the documentation if you want to get up to speed. ↩