Skip to content

Commit d06a023

Browse files
committed
feat: mcpp run and mcpp test name a script's missing #! interpreter
An artefact the run slot executes directly can be a script: emsdk's JavaScript launcher begins `#!/usr/bin/env node`. An emsdk payload installed before its recipe wrote `.mcpp-toolchain.json` names no runner, so the launcher runs through that line, and on a host without `node` on PATH the only output was `/usr/bin/env: 'node': No such file or directory`. mcpp had spawned `env` successfully, so none of its own launcher messages applied, and nothing named the cause or the remedy. mcpp.build.runner_lookup now reads a script's `#!` line as the kernel reads it (parse_script_interpreter, script_interpreter): the interpreter is the first word after `#!`, and through `env` the program is the first word that is neither `-S` nor a `NAME=value` assignment. A form it does not read with certainty (a relative interpreter, any other `env` option, `env` with no program) names no program, so the note never names the wrong one. Windows reads no `#!` line and is skipped. missing_interpreter_note says, when the interpreter is not an executable file or the program `env` would look up is on no directory of the artefact's PATH, which program is missing, that a toolchain payload names its runner in `.mcpp-toolchain.json` and one installed before its recipe wrote that file names none, and the remedy: `mcpp index update`, then `mcpp toolchain remove <spec>` and `mcpp toolchain install <spec>`. It names no toolchain, because which payload built a file is not a fact its first line holds. `mcpp run` prints the note before it executes an artefact with no runner and no execution host, against the PATH the artefact receives; the blank line before the program's output now follows the composed environment so the note stays above it. `mcpp test` prints it once per build, for the first test it executes directly. Neither prints it for `--print-launch`, and `mcpp test` not under `--message-format json`. Tests: five RunnerLookup cases cover the parse (direct, `env`, `env -S` with an assignment, CRLF), the forms that name no program, a missing `env` program and a missing interpreter path, and the cases that stay silent (a found interpreter, a binary, a missing file). docs/20 states the note in both languages in place of "mcpp does not yet explain it". Closes #621
1 parent 346b3f7 commit d06a023

5 files changed

Lines changed: 202 additions & 4 deletions

File tree

‎docs/20-toolchains.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -853,7 +853,10 @@ give such a payload a descriptor, refresh the index first and then reinstall:
853853
again, because the index is refreshed when a resolution misses and not because a
854854
recipe changed; measured in the sandbox verification of 2026.9.12.2. Until then
855855
the failure is the interpreter's own (`/usr/bin/env: 'node': No such file or
856-
directory`), which mcpp does not yet explain (#621).
856+
directory`). Before `mcpp run` and `mcpp test` execute an artefact directly,
857+
they read its `#!` line, and when the program it names is not there (`node` on
858+
no directory of the artefact's PATH) a note names that program and these three
859+
steps (#621).
857860

858861
For a target whose artifact runs elsewhere, the `runner` key is an argv prefix
859862
and the session belongs to a package rather than to the engine:

‎docs/zh/20-toolchains.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -769,8 +769,10 @@ runner 时,`mcpp run` 与 `mcpp test` 使用这个程序,因此不涉及 PAT
769769
与 `mcpp toolchain install <spec>`。仅仅重装会再次按同一份配方安装,因为
770770
索引只在解析未命中时刷新,而不因配方变化而刷新;这一点在 2026.9.12.2 的
771771
沙箱验证中实测过。在此之前,失败信息来自解释器自身
772-
(`/usr/bin/env: 'node': No such file or directory`),mcpp 尚未对它作出解释
773-
(#621)。
772+
(`/usr/bin/env: 'node': No such file or directory`)。`mcpp run` 与
773+
`mcpp test` 在直接执行产物之前会读取它的 `#!` 行;这一行指名的程序不存在时
774+
(产物所得 PATH 的任何目录中都没有 `node`),一条 note 会指出这个程序以及上述
775+
三步(#621)。
774776

775777
对于产物在别处运行的 target,`runner` 键是一个 argv 前缀,而那个会话属于
776778
一个**包**,不属于引擎:

‎src/build/execute.cppm‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2995,6 +2995,21 @@ void yield_terminal() {
29952995
mcpp::ui::print_closing_notices();
29962996
}
29972997

2998+
// A SCRIPT WHOSE `#!` INTERPRETER IS NOT THERE (#621), said before the
2999+
// artefact is executed directly: the refusal is the interpreter's own and
3000+
// comes after mcpp has handed the process over, so nothing of mcpp follows it.
3001+
// The PATH searched is the one the artefact receives -- the last value
3002+
// `childEnv` gives it, else this invocation's -- since that is the one `env`
3003+
// searches.
3004+
void note_missing_interpreter(const std::filesystem::path& exe,
3005+
const std::vector<std::pair<std::string, std::string>>& childEnv) {
3006+
std::string path = mcpp::invocation::get("PATH").value_or("");
3007+
for (auto const& [key, value] : childEnv)
3008+
if (key == "PATH") path = value;
3009+
if (auto note = mcpp::build::runner_lookup::missing_interpreter_note(exe, path); !note.empty())
3010+
mcpp::ui::note(note);
3011+
}
3012+
29983013
// mcpp#225 (E2): `mcpp run`'s fast path. Mirrors try_fast_build's
29993014
// fingerprint/freshness gate against the SAME cache entry `mcpp build`
30003015
// wrote (targetTriple == "" — a HOST build; see the precondition below), then
@@ -3451,7 +3466,6 @@ int run_artifact_via_runner(mcpp::build::BuildContext& ctx,
34513466
}
34523467
runClosure = *closure;
34533468
}
3454-
run_separator();
34553469

34563470
std::vector<std::pair<std::string, std::string>> childEnv;
34573471
auto [runEnvKey, runEnvValue] = compute_run_env(ctx.plan);
@@ -3464,6 +3478,9 @@ int run_artifact_via_runner(mcpp::build::BuildContext& ctx,
34643478
if (runClosure)
34653479
for (auto& kv : run_contract_env(ctx, exe, "run", choice.tripleKey, *runClosure))
34663480
childEnv.push_back(std::move(kv));
3481+
if (choice.tmpl.empty() && host.prefix.empty() && !print_launch_flag())
3482+
note_missing_interpreter(exe, childEnv);
3483+
run_separator();
34673484

34683485
// Direct exec (no /bin/sh): the loader env reaches ONLY the target child,
34693486
// never mcpp or a host shell. Fixes the bundled-glibc-vs-host-libtinfo
@@ -4464,6 +4481,9 @@ struct TestBuild {
44644481
// and each such result is NotRun, not RunFail. The reason is printed once.
44654482
std::atomic<bool> hostCannotRun{false};
44664483
std::string hostCannotRunReason;
4484+
// The first test executed directly was read for a missing `#!`
4485+
// interpreter (#621); the note, if any, is printed once per build.
4486+
bool interpreterNoted = false;
44674487
};
44684488

44694489
// Phase A goal set: every shared prerequisite — all package/dep compile
@@ -5320,6 +5340,16 @@ static int test_run_member(TestBuild& tb, const TestOptions& testOpts,
53205340
}
53215341
}
53225342

5343+
// Said once for the build, before any test runs: every test of one
5344+
// build is executed the same way, so one script's missing interpreter
5345+
// is every script's.
5346+
if (runnerTmpl.empty() && tb.runUnderPrefix.empty() && !tb.interpreterNoted && !json
5347+
&& !print_launch_flag() && !testOpts.noRun && !tb.builtNotRunHere
5348+
&& invocationNotRunReason.empty()) {
5349+
tb.interpreterNoted = true;
5350+
note_missing_interpreter(exe, childEnv);
5351+
}
5352+
53235353
runnable.push_back({lu.targetName, std::move(argv), std::move(childEnv),
53245354
buildMsOfTest, exe});
53255355
// The protocol it implements: what its entry states, else the marker

‎src/build/runner_lookup.cppm‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,4 +168,97 @@ inline std::string unrunnable_message(std::string_view triple,
168168
artifact.string(), errno_text(e), e, triple, triple);
169169
}
170170

171+
// THE PROGRAM A SCRIPT'S `#!` LINE HANDS IT TO (#621).
172+
//
173+
// An artefact the run slot executes directly can be a script: emsdk's
174+
// JavaScript launcher begins `#!/usr/bin/env node`. When that program is not
175+
// there, the refusal comes after mcpp has handed the process over -- from the
176+
// kernel, or from `env` once it has started (`/usr/bin/env: 'node': No such
177+
// file or directory`) -- so none of the messages above applies. The line is
178+
// read as the kernel reads it: the interpreter is the first word after `#!`
179+
// and the rest is its argument; through `env`, that argument names the program
180+
// `env` looks up on PATH. A form this does not read with certainty (an
181+
// interpreter that is not an absolute path, an `env` option other than `-S`,
182+
// `env` with no program) names no program, so a note built on it never names
183+
// the wrong one.
184+
struct ScriptInterpreter {
185+
std::string line; // the `#!` line, without its line end
186+
std::filesystem::path program; // what the kernel executes
187+
std::string viaEnv; // what `program`, an `env`, looks up on PATH; empty otherwise
188+
};
189+
190+
inline std::optional<ScriptInterpreter> parse_script_interpreter(std::string_view head) {
191+
if (!head.starts_with("#!")) return std::nullopt;
192+
head = head.substr(0, head.find_first_of("\r\n"));
193+
ScriptInterpreter out;
194+
out.line = std::string(head);
195+
constexpr std::string_view blanks = " \t";
196+
auto next_word = [&](std::string_view& rest) {
197+
const auto from = std::min(rest.find_first_not_of(blanks), rest.size());
198+
rest.remove_prefix(from);
199+
const auto to = std::min(rest.find_first_of(blanks), rest.size());
200+
auto word = rest.substr(0, to);
201+
rest.remove_prefix(to);
202+
return word;
203+
};
204+
std::string_view rest = head.substr(2);
205+
const auto program = next_word(rest);
206+
if (!program.starts_with('/')) return std::nullopt;
207+
out.program = std::filesystem::path(program);
208+
if (out.program.filename() != "env") return out;
209+
// `env [-S] [NAME=value]... <program> [<argument>]...`
210+
for (auto word = next_word(rest); !word.empty(); word = next_word(rest)) {
211+
if (word == "-S" || word == "--split-string") continue;
212+
if (word.starts_with('-')) return std::nullopt;
213+
if (word.find('=') != std::string_view::npos) continue;
214+
out.viaEnv = std::string(word);
215+
return out;
216+
}
217+
return std::nullopt;
218+
}
219+
220+
// The artefact's own `#!` line; none on Windows, which does not read one.
221+
inline std::optional<ScriptInterpreter> script_interpreter(const std::filesystem::path& artifact) {
222+
if constexpr (mcpplibs::os::is_windows) {
223+
return std::nullopt;
224+
} else {
225+
std::ifstream in(artifact, std::ios::binary);
226+
if (!in) return std::nullopt;
227+
// The kernel reads no more of the line than this (BINPRM_BUF_SIZE).
228+
std::string head(256, '\0');
229+
in.read(head.data(), static_cast<std::streamsize>(head.size()));
230+
head.resize(static_cast<std::size_t>(in.gcount()));
231+
return parse_script_interpreter(head);
232+
}
233+
}
234+
235+
// What `mcpp run` and `mcpp test` say before they execute `artifact` directly
236+
// when the program its `#!` line names is not there; empty when it is, and
237+
// when the artefact is no script this reads. `pathEnv` is the PATH the
238+
// artefact receives, the one `env` searches.
239+
//
240+
// The remedy is the one an emsdk payload installed before its recipe wrote
241+
// `.mcpp-toolchain.json` needs (docs/20, "Running what they produce"). The
242+
// note names no toolchain: it reads a file's first line, and which payload
243+
// built the file is not a fact that line holds.
244+
inline std::string missing_interpreter_note(const std::filesystem::path& artifact,
245+
std::string_view pathEnv) {
246+
auto script = script_interpreter(artifact);
247+
if (!script) return {};
248+
std::string missing;
249+
if (!detail::executable_file(script->program))
250+
missing = std::format("'{}' is not an executable file", script->program.string());
251+
else if (!script->viaEnv.empty() && !locate(script->viaEnv, {}, pathEnv).program)
252+
missing = std::format("'{}' is not on PATH", script->viaEnv);
253+
if (missing.empty()) return {};
254+
return std::format(
255+
"'{}' runs through its first line, `{}`, and {}.\n"
256+
" A toolchain payload names the program that runs its artefacts in\n"
257+
" `.mcpp-toolchain.json`; one installed before its recipe wrote that file\n"
258+
" names none, and its artefacts run through their `#!` line.\n"
259+
" fix: `mcpp index update`, then `mcpp toolchain remove <spec>` and\n"
260+
" `mcpp toolchain install <spec>` for the toolchain that built it.",
261+
artifact.string(), script->line, missing);
262+
}
263+
171264
} // namespace mcpp::build::runner_lookup

‎tests/unit/test_runner_lookup.cpp‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,76 @@ UTest spawn_failed_message_is_verbatim{"RunnerLookup/SpawnFailedMessageIsVerbati
148148
expect(eq(msg.find("runner = ["), std::string::npos)) << msg; // no runner advice
149149
}};
150150

151+
// A SCRIPT'S `#!` LINE, READ AS THE KERNEL READS IT (#621). The interpreter is
152+
// the first word; through `env`, the program is the first word that is neither
153+
// `-S` nor an assignment. A form read without certainty names no program.
154+
UTest a_shebang_names_its_interpreter{"RunnerLookup/AShebangNamesItsInterpreter", [] {
155+
auto direct = parse_script_interpreter("#!/bin/sh -e\nexit 0\n");
156+
expect(fatal(direct.has_value()));
157+
expect(eq(direct->program, std::filesystem::path("/bin/sh")));
158+
expect(eq(direct->viaEnv, std::string{}));
159+
expect(eq(direct->line, std::string("#!/bin/sh -e")));
160+
161+
auto viaEnv = parse_script_interpreter("#!/usr/bin/env node\r\n// emsdk\n");
162+
expect(fatal(viaEnv.has_value()));
163+
expect(eq(viaEnv->program, std::filesystem::path("/usr/bin/env")));
164+
expect(eq(viaEnv->viaEnv, std::string("node")));
165+
expect(eq(viaEnv->line, std::string("#!/usr/bin/env node")));
166+
167+
auto split = parse_script_interpreter("#! /usr/bin/env -S NODE_OPTIONS=x node --flag\n");
168+
expect(fatal(split.has_value()));
169+
expect(eq(split->viaEnv, std::string("node")));
170+
}};
171+
172+
UTest an_uncertain_shebang_names_no_program{"RunnerLookup/AnUncertainShebangNamesNoProgram", [] {
173+
expect(!parse_script_interpreter("\x7f" "ELF\x02\x01\x01").has_value());
174+
expect(!parse_script_interpreter("#!\n").has_value());
175+
expect(!parse_script_interpreter("#!node\n").has_value()); // not absolute
176+
expect(!parse_script_interpreter("#!/usr/bin/env\n").has_value()); // no program
177+
expect(!parse_script_interpreter("#!/usr/bin/env -i node\n").has_value());
178+
expect(!parse_script_interpreter("#!/usr/bin/env -u X node\n").has_value());
179+
}};
180+
181+
UTest a_script_whose_interpreter_is_missing_is_noted{"RunnerLookup/AScriptWhoseInterpreterIsMissingIsNoted", [] {
182+
auto root = fresh_root("mcpp-runner-lookup-shebang-1");
183+
auto env = make_exe(root / "sys", "env");
184+
auto script = root / "app.js";
185+
{ std::ofstream o(script); o << "#!" << env.string() << " node-absent\nconsole.log(1)\n"; }
186+
auto note = missing_interpreter_note(script, (root / "path").string());
187+
expect(ne(note.find(script.string()), std::string::npos)) << note;
188+
expect(ne(note.find("`#!" + env.string() + " node-absent`"), std::string::npos)) << note;
189+
expect(ne(note.find("'node-absent' is not on PATH"), std::string::npos)) << note;
190+
expect(ne(note.find(".mcpp-toolchain.json"), std::string::npos)) << note;
191+
expect(ne(note.find("mcpp index update"), std::string::npos)) << note;
192+
expect(ne(note.find("mcpp toolchain remove <spec>"), std::string::npos)) << note;
193+
expect(ne(note.find("mcpp toolchain install <spec>"), std::string::npos)) << note;
194+
195+
// ...and once the program is on the PATH the artefact receives, nothing.
196+
make_exe(root / "path", "node-absent");
197+
expect(eq(missing_interpreter_note(script, (root / "path").string()), std::string{}));
198+
}};
199+
200+
UTest a_missing_interpreter_path_is_noted{"RunnerLookup/AMissingInterpreterPathIsNoted", [] {
201+
auto root = fresh_root("mcpp-runner-lookup-shebang-2");
202+
auto script = root / "tool.sh";
203+
{ std::ofstream o(script); o << "#!" << (root / "absent" / "sh").string() << "\n"; }
204+
auto note = missing_interpreter_note(script, "");
205+
expect(ne(note.find("'" + (root / "absent" / "sh").string() + "' is not an executable file"),
206+
std::string::npos)) << note;
207+
}};
208+
209+
UTest a_program_or_a_found_interpreter_is_not_noted{"RunnerLookup/AProgramOrAFoundInterpreterIsNotNoted", [] {
210+
auto root = fresh_root("mcpp-runner-lookup-shebang-3");
211+
auto sh = make_exe(root / "sys", "sh");
212+
auto found = root / "found.sh";
213+
{ std::ofstream o(found); o << "#!" << sh.string() << "\nexit 0\n"; }
214+
expect(eq(missing_interpreter_note(found, ""), std::string{}));
215+
auto binary = root / "app";
216+
{ std::ofstream o(binary, std::ios::binary); o << "\x7f" "ELF"; }
217+
expect(eq(missing_interpreter_note(binary, ""), std::string{}));
218+
expect(eq(missing_interpreter_note(root / "absent", ""), std::string{}));
219+
}};
220+
151221
#else
152222

153223
UTest runner_lookup_windows_covered_by_integration{"RunnerLookup/WindowsCoveredByIntegration", [] { /* passes */; }};

0 commit comments

Comments
 (0)