Skip to content

feat: build cross modules standalone and during --prepare - #275

Merged
jwinarske merged 7 commits into
mainfrom
me/build-modules
Oct 21, 2026
Merged

jwinarske merged 7 commits into
mainfrom
me/build-modules

Conversation

@MEverett90

Copy link
Copy Markdown
Collaborator

Description

Addresses #272

Previously, cross modules could only be built as part of an app bundle
(--app). Without --app, declaring modules emitted a warning and skipped
them entirely.

This changes that in two ways:

  1. Standalone module builds — when --app is absent but target.modules
    is non-empty, modules are now built and staged into <buildRoot>/modules/
    instead of being silently skipped.

  2. --prepare module builds — modules are now built during --prepare,
    placed into <preparedEmbedder.buildRoot>/modules/, so a subsequent
    --deploy/--run finds them without needing a separate build step.

Modules whose paths contain unresolved ${app_root} are skipped with an
informational message (requires --app to resolve). --prepare skips the
standalone build path since it already ran.

build.app_path is deprecated in favour of the --app flag.

Type of Change

  • ✨ New feature (non-breaking change which adds functionality)
  • 🛠️ Bug fix (non-breaking change which fixes an issue)
  • ❌ Breaking change (fix or feature that would cause existing functionality to change)
  • 🧹 Code refactor
  • ✅ Build configuration change
  • 📝 Documentation
  • 🗑️ Chore

Modules declared in cross.modules are now compiled alongside the
embedder whenever --build is used, staging artifacts into
<buildRoot>/modules/ rather than silently skipping them when no --app
is provided. Modules are logically part of the embedder — they share
its toolchain and sysroot — and should not depend on a Flutter app
being present.

Deprecate build.app_path: emb matrix now warns when the field is set,
directing users to pass --app at the command line instead. The field
parsed silently but had no effect after the matrix command stopped
deriving --app from it.
_buildModules now skips (with an info log) any module whose path
contains ${app_root} when appDir is null, preventing a misleading
"source dir not found" error during --prepare or standalone --build.

Adds dry-run tests for manifests with plain and ${app_root} module paths,
and matrix command tests for host_dev_packages output and the
build.app_path deprecation warning.
Move expandManifestVars call before hasUnresolvedVars check so variables
that can be resolved (e.g. from moduleVars) don't cause modules to be
incorrectly skipped when --app is absent. Also eliminates the duplicate
expand call when constructing the src Directory.

Move build.app_path deprecation warning before the target loop to emit it
once per manifest rather than once per target.
@MEverett90
MEverett90 requested a review from jwinarske October 19, 2026 21:02
…re step) and copies them into the runnable rather than re-building. Uses existing fingerprint mechanism to determine if modules are up-to-date or need to be re-built.

@jwinarske jwinarske left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review of the implementation, not the goal — the goal is right and #272's point 2 is worth closing.

Verified before posting: buildRoot encodes buildKey, and buildKey carries sysrootKey plus a mod: entry per module with its defines and features, so the new source-fingerprint stamp cache correctly misses on a toolchain, sysroot or defines change. That looked unsound on first read and isn't.

Six comments below. Two are worth fixing before merge — the untested feature path and the stale documentation; the rest are small.

Note that #276 just landed and removed the build: block from all eight cross examples, which changes the blast radius of the deprecation warning (see the comment on matrix_command.dart).

Comment thread lib/src/commands/cross_command.dart Resolved
Comment thread lib/src/commands/cross_command.dart Resolved
Comment thread lib/src/commands/matrix_command.dart Resolved
Comment thread lib/src/commands/matrix_command.dart Resolved
Comment thread lib/src/commands/cross_command.dart Resolved
- Fix --prepare _buildModules call omitting appDir, causing false
  "skipped (path has ${app_root})" log when --app is passed
- Fix module build log message hardcoding "→ lib/" regardless of
  destination; now shows the actual staged directory basename
- Fix build.app_path deprecation warning firing only on non-default
  values; now triggers on key presence in both `emb matrix` and
  `emb cross --build`
- Remove host_dev_packages from matrix cell output (no workflow reader)
- Update README and CHANGELOG to document standalone/--prepare module
  build behaviour and the new staging destination
- Add test covering the ${app_root} skip path via --build --target local
  with pre-seeded build root, and update matrix tests for the revised
  deprecation and host_dev_packages behaviour
@MEverett90
MEverett90 requested a review from jwinarske October 20, 2026 21:12

@jwinarske jwinarske left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified all six addressed.

Mutation-checked the new skip test: replacing if (appDir == null && hasUnresolvedVars(expanded)) with if (false) makes --build --target local skips ${app_root} modules without --app fail (exit 70 against the expected 0), so it genuinely covers the path it claims to. dart analyze clean, both touched test files pass locally (74 tests), CI 41/41 with only the opt-in build job skipped.

The pre-seeded .emb-source-stamp + fake ELF to get past skipIfBuilt is a neat way into _buildModules without a toolchain — worth remembering for the standalone-build case, which still has no test.

Three nits below, none blocking.

Comment thread examples/cross/README.md Resolved
Comment thread lib/src/commands/cross_command.dart Resolved
Three nits from the second review pass.

`<buildRoot>/modules/` was documented as being "for use by downstream
tooling", which reads like a supported integration point. Nothing in a
manifest reaches it: the path variables are ${embedder_root}, ${app_root}
and ${runnable}, and none names the build root, so `cross.package.files`
cannot pick these artifacts up. Say that instead.

The deprecation warning in `emb cross` read only the selected target's
declaring file. A `.emb/` project can hold a shared `build:` block in its
base while the target comes from a sibling, so the warning missed a case the
same manifest would hit when flat. Checks both paths now, as a set, which
collapses to one load for a flat manifest. The presence test is now
`declaresAppPath` in build_config.dart, shared with `emb matrix` rather than
spelled out twice.

The ${app_root} skip test asserted on the `${app_root}` substring, which the
"source dir not found" error this path produces on a regression also prints.
Pins the message instead; the exit-code expectation was doing the real work.

Tests: `declaresAppPath` directly, and the `emb cross` warning end-to-end --
it had none, only the matrix side did. Both mutation-checked: `if (false)`
fails the --build test, `if (true)` fails the --dry-run test.

Not covered: the sibling-file case itself. Selecting a cross target needs a
real toolchain, and the native path makes both lookups the same file.

Signed-off-by: Joel Winarske <joel.winarske@linux.com>
@jwinarske

jwinarske commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Pushed 9493c9e to this branch with the three nits addressed.

  • README: <buildRoot>/modules/ is described as outside emb's reach rather than "for downstream tooling". No path variable names the build root, so files: cannot carry those artifacts.
  • emb cross warning: reads the selected target's file and the project's base, as a set. A .emb/ project can hold a shared build: block in its base while the target comes from a sibling; the set collapses to one load for a flat manifest. The presence test moved to declaresAppPath in build_config.dart, shared with emb matrix instead of spelled out twice.
  • Test: pins module app_plugin: skipped rather than the ${app_root} substring, which the source dir not found error on this path also prints.

Added tests for declaresAppPath and for the emb cross warning end-to-end — that side had none. Both mutation-checked: if (false) fails the --build test, if (true) fails the --dry-run test. Full suite 1278 passing, analyze and format clean.

Not covered: the sibling-file case itself. Selecting a cross target needs a real toolchain, and the native path makes both lookups the same file — so that fix is reasoned, not tested.

@jwinarske
jwinarske merged commit 604e229 into main Oct 21, 2026
42 checks passed
@jwinarske
jwinarske deleted the me/build-modules branch October 21, 2026 18:14
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.

2 participants