Toolchains¶

Catalyst toolchains are standalone YAML files that describe how Catalyst should format compiler, linker, and archiver commands for a target environment. They let projects override the built-in gcc-style defaults without modifying Catalyst source code.

Overview¶

Projects opt into a custom toolchain by setting manifest.toolchain in their profile configuration:

manifest:
  toolchain: msvc.yaml

If manifest.toolchain is omitted, Catalyst uses its default gcc toolchain definition.

Schema Overview¶

A Catalyst toolchain definition consists of one top-level section:

toolchain:
  name:        # Toolchain identifier
  extensions:  # Output file extensions and prefixes
  flags:       # Include/lib/define formatting templates
  compiler:    # C and C++ compilation commands
  linker:      # Executable and shared library link commands
  archiver:    # Static library archive command

toolchain¶

Defines the metadata and command templates Catalyst will use during generation.

toolchain.extensions¶

toolchain.flags¶

toolchain.compiler¶

toolchain.compiler.c¶

toolchain.compiler.cxx¶

toolchain.linker¶

toolchain.archiver¶

Example¶

toolchain:
  name: msvc
  extensions:
    object: .obj
    executable: .exe
    static_lib: .lib
    shared_lib: .dll
    static_lib_prefix: ""
    shared_lib_prefix: ""
  flags:
    include_dir: /I"{path}"
    lib_dir: /LIBPATH:"{path}"
    lib: "{name}.lib"
    define: /D{name}={value}
    define_empty: /D{name}
  compiler:
    c:
      executable: cl.exe
      command: '{cc} /c {source} /Fo"{object}" {cflags} {includes} {defines}'
    cxx:
      executable: cl.exe
      command: '{cxx} /EHsc /c {source} /Fo"{object}" {cxxflags} {includes} {defines}'
  linker:
    executable: link.exe
    executable_command: '{linker} {objects} /OUT:"{output}" {ldflags} {lib_dirs} {libs}'
    shared_lib_command: '{linker} /DLL {objects} /OUT:"{output}" {ldflags} {lib_dirs} {libs}'
  archiver:
    executable: lib.exe
    command: '{archiver} /OUT:"{output}" {objects}'

Fields omitted from a toolchain file retain their built-in defaults, so custom toolchains only need to override the pieces that differ from the default gcc behavior.

Toolchain Inheritance (extends)¶

To avoid duplicating toolchain configuration across different variants (like debug and release, or different sanitizers), a toolchain file can declare a base it inherits from using the extends key under toolchain.

toolchain:
  extends: tc_base.yaml
  name: "catalyst debug"
  compiler:
    cxx:
      flags: "-std=c++23 -O0 -ggdb -DDEBUG"

Precedence & Merging¶

A toolchain configuration is resolved by folding from the base of the inheritance chain toward the leaf:

1. Start from the built-in default gcc-style defaults.
2. If extends is specified, resolve the base toolchain recursively first.
3. Apply the current file's own keys on top, overriding per leaf scalar.

Precedence order (lowest to highest):

Every unspecified key inherits from its parent base toolchain.

For flag fields (e.g. compiler.c.flags, compiler.cxx.flags, linker.flags), you can control composition using:

• flags: Replaces the inherited flag string entirely.
• flags_append: Appends the provided flags to the inherited flags.
• flags_remove: Filters out matching space-separated tokens from the inherited flags.

Path Resolution¶

The extends path is resolved relative to the directory of the file that declares it, not the current working directory. This allows a set of toolchain files to remain relative to each other even if the build runs from a different directory. Absolute paths are used verbatim.

Validation¶

• Cycle Detection: If a cycle is detected (e.g. a.yaml extends b.yaml which extends a.yaml, or a file extends itself), it is reported as an error.
• Missing Base: If the base file cannot be opened, it fails with an error indicating both the target file path and the referring file path.
• Depth Limit: There is a hard cap limit of 32 parent toolchain files in the inheritance chain to prevent pathological chains.