Skip to content

docs: document extends: unqualified-first; drop dead build: from cross examples - #276

Merged
jwinarske merged 1 commit into
mainfrom
docs/board-extends-portability
Oct 20, 2026
Merged

jwinarske merged 1 commit into
mainfrom
docs/board-extends-portability

Conversation

@jwinarske

Copy link
Copy Markdown
Contributor

The documentation halves of #273 and #272. No code changes, no schema changes.

#273 — extends: is documented unqualified-first

The multi-source section presented <source>/<target> as how extends: resolves, with no mention that an unqualified name resolves across every configured source. A source name is a local choice recorded in boards.yaml, so a manifest written from that sentence only resolves for someone who picked the same name — the portability problem #273 reports.

_boardExtendsBase already tries the qualified key, then matches the target segment across all sources, and makes an ambiguous name a hard error listing the qualified alternatives. The portable form existed; the docs pointed away from it. Every board, example and doc elsewhere uses the unqualified form, and emb boards list prints unqualified targets grouped by source.

Also corrected in the same paragraph: "so names never collide" — board files don't (each source installs into its own subdirectory), board names do, which is what the ambiguity error is for.

This does not close #273. The remaining question — whether a board repo should declare its own canonical name — is discussed on the issue.

#272 — the cross examples no longer carry a build: block

All eight cross examples declared:

build:
  app_path: .
  archs: [arm64]
  modes: [release]
  output: bundles

emb cross and emb matrix never read it. build.app_path is parsed in one place (lib/src/manifest/build_config.dart:23) and consumed in one place (build_command.dart:129) — emb build. So these manifests declared a field with no effect on the command they demonstrate, which is what reads as an embedder manifest declaring its app.

The field itself is untouched: it is correct for emb build <package>, which builds one package's own app from its own manifest.

Verification

dart analyze clean, dart test 1267 passed, and emb matrix examples/cross still renders 30 cells. No test or workflow reads the removed block — cross_target_examples_test.dart parses only the cross: block, and no workflow runs emb build.

…s examples

Two documentation defects behind #273 and #272.

#273: the multi-source section presented `<source>/<target>` as how `extends:`
resolves, with no mention that an unqualified name resolves across every
configured source. A source name is a local choice recorded in boards.yaml, so
a manifest written from that sentence only resolves for someone who picked the
same name. `_boardExtendsBase` already tries the qualified key, then matches
the target segment across all sources, and makes an ambiguous name a hard error
listing the qualified alternatives -- so the portable form existed and the docs
pointed away from it. The same paragraph claimed names never collide: board
files do not, board names do, which is what that error is for.

#272: all eight cross examples carried a `build:` block that `emb cross` and
`emb matrix` never read. `build.app_path` is parsed by BuildConfig and consumed
only by `emb build`, so the block declared a field with no effect on the command
the examples demonstrate -- which is what reads as an embedder manifest
declaring its app. The field itself is left alone; it is correct for
`emb build <package>`.

`emb matrix examples/cross` still renders 30 cells.

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

Copy link
Copy Markdown
Contributor Author

cc @MEverett90

@jwinarske
jwinarske merged commit c78c5f1 into main Oct 20, 2026
33 checks passed
@jwinarske
jwinarske deleted the docs/board-extends-portability branch October 20, 2026 16:40
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.

Board source name leaks into extends: — manifests not portable across different source configurations

1 participant