Skip to content

fix(cross): --tar and --deploy carry cross.package.files - #258

Merged
jwinarske merged 1 commit into
mainfrom
fix/runnable-package-files
Oct 6, 2026
Merged

jwinarske merged 1 commit into
mainfrom
fix/runnable-package-files

Conversation

@jwinarske

Copy link
Copy Markdown
Contributor

Takes the near-term half of #216 — the silent drop — and leaves the two-package
model for a design pass. Design questions posted on the issue.

The bug

_runnable assembles the app bundle, installs the embedder binary, stages its
linked libraries, and stops. Nothing reads spec.files. Every package format goes
through _extraFiles → extraFiles:; --tar and --deploy never did. So a
systemd unit or a config file in cross.package.files reached a .deb and never
a deployed board, with no warning on either path — you find out on the device.

Semantics

Files stage under the bundle root: an absolute to: loses its leading separator,
a relative one lands as-is. Worth being explicit, because it is not an install —
--deploy copies the bundle to --deploy-dir, so /etc/app.conf ends up at
<deploy-dir>/etc/app.conf, not /etc/app.conf. Installing at real paths is what
--deb/--ipk/--rpm/--targz are for. #216 describes exactly this layout as
the interim behavior.

Two things the staging has to get right

A source already inside the bundle is skipped. README documents
${runnable}/lib/libmymodule.so: { to: /usr/lib/libmymodule.so }. Staged naively
that copies a library the bundle already carries to a second path inside the same
bundle, doubling what --tar writes and --deploy pushes. Filtered with
p.isWithin rather than a string prefix, so a multi-backend build's
runnable-drm is not read as inside runnable — there is a test for that.

--flatpak moved ahead of the staging. It applies files: itself at their
/app paths and copies the bundle wholesale, so a bundle already carrying them
at bundle-relative paths would ship every file twice. Reordering is the whole fix;
the two outputs are independent.

The refactor, and why

The copy loop moves out of PackageStager.stagePayload into a top-level
stageExtraFiles. I did not want a second copy of the containment rules hardened
in #235 — .. refused outright, p.isWithin as the backstop, octal-only modes,
chmod batched under both a path-count and an argv-byte bound. One implementation,
both callers.

Two deliberate changes to that code, both forced by the new caller:

  • Destinations may be relative. A bundle path need not be rooted; stagePayload
    keeps its own "must be absolute" check, so package formats are unchanged.
  • A source already at its destination is skipped. copySync onto itself truncates
    the file. Unreachable before, because the staging root was always a directory
    emb had just created; reachable now that it can be one the source lives in.

A regression I introduced and backed out: folding mode validation into the
shared function moved it past the binary copy, and #235's test — "nothing may be
chmodded on a bad mode" — caught it. stagePayload validates the whole mode set
before writing anything, as it did.

Tests

Five on stageExtraFiles (absolute dest, relative dest, self-copy skipped rather
than truncated, .. refused with the victim file verified intact, option-shaped
mode refused before anything is written) and three on filesNotAlreadyIn.

The wiring inside _runnable is not unit-tested: the command test harness stops
the build before the bundle is assembled, and reaching it needs a real toolchain
and engine. CI does not cover it either — validate runs --build without
--app, so _runnable never executes there, and the one example manifest with a
files: block has it commented out. Worth knowing when reviewing the ordering
change.

1216 tests pass; dart analyze and dart format clean; cspell clean.

Behavior change

This changes what --tar produces and what --deploy pushes for any manifest
declaring package.files. That is the point of the fix, but it is a change for
anyone who had worked around the drop by hand. Called out in the CHANGELOG.

The runnable bundle was the app bundle, the embedder binary and its linked
libraries. Nothing read `spec.files`, so a config file or a systemd unit declared
in `cross.package.files` reached a `.deb` but never a deployed board — silently,
with no warning on either path. Part of #216, which calls this out as the
impactful near-term fix; the two-package model in that issue is a separate change.

Files stage under the bundle root: an absolute `to:` loses its leading separator
(`/etc/app.conf` -> `<runnable>/etc/app.conf`), a relative one lands as-is. A
bundle is not an install — `--deploy` copies it to `--deploy-dir`, so these sit
under that directory rather than at `/etc`. Putting them at their real paths is
what the package formats are for.

Two cases the staging has to get right:

- A source already inside the bundle is skipped. The documented
  `${runnable}/lib/libfoo.so` pattern names a file the bundle already carries, and
  a second copy only doubles what goes over the wire. `p.isWithin`, not a string
  prefix, so `runnable-drm` is not read as inside `runnable`.
- `--flatpak` now runs before the staging. It applies `files:` itself, at their
  `/app` paths, and copies the bundle wholesale — so a bundle already carrying
  them at bundle-relative paths would ship every one twice.

The copy loop moves out of `PackageStager.stagePayload` into a top-level
`stageExtraFiles`, so both callers get one implementation of the containment
rules hardened in #235 rather than a second copy of them: `..` refused outright,
`p.isWithin` as the backstop, octal-only modes, batched chmod bounded by both
path count and argv bytes. Two changes to that code, both forced by the new
caller:

- Destinations may now be relative, since a bundle path need not be rooted.
- A source already at its destination is skipped. `copySync` onto itself
  truncates the file, and that was unreachable while the staging root was always
  a directory emb had just created.

Mode validation stays in `stagePayload` before the binary is written, not only
inside the shared function: #235's test asserts nothing is chmodded when a mode
is bad, and moving the check past the binary copy broke it.

Signed-off-by: Joel Winarske <joel.winarske@linux.com>
@jwinarske
jwinarske merged commit cb71f3a into main Oct 6, 2026
41 checks passed
@jwinarske
jwinarske deleted the fix/runnable-package-files branch October 6, 2026 16:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant