Tip

If this page does not contain a specific entry then it means there are no special migration steps or they are so simple that they are described in the release notes.

4.5.0 → 5.0.0

5.0.0 contains 2 big changes that require your attention: upgraded to VST3 SDK 3.7.0 and CMake refactoring.

Use of VST3 SDK 3.7.0

Jamba has been upgraded to use the latest (as of this time 08/2020) VST3 SDK: 3.7.0. As a result, you may have to make some changes in your code due to the fact that it is a new version of the SDK. For example if you were using Drag’n’Drop features you will need to change your code to use the new APIs.

VST2 Support

Steinberg has removed support for VST2 from the VST3 SDK. As a result, you need to tell Jamba where it is located. If you are reading this migration guide, it probably means you were using a previous version of Jamba which was using a version of the VST3 SDK containing the VST2 SDK already. It was located under <Root VST3 SDK 3.6.9>/VST2.

So you can either:

  • copy it in its new default location (/Users/Shared/Steinberg/VST_SDK.2.4 on macOS and C:/Users/Public/Documents/Steinberg/VST_SDK.2.4 on Windows)
  • create a link to it (for example on macOS ln -s <Root VST3 SDK 3.6.9>/VST2 /Users/Shared/Steinberg/VST_SDK.2.4)
  • define the VST2_SDK_ROOT variable in your CMakeLists.txt or provide it on the command line when configuring the project (for example configure.py --vst2 <path to vst2 sdk>)
Warning

If you donwload the latest VST3 SDK zip file (instead of cloning the repository) it does contain a VST2_SDK folder at the root but it is an incomplete VST2 SDK distribution and you need to get an older one (check Requirements section for details).

CMake refactoring

Part of the migration effort, the CMake code has been completely rewritten to be both easier to use and easier to extend/customize. As a result, you will need to migrate to the new model. The old CMake APIs (jamba_add_vst3plugin, jamba_create_archive, jamba_add_vst3_resource, jamba_gen_vst3_resources, jamba_dev_scripts, jamba_add_test) have all been deprecated and display a warning message as they no longer do anything.

Now you simply use a single API jamba_add_vst_plugin. You can check the documentation for more details on the API itself but for the sake of the migration, you simply need to call this single API with various arguments instead of calling the various scattered APIs.

Tip

One quick and easy way to bootstrap the process is to go to Jamba Web Quickstart, generate a blank plugin with your parameters and use the generated CMakeLists.txt as an example.

Let’s go over each changes:

  • You can safely remove vst369.cmake from your source tree and no longer include it in your CMakeLists.txt: Jamba now takes care of cloning the right repository and it uses the same JAMBA_DOWNLOAD_VSTSDK option to enable or disable it. It is still recommended to download the SDK separately and either install it in the default location or provide its location via the VST3_SDK_ROOT path variable.

  • Although you can leave it the way it is, you should provide the ${CMAKE_BINARY_DIR}/generated path to the main API like so (it is cleaner):

    # Generating the version.h header file which contains the plugin version (to make sure it is in sync with the version
    # defined here)
    set(VERSION_DIR "${CMAKE_BINARY_DIR}/generated")
    configure_file(${CPP_SOURCES}/version.h.in "${VERSION_DIR}/version.h")
    
    # ...
    
    jamba_add_vst_plugin(
            ...
            INCLUDE_DIRECTORIES "${VERSION_DIR}" # we add the version folder to the list of includes
            ...
    )
        

  • You no longer need to add include directories and libraries related to Jamba or the SDK. It is taken care of for you.

    # This is the old way
    set(target pongasoft_sam_spl_64)
    jamba_add_vst3plugin(${target} "${vst_sources}")
    target_include_directories(${target} PUBLIC ${VSTGUI_ROOT}/vstgui4)
    target_link_libraries(${target} PRIVATE base sdk vstgui_support sndfile r8brain-free-src jamba)
    
    # This is the new way (note how we only need non Jamba/VST libs)
    jamba_add_vst_plugin(
            TARGET pongasoft_sam_spl_64
            VST_SOURCES    "${vst_sources}" "${vst2_sources}"
            LINK_LIBRARIES "sndfile" "r8brain-free-src"
            ...
    )
        

  • The resources are now parameters to the API

    # Location of resources
    set(RES_DIR "${CMAKE_CURRENT_LIST_DIR}/resource")
    
    # List of resources (images)
    set(vst_resources
          "${RES_DIR}/background.png"
          ...
    )
    
    jamba_add_vst_plugin(
          ...
          UIDESC "${RES_DIR}/SampleSplitter.uidesc" # the main xml file for the GUI
          RESOURCES "${vst_resources}" # the resources for the GUI (png files)
          ...
    )

  • The tests are now parameters to the API

    # Location of the test cases
    set(TEST_DIR "${CMAKE_CURRENT_LIST_DIR}/test/cpp")
    
    # List of test cases
    set(test_case_sources
          "${TEST_DIR}/test-SampleBuffers.cpp"
    )
    
    jamba_add_vst_plugin(
          ...
          TEST_CASE_SOURCES   "${test_case_sources}" # the source files containing the test cases
          # TEST_SOURCES      "${CPP_SOURCES}/xxx.cpp" # individual files required for compiling tests but we could add ${vst_sources} if we needed more
          TEST_LINK_LIBRARIES "jamba" # the libraries needed for linking the tests (if your tests don't depend on Jamba you can comment this out)
          ...
    )

  • Remove the call to jamba_create_archive and provide the filename as RELEASE_FILENAME to the API. If you did not call jamba_create_archive you can turn off archive generation by setting the JAMBA_ENABLE_CREATE_ARCHIVE to OFF.

    # Old way
    jamba_create_archive(${target} "SAM-SPL 64")
    
    # New Way
    jamba_add_vst_plugin(
          ...
          RELEASE_FILENAME "SAM-SPL 64"
          ...
    )

  • Remove the call to jamba_dev_scripts as this is automatically done now. If you did not call jamba_dev_scripts you can turn off generation of the dev script by setting the JAMBA_ENABLE_DEV_SCRIPT to OFF.

Removed “prod” command

The new Jamba dev script no longer offers a prod command because you can simply recreate it by issuing jamba.sh -r -b test validate archive (the new script lets you issue more than one command and if one fails, the script stops immediately).

If you still want to be able to issue jamba.sh prod, you can simply add it as a target in your CMakeLists.txt because all commands that the script does not understand natively are simply treated as targets:

add_custom_target(prod
    COMMAND "${JAMBA_SCRIPT_COMMAND}" -b -r test validate archive
)