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 when you want to build, test, validate etc… from the command line.
Since 5.0.0, technically speaking, Jamba generates a python script which is invoked by the shell script. But it should be considered an implementation detail and the shell script remains the official way to invoke it.
Since 5.0.0, all the commands available to the script simply delegate to a CMake target so if you load the project in an IDE, you can invoke all commands by simply building the equivalent target.
You can rename the script if you want by setting the JAMBA_SCRIPT_COMMAND option.
Options
-h | help
Simply use the -h option to see all that the script offers
> jamba.sh -h
usage: jamba.sh [-hnvbdr] <command> [<command> ...] [-- [native-options]]
positional arguments:
command See "Commands" section
optional arguments:
-h, --help show this help message and exit
-n, --dry-run Dry run (prints what it is going to do)
-v, --verbose Verbose build
-b, --banner Display a banner before every command
-d, --debug use Debug build config
-r, --release use Release build config
Commands
---- Main commands ----
clean : clean all builds
build : build the plugin
test : run the tests for the plugin
validate : run the validator for the vst3 plugin
edit : run the editor (full editing available in Debug config only)
info : run the module info tool (display json info about the plugin)
inspect : run the inspector (inspects ALL installed plugins)
install : build and install all the plugins (vst3/audio unit)
uninstall : delete the installed plugins (vst3/audio unit)
archive : create an archive containing the plugins
---- VST3 commands ----
install-vst3 : install the vst3 plugin only
uninstall-vst3 : uninstall the vst3 plugin only
---- Audio Unit commands ----
build-au : builds the Audio Unit only
install-au : install the Audio Unit only
uninstall-au : uninstall the Audio Unit only
---- CMake target ----
<command> : Any unknown <command> is treated as a cmake target
--- Native options ----
Pass remaining options to the native tool (ex: -- -j 8 for parallel build)
-d / -r | Debug vs Release mode
By default, 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
-n | dry run
Using the -n option will not invoke any commands but instead show you what will happen.
> ./jamba.sh -n test validate
cmake --build . --config Debug --target jmb_test_vst3
cmake --build . --config Debug --target jmb_run_validator
Main Commands
The following commands are the most frequently used commands.
clean
Deletes all previous build.
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.
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.
test
Runs the unit tests. Jamba integrates with Google Test so that you can write unit tests for the various components of your plugin (if you have generated a blank plugin, tests can be found under test/cpp).
If you want to use a different test framework, check the CMake build documentation.
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.
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.
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.
The editor code is entirely disabled during a Release build so as a result, this command will open the plugin and lets you interact with it but right clicking will do nothing when run in Release mode.
Although the editor acts as a VST host, it only lets you play with the UI of the plugin or edit it, but none of the Real-Time or audio code is executed.
info
Runs the moduleinfo tool and prints the output on stdout. The same content is automatically bundled as a moduleinfo.json file inside the VST3 plugin.
inspect
Runs the VST3Inspector tool which is a tool that displays information about all installed VST3 plugins.
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.
On macOS, if you selected Audio Unit support, the Audio Unit plugin will be installed as well. You can use install-vst3 or install-au to install a specific one instead.
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.
This command does not uninstall a previously installed plugin, which is usually faster since only modified files will be updated. That being said, files that are no longer used will remain. You can run ./jamba.sh uninstall install if you want to make sure that you start from scratch.
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…
uninstall
Uninstalls the plugin from its default location (the location where it is installed during the install command).
Like its counterpart install, this command acts on all the types of plugins you have selected and you can use uninstall-vst and uninstall-au to uninstall a specific one instead.
archive
This is a convenient command which generates a zip file containing the plugin(s) (VST3 and Audio Unit) as well as the readme and license files (from the archive folder).
If you want to generate a different type of archive, check the CMake build documentation.
Audio Unit Commands (macOS 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.
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.
uninstall-au
Uninstalls the Audio Unit plugin from its default location.
CMake target
<command>
Invoke cmake (with the proper config flag and folder) with the provided command treated as the name of a CMake target
> ./jamba.sh -n my-custom-target
cmake --build . --config Debug --target my-custom-target
Native options
You can pass native options to the underlying tool. For example on macOS using the CodeBlocks - Unix Makefiles generator which does not use Xcode, you can use -- -j 8 to build the code in parallel using 8 cores which makes the build a lot faster.