Introduction

jamba.sh (jamba.bat for Windows) is the main script that Jamba generates for you to help in invoking the right set of cmake targets and dependencies when you want to build, test, validate etc…

Options

-h | help

Simply use the -h option to see all that the script offers

> jamba.sh -h
   Usage:  jamba.sh [-hdrn] <command>

     -h : usage help
     -d : use Debug build config (default)
     -r : use Release build config (Debug if not defined)
     -n : dry run (prints what it is going to do)

   Commands: 
     ---- VST Commands ----
     clean    : clean all builds
     build    : build the VST plugin
     edit     : start the GUI editor (Debug only)
     install  : install the VST plugin in their default location
     test     : run the unit tests
     validate : run the VST3 validator
     ---- Audio Unit Commands ----
     build-au    : build the Audio Unit wrapper plugin
     install-au  : install the Audio Unit plugin in its default location
     validate-au : run the Audio Unit validator
     ---- Generic Commands ----
     archive : generate the zip file containing the plugin(s) and README/License
     prod    : run test/validate/archive (default to Release, override with -d)
     ---- CMake target ----
     <target> : invoke cmake with the provided target

-d / -r | Debug vs Release mode

By default, and except noted otherwise (prod command), all commands are run in Debug mode which is perfect during development as you can attach a debugger and view all DLOG_F (from loguru) logging.

If you want to force validate in Release mode, then you invoke it this way:

> jamba.sh -r validate
Note

The prod command is the only command which defaults to Release mode (and can be overriden with -d for Debug mode) as it is designed to run all the phases of the build and build an archive ready to be released.

-n | dry run

Using the -n option will not invoke any commands but instead show you what will happen.

> ./jamba.sh -n validate
cmake --build . --config Debug --target acme_Kooza
cmake --build . --config Debug --target validator
./bin/Debug/validator VST3/Debug/acme_Kooza.vst3

VST Commands

The following commands are specific to the VST plugin.

clean

Deletes all previous build.

Note

Since this includes everything that was previously built (including the VST SDK and VSTGUI), running a build after this command will take longer.

build

Simply builds the plugin.

Tip

Since the plugin on its own cannot be run, you will most likely use another command like install (so that you can run it in a DAW), edit to run the plugin in the editor or validate to run the VST3 validation steps.

edit

Builds the plugin and runs the editor tool that ships with the SDK (the tool will be built if necessary). This tool acts as a VST host and loads the plugin so that you can edit the UI in a WYSIWYG fashion. To access the tool, you need to right click in the plugin and select the option to open it.

Tip

The editor code is actually part of the plugin (in debug mode only!) and as a result is also available if you load your plugin in any DAW (simply right click / select the option). But if you only want to work on the UI, it is usually faster to simply run the editor tool, vs installing the plugin and launching your favorite DAW to open it there.

Note

The editor is not available in Release mode because the code to actually edit the plugin is part of the built plugin itself. In Release mode this code is simply not compiled hence not included in the plugin.

install

Builds the plugin and install it in its default location (which depends on the platform). After this step you can launch your favorite DAW and your plugin should be there, ready to be loaded.

Tip

If you selected support for VST2, both VST2 and VST3 versions will be installed in their respective locations.

Note

Most DAWs only check/load new plugins on start and do not offer a way to refresh after the fact. So you usually have to close and reopen the DAW for the changes in your plugin to take effect.

Warning

Most DAWs will instantiate the new plugin on start when they detect there is a new plugin. If your plugin crashes it may crash your DAW. You may want to run the validate command first which does instantiate your plugin and run some validation steps. Always be careful when you test your plugin in a live DAW…

test

Runs the unit tests. Jamba integrates with Google Test so that you can write unit tests for the various components of your plugin (tests can be found under test/cpp).

Note

If you want to use a different test framework, feel free to replace it in the CMakeLists.txt section as this command does not rely on Google Test.

# the command relies on a test target and ctest not Google Test
> ./jamba.sh -n test
cmake --build . --config Debug --target acme_Kooza_test
ctest -C Debug

validate

Builds the plugin and runs the validator tool that ships with the SDK (the tool will be built if necessary). This tool loads the plugin, extracts and displays information about it (like vendor, parameters, etc…) then invokes several methods to make sure it is compliant with VST3.

Audio Unit Commands (jamba.sh only)

The VST3 SDK comes with a wrapper that lets you build a VST3 plugin and wraps it as an audio unit plugin. The following commands takes care of the complexity of doing all this. Because Audio Unit is a macOS only format, the following commands are not available with jamba.bat.

build-au

Builds the VST3 plugin and wraps it as an audio unit plugin.

install-au

Builds the audio unit plugin and installs it in its default location. After this step you can launch your favorite DAW and your plugin should be there, ready to be loaded.

validate-au

This command will run the audio unit validation tool which is installed on macOS (/usr/bin/auvaltool). This tool runs some validation steps on the audio unit like what Logic does when it detects a new plugin.

Info

Unlike the validate command, this command builds and installs the plugin. This is unfortunately due to the way this tool operates as there is no way to provide a path to a plugin to test and instead it requires “type / subtype / manufacturer” and looks into the default installation folders to locate the plugin.

> jamba.sh -n validate-au
cmake --build . --config Debug --target acme_Kooza_au
rm -rf /Users/ypujante/Library/Audio/Plug-Ins/Components/acme_Kooza.component
cp -r VST3/Debug/acme_Kooza_au.component /Users/ypujante/Library/Audio/Plug-Ins/Components/acme_Kooza.component
Audio Unit plugin installed under ~/Library/Audio/Plug-Ins/Components/acme_Kooza.component
AU_TYPE=/usr/libexec/PlistBuddy -c Print :AudioComponents:0:type VST3/Debug/acme_Kooza_au.component/Contents/Info.plist
AU_SUBTYPE=/usr/libexec/PlistBuddy -c Print :AudioComponents:0:subtype VST3/Debug/acme_Kooza_au.component/Contents/Info.plist
AU_MANUFACTURER=/usr/libexec/PlistBuddy -c Print :AudioComponents:0:manufacturer VST3/Debug/acme_Kooza_au.component/Contents/Info.plist
/usr/bin/auvaltool -v $AU_TYPE $AU_SUBTYPE $AU_MANUFACTURER
Tip

From experience, it seems that Apple’s Logic DAW is not good at detecting/loading a new version of a plugin you are working on even if you close and reopen the software. Killing the AudioComponentRegistrar background process and reopening Logic seems to force it to load the new one.

Generic Commands

archive

This is a convenient command which generates a zip file containing the plugin(s) (VST2, VST3 and Audio Unit) as well as the readme and license files (from the archive folder).

prod

Simply runs test (unit tests), validate (VST3 validation) and archive (zip file) in Release mode (by default) as a convenient way to build the plugin when ready to be released.

CMake target

<target>

Invoke cmake (with the proper config flag and folder) with the provided target

> ./jamba.sh -n my-custom-target
cmake --build . --config Debug --target my-custom-target