Skip to content

feat(cross): build.app_path is misaligned with the embedder/app separation model #272

Open

Description

@MEverett90

Background

build.app_path allows an embedder manifest to declare the Flutter app it bundles. The emb matrix command reads this field and injects --app <resolved_path> into the matrix cell's args, so CI runs emb cross --app without any extra workflow logic.

The problem

The field assumes a fixed 1:1 relationship between an embedder and a Flutter app — one app baked into the embedder manifest. In practice, emb is designed around the opposite model: embedder manifests and app manifests are independent so they can be mixed and matched at build time. A single embedder targets multiple boards; a single Flutter app deploys to multiple embedders. Hard-coding an app path into the embedder manifest breaks that composability.

A second issue: cross.modules entries are only compiled when --app is present. Since CI derives --app solely from build.app_path, any embedder manifest without that field silently skips its module builds. Modules are logically part of the embedder — they are local source trees compiled against the embedder's toolchain and sysroot. There is no good reason to gate their build on the presence of an app.

Suggested resolution

  1. Deprecate build.app_path without removing it. Removing it is a breaking change. Instead, emb cross --build and emb matrix should emit a warning when build.app_path is encountered: build.app_path has no effect and will be removed in a future release; pass --app at the command line instead.
  2. Make modules build without --app. Modules should be compiled alongside the embedder whenever cross.modules is declared, staging their artifacts into a dedicated output directory rather than silently skipping them.
  3. Ensure CI still exercises the --app + bundle assembly path. If build.app_path is no longer the mechanism for injecting --app, CI needs at least one example that is invoked with an explicit --app to cover the runnable bundle path (Flutter AOT + assemble + module staging). This could be a dedicated example manifest that documents the intended emb cross --app invocation pattern.

Activity

  1. jwinarske commented on Oct 20, 2026

    @jwinarske
    Contributor

    The premise does not hold on main. emb matrix never read build.app_path and never injected --app. app_path has one parse site (lib/src/manifest/build_config.dart:23) and one consumer (build_command.dart:129) — emb build. A matrix cell's args is <file>, plus --target <name> for a named target, and nothing else. So "CI runs emb cross <manifest> --app <app> without any extra workflow logic" never happened, and a deprecation warning from emb cross / emb matrix warns about a field those commands do not read.

    What is real is the examples. All eight cross examples carried a build: block that emb cross ignores — that dead schema is what reads as if an embedder manifest declares its app. Removed in #276.

    The field belongs to a different command and a different model. emb build <package> builds one package's own Flutter app from its own manifest; 1:1 is correct there. Deprecating it trades a cross-model complaint for a regression in emb build.

    "Silently skips" is inaccurate. cross_command.dart:1513 warns, and examples/cross/README.md:179 documents the skip.

    "No good reason to gate" has two reasons. Modules stage into the app bundle's lib/ beside libapp.so and are audited as part of it (auditBundleLib(..., moduleArtifacts: ...)); with no bundle there is no destination. And modules[].path accepts ${app_root}, which is unbindable without --app — hasUnresolvedKeyPaths exists for exactly that, and is why matrix omits sysroot_key/build_key for such cells.

    The disagreement underneath is real, but it is not a gate. cross.modules is app-owned by design and by documentation ("Modules (app-owned native libraries)… from the app's own source tree"). Embedder-owned native libraries are a reasonable thing to want, but they are a second kind, needing a destination, their own audit, and a packaging answer: deb/ipk/rpm carry the embedder binary plus cross.package.files, not the bundle, and no manifest variable names the build root (${embedder_root}, ${app_root}, ${runnable} are the three), so files: cannot reach a <buildRoot>/modules/ today. Worth doing; additive rather than a change to cross.modules.

    Point 3 is right, and understated. Because matrix never injected --app, no cross CI cell exercises the runnable bundle path at all — AOT, assemble, module staging, bundle audit. That is the same shape as the two blind spots the flatpak work turned up, and it is the one item here that needs no design decisions.

    #275 implements point 2; comments there rather than here.

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