Skip to content

Latest commit

 

History

History
35 lines (18 loc) · 8.75 KB

dist.md

File metadata and controls

35 lines (18 loc) · 8.75 KB

dist-appimage, dist-deb, dist-rpm, dist-wix and dist-web

Three dist-* members that turn the tree mcpp pack stages into an installable form: an AppImage on Linux, an MSI or a Burn bundle on Windows, and a web directory for wasm32-emscripten. dist-apple and dist-apk have pages of their own (dist-apple.md, dist-apk.md).

dist-appimage

Module mcpp.dist.appimage; engine floor: 2026.10.1.3 (0.19.0, mcpp#755; 2026.9.11.1 before). Its xim:appimagetool is installed when a pack asks for it (provision = "on-request"), so an ordinary Linux build downloads none.

Needs and behaviour. xim:appimagetool, which this feature declares on the cfg(linux) axis. Linux only. Turns the tree mcpp pack staged into one AppImage: the staged bundle is already an AppDir bar three files, so the member writes an AppRun, a .desktop entry and an icon into it and invokes one tool -- it never copies or re-lays-out a tree that can be hundreds of megabytes. From 0.11.1 options::icon may be an SVG as well as a PNG: the image carries <name>.svg, because the desktop entry names the icon without an extension and a reader finds it by the file's, and any other format is refused by name

dist-deb and dist-rpm

Modules mcpp.dist.deb and mcpp.dist.rpm, both on mcpp.dist.linux_package (feature dist-linux-package, which each implies); engine floor: 2026.10.30.1. Their xim:nfpm (2.49.0 or newer) is installed when a pack asks for it (provision = "on-request"), so an ordinary build downloads none. From 0.23.0.

Needs and behaviour. xim:nfpm, declared on the cfg(linux) axis; no dpkg-deb or rpmbuild on the host. Linux targets only; another target is refused by name. --pkg-format deb or --pkg-format rpm installs the tree mcpp pack staged, unchanged, under /opt/<name>, adds /usr/bin/<name> that execs the tree's launcher, and, unless options::desktop is false, a desktop entry in /usr/share/applications and the icon options::icon names (an SVG in hicolor/scalable/apps, a PNG in /usr/share/pixmaps). The control fields come from [package]: name, version, description, licence, repository, and the first author as maintainer; a package without a maintainer is refused rather than published under a guessed one. options::depends lists packages the machine provides, by the target distribution's names; the staged mcpp-package.json says what the tree left to the machine.

Reproducible. Every staged file is listed with an explicit mode and time (SOURCE_DATE_EPOCH, or 2000-01-01 when unset), because nfpm's tree entries keep each source file's mtime and its top-level mtime does not reach them; packing a re-staged, unchanged tree gives byte-identical packages. tests/linux-package-consumer packs both formats and reads them back.

dist-wix

Module mcpp.dist.wix; engine floor: 2026.10.1.3 (0.19.0, mcpp#755; 2026.9.11.1 before).

Needs and behaviour. xim:wix 5.0.2-1, which this feature declares on the Windows target axis; the .NET 6 runtime the tool needs is a Windows component the payload does not carry, and wix --version names it when it is missing. Windows only. --format msi renders a .wxs and passes the program in as a preprocessor variable, because a bind path that resolves to nothing is silent. From 0.10.0 --format setup is a Burn bundle chaining that MSI, with WiX's stock bootstrapper application (bal:WixStandardBootstrapperApplication, theme hyperlinkLicense, options::license_url its link) loaded through the WixToolset.BootstrapperApplications.wixext extension the 5.0.2-1 payload carries (options::extension names another). The bundle is written as <product_name>-<arch>.exe beside the MSI, with an UpgradeCode of its own, and options::bundle_output naming setup.exe is refused before wix runs, because wix refuses that name (WIX0388). A project with its own bootstrapper application supplies options::bundle_wxs, which receives the MSI as $(Msi). From 0.10.1 the MSI installs the staged tree, not the program alone: every file mcpp pack stages beside the program (a deployed file, a resolved DLL) is named file by file in a StagedFiles component group written beside the definition -- enumerated while the tree exists, never harvested from a directory -- placed at its staged path under INSTALLFOLDER, and declared an input of the action; the generated definition references the group, and a project's own options::wxs installs it with <ComponentGroupRef Id="StagedFiles" />. options::inputs and options::bundle_inputs declare the files a project's own definitions name beyond that (an icon, a bootstrapper application and its payloads). CI builds the bundle on windows-2022 and compares the MSI wix burn extract takes out of it with the one the first action wrote, and installs the MSI administratively and compares both the program and a deployed file

dist-web

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.

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

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.

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.

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.