Using the SDK · Magister Catalyst

Install

Extract the zip anywhere on an Apple Silicon Mac. The minimum macOS version is recorded in distribution.json; it includes the requirements of all bundled libraries. Linux and Intel Mac distributions are not available yet.

Select Xcode or Apple's Command Line Tools with xcode-select. C++ applications require C++23 support; CMake projects require CMake 3.24 or newer. Cosmic and Microcosm are included, along with their runtime dependencies and debugging tools. Standard C++ projects use the Apple compiler selected by Xcode or Command Line Tools. No separate LLVM installation is needed. Set the SDK location and command search path:

export CATALYST_SDK="$HOME/SDKs/Catalyst-1.0.0-macos-arm64"
export PATH="$CATALYST_SDK/bin:$PATH"
export MC_HOME="$CATALYST_SDK"

GPU compilation additionally requires Xcode's Metal Toolchain component:

xcodebuild -downloadComponent MetalToolchain

MC_HOME supplies the conf directory to Catalyst applications. Set it to your application's own configuration directory when appropriate. The SDK compilers default it to the SDK location when it is unset. Review and customize the supplied Nexus configuration before using it on your machines.

Read the guide and the SDK reference.

CMake applications

cmake_minimum_required(VERSION 3.24)
project(MyApplication LANGUAGES CXX)
find_package(Catalyst 1.0 CONFIG REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE Catalyst::Shared)

cmake -S . -B build -DCMAKE_PREFIX_PATH="$CATALYST_SDK"
cmake --build build

Catalyst::Catalyst supplies headers and their dependencies. Catalyst::Shared adds the core library; Catalyst::MacShared adds the Mac graphics library and core. These targets link the libraries included in the SDK.

Boost is linked statically. The SDK contains the Boost headers reached by the Catalyst headers for C++23 on macOS arm64. The header list is recorded in licenses/boost/headers.txt. A small libboost_iostreams.a supplies compiled gzip/zlib support for inline functions; the CMake targets link it and system zlib automatically. No Boost installation or Boost dylibs are required.

For Cosmic .cc files, call catalyst_cosmic_directory("${CMAKE_CURRENT_SOURCE_DIR}") after defining your targets. It preserves target include paths, definitions and compile options, and generates database row headers from .cson schemas. The imported executable targets are mc-cosmic, mc-microcosm, and mc-nexus. catalyst_debug_symbols(my_app) enables matching dSYM generation for Debug and RelWithDebInfo builds.

mc-cosmic -g -o hello hello.cc
mc-microcosm -g -o hello hello.mc
cmake -S "$CATALYST_SDK/examples" -B examples-build \
  -DCMAKE_PREFIX_PATH="$CATALYST_SDK"
cmake --build examples-build

On macOS, mc-cosmic automatically links both the core libcatalyst library and libcatalyst_mac when producing an executable. With CATALYST_SDK set to the extracted SDK directory as above, compile a graphics application with:

"$CATALYST_SDK/bin/mc-cosmic" main.cc -o my_graphics_app

Use --link FILE to add other object files or libraries; repeat it for each additional input. Object-only compilation with -c does not link libraries.

The SDK provides relative symbolic links cosmic → mc-cosmic, microcosm → mc-microcosm, and nexus → mc-nexus in bin. The examples directory contains tutorial sources and its own consumer CMake project; service examples may need their documented external services. Compiler sanitizers are not included in this release toolchain.

Use native object files when linking code from Apple's compiler into Cosmic programs with --link. LLVM bitcode inputs must be compatible with the embedded LLVM 23 compiler; Apple Clang can emit vendor extensions that it does not support.

Python and Swift

The zip includes bindings for cvar, CMessenger, and CServer, plus their support types. Both languages use the same native Catalyst library and value serialization. See the binding guide for values, delegates, messaging, ownership, and error handling.

Python

The prebuilt abi3 extension requires standard CPython 3.9 or newer, running natively on arm64. Add the SDK's version-independent package directory:

export PYTHONPATH="$CATALYST_SDK/lib/python${PYTHONPATH:+:$PYTHONPATH}"
python3 -c 'from catalyst import CVar; print(CVar({"answer": 42}).to_cson())'

No extension compilation or separate Python binding dependencies are needed. Keep the package in the SDK layout so its relative loader paths can find the bundled libraries. Free-threaded Python and subinterpreters are not supported.

Swift

The self-contained Swift package is in share/Catalyst/swift. It requires Swift 5.9 or newer and compiles its wrapper sources against the bundled C ABI; it does not require C++ interop. Add it as a local package dependency, then select the Catalyst library product for your target and use import Catalyst.

Set your application's macOS deployment target to at least minimum_macos from distribution.json. For a SwiftPM application, build with the native library's explicit path and runtime search path:

swift build \
  -Xlinker "-L$CATALYST_SDK/lib" \
  -Xlinker "$CATALYST_SDK/lib/libcatalyst.dylib" \
  -Xlinker -rpath -Xlinker "$CATALYST_SDK/lib"

The full library path prevents Swift's libCatalyst.a from shadowing the native libcatalyst.dylib on case-insensitive volumes. For Xcode applications, add the same native library and library search path, and configure runpaths and embedding for your application's final location as described below.

Frameworks and application deployment

Frameworks/Catalyst.framework contains the core library, SDK headers, and its runtime dependencies. Frameworks/CatalystMac.framework adds the Mac library and requires Catalyst.framework beside it. Link Catalyst::Framework or Catalyst::MacFramework in CMake to select these variants. Use one variant consistently throughout an application.

For an Xcode project, add both framework search paths and Catalyst.framework/Headers to the header search paths, and include headers as <mc/cvar.h>. Embed the required frameworks together in your application's Contents/Frameworks, with an @executable_path/../Frameworks runtime search path. Headers use C++23. Re-sign embedded code with your own Developer ID when signing your application. For direct Xcode integration, link Catalyst.framework/Versions/A/Libraries/libboost_iostreams.a and libz.tbd when using compression functions. The CMake framework targets include these link dependencies automatically.

For dylib deployment, copy the contents of lib/*.dylib, preserving symlinks, beside each other. Add that directory to your application's runtime search paths. CMake sets build-time paths to the SDK automatically; configure your application's install paths for its final layout. Do not combine the framework and dylib copies in one process.

The zip contains Developer ID signatures and is submitted to Apple's notary service before release. ZIP archives and standalone executables cannot have notarization tickets stapled to them; Gatekeeper retrieves their tickets online. See Apple's notarization workflow. Archives with -unsigned in their name are local previews with ad-hoc signatures and have not been notarized.

Third-party notices are in licenses, including the source archive and rebuild recipe for the dynamically linked LGPL libdwarf. This software is based in part on the work of the Independent JPEG Group.