e2e: runtime_search_dir, the prepare role and the stamp rule (mcpp#701, mcpp#702)

779: rewritten for runtime_search_dir (renamed from ...runtime_library_dir):
RUNPATH in build.ninja, mcpp run, a build.mcpp cache-hit replay, mcpp pack,
and a dependency's declaration reaching a consumer's executable through the
same LinkGlobal merge.

790: a prepare action's command writes a header and a shared library into a
directory whose contents build.mcpp never names; a unit that includes the
header compiles and a program linked against the library runs through
runtime_search_dir on the first build; the second build runs nothing; after
an input of the action changes, it runs once and then not again.

791: a prepare action whose command creates nothing fails naming its
declared directory. The stamp is declared beside that directory, not
inside it -- ninja creates a declared output's own parent directory before
running any edge, so a stamp nested inside the directory would make it
"exist" regardless of what the command did.

792: a build program whose rerun_if_changed or rerun_if_changed_glob names a
path inside a prepare directory is warned, naming both paths; a re-run input
outside any such directory is the silent control.

793: an unknown action role is refused, naming the value and the five roles;
each real role, including a real object action, is the control.

794/795: the R1' Windows leg -- a DLL in a declared runtime search directory
is found by `mcpp run` through PATH and placed beside the packed program by
`mcpp pack`. 794 requires windows and runs on Windows CI; this host cannot
run it. 795 exercises the identical property through mingw-cross + wine,
which this host can and does run, giving this round a passing reading
before release.

Author: speak-agent

tests/e2e/779_a_build_program_declares_a_runtime_search_dir.sh

@@ -1,11 +1,12 @@
 #!/usr/bin/env bash
 # requires: pack gcc
-# 779_a_build_program_declares_a_runtime_library_dir.sh --
-# `mcpp::runtime_library_dir(dir)`: the build-program form of `[runtime]
-# library_dirs` (docs/04 §2.11). A dependency that brings a prebuilt shared
-# library (a vcpkg prefix's `bin/`, a Qt SDK's `bin/`) knows where it lives
-# only at build-program time, and the manifest key cannot be computed -- it is
-# a fixed TOML array. This is the directive that closes that gap.
+# 779_a_build_program_declares_a_runtime_search_dir.sh --
+# `mcpp::runtime_search_dir(dir)`: the build-program form of
+# `runtime_search_dirs` (docs/04 §2.11). A dependency that brings a prebuilt
+# shared library (a vcpkg prefix's `bin/`, a Qt SDK's `bin/`) knows where it
+# lives only at build-program time, and the manifest key cannot be computed --
+# it is a fixed TOML array. This is the directive that closes that gap
+# (design §5.4 R1', mcpp#701/#702).
 #
 # What this holds, each with the wrong answer it excludes:
 #
@@ -22,10 +23,24 @@
 #      `mcpp run` working -- the same replay criterion `mcpp:deploy=` is held
 #      to in 651_a_build_program_deploys_what_it_generated.sh.
 #   4. `mcpp pack --format dir` STAGES IT into the bundle's `lib/` -- the
-#      same closure search `[runtime] library_dirs` already feeds. Checked
+#      same closure search `runtime_search_dirs` already feeds. Checked
 #      LAST: `mcpp pack` builds under a different profile and would otherwise
 #      invalidate the `dev`-profile build.mcpp cache the replay check (3)
 #      depends on.
+#   5. A DEPENDENCY'S DECLARATION REACHES THE CONSUMER'S EXECUTABLE: the
+#      directive is `Scope::LinkGlobal`, folded into `LinkIntent
+#      .runtimeSearchDirs` by the SAME per-package merge (`resolve_runtime_
+#      contract`, plan.cppm) the manifest key goes through, so a path
+#      dependency that calls `runtime_search_dir` in its OWN build.mcpp makes
+#      its consumer's binary run without the consumer naming the directory at
+#      all.
+#
+# It lands DIRECTLY on `LinkIntent::runtimeSearchDirs`, not the retiring
+# `RuntimeConfig::libraryDirs` (docs/04 §2.11) -- #702 as first written joined
+# the wrong field (design §5.3 point 1); nothing here would tell them apart
+# if it had not been fixed, since every reader below is fed FROM
+# `runtimeSearchDirs` either way once the manifest key itself is also routed
+# there.
 set -e
 
 TMP=$(mktemp -d)
@@ -66,7 +81,7 @@ EOF
 
 # The directive under test. `link_lib`/`link_search` also come from the
 # program, on purpose: the point is a dependency the build.mcpp DISCOVERS,
-# not one written into mcpp.toml by hand -- the case `[runtime] library_dirs`
+# not one written into mcpp.toml by hand -- the case `runtime_search_dirs`
 # cannot cover.
 cat > app/build.mcpp <<'EOF'
 import mcpp;
@@ -75,7 +90,7 @@ int main() {
     const std::string root = mcpp::manifest_dir();
     mcpp::link_lib("runtime_plugin");
     mcpp::link_search((root + "/rtlib").c_str());
-    mcpp::runtime_library_dir((root + "/rtlib").c_str());
+    mcpp::runtime_search_dir((root + "/rtlib").c_str());
     return 0;
 }
 EOF
@@ -90,7 +105,7 @@ G=$(find_graph)
 [ -n "$G" ] || fail "no build.ninja" b1.log
 RTDIR=$(realpath rtlib)
 grep -F -- "-Wl,-rpath,$RTDIR" "$G" >/dev/null \
-  || fail "runtime-library-dir directive missing from RUNPATH intent" "$G"
+  || fail "runtime-search-dir directive missing from RUNPATH intent" "$G"
 
 # ── 2. mcpp run finds the library only through that RUNPATH ────────────────
 "$MCPP" run > run1.log 2>&1 \
@@ -116,10 +131,87 @@ grep -F -- "-Wl,-rpath,$RTDIR" "$G2" >/dev/null \
 # ── 4. mcpp pack --format dir stages it into the bundle's lib/ ─────────────
 "$MCPP" pack --format dir > pack1.log 2>&1 || fail "pack --format dir failed" pack1.log
 STAGED=$(find target/dist -name 'libruntime_plugin.so' | head -1)
-[ -n "$STAGED" ] || fail "the runtime-library-dir closure was not staged by mcpp pack" pack1.log
+[ -n "$STAGED" ] || fail "the runtime-search-dir closure was not staged by mcpp pack" pack1.log
 case "$STAGED" in
   */lib/libruntime_plugin.so) : ;;
   *) fail "the staged library is not under the packed bundle's lib/" pack1.log ;;
 esac
 
-echo "PASS: 779_a_build_program_declares_a_runtime_library_dir"
+cd "$TMP"
+
+# ── 5. a dependency's declaration reaches the consumer's executable ────────
+# `libdep` is a path dependency whose OWN build.mcpp declares the plugin's
+# directory; `consumer` names none of this -- no `link_search`, no
+# `runtime_search_dir`, not even `link_lib` in its own manifest or program --
+# and still runs, because the directive is LinkGlobal and the merge that
+# folds a dependency's LinkIntent into its consumer's is the SAME one the
+# manifest key goes through (plan.cppm ~:911-948).
+mkdir -p libdep/src libdep/plugin
+
+cat > libdep/plugin/dep_plugin.c <<'EOF'
+int dep_plugin_answer(void) { return 7; }
+EOF
+gcc -shared -fPIC libdep/plugin/dep_plugin.c -o libdep/plugin/libdep_plugin.so
+
+cat > libdep/src/lib.cpp <<'EOF'
+extern "C" int dep_plugin_answer();
+int libdep_touch() { return dep_plugin_answer(); }
+EOF
+
+cat > libdep/mcpp.toml <<'EOF'
+[package]
+name    = "libdep"
+version = "0.1.0"
+
+[modules]
+sources = ["src/**/*.cpp"]
+
+[targets.libdep]
+kind = "lib"
+EOF
+
+cat > libdep/build.mcpp <<'EOF'
+import mcpp;
+#include <string>
+int main() {
+    const std::string root = mcpp::manifest_dir();
+    mcpp::link_lib("dep_plugin");
+    mcpp::link_search((root + "/plugin").c_str());
+    mcpp::runtime_search_dir((root + "/plugin").c_str());
+    return 0;
+}
+EOF
+
+mkdir -p consumer/src
+cat > consumer/src/main.cpp <<'EOF'
+extern "C" int dep_plugin_answer();
+int main() { return dep_plugin_answer() == 7 ? 0 : 1; }
+EOF
+
+cat > consumer/mcpp.toml <<'EOF'
+[package]
+name    = "consumer"
+version = "0.1.0"
+
+[toolchain]
+linux = "gcc@16.1.0"
+
+[dependencies]
+libdep = { path = "../libdep" }
+
+[targets.consumer]
+kind = "bin"
+main = "src/main.cpp"
+EOF
+
+cd consumer
+DEPDIR=$(realpath ../libdep/plugin)
+"$MCPP" build > b3.log 2>&1 || fail "consumer build failed" b3.log
+G3=$(find_graph)
+[ -n "$G3" ] || fail "no build.ninja for consumer" b3.log
+grep -F -- "-Wl,-rpath,$DEPDIR" "$G3" >/dev/null \
+  || fail "the dependency's runtime-search-dir did not reach the consumer's link" "$G3"
+"$MCPP" run > run3.log 2>&1 \
+  || fail "consumer run failed to find the dependency's plugin" run3.log b3.log
+
+echo "PASS: 779_a_build_program_declares_a_runtime_search_dir"

tests/e2e/790_a_prepare_action_populates_an_unknown_directory.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# requires: gcc
+# 790_a_prepare_action_populates_an_unknown_directory.sh — the `prepare`
+# role (design §5.4 P, mcpp#701/#702, SPEC-007 R3.3): construction whose file
+# names are not known when the build program runs, because they are decided
+# by a command it merely invokes (a vcpkg/CMake install, an SDK unpack) —
+# `install.sh` here, standing in for one of those. The build program declares
+# only the DIRECTORY (`a.output_dir`); the header and the shared library
+# inside it are named by the script, never by build.mcpp.
+#
+# What this holds:
+#
+#   1. ON THE FIRST BUILD, a unit that `#include`s a header the action wrote
+#      compiles, and the program — linked against a library the SAME action
+#      wrote, found only through `runtime_search_dir` — runs and gets the
+#      right answer. Neither the header nor the library exists before this
+#      build starts; both exist only because the compile and the link waited
+#      for the action (design §5.4 P's ordering: every compile edge and every
+#      link edge of the declaring package).
+#   2. A SECOND BUILD RUNS NOTHING: no compile, no link, no action — a plain
+#      "up to date" from ninja's own dependency tracking on unchanged inputs.
+#   3. AFTER AN INPUT OF THE ACTION CHANGES, it runs ONCE — and the build
+#      after THAT does not run it again (R2, design §5.4: the engine touches
+#      the action's stamp on every success, whether or not the command wrote
+#      it, so the stamp is newer than the input from that point on).
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+mkdir -p "$TMP/prep/src"
+cd "$TMP/prep"
+
+cat > mcpp.toml <<'EOF'
+[package]
+name    = "prep"
+version = "0.1.0"
+
+[toolchain]
+linux = "gcc@16.1.0"
+
+[targets.prep]
+kind = "bin"
+main = "src/main.cpp"
+EOF
+
+# The command a real rule package would run (vcpkg, a CMake `install`
+# target). It decides the file NAMES; build.mcpp never sees them, only the
+# directory they land in ($1).
+cat > install.sh <<'EOF'
+#!/usr/bin/env bash
+set -e
+PREFIX="$1"
+mkdir -p "$PREFIX/include" "$PREFIX/lib"
+cat > "$PREFIX/include/greet.h" <<HDR
+#ifdef __cplusplus
+extern "C" {
+#endif
+int prep_greet(void);
+#ifdef __cplusplus
+}
+#endif
+HDR
+cat > "$PREFIX/lib/greet.c" <<SRC
+int prep_greet(void) { return 99; }
+SRC
+gcc -shared -fPIC "$PREFIX/lib/greet.c" -o "$PREFIX/lib/libprepgreet.so"
+EOF
+chmod +x install.sh
+
+# The action's declared INPUT that changes in step 3 below. Its content is
+# never read by install.sh — it only has to be a file ninja can hash, the
+# same way a vcpkg manifest's checksum would gate a real installation.
+echo "recipe v1" > recipe.txt
+
+cat > src/main.cpp <<'EOF'
+#include <greet.h>
+int main() { return prep_greet() == 99 ? 0 : 1; }
+EOF
+
+cat > build.mcpp <<'EOF'
+import mcpp;
+#include <string>
+int main() {
+    const std::string root   = mcpp::manifest_dir();
+    const std::string prefix = std::string(mcpp::out_dir()) + "/prep-install";
+
+    mcpp::action a;
+    a.id   = "prep:install";
+    a.role = mcpp::roles::prepare;
+    // The stamp is a SIBLING of `prefix`, not nested inside it: ninja
+    // creates a declared output's own parent directory before running any
+    // edge, so a stamp inside `prefix` would make `prefix` exist regardless
+    // of what install.sh did (see 791, which depends on the two staying
+    // apart to mean anything).
+    a.arg((root + "/install.sh").c_str()).arg(prefix.c_str())
+     .input((root + "/install.sh").c_str())
+     .input((root + "/recipe.txt").c_str())
+     .output((prefix + ".stamp").c_str())
+     .output_dir(prefix.c_str())
+     .submit();
+
+    mcpp::include_dir((prefix + "/include").c_str());
+    mcpp::link_lib("prepgreet");
+    mcpp::link_search((prefix + "/lib").c_str());
+    mcpp::runtime_search_dir((prefix + "/lib").c_str());
+    return 0;
+}
+EOF
+
+MCPP="${MCPP:-mcpp}"
+ran_prepare() { grep -q 'PREPARE prep:install\|__action-stamp.*install\.sh' "$1"; }
+
+# ── 1. first build: header compiles, program runs through runtime_search_dir
+"$MCPP" build -v > b1.log 2>&1 || { cat b1.log; echo "FAIL: first build failed"; exit 1; }
+ran_prepare b1.log || { cat b1.log; echo "FAIL: the prepare action did not run on the first build"; exit 1; }
+nj=$(find target -name build.ninja | head -1)
+[[ -n "$nj" ]] || { echo "FAIL: no build.ninja"; exit 1; }
+grep -qE '^build [^:]*(prep\.stamp|prepgreet)' "$nj" >/dev/null || true   # sanity, not load-bearing
+out1="$("$MCPP" run 2>&1)" || { echo "FAIL: run failed after the first build: $out1"; exit 1; }
+
+# ── 2. second build runs nothing at all ─────────────────────────────────────
+"$MCPP" build -v > b2.log 2>&1 || { cat b2.log; echo "FAIL: second build failed"; exit 1; }
+if ran_prepare b2.log; then
+    cat b2.log; echo "FAIL: the prepare action re-ran on an unchanged second build"; exit 1
+fi
+if grep -qE '\bmain\.o\b' b2.log; then
+    cat b2.log; echo "FAIL: the compile re-ran on an unchanged second build"; exit 1
+fi
+
+# ── 3. an input changes: the action runs once, then not again ──────────────
+sleep 1
+echo "recipe v2" > recipe.txt
+"$MCPP" build -v > b3.log 2>&1 || { cat b3.log; echo "FAIL: third build (after the input changed) failed"; exit 1; }
+ran_prepare b3.log || { cat b3.log; echo "FAIL: the action did not re-run after its input changed"; exit 1; }
+
+"$MCPP" build -v > b4.log 2>&1 || { cat b4.log; echo "FAIL: fourth build failed"; exit 1; }
+if ran_prepare b4.log; then
+    cat b4.log
+    echo "FAIL: the action re-ran on the build after it passed -- R2's stamp rule did not hold"
+    exit 1
+fi
+out2="$("$MCPP" run 2>&1)" || { echo "FAIL: run failed after the recipe changed: $out2"; exit 1; }
+
+echo "PASS: 790_a_prepare_action_populates_an_unknown_directory"

tests/e2e/791_a_prepare_action_that_creates_nothing_fails.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# requires: gcc
+# 791_a_prepare_action_that_creates_nothing_fails.sh — design §5.4 P, SPEC-007
+# R3.3: "when the command succeeds and the directory does not exist, the
+# engine writes no stamp and fails the edge, naming the directory." A
+# `prepare` action promises a directory the build reads BY DIRECTORY
+# (`include_dir`/`link_search`/`runtime_search_dir`); a command that exits 0
+# without populating it is indistinguishable from one that silently did
+# nothing, so this cannot be a warning the way an incomplete environment is
+# (R1.2) -- nothing downstream can read a directory that was never created.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+mkdir -p "$TMP/app/src"
+cd "$TMP/app"
+
+cat > mcpp.toml <<'EOF'
+[package]
+name    = "app"
+version = "0.1.0"
+EOF
+printf '#include <cstdio>\nint main(){ std::printf("ok\\n"); }\n' > src/main.cpp
+
+cat > build.mcpp <<'EOF'
+import mcpp;
+#include <string>
+int main() {
+    const std::string prefix = std::string(mcpp::out_dir()) + "/never-created";
+    mcpp::action a;
+    a.id   = "empty:prepare";
+    a.role = mcpp::roles::prepare;
+    // The stamp lives BESIDE `prefix`, not inside it: ninja creates a
+    // declared output's own parent directory before running any edge, so a
+    // stamp nested inside `prefix` would make `prefix` exist by the time the
+    // engine checks for it regardless of what the command did, and this
+    // test would defend nothing.
+    a.arg("true")
+     .output((prefix + ".stamp").c_str())
+     .output_dir(prefix.c_str())
+     .submit();
+    return 0;
+}
+EOF
+
+MCPP="${MCPP:-mcpp}"
+if "$MCPP" build > b.log 2>&1; then
+    cat b.log
+    echo "FAIL: a prepare action whose command created nothing let the build succeed"
+    exit 1
+fi
+
+grep -qF "never-created" b.log \
+    || { cat b.log; echo "FAIL: the failure does not name the declared directory"; exit 1; }
+grep -qi "does not exist" b.log \
+    || { cat b.log; echo "FAIL: the failure does not say the directory does not exist"; exit 1; }
+
+# No half-satisfied edge: the stamp itself must not exist either, or a later
+# build would read a check that "passed" without its post-condition holding.
+if find target -name 'never-created.stamp' | grep -q .; then
+    echo "FAIL: a stamp was written despite the missing directory"; exit 1
+fi
+
+echo "PASS: 791_a_prepare_action_that_creates_nothing_fails"