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.

# 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 snapshots images (release only)
              [RELEASE_SNAPSHOTS snapshot_path [snapshot_2.0x_path]]

       # Optional name for the plugin archive (zip)
              [ARCHIVE_FILENAME archive_filename]
              [ARCHIVE_ARCHITECTURE archive_architecture]

       # 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

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.

# 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().

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 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().

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)

Targets

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