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]'.

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

@@ -74,9 +74,9 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.xlings
-          key: xlings-${{ runner.os }}-v2-${{ hashFiles('.xlings.json') }}
+          key: xlings-${{ runner.os }}-v3-${{ hashFiles('.xlings.json') }}
           restore-keys: |
-            xlings-${{ runner.os }}-v2-
+            xlings-${{ runner.os }}-v3-
 
       - name: Install qemu-user-static
         run: |

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;

tests/e2e/68_profile_passthrough.sh

@@ -17,15 +17,15 @@ strip    = true
 cxxflags = ["-fno-plt"]
 EOF
 
-# Built-in release default: -O2, no -g.
-"$MCPP" build --verbose > rel.log 2>&1 || { cat rel.log; echo "release build failed"; exit 1; }
+# Global default is now "dev" (-O0 -g, mainstream convention); release is opt-in.
+"$MCPP" build --release --verbose > rel.log 2>&1 || { cat rel.log; echo "release build failed"; exit 1; }
 grep -q -- "-O2" rel.log || { echo "release missing -O2"; exit 1; }
 
-# dev: -O0 -g.
+# Bare `mcpp build` (no flag) → the dev default: -O0 -g.
 rm -rf target
-"$MCPP" build --profile dev --verbose > dev.log 2>&1 || { cat dev.log; echo "dev build failed"; exit 1; }
-grep -q -- "-O0" dev.log || { echo "dev missing -O0"; exit 1; }
-grep -q -- "-g"  dev.log || { echo "dev missing -g"; exit 1; }
+"$MCPP" build --verbose > dev.log 2>&1 || { cat dev.log; echo "dev build failed"; exit 1; }
+grep -q -- "-O0" dev.log || { echo "default (dev) missing -O0"; exit 1; }
+grep -q -- "-g"  dev.log || { echo "default (dev) missing -g"; exit 1; }
 
 # dist from [profile.dist]: -O3 -flto + passthrough cxxflag, stripped binary.
 rm -rf target

tests/e2e/87_build_default_profile.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# 87_build_default_profile.sh — profile selection follows the mainstream convention:
+# the GLOBAL default is "dev" (-O0 -g, like Cargo/Meson/CMake/Zig/Bazel/MSBuild);
+# "release" is opt-in via --release / --profile release. A project can set its own
+# default with `[build] default-profile = "<name>"` (e.g. opt back into release).
+# Precedence: --profile/--release/--dev flag > [build].default-profile > "dev".
+# See .agents/docs/2026-06-29-manifest-environment-and-platform-design.md.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+cd "$TMP"
+
+# --- (1) A plain project: no [build].default-profile → GLOBAL default = dev. ---
+mkdir -p plain/src
+cat > plain/mcpp.toml <<'EOF'
+[package]
+name    = "plain"
+version = "0.1.0"
+EOF
+echo 'int main() { return 0; }' > plain/src/main.cpp
+( cd plain
+  "$MCPP" build > b.log 2>&1 || { cat b.log; echo "FAIL: build errored"; exit 1; }
+  grep -q '\-O0' compile_commands.json || { echo "FAIL: global default is not dev (-O0)"; cat compile_commands.json; exit 1; }
+  grep -q '\-g\b' compile_commands.json || { echo "FAIL: global default dev lacks -g"; exit 1; }
+  # --release opts into the optimized profile.
+  "$MCPP" build --release > b2.log 2>&1 || { cat b2.log; echo "FAIL: --release errored"; exit 1; }
+  grep -q '\-O2' compile_commands.json || { echo "FAIL: --release did not yield -O2"; cat compile_commands.json; exit 1; }
+)
+
+# --- (2) A project that opts into release via [build].default-profile. ---
+mkdir -p opt/src
+cat > opt/mcpp.toml <<'EOF'
+[package]
+name    = "opt"
+version = "0.1.0"
+[build]
+default-profile = "release"
+EOF
+echo 'int main() { return 0; }' > opt/src/main.cpp
+( cd opt
+  "$MCPP" build > b.log 2>&1 || { cat b.log; echo "FAIL: build errored"; exit 1; }
+  grep -q '\-O2' compile_commands.json || { echo "FAIL: [build].default-profile=release did not yield -O2"; cat compile_commands.json; exit 1; }
+  # --dev overrides the project's release default back to -O0.
+  "$MCPP" build --dev > b2.log 2>&1 || { cat b2.log; echo "FAIL: --dev errored"; exit 1; }
+  grep -q '\-O0' compile_commands.json || { echo "FAIL: --dev did not override project default to -O0"; cat compile_commands.json; exit 1; }
+)
+
+echo "OK"