From 42df0ad925d3b1a7f6d0d967d65ce6b887b7125a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= Date: Tue, 16 Feb 2021 15:39:42 -0800 Subject: [PATCH] doc: west: clean up manifest import details MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move the content related to handling imports that refer to multiple files handled to right after the ordered list which defines the order that manifests are imported. The current placement at the end of this docs section was poorly chosen. Create subsections for how projects and extensions are decided in the final resolved manifest. The project revisions in the top level example manifest fragment are not important here. Remove them for clarity. The top level manifest file need not be named west.yml now; adjust accordingly. This is prep work for adding a new subsection for group-filter. Signed-off-by: Martí Bolívar --- doc/guides/west/manifest.rst | 62 +++++++++++++++++++++++------------- 1 file changed, 39 insertions(+), 23 deletions(-) diff --git a/doc/guides/west/manifest.rst b/doc/guides/west/manifest.rst index 42e8e115f65..2dadcbd8ae1 100644 --- a/doc/guides/west/manifest.rst +++ b/doc/guides/west/manifest.rst @@ -1653,29 +1653,26 @@ For this example, west resolves imports in this order: Manifest Import Details ======================= -This section describes how west imports a manifest file a bit more formally. +This section describes how west resolves a manifest file that uses ``import`` a +bit more formally. Overview -------- -A west manifest's ``projects`` and ``self`` sections can have ``import`` keys, -like so: +The ``import`` key can appear in a west manifest's ``projects`` and ``self`` +sections. The general case looks like this: .. code-block:: yaml - # Top-level west.yml. + # Top-level manifest file. manifest: - # ... projects: - name: foo - revision: rev-1 import: import-1 - name: bar - revision: rev-2 import: import-2 # ... - name: baz - revision: rev-N import: import-N self: import: self-import @@ -1683,17 +1680,39 @@ like so: Import keys are optional. If any of ``import-1, ..., import-N`` are missing, west will not import additional manifest data from that project. If ``self-import`` is missing, no additional files in the manifest repository -(beyond the top-level west.yml) are imported. +(beyond the top-level file) are imported. -The ultimate outcome of resolving manifest imports is a final list of projects, -which is produced by combining the ``projects`` defined in the top-level file -with those defined in imported files. Importing is done in this order: +The ultimate outcomes of resolving manifest imports are: + +- a ``projects`` list, which is produced by combining the ``projects`` defined + in the top-level file with those defined in imported files + +- a set of extension commands, which are drawn from the the ``west-commands`` + keys in in the top-level file and any imported files + +Importing is done in this order: #. Manifests from ``self-import`` are imported first. -#. The top-level manifest file's ``projects`` are added in next. +#. The top-level manifest file's definitions are handled next. #. Manifests from ``import-1``, ..., ``import-N``, are imported in that order. -This process recurses if necessary. +When an individual ``import`` key refers to multiple manifest files, they are +processed in this order: + +- If the value is a relative path naming a directory (or a map whose ``file`` + is a directory), the manifest files it contains are processed in + lexicographic order -- i.e., sorted by file name. +- If the value is a sequence, its elements are recursively imported in the + order they appear. + +This process recurses if necessary. E.g., if ``import-1`` produces a manifest +file that contains an ``import`` key, it is resolved recursively using the same +rules before its contents are processed further. + +Projects +-------- + +This section describes how the final ``projects`` list is created. Projects are identified by name. If the same name occurs in multiple manifests, the first definition is used, and subsequent definitions are ignored. For @@ -1727,20 +1746,17 @@ extra projects shouldn't take too much time unless it's really needed. See the documentation for the :ref:`update.fetch ` configuration option for more information. +Extensions +---------- + +All extension commands defined using ``west-commands`` keys discovered while +handling imports are available in the resolved manifest. + If an imported manifest file has a ``west-commands:`` definition in its ``self:`` section, the extension commands defined there are added to the set of available extensions at the time the manifest is imported. They will thus take precedence over any extension commands with the same names added later on. -When an individual ``import`` key refers to multiple manifest files, they are -processed in this order: - -- If the value is a relative path naming a directory (or a map whose ``file`` - is a directory), the manifest files it contains are processed in - lexicographic order -- i.e., sorted by file name. -- If the value is a sequence, its elements are recursively imported in the - order they appear. - .. _west-manifest-cmd: Manifest Command