Repository navigation
Description
Description
emb cross can build an embedder and a Flutter app bundle together in a single invocation via --build --app
, but packaging and deployment treats them as a single merged unit rather than two independent components. This is architecturally wrong: the embedder and the Flutter app are distinct artifacts with separate lifecycles, versioning, and installation concerns. There should be a first-class way to produce and deploy a package for each from one command.Currently, the app manifest's cross.package block is deep-merged onto the embedder's cross.package before any packaging step runs. This means only one package is ever produced, app-level metadata (name, version, maintainer, files) clobbers or entangles with embedder-level metadata, and there is no way to get cleanly separated artifacts. Additionally, package.files defined in the app manifest are never included in --tar/--deploy output (the runnable bundle path), so config files, systemd units, and other app-side payload silently fail to reach the device regardless of which packaging format is used.
The intended model should be: when --app
is present and the app manifest defines cross.package, that spec is treated as a fully independent package — resolved against the app manifest directory, built in parallel with the embedder package, and deployed together in a single --deploy invocation. The app package is files:-only (no binary anchor); it carries whatever the app needs on the device — configuration, service files, data, etc. — at their proper target paths.Requirements
- Remove the deep-merge of app-side cross.package into the embedder's PackageSpec; app and embedder packaging specs are independent
- App cross.package is resolved relative to the app manifest directory (not the embedder manifest directory)
- When --app is present and the app manifest defines cross.package, a separate package artifact is produced for the app alongside the embedder package, for each active packaging format (--tar, --targz, --deb, --ipk, --rpm)
- The app package has no binary anchor; it is a files:-only package (analogous to a data or config package in a traditional package manager)
- Both packages are deployed in a single --deploy invocation when present
- package.files entries in the app manifest are staged into the runnable bundle for --tar and --deploy (fixes the current silent drop, provides a path forward while the full two-package model is implemented)
- App-side cross.package metadata (name, version, maintainer, description) no longer affects the embedder package in any format
- The existing cross.package merge behavior for non-packaging fields (defines, augment, sysroot.dev_packages) is preserved — only package is split out
- Documentation updated to describe the two-package model and the distinction between embedder and app packaging
Additional Context
The current silent-drop behavior for --deploy is the most impactful immediate bug: a user who defines cross.package.files in their app manifest to carry a config file or systemd service unit will see those files never reach the device, with no warning or error. This should be addressed as a near-term fix independent of the full two-package implementation.
The package.files destination paths for app-side entries must be absolute for --targz/--deb/--ipk/--rpm (the existing PackageStager enforces this). The --tar/--deploy runnable path can accept either: absolute target paths are made bundle-root-relative by stripping the leading /; relative paths land as-is in the bundle.
Activity
jwinarske commentedon Oct 6, 2026
Verified both claims against
main.The merge is real.
_mergeCross(cross_project.dart:636) runsdeepMergeover the cross block with explicit cases for
backends(replace),sysroot.dev_packagesandaugment(union).packagehas no case, so the app'sblock merges field-by-field onto the embedder's, exactly as described.
The silent drop is real.
_runnable(cross_command.dart:2321) assembles theapp bundle, installs the embedder binary, stages its linked libraries, and stops.
Every package format reaches
files:through_extraFiles->extraFiles:;--tarand--deploynever readspec.filesat all.Taking the drop now, since you scoped it as separable: #258. Files stage under the
bundle root, absolute
to:loses its leading separator. Two notes on that PRworth your eye — a source already inside the bundle is skipped (the documented
${runnable}/lib/libfoo.sopattern would otherwise ship the library twice), and--flatpakmoved ahead of the staging because it appliesfiles:itself at/apppaths and copies the bundle wholesale.On the two-package model
Agreed on the architecture — the embedder and the app are separate artifacts with
separate lifecycles, and the merge entangles them. What I do not want to do is
invent the answers to these while implementing, because each one is visible in
what users ship:
Naming and versioning. The app package needs a name and version independent of
the embedder's.
package.namealready names the staging directory and isvalidated as such. Does the app package default to the Flutter app's pubspec name
and version when
cross.package.nameis absent in the app manifest, or is itrequired? Two packages colliding on one name is a silent overwrite in
dist/.Dependency. Does the app package declare a dependency on the embedder package
(
Depends:,Requires:), and at what version constraint? Without one, installingthe app alone leaves a config file with no binary to read it. With an exact pin,
every embedder rebuild forces an app rebuild. This is the decision with the longest
tail — it is in the metadata of every artifact emb emits from then on.
Deploy order. "Both deployed in a single
--deploy" — in which order, and whathappens when the second fails after the first installed? A board left with a new
app package against an old embedder is a worse state than a failed deploy.
What
--debmeans. Today it names one output. Two outputs need two paths andtwo log lines;
--targzand--tardiffer again. Does--debwith no appmanifest
packageblock still produce one, or is the two-package shape alwayspresent once
--appis given?Cache keys and
emb.lock.augmentOverlayKeyandbuildKeyhash the target,and the lock records what was resolved. Two package specs under one target — does
the app spec participate in any key, and does
emb.lockgain an entry for it?Getting this wrong means a stale app package served from cache.
Scripts.
package.scripts(maintainer scripts) are embedder-side today andallowlisted by name. A files-only app package that wants a
postinstto reloadsystemd would need its own set, which is a new surface on the hardening in #235.
My read is that the first two decide the shape and the rest follow. If you want to
settle naming/versioning and the dependency question here, I can take the
implementation from there.
One scoping note: the requirement list says app-side
files:are what get stagedinto the runnable, but post-merge there is nothing distinguishing them from the
embedder's — the embedder's own entries were dropped by the same code path. #258
stages all of them. If the split needs to be per-origin, the
packageblock needsprovenance stamped on it the way augments carry
_source; worth deciding togetherwith the two-package model rather than before it.