Any → 7.0.0 (required if you used to build vst2)

• Remove the option(JAMBA_ENABLE_VST2 "Use VST2" ON) entry from your CMakeLists.txt or set it to OFF (and you can clean up any references to vst2 if you want to). Since you are changing a CMake cached string, make sure you delete the CMake cache (or entire folder) and regenerate the project.

5.1.5 → 6.0.0 (required)

The SDK used by 6.0.0 introduces some non backward compatible changes which must be manually addressed:

Plugin initialization

InitModule() (resp. DeinitModule()) was required to be implemented by the plugin to provide entry for one time setup (resp. teardown) of the plugin library. Even if the implementation was empty it was required to be defined. In 3.7.5, the SDK now implements the methods to initialize itself properly (vstgui in particular) and has introduced a new (optional) mechanism for the cases when setup (resp. teardown) is required. Here are the steps to migrate:

• If the implementations were empty already, you can safely delete them.
• Otherwise you need to use the new Steinberg::ModuleInitializer (resp. Steinberg::ModuleTerminator) concept. Here is an example:

  static Steinberg::ModuleInitializer InitPlugin([] () {
     // code that used to be in InitModule()
  });

Module Info

The new SDK introduced the concept of module info (a generated modulinfo.json) file. This tool uses the PROJECT_VERSION defined in CMakeLists.txt so if you do not have one, the tool will fail. Since the PLUGIN_VERSION is already defined in the CMakeLists.txt, the easiest way to fix this issue is to add it to the project() definition like this:

# From CMakeLists.txt
project(MyPlugin VERSION "${PLUGIN_VERSION}")

GlobalKeyboardHook (optional)

This will affect your code only if you were using GlobalKeyboardHook. Otherwise you can skip it. The SDK has replaced onKeyDow() and onKeyUp() by a single onKeyboardEvent method with a completely different API. So you need to change any calls appropriately. Here is an example:

// old code
Views::registerGlobalKeyboardHook(this)->onKeyDown(
    [this] (VstKeyCode const &iKeyCode) ->  auto {
      if(iKeyCode.character == 'z' && iKeyCode.modifier == 0)
      {
          zoomToSelection();
          return CKeyboardEventResult::kKeyboardEventHandled;
      }

      return CKeyboardEventResult::kKeyboardEventNotHandled;
  });

// new code
Views::registerGlobalKeyboardHook(this)->onKeyboardEvent(
    [this] (KeyboardEvent &iEvent) {
      if(iEvent.character == 'z'
          && iEvent.type == VSTGUI::EventType::KeyDown
          && iEvent.modifiers.empty())
      {
          zoomToSelection();
          iEvent.consumed = true;
      }
  });

5.1.1 → 5.1.2 (optional)

5.1.2 adds support for Apple Silicon / universal build. In order for your existing plugin to benefit from it, apply the following changes to your existing files:

• Rename your local jamba.cmake to fetch_jamba.cmake and remove the last line (include(${JAMBA_ROOT_DIR}/jamba.cmake)) because now jamba will be fetched before the project definition in order to include support for Apple Silicon.

• Change your CMakeLists.txt this way:

  # Define a new variable which specifies which macOS you are targetting (optional)
  set(JAMBA_MACOS_DEPLOYMENT_TARGET "10.14" CACHE STRING "macOS deployment target")
  
  # download jamba framework
  include(fetch_jamba.cmake)
  
  # Determine proper architecture for the project
  include("${JAMBA_ROOT_DIR}/cmake/JambaSetArchitecture.cmake")
  
  # ...
  
  project(XXX)
  
  # ...
  
  # Include Jamba
  include("${JAMBA_ROOT_DIR}/jamba.cmake")

  Warning

  It is very important to include JambaSetArchitecture.cmake prior to invoking project.

• Optionally you can add a new entry for the architecture so that the name of the archive (zip file) reflects it

  jamba_add_vst_plugin(
      ...
      ARCHIVE_ARCHITECTURE "${JAMBA_ARCHIVE_ARCHITECTURE}"
      ...
  )

• Optionally you can add a define for the architecture in src/cpp/version.h.in and use it in your code

  #define BUILD_ARCHIVE_ARCHITECTURE "@JAMBA_ARCHIVE_ARCHITECTURE@"

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

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.

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
)