@@ -16,22 +16,45 @@ Downloading xim:musl-gcc@15.1.0 [====> ] 312 MB / 808 MB 3.7 MB/s
1616Default set to gcc@15.1.0-musl
1717```
1818
19- Linux defaults to ` gcc@15.1.0-musl ` ; macOS defaults to ` llvm@20.1.7 ` .
19+ The first-run default is host-aware: Linux x86_64 → ` gcc@16.1.0 ` (glibc — the
20+ native ABI, so X11/GL/system libraries link out of the box); other Linux
21+ arches (aarch64, …) → ` gcc@15.1.0-musl ` (self-contained, fully static);
22+ macOS and Windows → ` llvm@20.1.7 ` . Fully-static musl output stays one flag
23+ away on any Linux host: ` mcpp build --target x86_64-linux-musl ` .
2024
2125Subsequent builds do not trigger this process again.
2226
2327> [ !TIP]
2428> 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.
2529
30+ ## The Identity Model: Toolchain × Target
31+
32+ Two orthogonal axes name everything:
33+
34+ - ** toolchain** = ` family@version ` , family ∈ ` gcc | llvm | msvc ` — * who compiles*
35+ - ** target** = a triple ` arch-os[-env] ` (e.g. ` x86_64-linux-musl ` ,
36+ ` x86_64-windows-gnu ` , ` aarch64-macos ` ) — * what it produces for*
37+
38+ Variants live in the target's ` env ` segment (` gnu | musl | msvc ` ), never in
39+ the toolchain name. "Cross" is not a name either — it's just the relation
40+ ` host ≠ target ` , and the same command works for both. Legacy spellings
41+ (` musl-gcc ` , ` gcc@15.1.0-musl ` , ` mingw ` , ` mingw-cross ` , ` clang ` ,
42+ ` x86_64-w64-mingw32 ` ) are ** permanently accepted aliases** that normalize to
43+ this model with a one-line ` note: ` hint.
44+
2645## Manual Installation
2746
2847``` bash
29- mcpp toolchain install gcc 16.1.0 # GNU libc, for the default dynamic-linking case
30- mcpp toolchain install gcc 15.1.0-musl # musl libc, for fully static builds
31- mcpp toolchain install musl-gcc 15.1.0 # equivalent to the line above
32- mcpp toolchain install llvm 20.1.7 # LLVM/Clang, the default toolchain on macOS
48+ mcpp toolchain install gcc 16.1.0 # host target (GNU libc on Linux)
49+ mcpp toolchain install llvm 20.1.7 # LLVM/Clang, the default on macOS/Windows
50+ mcpp toolchain install gcc 16 --target x86_64-linux-musl # musl target payload
51+ mcpp toolchain install --target x86_64-windows-gnu # family omitted → the
52+ # target's convention pin (gcc@16.1.0)
3353```
3454
55+ Explicit installation is mostly for CI cache warm-up and offline prep —
56+ ` mcpp build --target <triple> ` auto-installs whatever the target needs.
57+
3558Version numbers support partial matching:
3659
3760``` bash
@@ -41,56 +64,76 @@ mcpp toolchain install gcc@16 # the @ form works too
4164
4265## Switching the Default Toolchain
4366
67+ The default is a * pair* — toolchain axis + target axis (target omitted = host):
68+
4469``` bash
4570mcpp toolchain default gcc@16.1.0
46- mcpp toolchain default gcc 15 # with a partial version, picks the highest installed match
71+ mcpp toolchain default gcc 15 # partial version → highest installed match
72+ mcpp toolchain default gcc@16 --target x86_64-linux-musl # "default to fully-static musl"
4773```
4874
75+ The pair persists as ` [toolchain] default = "gcc@16.1.0" ` +
76+ ` default_target = "x86_64-linux-musl" ` in ` ~/.mcpp/config.toml ` . (Older
77+ configs with combined spellings like ` default = "gcc@15.1.0-musl" ` keep
78+ working unchanged.)
79+
4980## Inspecting Toolchain Status
5081
5182``` bash
5283mcpp toolchain list
5384```
5485
55- The output looks like this :
86+ The output has two blocks — one per axis :
5687
5788```
58- Installed:
59- TOOLCHAIN BINARY
60- gcc 15.1.0-musl @mcpp/registry/data/xpkgs/xim-x-musl-gcc/15.1.0/bin/x86_64-linux-musl-g++
61- * gcc 16.1.0 @mcpp/registry/data/xpkgs/xim-x-gcc/16.1.0/bin/g++
62-
63- Available (run `mcpp toolchain install <compiler> <version>`):
64- TOOLCHAIN
65- gcc 13.3.0
66- gcc 11.5.0
67- ...
89+ Toolchains:
90+ * gcc 16.1.0 (default)
91+ gcc 15.1.0
92+ llvm 22.1.8
93+
94+ Targets:
95+ TARGET NOTE TOOLCHAIN STATUS
96+ x86_64-linux-gnu host gcc 16.1.0 installed
97+ * x86_64-linux-musl static gcc 16.1.0 installed
98+ x86_64-windows-gnu PE, static, cross gcc 16.1.0 installed
99+ aarch64-linux-musl static, cross gcc 16.1.0 available
100+ riscv64-linux-musl static, cross — planned
101+
102+ Available toolchains (run `mcpp toolchain install <family> <version>`):
103+ gcc 15.1.0 / 13.3.0 / 11.5.0 / 9.4.0
104+ llvm 20.1.7
68105```
69106
70- The entry marked with ` * ` is the current default toolchain. ` @mcpp/... ` is shorthand for ` ~/.mcpp/... ` , used to keep the output narrower.
107+ ` * ` marks the default pair. The Targets block is the live view of the target
108+ vocabulary: ` installed ` payloads, ` available ` targets this host can install,
109+ and ` planned ` targets that are registered but not yet shipped.
71110
72- ## MinGW (Windows-native GCC , no Visual Studio required)
111+ ## Windows PE via MinGW-w64 ( ` x86_64-windows-gnu ` , no Visual Studio required)
73112
74- On Windows, ` mingw ` installs a self-contained MinGW-w64 GCC (winlibs
75- standalone build, UCRT runtime) into mcpp's sandbox — the same managed-xpkg
76- model as ` gcc ` /` llvm ` , no Visual Studio needed:
113+ "MinGW" in mcpp is a ** target** , not a toolchain name: ` x86_64-windows-gnu `
114+ — GCC producing Windows PE with the GNU CRT. The same identity works from
115+ both hosts; which self-contained payload serves it is resolved automatically
116+ (Windows host → winlibs UCRT build; Linux host → the from-source MSVCRT
117+ cross toolchain, wine-verified in CI):
77118
78119``` bash
79- mcpp toolchain install mingw 16.1.0
80- mcpp toolchain default mingw@16.1.0
120+ mcpp build --target x86_64-windows-gnu # from Windows OR Linux
121+ mcpp toolchain default gcc@16 --target x86_64-windows-gnu
122+ # legacy spellings still accepted: mingw@16.1.0, mingw-cross@16.1.0,
123+ # --target x86_64-w64-mingw32
81124```
82125
83126It uses the regular GCC module pipeline (` gcm.cache ` , ` import std ` via
84- libstdc++'s ` bits/std.cc ` ). Produced binaries statically link libstdc++ and
85- libgcc by default, so they run standalone — no ` libstdc++-6.dll ` needs to
86- travel next to your exe (opt out with ` [build] static_stdlib = false ` ).
87- ` [build] linkage = "static" ` upgrades that to a fully static link.
127+ libstdc++'s ` bits/std.cc ` ). The target's default linkage is ** static** —
128+ the produced ` .exe ` is fully self-contained (no ` libstdc++-6.dll ` to ship,
129+ runs directly under wine); ` [build] linkage = "dynamic" ` opts out.
88130
89131In a manifest:
90132
91133``` toml
92134[toolchain ]
93- windows = " mingw@16.1.0"
135+ windows = " gcc@16" # gcc family on Windows = MinGW-w64
136+ # legacy value "mingw@16.1.0" keeps working
94137```
95138
96139## MSVC (System Toolchain, Windows)
@@ -157,13 +200,42 @@ macos = "llvm@20"
157200
158201A project-level declaration takes precedence over the global default configuration.
159202
160- ## Cross-Toolchain Builds
203+ ## Targets & Cross Builds
161204
162205``` bash
163- mcpp build --target x86_64-linux-musl
206+ mcpp build --target x86_64-linux-musl # fully static ELF
207+ mcpp build --target aarch64-linux-musl # cross-arch (aarch64 on x86_64)
208+ mcpp build --target x86_64-windows-gnu # Windows PE from Linux
209+ ```
210+
211+ ` --target ` is validated against the known-target vocabulary (see the README
212+ platform table, which mirrors it): a typo is a ** hard error with a
213+ suggestion** (` did you mean 'x86_64-linux-musl'? ` ) — never a silent host
214+ build. Custom triples outside the vocabulary are allowed when an explicit
215+ ` [target.<triple>] ` section declares them in ` mcpp.toml ` .
216+
217+ Each known target carries a convention: its pinned toolchain (installed on
218+ demand) and its default linkage (` *-linux-musl ` and ` x86_64-windows-gnu `
219+ default to static). An explicit ` [target.<triple>] ` section overrides both:
220+
221+ ``` toml
222+ [target .x86_64-linux-musl ]
223+ toolchain = " gcc@16.1.0"
224+ linkage = " static"
225+ ```
226+
227+ A project can set its * default* build target — this is where "this project
228+ ships fully-static" belongs (static output is a product property, not a
229+ compiler-family property):
230+
231+ ``` toml
232+ [build ]
233+ target = " x86_64-linux-musl" # ≙ cargo's build.target
164234```
165235
166- 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 ` ] ( ../examples/03-pack-static/ ) .
236+ Combined with ` mcpp pack --mode static ` this produces a fully static release
237+ package; for a complete example, see
238+ [ ` examples/03-pack-static ` ] ( ../examples/03-pack-static/ ) .
167239
168240## Uninstalling
169241
0 commit comments