Distributable, // Binary — leaves this machine as a program

Test, // TestBinary — runs here, right now, then is discarded

Intermediate, // StaticLibrary — carries no runtime, contract is vacuous

// SharedLibrary — loaded INTO a process that already has a C++ runtime.

//

// Split out of `Distributable` after a .so that carried its own static

// libstdc++ exported 2931 std symbols — 777 of them GLOBAL definitions

// that exist nowhere but libstdc++.a — and the executable linking it bound

// ITS std references to them, silently defeating the executable's own

// `-static-libstdc++`. "Leaves this machine" is true of both, but the

// HAZARD is not the same, and the hazard is what the contract is for.

//

// Appended rather than inserted: `CompileFlags::ldStdlibByRole` indexes by

// the enum value, so moving the existing three would silently re-map every

// stored contract.

SharedLibrary,

// No C++ runtime dependency outside the artifact. The default, and what

// makes the macOS deployment floor (14.0) real rather than aspirational.

SelfContained,

// Links the C++ runtime of the toolchain mcpp installed, found again at

// run time through the toolchain's rpath. The artifact travels only with

// that toolchain present.

ToolchainCoupled,

// Links whatever C++ runtime the driver resolves by default — the system

// one on most hosts. The form distro packaging (Debian/Homebrew) requires,

// and the form `static_stdlib = false` has always been documented to mean.

HostCoupled,

switch (c) {

case Contract::SelfContained: return "self-contained";

case Contract::ToolchainCoupled: return "toolchain-coupled";

case Contract::HostCoupled: return "host-coupled";

}

return "self-contained";

switch (r) {

case Role::Distributable: return "distributable";

case Role::Test: return "test";

case Role::Intermediate: return "intermediate";

case Role::SharedLibrary: return "shared-library";

}

return "distributable";

if (s == "self-contained") return Contract::SelfContained;

if (s == "toolchain-coupled") return Contract::ToolchainCoupled;

if (s == "host-coupled") return Contract::HostCoupled;

return std::nullopt;

switch (r) {

case Role::Distributable: return Contract::SelfContained;

case Role::Test: return Contract::SelfContained;

case Role::Intermediate: return Contract::SelfContained;

case Role::SharedLibrary:

// ELF has ONE global symbol namespace and the first definition

// loaded wins. A .so that statically embedded libstdc++ exports

// those symbols UNVERSIONED, and the linker then resolves

// the executable's own std references against that .so — because

// `-lfoo` precedes the driver's `-lstdc++`, so the archive member

// is never pulled. The executable's `-static-libstdc++` becomes a

// no-op and its C++ runtime is, in fact, whichever build of that

// .so happens to be loaded. Swap the .so for another build of the

// same SONAME and `std::runtime_error::what()` simply is not

// there. Coupling to the toolchain's libstdc++.so is the only

// spelling under which the executable keeps its own contract.

//

// The other two formats do not have that hazard, and their

// current behaviour is therefore correct and unchanged:

//

// Mach-O the self-contained mechanism already IS hiding —

// `-Wl,-load_hidden,<archive>` gives the archive's

// symbols hidden visibility precisely so dyld cannot

// unify them (PR #117). ToolchainCoupled is also a

// documented dead end there (#202): LLVM's macOS

// libc++abi/libunwind dylibs upward-link /usr/lib/libc++

// and a second libc++ loads alongside the toolchain's.

//

// PE no global symbol namespace at all — imports resolve

// per-DLL by name, so a DLL's private CRT cannot be

// picked up by anything else. `-static` is additionally

// the standalone-DLL convention there.

return f == Format::Elf ? Contract::ToolchainCoupled

: Contract::SelfContained;

}

return Contract::SelfContained;

Contract requested = Contract::SelfContained;

Role role = Role::Distributable;

// Did a human write this contract down, or is it just our default?

//

// The distinction decides whether a cell with no mechanism SPEAKS. A

// diagnostic is for a BROKEN PROMISE: mcpp said the artifact would be

// self-contained and it is not. Most roles DEFAULT to self-contained, so

// on a runtime where that default cannot be delivered, warning on every

// build would be noise nobody can act on. Cells where mcpp DOES promise

// something (a missing libc++.a under the default, say) report regardless.

bool explicitRequest = false;

// MSVC only: is this project compiled with the static CRT (`/MT`)?

//

// A whole-PROJECT fact, not a per-role one, and that is a property of the

// platform rather than a simplification: cl bakes _MSVC_MT / _MSVC_MD

// into the std module, one std module is built per project, and a TU

// importing the other one fails inside the ucrt headers (#422). So the

// table can honour a project-level request and must refuse a per-role

// one — out loud, since silently ignoring it is how a knob becomes

// decoration. Derived by `msvc_wants_static_crt`, which is also what

// emits the flag.

bool msvcStaticCrt = false;

// Toolchain capability id: "libstdc++", "libc++", or an MSVC STL spelling.

std::string_view stdlibId;

Format format = Format::Elf;

// MinGW targets are PE + libstdc++ and take the whole-link `-static`

// rather than the piecemeal `-static-libstdc++` (the latter still leaves

// libwinpthread-1.dll behind).

bool mingw = false;

// Host is Windows. Only reason it is here: the historical flag string

// adds `-static-libgcc` on a Windows HOST, and this table reproduces the

// existing bytes rather than quietly "improving" them.

bool hostIsWindows = false;

// `linkage = "static"` — the libc axis. On PE it shares the one `-static`

// spelling with the C++ runtime axis, so the table has to see it.

bool fullStaticLibc = false;

// Already-escaped archive paths for the explicit-archive mechanisms.

// Empty string = that archive is not available on this toolchain.

std::string libcxxArchive;

std::string libcxxAbiArchive;

std::string libunwindArchive;

// macOS only: the libc++ archive actually defines the ABI symbol the

// initializer-ordering shim binds to. Checked against the archive rather

// than assumed, so an unexpected spelling disables the shim instead of

// producing an undefined reference at link time.

bool streamInitSymbolPresent = false;

// macOS only: a deployment floor was resolved. The static-libc++

// mechanism exists to make that floor real, so without one there is

// nothing to make real.

bool macosFloor = false;

// Flags for this link unit, each with a leading space. Per-unit rather

// than global precisely so two roles in one build can differ.

std::string unitFlags;

// The subset that is NOT a statement about the C++ runtime, for a link

// unit with no C++ in it (mcpp#426). Accumulated HERE, beside the flags

// themselves, rather than filtered downstream: which of these is a C++

// decision is knowledge this table has and a string filter would have to

// re-derive. On macOS the difference is not cosmetic — the self-contained

// contract names `libc++.a`/`libc++abi.a` by path, so a pure-C library

// would otherwise have the C++ runtime linked INTO it.

std::string unitFlagsC;

Contract effective = Contract::SelfContained;

// effective != requested. `diagnostic` is then non-empty and the caller

// is required to surface it — see INV-1/INV-4 in the analysis doc.

bool degraded = false;

std::string diagnostic;

// Mach-O + static libc++: the archive's stream initializer is appended

// LAST in __init_offsets (Mach-O has no priority-ordered init section and

// libc++'s <iostream> carries no `ios_base::Init` guard of its own), so a

// global constructor that touches std::cout runs before the streams

// exist. Asks the backend for the ordering shim. See issue #336.

bool streamInitShim = false;

// PE + MSVC runtime + toolchain-coupled: the toolset's own redistributable

// CRT DLLs must be STAGED BESIDE the artifact.

//

// On ELF, `toolchain-coupled` needs no files copied — the artifact carries

// an rpath into the toolchain's lib directory and the loader follows it.

// PE has no rpath: a DLL is resolved from the directory of the executable

// (and then PATH), so on this format the mechanism IS the copy. Same

// contract, same meaning, different mechanism — which is exactly the split

// this module's three layers exist to express.

bool deployToolchainRuntime = false;

std::initializer_list<std::string_view> archives) {

if (role != Role::SharedLibrary) return {};

std::string out;

for (auto archive : archives) {

out += " -Wl,--exclude-libs,";

out += archive;

}

return out;

Mechanism m;

m.effective = in.requested;

// An archive is linked, not run. It embeds no runtime and imposes none —

// the contract belongs to whatever eventually links it.

if (in.role == Role::Intermediate)

return m;

const bool haveCxxArchives =

!in.libcxxArchive.empty() && !in.libcxxAbiArchive.empty();

switch (in.format) {

// ------------------------------------------------------------- Mach-O

case Format::MachO: {

if (!detail::is_libcxx(in.stdlibId)) {

// Mach-O without libc++ is not a configuration mcpp produces.

m.effective = Contract::HostCoupled;

m.unitFlags = " -lc++";

if (in.requested != Contract::HostCoupled && in.explicitRequest) {

m.degraded = true;

m.diagnostic = std::format(

"cxx_runtime = \"{}\" is not available for stdlib '{}' on "

"Mach-O; using host-coupled", to_string(in.requested), in.stdlibId);

}

return m;

}

if (in.requested == Contract::ToolchainCoupled) {

// The toolchain's libc++.dylib is a dead end on this

// distribution: LLVM's macOS libc++abi/libunwind dylibs

// upward-link /usr/lib/libc++, so the SYSTEM libc++ loads

// alongside the toolchain's and objects freed across the two

// copies abort in libmalloc (#202 crash forensics).

m.effective = Contract::SelfContained;

m.degraded = true;

m.diagnostic =

"cxx_runtime = \"toolchain-coupled\" is not supported on macOS "

"(LLVM's libc++abi/libunwind dylibs upward-link /usr/lib/libc++, "

"which loads a second libc++ into the process); using self-contained";

}

if (m.effective == Contract::SelfContained) {

if (!haveCxxArchives || !in.macosFloor) {

m.effective = Contract::HostCoupled;

m.degraded = true;

m.diagnostic = haveCxxArchives

? "no macOS deployment floor resolved, so the static libc++ "

"that makes the floor real is pointless; using host-coupled"

: "this toolchain ships no libc++.a/libc++abi.a; "

"using host-coupled (the artifact then runs only on the "

"build machine's macOS version and above)";

m.unitFlags = " -lc++";

return m;

}

// -Wl,-load_hidden,<path> rather than a plain by-path link: it

// forces the ARCHIVE (never a sibling dylib) AND gives its

// symbols hidden visibility. Without the hidden part, dyld

// unifies them with the system libc++ from the shared cache and

// ostream<<int crosses into the other copy's locale machinery

// (PR #117 forensics).

m.unitFlags = " -nostdlib++"

" -Wl,-load_hidden," + in.libcxxArchive +

" -Wl,-load_hidden," + in.libcxxAbiArchive;

// The ordering shim binds a libc++ INTERNAL ABI symbol, so its

// presence is verified against the archive instead of assumed.

// Getting this wrong must not break the link — hence a check

// here rather than a weak reference in the shim: Mach-O's

// weak-undefined form is `weak_import` and applies to dylib

// symbols, so a plain weak declaration would NOT have saved a

// missing archive symbol (it did not: ld64.lld errored outright).

m.streamInitShim = in.streamInitSymbolPresent;

if (!m.streamInitShim) {

m.diagnostic =

"this libc++ does not export the stream initializer mcpp "

"orders first on macOS; a global object whose constructor "

"uses std::cout may crash at startup (mcpp#336). Use "

"cxx_runtime = \"host-coupled\" if you hit it";

}

return m;

}

// HostCoupled

m.unitFlags = " -lc++";

return m;

}

// ---------------------------------------------------------------- PE

case Format::Pe: {

if (!detail::is_libstdcxx(in.stdlibId)) {

// MSVC STL (cl.exe, or clang on the MSVC ABI). The CRT model is

// the mechanism here, and it is a whole-project switch: /MT is

// self-contained (no vcruntime DLL dependency), /MD is

// host-coupled. `msvcStaticCrt` is that switch, already derived

// by whoever emits the flag — so what this table reports and what

// cl was actually told cannot disagree.

//

// No unit flags: the model is a COMPILE flag on every TU, not

// something added to the link line.

m.effective = in.msvcStaticCrt ? Contract::SelfContained

: Contract::HostCoupled;

if (in.requested == Contract::SelfContained && !in.msvcStaticCrt) {

// Asked for, not delivered. Only reachable from a per-ROLE

// override, because a project-level one would have set

// msvcStaticCrt — so name that, instead of the old "not

// implemented", which stopped being true and had already

// been contradicted by flags.cppm emitting /MT for

// `linkage = "static"`.

m.degraded = in.explicitRequest;

m.diagnostic = in.explicitRequest

? "on the MSVC runtime the CRT model is a whole-project "

"property — one std module is built per project and cl "

"bakes _MSVC_MT/_MSVC_MD into it, so a single role "

"cannot differ. Move it to [build] cxx_runtime = "

"\"self-contained\" (or linkage = \"static\") to apply "

"it everywhere; using host-coupled here"

: "";

} else if (in.requested == Contract::ToolchainCoupled) {

// THIS USED TO BE A FLAT REFUSAL, and the sentence it refused

// with was half true:

//

// "…has no meaning for the MSVC runtime (it ships with the

// OS/redistributable, not with the toolchain)"

//

// True of `ucrtbase.dll`, which IS an OS component since

// Win10. NOT true of `vcruntime140.dll` / `msvcp140.dll`,

// which are the toolset's own and sit inside every MSVC

// toolset ever shipped:

//

// VC\Redist\MSVC\<ver>\<arch>\Microsoft.VC<N>.CRT\*.dll

//

// That is the same relationship gcc has to libstdc++.so, so it

// takes the same contract — and refusing it left a hole in the

// matrix that had a real cost: the default `/MD` artifact

// depends on DLLs a machine with only a managed toolset does

// not have, and there was no spelling that made them travel.

//

// `/MT` is the one case that stays a degradation, and it is a

// genuine contradiction rather than a missing mechanism: a

// static CRT leaves NO DLL to couple to. Say which one won.

if (in.msvcStaticCrt) {

m.effective = Contract::SelfContained;

m.degraded = true;

m.diagnostic =

"cxx_runtime = \"toolchain-coupled\" cannot apply to a "

"project compiled with the static CRT (/MT): there is "

"no vcruntime140.dll/msvcp140.dll dependency left to "

"couple to. Drop linkage = \"static\" (or the "

"project-wide self-contained contract) if the toolset's "

"CRT should travel beside the artifact instead; using "

"self-contained";

} else {

m.effective = Contract::ToolchainCoupled;

m.deployToolchainRuntime = true;

}

}

return m;

}

// MinGW. `-static` is the standalone-exe convention here: the

// piecemeal -static-libstdc++ recipe still leaves libwinpthread-1.dll.

// It is also the spelling the libc axis uses, so `linkage = "static"`

// keeps it regardless of the C++ runtime contract.

const bool wantStatic =

m.effective == Contract::SelfContained || in.fullStaticLibc;

// `-static` and `-static-libgcc` are libc / compiler-runtime

// decisions, not C++ ones: a self-contained pure-C DLL wants both.

if (wantStatic) { m.unitFlags += " -static"; m.unitFlagsC += " -static"; }

if (m.effective == Contract::SelfContained) {

m.unitFlags += " -static-libstdc++";

if (in.hostIsWindows) {

m.unitFlags += " -static-libgcc";

m.unitFlagsC += " -static-libgcc";

}

}

return m;

}

// --------------------------------------------------------------- ELF

case Format::Elf:

default: {

if (detail::is_libstdcxx(in.stdlibId)) {

if (m.effective == Contract::SelfContained) {

m.unitFlags = " -static-libstdc++";

m.unitFlags += detail::hide_static_cxx_runtime(

in.role, {"libstdc++.a"});

}

// ToolchainCoupled and HostCoupled are the same emission on ELF

// (no flag); they differ in the rpath the link already carries,

// which is the documented limit of this contract. For a shared

// library ToolchainCoupled is the DEFAULT (see `default_contract`)

// and "no flag" is the entire mechanism: the driver links

// libstdc++.so, and the toolchain's lib directory is already an

// `-L` and an rpath entry on this line.

return m;

}

if (detail::is_libcxx(in.stdlibId)) {

if (m.effective != Contract::SelfContained)

return m; // driver default: the toolchain's libc++.so via rpath

if (!haveCxxArchives) {

m.effective = Contract::ToolchainCoupled;

m.degraded = true;

m.diagnostic =

"this toolchain ships no libc++.a/libc++abi.a; using "

"toolchain-coupled (the artifact keeps a run-time dependency "

"on the toolchain's libc++.so)";

return m;

}

// Verified locally: -nostdlib++ plus the three archives leaves

// NEEDED = libc/libm/loader only. Without libunwind.a the binary

// still pulls libunwind.so.1, which is not self-contained — so it

// is part of the mechanism, not an optional extra.

m.unitFlags = " -nostdlib++ " + in.libcxxArchive

+ " " + in.libcxxAbiArchive;

m.unitFlags += detail::hide_static_cxx_runtime(

in.role, {"libc++.a", "libc++abi.a"});

if (!in.libunwindArchive.empty()) {

m.unitFlags += " " + in.libunwindArchive;

m.unitFlags += detail::hide_static_cxx_runtime(

in.role, {"libunwind.a"});

} else {

m.degraded = true; // effective stays SelfContained: the C++

// runtime IS embedded; the unwinder is not

m.diagnostic =

"this toolchain ships no libunwind.a; the C++ runtime is "

"embedded but the artifact keeps a run-time dependency on "

"libunwind.so";

}

return m;

}

// Unknown stdlib on ELF: emit nothing rather than guess, but say so

// when something was actually asked for.

m.effective = Contract::HostCoupled;

if (in.requested != Contract::HostCoupled && in.explicitRequest) {

m.degraded = true;

m.diagnostic = std::format(

"cxx_runtime = \"{}\" has no mechanism for stdlib '{}'; "

"using host-coupled", to_string(in.requested), in.stdlibId);

}

return m;

}

}

return

"/* Generated by mcpp. macOS + self-contained (static libc++) only.\n"

" * Mach-O has no priority-ordered initializer section, so the stream\n"

" * initializer pulled out of libc++.a lands LAST in __init_offsets and\n"

" * a global constructor that touches std::cout sees an unconstructed\n"

" * stream (null vptr -> SIGSEGV at process start). libc++'s <iostream>\n"

" * has no ios_base::Init guard of its own, unlike libstdc++/MSVC STL,\n"

" * so the header cannot fix it either. mcpp-community/mcpp#336.\n"

" *\n"

" * Weak: a toolchain without this exact ABI symbol links as before.\n"

" */\n"

"extern void mcpp_libcxx_ios_init(void *)\n"

" __attribute__((weak_import))\n"

" __asm__(\"__ZNSt3__18ios_base4InitC1Ev\");\n"

"\n"

"static char mcpp_libcxx_ios_init_storage[8];\n"

"\n"

"__attribute__((constructor))\n"

"static void mcpp_force_std_streams(void) {\n"

" if (mcpp_libcxx_ios_init)\n"

" mcpp_libcxx_ios_init(mcpp_libcxx_ios_init_storage);\n"

"}\n";