Skip to content

Commit 0f1fa1a

Browse files
authored
0.22.0: dist-web's page is the one distributable, a runner named web serves it, and the engine is told the program it wraps (#54)
* 0.22.0: dist-web's page is the one distributable, and a runner named web serves it The page's step takes every copied file as an input, so the page is the format's one distributable and `mcpp run --pkg-format web' is handed it; 0.21.0 declared each copied file a distributable, and the engine refused to choose. The page's source is written to <out_dir>/.dist-web/<target>-<page>.in, not beside the build's outputs as <target>-index.html, where it was opened as the product and loaded nothing. When the directory is declared, a note names it and says how it is opened: a browser loads the module only over HTTP. `options::runner' (default true) declares a long-lived runner named `web': emrun from the resolved Emscripten toolchain (emrun.bat on Windows), given `--hostname localhost' and the page. `mcpp run --pkg-format web' serves the directory on this machine with the types a browser requires, opens the page, and serves until the operator ends it. Another browser, port or address is a machine's choice, made by replacing the runner in its config.toml. docs/dist.md states that link arguments are not a function of the package format: `mcpp pack' stages the program the build linked; a link difference is a profile's. tests/web-consumer asserts the one distributable, the note, the runner and what it serves. * dist-web: state why a web pack is declined as a warning, not on standard error * 0.22.0: the version in the source and the development guide * dist-web: state the program it wraps to the engine where the engine reads it
1 parent 06729d4 commit 0f1fa1a

7 files changed

Lines changed: 149 additions & 25 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ module name the member declares, and configures it there.
99

1010
```toml
1111
[build-dependencies.mcpp]
12-
plugins = { version = "0.21.0", features = ["rules-spirv"], host-module = true }
12+
plugins = { version = "0.22.0", features = ["rules-spirv"], host-module = true }
1313
```
1414

1515
```cpp

‎dist/web.cppm‎

Lines changed: 106 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,14 @@ struct options {
126126
// Where the produced directory lands. Empty means `<out_dir>/web`.
127127
std::string output;
128128
std::string out_dir = std::string(mcpp::out_dir());
129+
130+
// A runner named `web` (0.22.0): `mcpp run --pkg-format web` serves the
131+
// directory on this machine and opens the page in a browser, through the
132+
// `emrun` the Emscripten toolchain carries, until the operator ends it
133+
// (a long-lived runner). It listens on `localhost` only; a machine that
134+
// wants another browser, port or address replaces the runner in its
135+
// `config.toml` (`[target.wasm32-emscripten.runners] web = [...]`).
136+
bool runner = true;
129137
};
130138

131139
// ─── The plan ──────────────────────────────────────────────────────────────
@@ -146,6 +154,7 @@ struct plan {
146154
std::string reason;
147155
std::string web_dir; // <out_dir>/web
148156
std::string stage_bin; // ${mcpp.stage_dir}/bin, kept for the floor check
157+
std::string page; // the page, the format's distributable
149158
std::vector<step> steps;
150159
explicit operator bool() const { return applies; }
151160
};
@@ -244,27 +253,27 @@ inline plan plan_for(options opt = {}) {
244253
// something that does not exist there, and the engine has already
245254
// accepted the value because the graph declared it.
246255
if (const std::string os = mcpp::target_os(); os != "emscripten") {
247-
std::cerr << std::format(
256+
mcpp::warning(std::format(
248257
"mcpp.dist.web: a web directory wraps a wasm32-emscripten "
249-
"program, and this build targets '{}'.\n"
250-
" use: --format tar, or build for --target wasm32-emscripten",
251-
os.empty() ? "unknown" : os) << '\n';
258+
"program, and this build targets '{}'; use --pkg-format tar, or "
259+
"build for --target wasm32-emscripten",
260+
os.empty() ? "unknown" : os).c_str());
252261
p.reason = "not the emscripten target";
253262
return p;
254263
}
255264

256265
const std::string stage = mcpp::pack_stage_dir();
257266
if (stage.empty()) {
258-
std::cerr << "mcpp.dist.web: mcpp reported no staged tree. This "
259-
"member needs mcpp 2026.9.12.2 or newer.\n";
267+
mcpp::warning("mcpp.dist.web: mcpp reported no staged tree. This "
268+
"member needs mcpp 2026.9.12.2 or newer.");
260269
p.reason = "no staged tree";
261270
return p;
262271
}
263272

264273
const std::string target = target_for(opt);
265274
if (target.empty()) {
266-
std::cerr << "mcpp.dist.web: no target to wrap. Set "
267-
"`options::target` to the program target's name.\n";
275+
mcpp::warning("mcpp.dist.web: no target to wrap. Set "
276+
"`options::target` to the program target's name.");
268277
p.reason = "no target";
269278
return p;
270279
}
@@ -277,18 +286,17 @@ inline plan plan_for(options opt = {}) {
277286
const std::string stageBin = stage + "/bin";
278287
const std::string launcher = stageBin + "/" + target + ".js";
279288
if (!is_file(launcher)) {
280-
std::cerr << std::format(
289+
mcpp::warning(std::format(
281290
"mcpp.dist.web: the staged tree at {0} carries no launcher for "
282-
"target '{1}'.\n"
283-
" expected: {0}/{1}.js",
284-
stageBin, target) << '\n';
291+
"target '{1}' (expected {0}/{1}.js); name the program with "
292+
"`options::target`",
293+
stageBin, target).c_str());
285294
p.reason = "no launcher in the staged tree";
286295
return p;
287296
}
288297

289298
const auto pageFile = page_name(opt);
290299
if (!pageFile) {
291-
std::cerr << "mcpp.dist.web: " << pageFile.error() << '\n';
292300
mcpp::warning(("mcpp.dist.web: " + pageFile.error()).c_str());
293301
p.reason = "page name refused";
294302
return p;
@@ -298,8 +306,8 @@ inline plan plan_for(options opt = {}) {
298306
const std::string tpl =
299307
(std::filesystem::path(mcpp::manifest_dir()) / opt.template_file).string();
300308
if (!is_file(tpl)) {
301-
std::cerr << std::format(
302-
"mcpp.dist.web: the template {} was not found", tpl) << '\n';
309+
mcpp::warning(std::format(
310+
"mcpp.dist.web: the template {} was not found", tpl).c_str());
303311
p.reason = "template not found";
304312
return p;
305313
}
@@ -325,12 +333,14 @@ inline plan plan_for(options opt = {}) {
325333
: (std::filesystem::path(opt.out_dir) / "web").string();
326334

327335
// The side file carries the page name, so two packs of one program with
328-
// different pages do not overwrite each other's rendering; the default
329-
// keeps the name 0.11 wrote (`<target>-index.html`).
336+
// different pages do not overwrite each other's rendering. It is the
337+
// page's source, not a page (0.22.0): it lives in a hidden directory and
338+
// ends in `.in`, because one written beside the build's outputs as
339+
// `<target>-index.html` was opened as the product and loaded nothing.
330340
const std::string indexSrc =
331-
(std::filesystem::path(opt.out_dir) / (target + "-" + *pageFile)).string();
341+
(std::filesystem::path(opt.out_dir) / ".dist-web" / (target + "-" + *pageFile + ".in")).string();
332342
if (!write_if_different(indexSrc, templateBytes)) {
333-
std::cerr << std::format("mcpp.dist.web: cannot write {}", indexSrc) << '\n';
343+
mcpp::warning(std::format("mcpp.dist.web: cannot write {}", indexSrc).c_str());
334344
p.reason = std::format("cannot write {}", *pageFile);
335345
return p;
336346
}
@@ -362,8 +372,8 @@ inline plan plan_for(options opt = {}) {
362372
// assertion, because a member's job on a broken invariant is to say
363373
// so, not to crash the build program that is packaging someone
364374
// else's project.
365-
std::cerr << std::format(
366-
"mcpp.dist.web: {} carries no files to stage", stageBin) << '\n';
375+
mcpp::warning(std::format(
376+
"mcpp.dist.web: {} carries no files to stage", stageBin).c_str());
367377
p.reason = "staged bin/ is empty";
368378
return p;
369379
}
@@ -394,15 +404,23 @@ inline plan plan_for(options opt = {}) {
394404
p.steps.push_back(std::move(s));
395405
}
396406

407+
// THE PAGE IS THE DIRECTORY'S ONE DISTRIBUTABLE (0.22.0). A distributable
408+
// is an output no other action consumes; each copied file was one, so the
409+
// format had as many as the directory has files and `mcpp run --pkg-format
410+
// web` refused to choose. The page's step takes every copied file as an
411+
// input: it is ordered after them, and it is what a runner is handed.
397412
step page;
398413
page.id = "mcpp.dist.web.index";
399414
page.role = "artifact";
400415
page.description = "INDEX.HTML";
401416
page.argv = { "${mcpp.self}", "stage", "--verify", "content", "--output",
402417
webDir + "/" + *pageFile, indexSrc };
403418
page.inputs = { indexSrc };
419+
for (auto const& s : p.steps)
420+
page.inputs.insert(page.inputs.end(), s.outputs.begin(), s.outputs.end());
404421
page.outputs = { webDir + "/" + *pageFile };
405422
p.steps.push_back(std::move(page));
423+
p.page = webDir + "/" + *pageFile;
406424

407425
p.applies = true;
408426
return p;
@@ -437,6 +455,17 @@ inline bool submit(const plan& p) {
437455
// catch "nothing was linked or staged", not to police a size budget. A
438456
// wasm launcher plus its module is comfortably larger than this on any
439457
// program that links `import std`.
458+
// HOW THE DIRECTORY IS OPENED, said once it is declared: a browser loads
459+
// the module only over HTTP, and a page opened from disk loads nothing
460+
// without saying why.
461+
{
462+
static std::string message, hint;
463+
message = std::format("the web directory is {}", p.web_dir);
464+
hint = std::format("open it over HTTP: `mcpp run --pkg-format web` serves it and opens {}, "
465+
"or serve the directory with any static server; a page opened from disk "
466+
"cannot load its .wasm", std::filesystem::path(p.page).filename().string());
467+
mcpp::report({.severity = "note", .message = message.c_str(), .hint = hint.c_str()});
468+
}
440469
if (bytes < 4u * 1024u) {
441470
static char msg[512];
442471
std::snprintf(msg, sizeof msg,
@@ -448,14 +477,70 @@ inline bool submit(const plan& p) {
448477
return true;
449478
}
450479

480+
// ─── The runner ────────────────────────────────────────────────────────────
481+
482+
// THE RUNNER NAMED FOR THE FORMAT (0.22.0). `mcpp run --pkg-format web` hands
483+
// the format's distributable -- the page -- to the runner named `web`. emrun,
484+
// which the Emscripten toolchain carries, serves the page's directory with the
485+
// types a browser requires (`application/wasm`), opens the page, and serves
486+
// until the operator ends it; it does not end by itself, so the runner is
487+
// declared long-lived. `--hostname localhost`: emrun listens on every address
488+
// unless told otherwise, and a development server is not offered to the
489+
// network by default.
490+
//
491+
// Declared on every pass of the wasm32-emscripten row, as the format itself
492+
// is: `mcpp run` reads it from a build that is not packaging. On Windows the
493+
// toolchain carries the script as `emrun.bat`; the program is named by its
494+
// path because it is not in the bin/ of a payload, where the engine looks for
495+
// a runner's bare name.
496+
inline void declare_runner() {
497+
if (mcpp::target_os() != std::string_view("emscripten")) return;
498+
const char* root = mcpp::toolchain_dir();
499+
if (!root || !*root) return;
500+
const std::string host = mcpp::host();
501+
const bool windows = host.find("windows") != std::string::npos;
502+
static std::string program;
503+
program = (std::filesystem::path(root) / "emscripten" / (windows ? "emrun.bat" : "emrun"))
504+
.generic_string();
505+
if (!is_file(program)) {
506+
static std::string why;
507+
why = std::format("mcpp.dist.web: the toolchain at {} carries no {}, so `mcpp run "
508+
"--pkg-format web` has no runner", root,
509+
std::filesystem::path(program).filename().string());
510+
mcpp::warning(why.c_str());
511+
return;
512+
}
513+
for (const char* tok : {program.c_str(), "--hostname", "localhost", "{}"})
514+
mcpp::runner("web", tok);
515+
mcpp::runner_longlived("web");
516+
}
517+
451518
// ─── The one call a consumer makes ─────────────────────────────────────────
452519

520+
// THE PROGRAM THE DIRECTORY WRAPS, STATED TO THE ENGINE (0.22.1; mcpp
521+
// 2026.11.16.1, protocol 19). `mcpp pack --pkg-format web` with no program
522+
// named packs the program `options::target` names, as `mcpp pack <program>`
523+
// would: a package of several programs packed its first, which this format
524+
// then did not find. Stated when the engine's module has the call; an older
525+
// engine keeps its own choice, which `mcpp pack <program>` overrides.
526+
namespace pack_program_probe {
527+
using namespace mcpp;
528+
template <class S>
529+
concept stated = requires(S s) { pack_program(s); };
530+
template <class S>
531+
void state(S program) {
532+
if constexpr (stated<S>) pack_program(program);
533+
}
534+
} // namespace pack_program_probe
535+
453536
// DECLARE UNCONDITIONALLY, SUBMIT CONDITIONALLY -- and both halves are here
454537
// so a consumer cannot do one without the other. See `dist/appimage.cppm`'s
455538
// own comment on this function for why the declaration cannot be gated the
456539
// same way `plan_for` gates its submission.
457540
inline bool generate(options opt = {}) {
458541
mcpp::provides_pack_format("web");
542+
if (!opt.target.empty()) pack_program_probe::state(opt.target.c_str());
543+
if (opt.runner) declare_runner();
459544
return submit(plan_for(std::move(opt)));
460545
}
461546

‎docs/dist.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,9 @@ Module `mcpp.dist.wix`; engine floor: 2026.10.1.3 (0.19.0, mcpp#755; 2026.9.11.1
1919
Module `mcpp.dist.web`; engine floor: 2026.9.13.1, the release that carries `${mcpp.self}` and `mcpp stage`'s argument shape as an engine contract (`stage --verify content --output <dst> <src>`) -- what lets this member's copy run on every host mcpp does, Windows included, in place of the `cp` this member used through 0.8.0.
2020

2121
**Needs and behaviour.** nothing beyond mcpp: `wasm32-emscripten` only. Copies `${mcpp.stage_dir}/bin/` -- the `.js` launcher, the implicit `.wasm`, the `.data` when present, and every `mcpp::deploy`'d file, all of which #622 A5 and A4 already stage there -- to `<out_dir>/web/`, dropping the `bin/` prefix a browser has no use for, and writes an `index.html` rendered from a project template or a built-in default that loads the script with a plain `<script src>`. Each staged file and the rendered page are copied with `${mcpp.self} stage --verify content --output <dst> <src>`, the same copier every `stage_file` edge in `build.ninja` already runs -- no host-specific copy tool, no plan-time `create_directories` (`stage` creates the destination's parent), and a second `mcpp pack --format web` with nothing changed copies nothing. From 0.12.0 `options::page` names the page (`index.html` by default), for a project whose other build names it after the target; a name that is not a bare `*.html` file name is refused at plan time
22+
23+
**The page, the runner and where the directory is (0.22.0).** The page is the format's one distributable: its step takes every copied file as an input, so no copied file is an output nothing consumes, and `mcpp run --pkg-format web` is handed the page (0.21.0 declared each copied file a distributable, and the engine refused to choose among them). The page's source is written to `<out_dir>/.dist-web/<target>-<page>.in`, not beside the build's outputs as `<target>-index.html`, where it was opened as the product and loaded nothing. When `mcpp pack --pkg-format web` declares the directory, a note names it and says how it is opened: a browser loads the module only over HTTP, and a page opened from disk cannot load its `.wasm`. When the member declines a request (another target, no launcher for the program it wraps, a page name it refuses), it states the reason as a warning, which a build program's successful run shows and its standard error does not; mcpp 2026.11.16.1 and later repeat it in the refusal of a pack that produced nothing. With mcpp 2026.11.16.1 and later (protocol 19) it also states the program `options::target` names to the engine (`mcpp::pack_program`), so `mcpp pack --pkg-format web` in a package with several programs packs that one without the program being named; an older engine keeps its own choice.
24+
25+
`options::runner` (default true) declares a long-lived runner named `web`: `emrun` from the resolved Emscripten toolchain (`<toolchain_dir>/emscripten/emrun`, `emrun.bat` on Windows), given `--hostname localhost` and the page. `mcpp run --pkg-format web` therefore serves the directory on this machine with the types a browser requires (`application/wasm`), opens the page in the default browser, and serves until the operator ends it. The server listens on `localhost` only; a machine that wants another browser, port or address replaces the runner in its `config.toml` (`[target.wasm32-emscripten.runners] web = ["<emsdk>/emscripten/emrun", "--port", "8080", "{}"]`). Measured on Linux: the module is served as `application/wasm`; on a machine with no browser emrun says so and keeps serving.
26+
27+
**Link arguments are not a function of the package format.** A build program that branches on `mcpp::pack_format()` to change link arguments (`-sSINGLE_FILE=1` for one format and not another) changes nothing: `mcpp pack` stages the program the build already linked, and its second pass does not link again. A link difference is a profile's (`[profile.web] ldflags`, selected with `--profile web`), which also names the build directory, so the two links do not overwrite each other.

‎docs/plugin-development.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ mcpp-index refuses such a package.
5252

5353
```toml
5454
[build-dependencies.mcpp]
55-
plugins = { version = "0.21.0", features = ["plugins-core"], host-module = true, reexport = true }
55+
plugins = { version = "0.22.0", features = ["plugins-core"], host-module = true, reexport = true }
5656
```
5757

5858
`reexport = true` is needed when the plugin's consumers import L2 modules in

‎mcpp.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[package]
22
name = "plugins"
33
namespace = "mcpp"
4-
version = "0.21.0"
4+
version = "0.22.0"
55
# The first mcpp release that speaks protocol 17 (SPEC-013, mcpp#847): the
66
# platform's directives `mcpp.plugins.platform` states (`link_driver`,
77
# `link_input`, `artifact_name`, `seal`, `run_host`), the `platform` phase, and

‎src/plugins.cppm‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ export namespace mcpp::plugins {
4646
//
4747
// One package, one version: the number lives in mcpp.toml, and the CI step
4848
// `the collection states its own version` compares the two.
49-
inline constexpr std::string_view version = "0.21.0";
49+
inline constexpr std::string_view version = "0.22.0";
5050

5151
} // namespace mcpp::plugins
5252

‎tests/web-consumer/check-web-plan.sh‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,39 @@ out=$(node "$WEB/web-consumer.js")
7373
[ "$out" = "1-2-3" ] || fail "node did not print 1-2-3 (got: $out)"
7474
echo "ok: node $WEB/web-consumer.js prints 1-2-3"
7575

76+
echo "== the page is the one distributable, and its source is not mistaken for it (0.22.0) =="
77+
grep -q "Packed .*/web/index.html" pack.log || fail "mcpp pack did not name index.html as the distributable" pack.log
78+
grep -q "note: .*the web directory is" pack.log || fail "mcpp pack did not say where the web directory is" pack.log
79+
grep -q "open it over HTTP" pack.log || fail "mcpp pack did not say how the directory is opened" pack.log
80+
stray=$(find target -name '*-index.html' -not -path '*/.dist-web/*')
81+
[ -z "$stray" ] || fail "a page source lies beside the build's outputs as a page: $stray"
82+
echo "ok: one distributable (index.html); the page's source is .dist-web/*.html.in"
83+
84+
echo "== mcpp run --pkg-format web serves the page through the runner named web (0.22.0) =="
85+
"$MCPP" run --target wasm32-emscripten --list-runners > runners.log 2>&1 || fail "--list-runners failed" runners.log
86+
grep -E '^ +web +.*emrun.*long-lived' runners.log || fail "no long-lived runner named web" runners.log
87+
# No browser on a CI machine: emrun says so and keeps serving, which is what
88+
# is measured -- the page and the module, with the type a browser requires.
89+
# mcpp becomes the runner (its image replaced on POSIX), so the started
90+
# process is the server, and an interrupt is the operator ending it.
91+
"$MCPP" run --pkg-format web --target wasm32-emscripten > serve.log 2>&1 &
92+
server=$!
93+
served=
94+
for i in $(seq 1 45); do
95+
if curl -fsS -o target/served.wasm -w '%{content_type}' http://localhost:6931/web-consumer.wasm > target/served.type 2>/dev/null; then served=1; break; fi
96+
sleep 1
97+
done
98+
[ -n "$served" ] || fail "nothing was served on localhost:6931" serve.log
99+
grep -q 'application/wasm' target/served.type || fail "the module was not served as application/wasm" target/served.type
100+
curl -fsS http://localhost:6931/index.html | grep -q 'web-consumer.js' || fail "the page was not served" serve.log
101+
grep -q 'localhost' serve.log || fail "the server does not say it listens on localhost" serve.log
102+
# A background job of a script ignores SIGINT (POSIX), so the operator's end
103+
# is stated as SIGTERM here.
104+
kill -TERM "$server"
105+
for i in $(seq 1 20); do kill -0 "$server" 2>/dev/null || break; sleep 1; done
106+
kill -0 "$server" 2>/dev/null && { kill -KILL "$server"; fail "the server did not end when interrupted" serve.log; }
107+
echo "ok: the page and its module are served on localhost (application/wasm)"
108+
76109
echo "== options::page names the page, and refuses a name that is not a bare *.html file =="
77110
# A copy of this fixture beside it, so its path dependency on the collection
78111
# (`../..`) still resolves; the copy's build program sets `options::page`.

0 commit comments

Comments
 (0)