Introduction

Jamba uses CMake as its build system. In order to use the Jamba framework, you simply need to include jamba.cmake located at the root of the Jamba project.

Tip

This is automatically done for you if you have generated a blank plugin.

Note

Although Jamba is designed to be a framework, if you want to only use Jamba as a library, then you can simply do

# Use Jamba as a library only
add_subdirectory("${JAMBA_ROOT}/src" jamba)

You can configure Jamba by setting (CMake) options prior to including jamba.cmake and invoking its main API jamba_add_vst_plugin.

Main API

The framework exposes a single function called jamba_add_vst_plugin to create the plugin targets and script. Most arguments are completely optional and come with sensible defaults.

jamba_add_vst_plugin(
       # Required argument (list of source files)
              VST_SOURCES src1 [scr2...]

       # Optional targets
              [TARGET target]
              [TEST_TARGET test_target]
              [TARGETS_PREFIX targets_prefix]
              
       # Optional name for the plugin file
              [RELEASE_FILENAME release_filename]

       # Optional resources
              [UIDESC uidesc_file]
              [RESOURCES res1 [res2...]]

       # Optional include directories (to include extra '.h' files)
              [INCLUDE_DIRECTORIES dir1 [dir2...]]

       # Optional compiler options
              [COMPILE_DEFINITIONS def1 [def2...]]
              [COMPILE_OPTIONS option1 [option2...]]

       # Optional linker libraries
              [LINK_LIBRARIES lib1 [lib2...]]
              
       # Optional tests
              [TEST_CASE_SOURCES src1 [src2...]]
              [TEST_SOURCES src1 [src2...]]
              [TEST_INCLUDE_DIRECTORIES dir1 [dir2...]]
              [TEST_COMPILE_DEFINITIONS def1 [def2...]]
              [TEST_COMPILE_OPTIONS option1 [option1...]]
              [TEST_LINK_LIBRARIES lib1 [lib2...]]

       # Optional location of the Info.plist file for macOS
              [MAC_INFO_PLIST_FILE mac_info_plist_file]

       # Optional location the python3 executable
              [PYTHON3_EXECUTABLE python3_exe]

       # Optional installation location for the plugins 
              [INSTALL_PREFIX_DIR install_prefix_dir]

       # Optional directory to be included in the archive 
              [ARCHIVE_ROOT_DIR archive_root_dir]

)

Detailed description

Argument / Option Description Example
VST_SOURCES The list of sources (cpp) files that are compiled to create the logic of the plugin Usually refers to some list ${vst_sources}
TARGET The name of the target for the vst3 plugin. Defaults to the project name. Useful to set only if you are planning to further configure the plugin build via CMake target_xxx apis. my-plugin
TEST-TARGET The name of the target for the test executable. Defaults to ${TARGET}_test. Useful to set only if you are planning to further configure the test executable via CMake target_xxx apis. plugin-tests
TARGETS_PREFIX Jamba generates many (convenient) targets that are invoked by the jamba.sh (resp. jamba.bat) dev script. This prefix is added to all targets to make it easier to differentiate them in the IDE since they are the ones that you will use. The other targets generated by the VST3 SDK can then be simply ignored. jmb_
RELEASE_FILENAME The name of the plugin that will be installed which is usually used by DAWs as the name of the plugin. Note that Jamba automatically adds _Debug to it when building in Debug mode so that it is easy to differentiate a released plugin vs. one under construction. SAM-SPL 64
UIDESC The xml file that describes the UI (required by VSTGUI). Defaults to resource/${TARGET}.uidesc resource/MyPlugin.uidesc
RESOURCES The list of resources (images) required/referenced by the UI. Usually refers to some list ${vst_resources}
INCLUDE_DIRECTORIES The list of directories to add (-I) for compiling the plugin, for example for generated files. ${CMAKE_BINARY_DIR}/generated
COMPILE_DEFINITIONS The list of compile definitions applied to the compiler when building the plugin. Note that -D should not be included. BOOST_MODE=1 BOOST2
COMPILE_OPTIONS The list of compile options applied to the compiler when building the plugin. -Wall
LINK_LIBRARIES The list of libraries to link with when linking the plugin. sndfile
TEST_CASE_SOURCES The list of sources (cpp) files containing the test cases that will be part of the test suite Usually refers to some list ${test_case_sources}
TEST_SOURCES The list of sources (cpp) files that the tests require to compile. Using ${vst_sources} here is common if your tests are testing the vast majority of your classes. Otherwise you can simply add a subset of the list. For example if in TEST_CASE_SOURCES you have test/cpp/testMyBuffer.cpp you would most likely need src/cpp/MyBuffer.cpp to be added to TEST_SOURCES for your test to compile Usually refers to some list ${test_sources}
TEST_INCLUDE_DIRECTORIES The list of directories to add (-I) for compiling the tests, for example for generated files. ${CMAKE_BINARY_DIR}/generated
TEST_COMPILE_DEFINITIONS The list of compile definitions applied to the compiler when building the tests. Note that -D should not be included. BOOST_MODE=1 BOOST2
TEST_COMPILE_OPTIONS The list of compile options applied to the compiler when building the tests. -Wall
TEST_LINK_LIBRARIES The list of libraries to link with when linking the tests. Note that jamba is not added by default so if you need it, you should add it here (for example if you use loguru in your tests). If your tests are only unit tests for non Jamba dependent classes you wouldn’t need it. jamba
MAC_INFO_PLIST_FILE The location of the Info.plist file required by the plugin when building for macOS. Defaults to mac/Info.plist mac/Info.plist
PYTHON3_EXECUTABLE The python 3 executable which is determined by default but you can override it here /opt/local/bin/python3
INSTALL_PREFIX_DIR The location where the plugins are installed. Uses the default platform location. You would change this if you want to install in a non standard location (or if for example, on macOS, you wanted to install for all users instead, you would set this to /Library/Audio/Plug-Ins) /my/own/location
ARCHIVE_ROOT_DIR The location of a folder that will be included at the root of the archive (zip) generated part of the archive command. Usually contains README files or Licenses. Defaults to ${CMAKE_CURRENT_LIST_DIR}/archive ${CMAKE_BINARY_DIR}/processedDocs

Configuring

Basic build configuration

Jamba uses CMake Cache variables (and options). For convenience they are all located under ${JAMBA_ROOT}/cmake/JambaOptions.cmake. Since they are CMake Cache variables, you can simply change them by any means provided by CMake. For example, you can set them in your own CMakeLists.txt prior to including jamba.cmake or provide them on the cmake command line or use cmake-gui.

Consult the JambaOptions.cmake file for the most up to date description of these configuration options.

Advanced build configuration

Jamba CMake build is split in many modules, all located under ${JAMBAR_ROOT}/cmake. The main API (jamba_add_vst_plugin) simply includes these modules and invoke a method that is defined in the module.

Some options let you turn on or off entire modules (like for example JAMBA_ENABLE_CREATE_ARCHIVE allow you to completely bypass including the JambaCreateArchive.cmake module).

But if you want to go further and provide your own (override) version, you can simply add your own module folder (via the CMAKE_MODULE_PATH) to CMake and create a module with the same name which creates the top level function.

Tip

The modules have access to all the arguments (as well as default values) provided to jamba_add_vst_plugin by adding the prefix ARG. For example ${ARG_TARGET} refers to the TARGET argument provided to jamba_add_vst_plugin.

# Example setup to override archive

# create JambaCreateArchive.cmake file which defines jamba_create_archive()
MyPlugin/cmake/JambaCreateArchive.cmake

# in MyPlugin/CMakeLists.txt
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake")
...
include(jamba.cmake)

Example: Using a different test framework

Jamba by default sets up GoogleTest. If you want to use a totally different test framework, you can simply create your own JambaAddTest.cmake override module which needs to provide the CMake function jamba_add_test().

Note

Another way to achieve a similar result is to disable testing by Jamba entirely by setting the JAMBA_ENABLE_TESTING option to OFF and then implement testing whichever way you want in your own CMakeLists.txt.

Example: Creating a different archive

Since 5.0.0, the Jamba build framework uses CMake install functionality (with components) in order to instal the plugins which then enables the archive to be generated by using CPack. The archive generated by Jamba is a simple zip file which contains all the components (vst3, vst2 and au for macOS) and an optional root directory (for READMEs and Licenses).

CPack offers many other generators which let you generate installers, DMG images, etc…

If you wish to do so, you can simply provide your own JambaCreateArchive.cmake override module which needs to provide the CMake function jamba_create_archive().

Note

Another way to achieve a similar result is to disable archive by Jamba entirely by setting the JAMBA_ENABLE_CREATE_ARCHIVE option to OFF and then implement archiving whichever way you want in your own CMakeLists.txt.

Advanced plugin configuration

The main function jamba_add_vst_plugin generates a primary target (whose name can be set via the TARGET argument) which represents the VST3 plugin. This target is available after calling the function to further configure the plugin if necessary.

# For example
jamba_add_vst_plugin(TARGET foo
                     ...
                     LINK_LIBRARIES bar)
                     
# is 100% equivalent to
jamba_add_vst_plugin(TARGET foo
                     ...
)
target_link_libraries(foo PUBLIC bar)
Tip

Although Jamba, at this time, does not have any specific facility to add a snapshot, you can do so by invoking the VST3 CMake function smtg_add_vst3_snapshot directly:

jamba_add_vst_plugin(TARGET foo ...)
smtg_add_vst3_snapshot(foo "resource/1A410F8ABFB94A049CF832E0D3F0E2EE_snapshot.png")
smtg_add_vst3_snapshot(foo "resource/1A410F8ABFB94A049CF832E0D3F0E2EE_snapshot_2.0x.png")

Targets

Jamba generates many (convenient) targets that are invoked by the dev script and to make it easy to invoke them from an IDE.

Tip

It is strongly recommended to define the TARGETS_PREFIX argument in order for the targets to be grouped together.