DOCSEARCHbyAlgolia
Submit Docs

Max SDK

repository·main·Indexed 43 days ago

https://github.com/cycling74/max-sdk

Headers, source code, and libraries for building C or C++ external objects (plug-ins) for the Max software environment. Includes CMake build configurations for Xcode and Visual Studio, guidance on configuring CMakeLists.txt for externals, and instructions for distributing DLLs and dylibs within Max Packages.

Tokens
1.4K
Snippets
4
Records
6
Agent score
56%

What's inside Max SDK

  2. Configure dylib install names on macOS for Max Packages

    main

    On macOS, a dylib must be located at the exact path specified in its 'install name' for an external to load it. To avoid requiring global system directories (like /usr/local/lib), use relative paths.

    Scenario 1: Single external with a bundled library

    If your library is inside your .mxo bundle (e.g., in a Frameworks folder), use @loader_path to point to it.

    Bundle Structure:

    myobject.mxo
  Contents
    MacOS
      myobject
    Frameworks
      somelibrary.framework

    Linker Flag: Set the install name to @loader_path/../Frameworks/somelibrary.framework.

    Scenario 2: Multiple externals sharing a library in a Max Package

    If multiple externals in a Max package need to access the same library, place the library in the package's support folder. Use a relative path that traverses up from the external's location to the support directory.

    Linker Flag Example:

    LDFLAGS += -install_name "@loader_path/../../../../support/$(NAME).dylib"
    LDFLAGS += -install_name "@loader_path/../../../../support/$(NAME).dylib"

  3. Install and build Max externals using CMake

    main

    The Max SDK uses CMake to generate project files for Xcode (macOS) or Visual Studio (Windows). This is a required step to support modern platforms like Apple silicon.

    Prerequisites

    • CMake: version >= 3.25
    • IDE: Xcode (macOS) or Visual Studio (Windows)
    • SDK Location: Clone or download max-sdk and place it in your Max Package folder or a directory within your Max search path.

    Build Steps

    1. Create a build directory:

      mkdir build
cd build

    2. Generate project files:

      • macOS (Xcode):
        cmake -G Xcode ..
      • Windows (Visual Studio):
        cmake -G "Visual Studio 17 2022" ..

    3. Build the project: You can build via your IDE or using the command line:

      cmake --build . --config Debug
cmake --build . --config Release

    Troubleshooting Apple Silicon Security

    If you encounter a cannot be loaded due to system security policy error when loading your .mxo on Apple silicon, ad-hoc codesign your external:

    codesign --force --deep -s - myobject.mxo
    mkdir build
cd build
cmake -G Xcode ..
cmake --build . --config Release

  4. Distribute DLLs in Max Packages using the 'support' folder

    main

    When distributing a Max external that depends on a dynamically-linked library (DLL on Windows, dylib on Mac), it is recommended to use the Max 'packages' feature.

    To do this:

    1. Create a folder named support within your Max package folder.
    2. Place your DLL or dylib inside this support folder.

    On Windows, Max automatically adds the support folder to the search path for DLLs. On macOS, you must configure the library's 'install name' to point to this relative location to ensure it is found correctly.

  5. Configure a Max external's CMakeLists.txt

    main

    Every Max external requires its own CMakeLists.txt to interface with the SDK build machinery.

    Minimal Configuration (Automatic File Discovery)

    Use max::glob ON to automatically include all .c and .cpp files in the directory. This is the simplest way to set up a project.

    set_property(DIRECTORY PROPERTY max::external YES)
set_property(DIRECTORY PROPERTY max::glob ON)
project(myexternal)

    Explicit File Configuration

    If you need precise control over which files are compiled, omit max::glob and use target_sources to list files manually after the project() call.

    set_property(DIRECTORY PROPERTY max::external YES)
project(myexternal)

target_sources(myexternal PRIVATE myexternal.cpp helper.cpp)

    Key CMake Properties and Commands

    • max::external YES: A directory property that tells the SDK to treat this directory as a Max external.
    • max::glob ON: Automatically includes all .c and .cpp files in the directory as source files.
    • project(name): Names the external and triggers target creation. The resulting output will be name.mxo (macOS) or name.mxe64 (Windows).
    • Target Customization: After the project() command, the target named ${PROJECT_NAME} is available for standard CMake commands like target_link_libraries, target_include_directories, and target_compile_definitions.

  6. Inspect and modify dylib install names on macOS

    main

    If you are using a pre-compiled third-party library, its install_name might not be compatible with your distribution method.

    Inspecting the install name

    Use the otool command-line tool to find the LC_ID_DYLIB section. This reveals the path the library expects to be found at.

    $ otool -l /path/to/your/library.dylib

    Look for the name field under cmd LC_ID_DYLIB.

    Modifying the install name

    If the library's path is incorrect for your package structure, do not modify the original. Instead, copy the library and use the install_name_tool command-line utility to change the path on the copy.

    $ otool -l /Applications/Max\ 6.1/Max.app/Contents/Frameworks/MaxAudioAPI.framework/Versions/A/MaxAudioAPI
	Load command 3
	  cmd LC_ID_DYLIB
  cmdsize 104
     name @executable_path/../Frameworks/MaxAudioAPI.framework/Versions/A/MaxAudioAPI (offset 24)