feat(profile): default build profile = dev (mainstream), --release opt-in (v0.0.76) (#188)

* feat(profile): default build profile = dev (mainstream); --release opt-in; v0.0.76

Resolves #179. mcpp's old default profile was "release" (inherited from its
xmake/xlings lineage), but the dominant convention is the opposite: a bare build
is debug/dev and release is opt-in (Cargo/Meson/CMake/Zig/Bazel/MSBuild). Since
mcpp's surface is Cargo-flavored, flip the global default to "dev" (-O0 -g);
release is opt-in via --release / --profile release.

- prepare.cppm: global default profile release -> dev. Precedence:
  --profile/--release/--dev flag > [build].default-profile > "dev".
- cli.cppm/cmd_build.cppm: add --release / --dev shorthands (--release is now the
  mainstream opt-in flag).
- manifest.cppm: [build].default-profile (alias: profile) — a project's own
  default; its role inverts under the flip to "opt into release" for projects
  that ship/run optimized. This is the migration mechanism.
- mcpp.toml: default-profile = "release" — keeps mcpp's self-host CI build and
  release.yml at -O2 with ZERO workflow changes (no --release threaded through
  release pipelines; mcpp's own CI doesn't slow to -O0).
- cross-build-test.yml: bump xlings cache key v2->v3 (the failing job was a
  poisoned ~/.xlings cache from the bootstrap-pin-timing, not code).

Tests: 87_build_default_profile.sh (global dev; --release/--dev; project
default-profile=release; --dev override), 68_profile_passthrough.sh (updated for
the new default). Regression: unit 27/0. Doc: design doc L0.5 (convention table +
decision + migration). mcpp self-build verified 'Finished release [optimized]'.

* ci+docs: revert cross-build cache key to v2 (warm); document dev default in user docs

- cross-build-test.yml: revert xlings cache key v3->v2. The v3 bump forced a COLD
  ~/.xlings, whose first-time toolchain install 127'd; v2 reuses the warm cache
  the passing e2e/ci-linux jobs already use (has 0.0.75 + the toolchain). The
  original 'version 0.0.75 not found' poison is moot now 0.0.75 is fully
  propagated. The self-host bootstrap is otherwise unrelated to this PR's code
  (e2e passed; step 6 bootstrap succeeded).
- docs/05-mcpp-toml.md (+ zh): document the new convention — bare `mcpp build`
  uses dev (-O0 -g); release is opt-in via --release/--profile release; --dev
  shorthand; [build].default-profile per-project default (and the distribution
  note).

* ci(cross-build): xlings 0.4.30 -> 0.4.61 + force index re-sync (fix bootstrap pin resolution)

The cross-build aarch64 job failed at the self-host bootstrap with
'xlings: version <pin> not found for mcpp' — the classic first-PR-after-a-
bootstrap-pin-bump failure: a warm cached ~/.xlings carried a 'fresh-looking'
TTL refresh marker, so 0.4.30's `xlings update` no-op'd and the stale index
never saw the just-bumped pin (0.0.75). (Not this PR's code: e2e passed, the
build+tests pass locally.)

Fix: (1) bump XLINGS_VERSION to 0.4.61 (current; has the index-refresh fixes);
(2) delete the .xlings-index-cache.json TTL markers before `xlings update` so it
actually re-pulls the latest index while the toolchain payloads stay cached
(avoids both the stale-index 'not found' and the cold-cache toolchain 127).

* ci(cross-build): keep xlings 0.4.30, fix via index marker-clear only

0.4.61 resolved the pin (index re-sync worked) but 404'd downloading
xim:mcpp@0.0.75 — it changed the XLINGS_RES download resolution and no longer
matches the xlings-res/mcpp asset layout (0.4.30's resolution works; e2e@0.4.30
downloads 0.0.75 fine). The actual bug was the STALE INDEX (a fresh-looking TTL
marker made 0.4.30's `xlings update` no-op). Revert to 0.4.30 and keep the
.xlings-index-cache.json marker-clear, so update re-pulls the index (gets the
bootstrap pin) while download uses 0.4.30's working path.

* ci(cross-build): xlings 0.4.61 (root cause was broken xlings-res assets, now fixed)

The real root cause of the cross-build bootstrap failures was NOT the xlings
version or the profile code: the xlings-res/mcpp 0.0.75 GitHub release assets
were uploaded in a BROKEN state during a flaky network (asset records present
but blobs missing -> HTTP 404 on download). cross-build uses --mirror GLOBAL
(GitHub), so its 'xlings install mcpp@0.0.75' 404'd; the downstream symptom on
0.4.30 was 'version 0.0.75 not found'. GitCode assets were fine all along.

Re-uploaded all 4 GitHub xlings-res/mcpp 0.0.75 assets clean (verified GET 200 +
correct sizes). With downloads working, use 0.4.61 (current) + keep the
.xlings-index-cache.json marker-clear (forces index re-sync past a stale TTL
marker on warm caches).

Author: Sunrisepeak

.agents/docs/2026-06-29-manifest-environment-and-platform-design.md

@@ -92,6 +92,43 @@ expressible, all backed by existing xlings behavior.
 
 ---
 
+## L0.5 — Default build profile: follow the mainstream (dev), `--release` opt-in
+
+(Issue #179.) mcpp's old default was `release`; the prevailing convention across
+modern build tools is the **opposite** — a bare build is **debug/dev**, release is
+opt-in:
+
+| Tool | bare-command default | release via |
+|---|---|---|
+| Cargo | **dev/debug** (-O0 + debuginfo) | `cargo build --release` |
+| Meson | **debug** | `--buildtype=release` |
+| CMake | empty `CMAKE_BUILD_TYPE` (≈debug) | `-DCMAKE_BUILD_TYPE=Release` |
+| Zig | **Debug** | `-Doptimize=ReleaseFast/Safe/Small` |
+| Bazel | **fastbuild** (no opt) | `-c opt` |
+| MSBuild/VS | **Debug** | Release configuration |
+| **xmake** | **release** | `xmake f -m debug` |
+
+Debug-default dominates (Cargo/Meson/CMake/Zig/Bazel/MSBuild); only the **xmake**
+lineage defaults to release — exactly where mcpp's old default came from (mcpp builds
+on xlings/xmake). But mcpp's *surface* is Cargo-flavored, so users expect Cargo
+semantics. **Decision: flip the global default to `dev` (-O0 -g); release is opt-in
+via `--release` / `--profile release`.**
+
+- **Precedence**: `--profile NAME` / `--release` / `--dev` flag > `[build].default-profile`
+  (project default) > global `dev`. (`prepare.cppm`; `--dev`/`--release` are shorthands
+  in `cli.cppm`/`cmd_build.cppm`.)
+- **`[build].default-profile`** (alias: `profile`) — a project's own default; its role
+  *inverts* under the flip: it now means **"opt into release"** for projects that ship/
+  run optimized by default. **mcpp's own `mcpp.toml` sets `default-profile = "release"`**
+  so the self-host CI build and `release.yml` stay `-O2` with **zero workflow changes** —
+  the knob *is* the migration mechanism (no `--release` threaded through release pipelines,
+  and mcpp's own CI doesn't slow to `-O0`).
+- **Distribution footgun**: a project that defaults to dev passes `--release` to produce
+  a distributable (a pack-time release guard is a possible follow-up).
+- Tests: `tests/e2e/87_build_default_profile.sh`, `68_profile_passthrough.sh` (updated).
+
+---
+
 ## L0 — Dependency categories: keep three axes, wire `build`
 
 Keep Cargo/Conan's **normal / dev / build** trichotomy (mcpp already declares all

.github/workflows/cross-build-test.yml

@@ -87,7 +87,12 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '0.4.30'
+          # 0.4.61 (current). The earlier 0.4.61 "download 404 for mcpp@<pin>" was
+          # NOT a version bug — the xlings-res/mcpp GitHub release assets were
+          # uploaded in a broken state (records present, blobs missing → 404 on
+          # GET); re-uploaded clean. The stale-INDEX half is handled by the
+          # marker-clear below.
+          XLINGS_VERSION: '0.4.61'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           curl -fsSL -o "/tmp/${tarball}" \
@@ -96,8 +101,10 @@ jobs:
           "/tmp/xlings-${XLINGS_VERSION}-linux-x86_64/subos/default/bin/xlings" self install
           export PATH="$HOME/.xlings/subos/default/bin:$PATH"
           xlings --version
-          # Refresh the index so a cached ~/.xlings still sees newly published
-          # cross toolchains (xim:aarch64-linux-musl-gcc, static ninja, ...).
+          # Force a real index re-sync even on a warm cache: drop the TTL refresh
+          # markers so `xlings update` actually pulls the latest index (sees the
+          # current bootstrap pin) while the toolchain payloads stay cached.
+          find "$HOME/.xlings" -name '.xlings-index-cache.json' -delete 2>/dev/null || true
           xlings config --mirror GLOBAL 2>/dev/null || true
           xlings update -y 2>/dev/null || xlings update 2>/dev/null || true
           xlings install mcpp -y

docs/05-mcpp-toml.md

@@ -411,8 +411,16 @@ cxxflags = ["-fno-plt"]
 ldflags  = []
 ```
 
-- Selection: `mcpp build --profile <name>` (and `mcpp test --profile <name>`, which builds the
-  code-under-test plus the test binaries under that profile), defaulting to `release`.
+- Selection & default: a bare `mcpp build` uses the **`dev`** profile (`-O0 -g`) — the
+  mainstream convention (cf. Cargo/Meson/CMake/Zig/Bazel). **Release is opt-in:**
+  `mcpp build --release` (shorthand) or `--profile release`. `--dev` is the explicit
+  shorthand for dev. Same applies to `mcpp test --profile <name>` (builds the
+  code-under-test plus the test binaries under that profile).
+- **Per-project default** — `[build].default-profile = "<name>"` (alias: `profile`) sets
+  the project's own default when no flag is passed. The typical use is a tool/library
+  that should build optimized by default: `[build] default-profile = "release"`. Precedence:
+  `--profile`/`--release`/`--dev` flag **>** `[build].default-profile` **>** global `dev`.
+  (A project that defaults to dev should pass `--release` when producing a distributable.)
 - Built-in profiles: `release` (-O2) / `dev`, `debug` (-O0 -g) / `dist` (-O3 + strip;
   **LTO is not enabled by default**). `[profile.<built-in name>]` can override a
   built-in definition wholesale.

docs/zh/05-mcpp-toml.md

@@ -389,8 +389,14 @@ cxxflags = ["-fno-plt"]
 ldflags  = []
 ```
 
-- 选择:`mcpp build --profile <name>`(以及 `mcpp test --profile <name>`,会让被测代码与测试二进制
-  都在该 profile 下编译),默认 `release`。
+- 选择与默认:裸 `mcpp build` 走 **`dev`** 档(`-O0 -g`)——主流惯例(参照
+  Cargo/Meson/CMake/Zig/Bazel)。**release 为 opt-in:** `mcpp build --release`(短写)或
+  `--profile release`;`--dev` 是 dev 的显式短写。`mcpp test --profile <name>` 同理
+  (被测代码与测试二进制都在该 profile 下编译)。
+- **项目级默认** —— `[build].default-profile = "<name>"`(别名 `profile`)设置该项目在不带
+  flag 时的默认。典型用途是"以发布优化为常态"的工具/库:`[build] default-profile = "release"`。
+  优先级:`--profile`/`--release`/`--dev` flag **>** `[build].default-profile` **>** 全局 `dev`。
+  (默认 dev 的项目在产出可分发物时应显式 `--release`。)
 - 内置档案:`release`(-O2)/ `dev`、`debug`(-O0 -g)/ `dist`(-O3 + strip;
   **不默认开 lto**)。`[profile.<内置名>]` 可整体覆盖内置定义。
 

mcpp.toml

@@ -1,12 +1,17 @@
 [package]
 name        = "mcpp"
-version     = "0.0.75"
+version     = "0.0.76"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]
 repo        = "https://github.com/mcpp-community/mcpp"
 
 [build]
+# The global default profile is now "dev" (-O0 -g, mainstream convention);
+# mcpp itself is a shipped tool, so opt its plain `mcpp build` (and release.yml's
+# self-host build) back into the optimized profile. Without this the released
+# binary would be -O0. A `--profile`/`--dev`/`--release` flag still overrides.
+default-profile = "release"
 # nlohmann/json.hpp lives in src/libs/json/; expose it to the global
 # module fragment `#include <json.hpp>` in src/libs/json.cppm.
 include_dirs = ["src/libs/json"]

src/build/prepare.cppm

@@ -554,10 +554,19 @@ prepare_build(bool print_fingerprint,
     //   1. project mcpp.toml [toolchain].<platform> or .default
     //   2. global ~/.mcpp/config.toml [toolchain].default
     //   3. hard error (no system fallback)
-    // Resolve the build profile: --profile (default "release") → built-in
-    // defaults, overlaid by any [profile.<name>] from the manifest → buildConfig.
+    // Resolve the build profile, overlaid by any [profile.<name>] from the
+    // manifest → buildConfig.
     {
-        std::string pname = overrides.profile.empty() ? "release" : overrides.profile;
+        // Precedence: --profile / --release / --dev flag (overrides.profile) >
+        // [build].default-profile (project default) > "dev" (global default).
+        // The global default is "dev" (-O0 -g) to follow the dominant convention
+        // (Cargo/Meson/CMake/Zig/Bazel/MSBuild all default to debug); release is
+        // opt-in via --release / --profile release. A project that wants its
+        // plain `mcpp build` optimized sets [build].default-profile = "release"
+        // (mcpp's own mcpp.toml does this, so the released binary stays -O2).
+        std::string pname = !overrides.profile.empty()             ? overrides.profile
+                          : !m->buildConfig.defaultProfile.empty() ? m->buildConfig.defaultProfile
+                          :                                          "dev";
         mcpp::manifest::Profile pr;
         if (pname == "dev" || pname == "debug") { pr.optLevel = "0"; pr.debug = true; }
         else if (pname == "dist")               { pr.optLevel = "3"; pr.strip = true; }

src/cli.cppm

@@ -226,6 +226,8 @@ int run(int argc, char** argv) {
                 .help("Build only the named workspace member"))
             .option(cl::Option("profile").takes_value().value_name("NAME")
                 .help("Build profile: release (default) | dev | dist | <[profile.*] name>"))
+            .option(cl::Option("release").help("Shorthand for --profile release"))
+            .option(cl::Option("dev").help("Shorthand for --profile dev (-O0 -g)"))
             .option(cl::Option("features").takes_value().value_name("LIST")
                 .help("Activate root-package features (comma-separated)"))
             .option(cl::Option("cap").takes_value().value_name("LIST")

src/cli/cmd_build.cppm

@@ -26,7 +26,12 @@ export int cmd_build(const mcpplibs::cmdline::ParsedArgs& parsed) {
     mcpp::build::BuildOverrides ov;
     if (auto t = parsed.value("target")) ov.target_triple = *t;
     if (auto p = parsed.value("package")) ov.package_filter = *p;
+    // Profile selection precedence: --profile NAME > --release / --dev > the
+    // project default ([build].default-profile) > "release", resolved in
+    // prepare_build. --release/--dev are shorthands only.
     if (auto pr = parsed.value("profile")) ov.profile = *pr;
+    else if (parsed.is_flag_set("release")) ov.profile = "release";
+    else if (parsed.is_flag_set("dev"))     ov.profile = "dev";
     if (auto fs = parsed.value("features")) ov.features = *fs;
     if (auto cp = parsed.value("cap")) ov.capabilities = *cp;
     ov.strict = parsed.is_flag_set("strict");

src/manifest.cppm

@@ -148,6 +148,14 @@ struct BuildConfig {
     bool                                debug    = false; // -g
     bool                                lto      = false; // -flto
     bool                                strip    = false; // link -s
+    // `[build].default-profile` (alias: `profile`) — the project's DEFAULT
+    // profile when no --profile/--dev/--release is passed. The global convention
+    // default stays "release"; this lets a project opt its plain `mcpp build`
+    // into e.g. "dev" without typing --profile. Precedence: --profile/--dev/
+    // --release flag > [build].default-profile > "release". NOTE (distribution
+    // footgun): a project that defaults to dev should pass `--profile release`
+    // when producing a distributable (a pack-time release guard is a follow-up).
+    std::string                         defaultProfile;
 };
 
 // `[runtime]` — requirements needed when launching built binaries.
@@ -1118,6 +1126,8 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
     if (auto v = doc->get_string_array("build.cxxflags")) m.buildConfig.cxxflags = *v;
     if (auto v = doc->get_string_array("build.ldflags"))  m.buildConfig.ldflags  = *v;
     if (auto v = doc->get_string("build.c_standard"))     m.buildConfig.cStandard = *v;
+    if (auto v = doc->get_string("build.default-profile")) m.buildConfig.defaultProfile = *v;
+    else if (auto v = doc->get_string("build.profile"))   m.buildConfig.defaultProfile = *v;  // accepted alias
     if (auto v = doc->get_string("build.macos_deployment_target"))
         m.buildConfig.macosDeploymentTarget = *v;
     for (auto const& flag : m.buildConfig.cxxflags) {

src/toolchain/fingerprint.cppm

@@ -18,7 +18,7 @@ import mcpp.toolchain.detect;
 
 export namespace mcpp::toolchain {
 
-inline constexpr std::string_view MCPP_VERSION = "0.0.75";
+inline constexpr std::string_view MCPP_VERSION = "0.0.76";
 
 struct FingerprintInputs {
     Toolchain                       toolchain;