Skip to content

03-toolchains.md

Latest commit

 

History

History
125 lines (85 loc) · 4.85 KB

03-toolchains.md

File metadata and controls

125 lines (85 loc) · 4.85 KB

03 — Toolchain Management

mcpp maintains an independent toolchain sandbox, fully isolated from the system PATH.

Motivation

C++23 modules are fairly sensitive to compiler versions, and different releases of GCC / Clang differ noticeably in how they handle module semantics. The versions shipped by system package managers tend to lag behind, and keeping multiple versions side by side carries a maintenance burden. mcpp installs all toolchains into a single sandbox directory (~/.mcpp/registry/data/xpkgs/), letting each project pick the version it needs without touching the system environment.

Automatic Installation

The first time you run mcpp build, if no toolchain is configured yet, mcpp automatically installs the default toolchain for your platform and sets it as the global default:

First run no toolchain configured — installing gcc@15.1.0-musl (musl, static) as default
Downloading xim:musl-gcc@15.1.0 [====>      ] 312 MB / 808 MB  3.7 MB/s
Default set to gcc@15.1.0-musl

Linux defaults to gcc@15.1.0-musl; macOS defaults to llvm@20.1.7.

Subsequent builds do not trigger this process again.

Tip

In CI or offline environments, you can disable automatic installation by setting MCPP_NO_AUTO_INSTALL=1. With this set, if no toolchain is installed, mcpp build fails immediately instead of making any network requests.

Manual Installation

mcpp toolchain install gcc 16.1.0           # GNU libc, for the default dynamic-linking case
mcpp toolchain install gcc 15.1.0-musl      # musl libc, for fully static builds
mcpp toolchain install musl-gcc 15.1.0      # equivalent to the line above
mcpp toolchain install llvm 20.1.7          # LLVM/Clang, the default toolchain on macOS

Version numbers support partial matching:

mcpp toolchain install gcc 15               # installs the highest 15.x.y version (15.1.0)
mcpp toolchain install gcc@16               # the @ form works too

Switching the Default Toolchain

mcpp toolchain default gcc@16.1.0
mcpp toolchain default gcc 15               # with a partial version, picks the highest installed match

Inspecting Toolchain Status

mcpp toolchain list

The output looks like this:

Installed:
     TOOLCHAIN               BINARY
     gcc 15.1.0-musl         @mcpp/registry/data/xpkgs/xim-x-musl-gcc/15.1.0/bin/x86_64-linux-musl-g++
  *  gcc 16.1.0              @mcpp/registry/data/xpkgs/xim-x-gcc/16.1.0/bin/g++

Available (run `mcpp toolchain install <compiler> <version>`):
     TOOLCHAIN
     gcc 13.3.0
     gcc 11.5.0
     ...

The entry marked with * is the current default toolchain. @mcpp/... is shorthand for ~/.mcpp/..., used to keep the output narrower.

Project-Level Version Pinning

If a project needs to pin a specific version rather than rely on the global default, declare it in the project's mcpp.toml:

[toolchain]
default = "gcc@16.1.0"

# you can also dispatch by platform
[toolchain]
linux = "gcc@15.1.0-musl"
macos = "llvm@20"

A project-level declaration takes precedence over the global default configuration.

Cross-Toolchain Builds

mcpp build --target x86_64-linux-musl

mcpp reads the [target.x86_64-linux-musl] section in mcpp.toml, overriding the default toolchain and linkage settings. Combined with mcpp pack --mode static, this lets you produce a fully static release package; for a complete example, see examples/03-pack-static.

Uninstalling

mcpp toolchain remove gcc@16.1.0

Resetting the Sandbox

rm -rf ~/.mcpp                              # remove the entire sandbox
mcpp build                                  # the next build triggers first-run installation again

Environment Variables

mcpp's runtime behavior can be adjusted with the following environment variables:

Variable Purpose
MCPP_HOME Override the sandbox location (default ~/.mcpp/); an absolute path takes top priority
MCPP_NO_AUTO_INSTALL=1 Disable automatic toolchain installation; useful for CI and offline environments
MCPP_NO_COLOR=1 / NO_COLOR=1 Disable colored output
MCPP_LOG=trace|debug|info|warn|error Log level

When MCPP_HOME is not set explicitly, mcpp locates the sandbox automatically based on the parent directory of the binary (after a release tarball is extracted to ~/.mcpp/, ~/.mcpp/ is the home), so the release build runs without any environment variable configuration.

ABI Capability Enforcement

A dependency can declare an abi:<name> capability (for example, compat.glfw declares abi:glibc). When the resolved toolchain's ABI does not satisfy any dependency's abi requirement, the build fails early with a suggested fix (for example, a musl-static toolchain encountering an abi:glibc dependency), replacing deeper link/header errors. Inspect with: mcpp why toolchain.