Dependencies¶

Catalyst provides built-in dependency management supporting multiple sources. Dependencies are defined in the dependencies list within your profile configuration.

Supported Sources¶

1. git¶

Fetches a library from a remote Git repository.

- name: fmt
  source: git
  url: https://github.com/fmtlib/fmt.git
  version: 10.0.0

2. vcpkg¶

Uses vcpkg to satisfy the dependency.

- name: nlohmann-json
  source: vcpkg
  version: 3.11.2
  triplet: x64-linux

Transitive dependencies¶

vcpkg packages each dependency as its own port, so a single library can rely on several others installed alongside it (for example, ryml depends on c4core). By default Catalyst discovers and links these automatically by reading vcpkg's profile-local installed-package database (<build-dir>/vcpkg_installed/vcpkg/status), so you only need to declare the packages you use directly:

# c4core is linked automatically as a transitive dependency of ryml.
- name: ryml
  source: vcpkg
  triplet: x64-linux

Build-time helper ports (such as vcpkg-cmake) are skipped because they ship no link or include artifacts, and packages are emitted in a valid static-link order (a package always precedes the packages it depends on). Set transitive: false on a dependency to opt out and link only that package — useful if you prefer to pin every transitive package explicitly.

Catalyst uses vcpkg manifest mode and installs packages beneath the composed profile's generated build tree (<build-dir>/vcpkg_installed). The generated manifest records the current vcpkg registry commit as its builtin baseline and uses overrides for every exact version declared by the project or lockfile.

3. local¶

Builds a dependency found on the local filesystem.

- name: my-lib
  source: local
  path: ../libs/my-lib

Local dependencies export their resolved feature macros to consumers, including transitively. The selected profiles and using overrides apply both to the dependency's own build and to those exported definitions. Local builds are checked incrementally on every catalyst build.

4. system¶

Uses pkg-config to find a system-installed library.

- name: openssl
  source: system

5. conan¶

Uses Conan 2.x to fetch and resolve dependencies using Conan's native PkgConfigDeps generator.

- name: fmt
  source: conan
  version: 10.1.1

6. custom¶

Runs a user-supplied command or script and parses its stdout as pkg-config-style flags (-I..., -L..., -l...) — the same shape pkg-config --cflags --libs <pkg> would print. Useful for emulating FindXYZ.cmake-style discovery logic that Catalyst has no built-in source for.

- name: openssl
  source: custom
  command: "pkg-config --cflags --libs openssl"

- name: mylib
  source: custom
  script: "scripts/find_mylib.sh"
  version: 1.2.3

The command/script must print pkg-config-style flags to stdout; a nonzero exit or output with no recognizable -I/-L/-l tokens is treated as "dependency not found". It re-runs on every generate (no caching), participates in neither catalyst fetch nor catalyst lock (same as system), and runs with the current working directory and PATH of the catalyst process.

Adding Dependencies via CLI¶

You can use the catalyst add command to append dependencies to your configuration without editing YAML manually.

catalyst add git https://github.com/fmtlib/fmt.git -v 10.0.0
catalyst add vcpkg nlohmann-json -t x64-linux

Reproducible Builds with Lockfiles¶

Catalyst supports pinning dependency versions to ensure that everyone working on a project uses the exact same revisions.

By running catalyst lock, you generate a catalyst.lock file. This file pins: - Git dependencies to specific 40-character commit hashes. - Vcpkg dependencies to their resolved versions, port revisions, triplets, and builtin registry baseline. - Local/System dependencies to their paths.

When a catalyst.lock is present, catalyst fetch and catalyst build will prioritize its contents over the loose version constraints in catalyst.yaml.