Skip to content

feat(cross): No unified single-command build+package+deploy for embedder and app as separate packages #216

Open

Description

@MEverett90

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

  1. jwinarske commented on Oct 6, 2026

    @jwinarske
    Contributor

    Verified both claims against main.

    The merge is real. _mergeCross (cross_project.dart:636) runs deepMerge
    over the cross block with explicit cases for backends (replace),
    sysroot.dev_packages and augment (union). package has no case, so the app's
    block merges field-by-field onto the embedder's, exactly as described.

    The silent drop is real. _runnable (cross_command.dart:2321) assembles the
    app bundle, installs the embedder binary, stages its linked libraries, and stops.
    Every package format reaches files: through _extraFiles -> extraFiles:;
    --tar and --deploy never read spec.files at 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 PR
    worth your eye — a source already inside the bundle is skipped (the documented
    ${runnable}/lib/libfoo.so pattern would otherwise ship the library twice), and
    --flatpak moved ahead of the staging because it applies files: itself at
    /app paths 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.name already names the staging directory and is
    validated as such. Does the app package default to the Flutter app's pubspec name
    and version when cross.package.name is absent in the app manifest, or is it
    required? 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, installing
    the 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 what
    happens 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 --deb means. Today it names one output. Two outputs need two paths and
    two log lines; --targz and --tar differ again. Does --deb with no app
    manifest package block still produce one, or is the two-package shape always
    present once --app is given?

    Cache keys and emb.lock. augmentOverlayKey and buildKey hash 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.lock gain an entry for it?
    Getting this wrong means a stale app package served from cache.

    Scripts. package.scripts (maintainer scripts) are embedder-side today and
    allowlisted by name. A files-only app package that wants a postinst to reload
    systemd 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 staged
    into 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 package block needs
    provenance stamped on it the way augments carry _source; worth deciding together
    with the two-package model rather than before it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions