Skip to content

Commit a3a24db

Browse files
run: an artifact for another system is built, not run, until a runner states how (mcpp#911 G11)
An artifact of a row a platform defines whose execution is another system is refused by `mcpp run` and reported not run by `mcpp test` unless a runner or an execution host is stated; a runner package is a target tool the runner names, started with the run protocol (docs/41). Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
1 parent 4a3cbe4 commit a3a24db

4 files changed

Lines changed: 79 additions & 6 deletions

File tree

‎docs/41-devices.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,28 @@ A runner that executes the artifact where it lies ignores the variable. A
142142
runner that moves the artifact — to a device, a container, a remote host —
143143
copies each listed file to the destination beside the moved artifact.
144144

145+
### Runner packages and the systems a platform defines (2026.11.9.1+)
146+
147+
A runner is a program; a package that builds it is a **runner package** (a virtual
148+
machine, a remote host over ssh, a device). The project names the package as one
149+
of the target's tools and the runner by the tool's name:
150+
151+
```toml
152+
[target.x86_64-freebsd]
153+
runner = ["freebsd-vm", "{}"]
154+
155+
[target.x86_64-freebsd.tools]
156+
freebsd-vm = { git = "https://example.org/freebsd-vm.git", tag = "v1" }
157+
```
158+
159+
The tool is built for this machine and started with the argv and the
160+
environment above: it transfers the artifact and the files `MCPP_RUNTIME_FILES`
161+
lists, runs the argv, streams the program's output, and exits with the
162+
program's status. An artifact of a row a platform defines whose `execution` is
163+
another system than this machine's, with no runner and no execution host
164+
(`run_under`), is **built, not run**: `mcpp run` refuses it naming the keys that
165+
state a runner, and `mcpp test` reports its tests as not run.
166+
145167
## Running a distributable
146168

147169
`mcpp run --pkg-format <f>` packs the distributable `<f>` and runs it. Without

‎docs/zh/41-devices.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,23 @@ libfw.so<TAB>/abs/project/target/<triple>/<fp>/bin/libfw.so
123123
容器或远程主机——会把列出的每个文件复制到被移走产物旁边对应的目的
124124
路径。
125125

126+
### runner 包与平台定义的系统(2026.11.9.1+)
127+
128+
runner 是一个程序;构建它的包是 **runner 包**(虚拟机、经 ssh 的远程主机、设备)。工程把该包写为目标的工具之一,
129+
以工具名指定 runner:
130+
131+
```toml
132+
[target.x86_64-freebsd]
133+
runner = ["freebsd-vm", "{}"]
134+
135+
[target.x86_64-freebsd.tools]
136+
freebsd-vm = { git = "https://example.org/freebsd-vm.git", tag = "v1" }
137+
```
138+
139+
该工具为本机构建,以上述 argv 与环境启动:它传送产物及 `MCPP_RUNTIME_FILES` 所列文件,执行 argv,转发程序的输出,
140+
并以程序的退出码退出。平台定义的行中,`execution` 为本机以外系统的产物,若无 runner 也无执行主机(`run_under`),
141+
即**已构建、未运行**:`mcpp run` 拒绝并给出声明 runner 的键,`mcpp test` 把其测试报告为未运行。
142+
126143
## 运行一个可分发物
127144

128145
`mcpp run --pkg-format <f>` 打包可分发物 `<f>` 并运行它。不带 `--runner`

‎src/build/execute.cppm‎

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1356,9 +1356,29 @@ ExecutionHost locate_run_under(const mcpp::build::BuildContext& ctx, std::string
13561356
// and the OS run only there. `--no-runner` states that the triple is native
13571357
// here, and is believed.
13581358
std::optional<std::string> unreachable_execution(const mcpp::build::BuildContext& ctx,
1359-
std::string_view tripleKey, bool noRunner) {
1359+
std::string_view tripleKey, bool noRunner,
1360+
bool runnerDeclared = false) {
13601361
if (noRunner || !ctx.runUnder.empty()) return std::nullopt;
13611362
auto t = mcpp::toolchain::triple::parse(tripleKey);
1363+
// AN ARTIFACT OF A SYSTEM A PLATFORM DEFINES runs where its row's
1364+
// `execution` names (mcpp#911 G11): on this machine when that is this
1365+
// machine's system, else through a runner -- a runner package's program,
1366+
// which reaches a VM, a remote host or a device by the run protocol
1367+
// (docs/41) -- or an execution host. With neither it is built, not run.
1368+
if (auto const* d = t ? t->defined() : nullptr; d && !runnerDeclared) {
1369+
const std::string_view system = d->execution.empty() ? std::string_view(t->os) : d->execution;
1370+
const std::string_view here = mcpplibs::os::is_windows ? "windows"
1371+
: mcpplibs::os::is_macos ? "macos" : "linux";
1372+
if (system != here)
1373+
return std::format(
1374+
"{} artifacts run on {}, not on this {} host: built, not run.\n"
1375+
" State how they run: [target.{}] runner = [\"<program>\", \"{{}}\"], the program a "
1376+
"runner package builds\n"
1377+
" ([target.{}.tools] <program> = {{ ... }}; the run protocol is docs/41), or an "
1378+
"execution host:\n"
1379+
" [target.{}] run_under = [\"remote-run\", \"<host>\", \"--\"].",
1380+
tripleKey, system, here, tripleKey, tripleKey, tripleKey);
1381+
}
13621382
// A RUNNER THAT RUNS THE ARTIFACT ON A MACHINE OF ITS ARCHITECTURE
13631383
// (`runner = { ..., host = "same-arch" }`, SPEC-013): an ok image's loader
13641384
// is a program of this machine, and an image of another architecture is
@@ -1534,7 +1554,7 @@ export RunnerOnThisMachine runner_on_this_machine(const BuildContext& ctx) {
15341554
RunnerOnThisMachine out;
15351555
const auto choice = choose_runner(ctx);
15361556
out.arch = std::string(mcpp::toolchain::platform::host_arch);
1537-
if (auto why = unreachable_execution(ctx, choice.tripleKey, false)) out.refusal = *why;
1557+
if (auto why = unreachable_execution(ctx, choice.tripleKey, false, !choice.tmpl.empty())) out.refusal = *why;
15381558
if (!ctx.runUnder.empty()) {
15391559
auto host = locate_run_under(ctx, choice.tripleKey);
15401560
if (!host.error.empty()) out.refusal = host.error;
@@ -3317,7 +3337,7 @@ int run_artifact_via_runner(mcpp::build::BuildContext& ctx,
33173337
return 126;
33183338
}
33193339
if (isRunSlot) {
3320-
if (auto why = unreachable_execution(ctx, choice.tripleKey, no_runner)) {
3340+
if (auto why = unreachable_execution(ctx, choice.tripleKey, no_runner, !choice.tmpl.empty())) {
33213341
std::println(libc::stderr(), "error: {}", *why);
33223342
return 2;
33233343
}
@@ -3504,8 +3524,9 @@ std::optional<ChosenLeg> choose_run_leg(std::span<const mcpp::toolchain::target_
35043524
mcpp::ui::error(std::format("the {} leg: {}", leg->triple, ctx.error()));
35053525
return std::nullopt;
35063526
}
3507-
const auto key = choose_runner(*ctx, noRunner).tripleKey;
3508-
if (auto why = unreachable_execution(*ctx, key, noRunner)) {
3527+
const auto chosen = choose_runner(*ctx, noRunner);
3528+
const auto key = chosen.tripleKey;
3529+
if (auto why = unreachable_execution(*ctx, key, noRunner, !chosen.tmpl.empty())) {
35093530
passed.push_back(std::format("{}: {}", leg->triple, why->substr(0, why->find('\n'))));
35103531
continue;
35113532
}
@@ -4463,7 +4484,8 @@ static void test_resolve_runner(TestBuild& tb, const TestOptions& testOpts, bool
44634484
}
44644485
// Not run, with the reason, as a missing runner is: the tests built. Or,
44654486
// where the caller asks, built and not run (a platform package's targets).
4466-
if (auto why = unreachable_execution(*ctx, runnerChoice.tripleKey, testOpts.noRunner)) {
4487+
if (auto why = unreachable_execution(*ctx, runnerChoice.tripleKey, testOpts.noRunner,
4488+
!runnerChoice.tmpl.empty())) {
44674489
if (testOpts.unreachableIsBuilt) {
44684490
tb.builtNotRunHere = true;
44694491
if (!json) mcpp::ui::info("note", std::format("built, not run on this host: {}", *why));

‎tests/e2e/1040_a_platform_defines_a_target.sh‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,18 @@ out=$("$MCPP" build --target x86_64-toyos 2>&1) || fail "a row for another syste
9696
grep -q "the artifacts are for toyos, not this machine" <<<"$out" || fail "the build judged a foreign artifact by this machine" "$out"
9797
echo " ok an artifact for another system is built and its closure is not judged here"
9898

99+
# An artifact for another system is built, not run, without a runner; a runner states how it runs
100+
# (mcpp#911 G11).
101+
set +e; out=$("$MCPP" run --target x86_64-toyos 2>&1); rc=$?; set -e
102+
[ "$rc" != 0 ] || fail "an artifact for toyos was run on this host" "$out"
103+
grep -q "x86_64-toyos artifacts run on toyos, not on this .* host: built, not run" <<<"$out" \
104+
|| fail "the refusal does not say built, not run" "$out"
105+
sed -i 's|^platform = { path = "../toy" }$|&\nrunner = ["env", "{}"]|' mcpp.toml
106+
set +e; out=$("$MCPP" run --target x86_64-toyos 2>&1); rc=$?; set -e
107+
[ "$rc" = 7 ] || fail "the runner did not run it (exit $rc)" "$out"
108+
sed -i '/^runner = \["env", "{}"\]$/d' mcpp.toml
109+
echo " ok without a runner it is built, not run; a runner runs it"
110+
99111
# The platform names its programs; a build program that names them for the host does not change
100112
# the platform's suffix, and the build says so (mcpp#911 B2).
101113
sed -i 's/^driver = "compiler"$/driver = "compiler"\nexe = "{name}.toy"/' "$t/toy/mcpp.toml"

0 commit comments

Comments
 (0)