Repository navigation
docs: document extends: unqualified-first; drop dead build: from cross examples - #276
Merged
Merged
Conversation
…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>
Contributor
Author
|
cc @MEverett90 |
1 of 7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The documentation halves of #273 and #272. No code changes, no schema changes.
#273 —
extends:is documented unqualified-firstThe multi-source section presented
<source>/<target>as howextends:resolves, with no mention that an unqualified name resolves across every configured source. A source name is a local choice recorded inboards.yaml, so a manifest written from that sentence only resolves for someone who picked the same name — the portability problem #273 reports._boardExtendsBasealready 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, andemb boards listprints 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:blockAll eight cross examples declared:
emb crossandemb matrixnever read it.build.app_pathis 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 analyzeclean,dart test1267 passed, andemb matrix examples/crossstill renders 30 cells. No test or workflow reads the removed block —cross_target_examples_test.dartparses only thecross:block, and no workflow runsemb build.