From c20a081423c8ec23145d9ac1f609cccbbea3c5ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= Date: Mon, 7 Oct 2019 14:59:04 -0700 Subject: [PATCH] doc: west: document manifest import feature MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit West now supports importing other manifest files. Document the basic behavior. Add a local table of contents for HTML output, to get a quick index of the subsections of the "Manifest Imports" section. Signed-off-by: Martí Bolívar --- doc/guides/west/manifest.rst | 843 ++++++++++++++++++++++++++++++++++- 1 file changed, 841 insertions(+), 2 deletions(-) diff --git a/doc/guides/west/manifest.rst b/doc/guides/west/manifest.rst index 048b7fb641b..d0762e9048b 100644 --- a/doc/guides/west/manifest.rst +++ b/doc/guides/west/manifest.rst @@ -8,6 +8,11 @@ manifest files, and the ``west manifest`` command. For API documentation on the ``west.manifest`` module, see :ref:`west-apis-manifest`. For a more general introduction and command overview, see :ref:`west-multi-repo`. +.. only:: html + + .. contents:: + :depth: 3 + .. _west-mr-model: Multiple Repository Model @@ -64,6 +69,8 @@ Notice the following important details: name as a manifest revision, at the cost of being able to bisect manifest repository history. +.. _west-manifest-files: + Manifest Files ************** @@ -102,7 +109,7 @@ example: .. code-block:: yaml manifest: - # [...] + # ... remotes: - name: remote1 url-base: https://git.example.com/base1 @@ -209,6 +216,9 @@ The list of project keys and their usage follows. Sometimes we'll refer to the the project which describes additional west commands provided by that project. This file is named :file:`west-commands.yml` by convention. See :ref:`west-extensions` for details. +- ``import``: Optional. If ``true``, imports projects from manifest files in + the given repository into the current manifest. See + :ref:`west-manifest-import` for more details. The ``defaults`` subsection can provide default values for project attributes. In particular, the default remote name and revision can be @@ -251,13 +261,17 @@ manifest repository itself. Its value is a map with the following keys: - ``west-commands``: Optional. This is analogous to the same key in a project sequence element. +- ``import``: Optional. This is also analogous to the ``projects`` key, but + allows importing projects from other files in the manifest repository. See + :ref:`west-manifest-import`. + As an example, let's consider this snippet from the zephyr repository's :file:`west.yml`: .. code-block:: yaml manifest: - # [...] + # ... self: path: zephyr west-commands: scripts/west-commands.yml @@ -272,6 +286,808 @@ repository root. The pykwalify schema :file:`manifest-schema.yml` in the west source code repository is used to validate the manifest section. +.. _west-manifest-import: + +Manifest Imports +**************** + +You can use the ``import`` key briefly described above to include projects from +other manifest files in your :file:`west.yml`. This key can be either a +``project`` or ``self`` section attribute: + +.. code-block:: yaml + + manifest: + projects: + - name: some-project + import: ... + self: + import: ... + +You can use a "self: import:" to load additional files from the repository +containing your :file:`west.yml`. You can use a "project: ... import:" to load +additional files defined in that project's Git history. + +West resolves the final manifest from individual manifest files in this order: + +#. imported files in ``self`` +#. your :file:`west.yml` file +#. imported files in ``projects`` + +During resolution, west ignores projects which have already been defined in +other files. For example, a project named ``foo`` in your :file:`west.yml` +makes west ignore other projects named ``foo`` imported from your ``projects`` +list. + +The ``import`` key can be a boolean, path, mapping, or sequence. We'll describe +these in order, using examples: + +- :ref:`Boolean ` + - :ref:`west-manifest-ex1.1` + - :ref:`west-manifest-ex1.2` + - :ref:`west-manifest-ex1.3` +- :ref:`Relative path ` + - :ref:`west-manifest-ex2.1` + - :ref:`west-manifest-ex2.2` + - :ref:`west-manifest-ex2.3` +- :ref:`Mapping with additional configuration ` + - :ref:`west-manifest-ex3.1` + - :ref:`west-manifest-ex3.2` + - :ref:`west-manifest-ex3.3` +- :ref:`Sequence of paths and mappings ` + - :ref:`west-manifest-ex4.1` + - :ref:`west-manifest-ex4.2` + +A more :ref:`formal description ` of how this works is +last, after the examples. + +Troubleshooting Note +==================== + +If you're using this feature and find west's behavior confusing, try +:ref:`resolving your manifest ` to see the final results +after imports are done. + +.. _west-manifest-import-bool: + +Option 1: Boolean +================= + +This is the easiest way to use ``import``. + +If ``import`` is ``true`` as a ``projects`` attribute, west imports projects +from the :file:`west.yml` file in that project's root directory. If it's +``false`` or missing, it has no effect. For example, this manifest would import +:file:`west.yml` from the ``p1`` git repository at revision ``v1.0``: + +.. code-block:: yaml + + manifest: + # ... + projects: + - name: p1 + revision: v1.0 + import: true # Import west.yml from p1's v1.0 git tag + - name: p2 + import: false # Nothing is imported from p2. + - name: p3 # Nothing is imported from p3 either. + +It's an error to set ``import`` to either ``true`` or ``false`` inside +``self``, like this: + +.. code-block:: yaml + + manifest: + # ... + self: + import: true # Error + +.. _west-manifest-ex1.1: + +Example 1.1: Downstream of a Zephyr release +------------------------------------------- + +You have a source code repository you want to use with Zephyr v1.14.1 LTS. You +want to maintain the whole thing using west. You don't want to modify any of +the mainline repositories. + +In other words, the west installation you want looks like this: + +.. code-block:: none + + my-downstream + ├── .west # west directory + ├── zephyr # mainline zephyr repository + ├── modules # modules from mainline zephyr + │   ├── hal + │   └── [...other directories..] + ├── [ ... other projects ...] # other mainline repositories + └── my-repo # your downstream repository + ├── west.yml + └── [...other files..] + +You can do this with the following :file:`my-repo/west.yml`: + +.. code-block:: yaml + + # my-repo/west.yml: + manifest: + remotes: + - name: zephyrproject-rtos + url-base: https://github.com/zephyrproject-rtos + projects: + - name: zephyr + remote: zephyrproject-rtos + revision: v1.14.1 + import: true + +You can then create the installation on your computer like this, assuming +``my-repo`` is hosted at ``https://git.example.com/my-repo``: + +.. code-block:: console + + west init -m https://git.example.com/my-repo my-downstream + cd my-downstream + west update + +After ``west init``, :file:`my-downstream/my-repo` will be cloned. + +After ``west update``, all of the projects defined in the ``zephyr`` +repository's :file:`west.yml` at revision ``v1.14.1`` will be cloned into +:file:`my-downstream` as well. + +You can add and commit any code to :file:`my-repo` you please at this point, +including your own Zephyr applications, drivers, etc. See :ref:`application`. + +.. _west-manifest-ex1.2: + +Example 1.2: "Rolling release" Zephyr downstream +------------------------------------------------ + +This is similar to :ref:`west-manifest-ex1.1`, except we'll use ``revision: +master`` for the zephyr repository: + +.. code-block:: yaml + + # my-repo/west.yml: + manifest: + remotes: + - name: zephyrproject-rtos + url-base: https://github.com/zephyrproject-rtos + projects: + - name: zephyr + remote: zephyrproject-rtos + revision: master + import: true + +You can create the installation in the same way: + +.. code-block:: console + + west init -m https://git.example.com/my-repo my-downstream + cd my-downstream + west update + +This time, whenever you run ``west update``, the special :ref:`manifest-rev +` branch in the ``zephyr`` repository will be updated to +point at a newly fetched ``master`` branch tip from the URL +https://github.com/zephyrproject-rtos/zephyr. + +The contents of :file:`zephyr/west.yml` at the new ``manifest-rev`` will then +be used to import projects from Zephyr. This lets you stay up to date with the +latest changes in the Zephyr project. The cost is that running ``west update`` +will not produce reproducible results, since the remote ``master`` branch can +change every time you run it. + +It's also important to understand that west **ignores your working tree's** +:file:`zephyr/west.yml` entirely when resolving imports. West always uses the +contents of imported manifests as they were committed to the latest +``manifest-rev`` when importing from a project. + +You can only import manifest from the file system if they are in your manifest +repository's working tree. See :ref:`west-manifest-ex2.2` for an example. + +.. _west-manifest-ex1.3: + +Example 1.3: Downstream of a Zephyr release, with module fork +------------------------------------------------------------- + +This manifest is similar to the one in :ref:`west-manifest-ex1.1`, except it: + +- is a downstream of Zephyr 2.0 +- includes a downstream fork of the :file:`modules/hal/nordic` + :ref:`module ` which was included in that release + +.. code-block:: yaml + + # my-repo/west.yml: + manifest: + remotes: + - name: zephyrproject-rtos + url-base: https://github.com/zephyrproject-rtos + - name: my-remote + url-base: https://git.example.com + projects: + - name: hal_nordic + remote: my-remote + revision: my-sha + path: modules/hal/nordic + - name: zephyr + remote: zephyrproject-rtos + revision: v2.0.0 + import: true + + # subset of zephyr/west.yml contents at v2.0.0: + manifest: + defaults: + remote: zephyrproject-rtos + remotes: + - name: zephyrproject-rtos + url-base: https://github.com/zephyrproject-rtos + projects: + # ... + - name: hal_nordic + path: modules/hal/nordic + revision: another-sha + +With this manifest file, the project named ``hal_nordic``: + +- is cloned from ``https://git.example.com/hal_nordic`` instead of + ``https://github.com/zephyrproject-rtos/hal_nordic``. +- is updated to commit ``my-sha`` by ``west update``, instead of + the mainline commit ``another-sha`` + +In other words, when your top-level manifest defines a project, like +``hal_nordic``, west will ignore any other definition it finds later on while +resolving imports. + +This does mean you have to copy the ``path: modules/hal/nordic`` value into +:file:`my-repo/west.yml` when defining ``hal_nordic`` there. The value from +:file:`zephyr/west.yml` is ignored entirely. See :ref:`west-manifest-resolve` +for troubleshooting advice if this gets confusing in practice. + +When you run ``west update``, west will: + +- update zephyr's ``manifest-rev`` to point at the ``v2.0.0`` tag +- import :file:`zephyr/west.yml` at that ``manifest-rev`` +- locally check out the ``v2.0.0`` revisions for all zephyr projects except + ``hal_nordic`` +- update ``hal_nordic`` to ``my-sha`` instead of ``another-sha`` + +.. _west-manifest-import-path: + +Option 2: Relative path +======================= + +The ``import`` value can also be a relative path to a manifest file or a +directory containing manifest files. The path is relative to the root directory +of the ``projects`` or ``self`` repository the ``import`` key appears in. + +Here is an example: + +.. code-block:: yaml + + manifest: + projects: + - name: project-1 + revision: v1.0 + import: west.yml + - name: project-2 + revision: master + import: p2-manifests + self: + import: submanifests + +This will import the following: + +- the contents of :file:`project-1/west.yml` at ``manifest-rev``, which points + at tag ``v1.0`` after running ``west update`` +- any YAML files in the directory tree :file:`project-2/p2-manifests` + at the latest ``master``, as fetched by ``west update``, sorted by file name +- YAML files in :file:`submanifests` in your manifest repository, + as they appear on your file system, sorted by file name + +Notice how ``projects`` imports get data from Git using ``manifest-rev``, while +``self`` imports get data from your file system. This is because as usual, west +leaves version control for your manifest repository up to you. + +.. _west-manifest-ex2.1: + +Example 2.1: Downstream of a Zephyr release with explicit path +-------------------------------------------------------------- + +This is an explicit way to write an equivalent manifest to the one in +:ref:`west-manifest-ex1.1`. + +.. code-block:: yaml + + manifest: + remotes: + - name: zephyrproject-rtos + url-base: https://github.com/zephyrproject-rtos + projects: + - name: zephyr + remote: zephyrproject-rtos + revision: v1.14.1 + import: west.yml + +The setting ``import: west.yml`` means to use the file :file:`west.yml` inside +the ``zephyr`` project. This example is contrived, but shows the idea. + +This can be useful in practice when the name of the manifest file you want to +import is not :file:`west.yml`. + +.. _west-manifest-ex2.2: + +Example 2.2: Downstream with directory of manifest files +-------------------------------------------------------- + +Your Zephyr downstream has a lot of additional repositories. So many, in fact, +that you want to split them up into multiple manifest files, but keep track of +them all in a single manifest repository, like this: + +.. code-block:: none + + my-repo/ + ├── submanifests + │ ├── 01-libraries.yml + │ ├── 02-vendor-hals.yml + │ └── 03-applications.yml + └── west.yml + +You want to add all the files in :file:`my-repo/submanifests` to the main +manifest file, :file:`my-repo/west.yml`, in addition to projects in +:file:`zephyr/west.yml`. You want to track the latest mainline master +instead of using a fixed revision. + +Here's how: + +.. code-block:: yaml + + # my-repo/west.yml: + manifest: + remotes: + - name: zephyrproject-rtos + url-base: https://github.com/zephyrproject-rtos + projects: + - name: zephyr + remote: zephyrproject-rtos + import: true + self: + import: submanifests + +Manifest files are imported in this order during resolution: + +#. :file:`my-repo/submanifests/01-libraries.yml` +#. :file:`my-repo/submanifests/02-vendor-hals.yml` +#. :file:`my-repo/submanifests/03-applications.yml` +#. :file:`my-repo/west.yml` +#. :file:`zephyr/west.yml` + +.. note:: + + The :file:`.yml` file names are prefixed with numbers in this example to + make sure they are imported in the specified order. + + You can pick arbitrary names. West sorts files in a directory by name before + importing. + +Notice how the manifests in :file:`submanifests` are imported *before* +:file:`my-repo/west.yml` and :file:`zephyr/west.yml`. In general, an ``import`` +in the ``self`` section is processed before the manifest files in ``projects`` +and the main manifest file. + +This means projects defined in :file:`my-repo/submanifests` take highest +precedence. For example, if :file:`01-libraries.yml` defines ``hal_nordic``, +the project by the same name in :file:`zephyr/west.yml` is simply ignored. As +usual, see :ref:`west-manifest-resolve` for troubleshooting advice. + +This may seem strange, but it allows you to redefine projects "after the fact", +as we'll see in the next example. + +.. _west-manifest-ex2.3: + +Example 2.3: Continuous Integration overrides +--------------------------------------------- + +Your continuous integration system needs to fetch and test multiple +repositories in your west installation from a developer's forks instead of your +mainline development trees, to see if the changes all work well together. + +Starting with :ref:`west-manifest-ex2.2`, the CI scripts add a +file :file:`00-ci.yml` in :file:`my-repo/submanifests`, with these contents: + +.. code-block:: yaml + + # my-repo/submanifests/00-ci.yml: + manifest: + projects: + - name: a-vendor-hal + url: https://github.com/a-developer/hal + revision: a-pull-request-branch + - name: an-application + url: https://github.com/a-developer/application + revision: another-pull-request-branch + +The CI scripts run ``west update`` after generating this file in +:file:`my-repo/submanifests`. The projects defined in :file:`00-ci.yml` have +higher precedence than other definitions in :file:`my-repo/submanifests`, +because the name :file:`00-ci.yml` comes before the other file names. + +Thus, ``west update`` always checks out the developer's branches in the +projects named ``a-vendor-hal`` and ``an-application``, even if those same +projects are also defined elsewhere. + +.. _west-manifest-import-map: + +Option 3: Mapping +================= + +The ``import`` key can also contain a mapping with the following keys: + +- ``file``: Optional. The name of the manifest file or directory to import. + This defaults to :file:`west.yml` if not present. +- ``name-whitelist``: Optional. If present, a name or sequence of project names + to include. +- ``path-whitelist``: Optional. If present, a path or sequence of project paths + to match against. This is a shell-style globbing pattern, currently + implemented with `pathlib`_. Note that this means case sensitivity is + platform specific. +- ``name-blacklist``: Optional. Like ``name-whitelist``, but contains project + names to exclude rather than include. +- ``path-blacklist``: Optional. Like ``path-whitelist``, but contains project + paths to exclude rather than include. + +.. _re: https://docs.python.org/3/library/re.html +.. _pathlib: + https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.match + +Whitelists override blacklists if both are given. For example, if a project is +blacklisted by path, then whitelisted by name, it will still be imported. + +.. _west-manifest-ex3.1: + +Example 3.1: Downstream with name whitelist +------------------------------------------- + +Here is a pair of manifest files, representing a mainline and a +downstream. The downstream doesn't want to use all the mainline +projects, however. We'll assume the mainline :file:`west.yml` is +hosted at ``https://git.example.com/mainline/manifest``. + +.. code-block:: yaml + + # mainline west.yml: + manifest: + projects: + - name: mainline-app + path: examples/app + url: https://git.example.com/mainline/app + - name: lib + path: libraries/lib + url: https://git.example.com/mainline/lib + - name: lib2 + path: libraries/lib2 + url: https://git.example.com/mainline/lib2 + + # downstream west.yml: + manifest: + projects: + - name: mainline + url: https://git.example.com/mainline/manifest + import: + name-whitelist: + - mainline-app + - lib2 + - name: downstream-app + url: https://git.example.com/downstream/app + - name: lib3 + path: libraries/lib3 + url: https://git.example.com/downstream/lib3 + +An equivalent manifest in a single file would be: + +.. code-block:: yaml + + manifest: + projects: + - name: mainline + url: https://git.example.com/mainline/manifest + - name: downstream-app + url: https://git.example.com/downstream/app + - name: lib3 + path: libraries/lib3 + url: https://git.example.com/downstream/lib3 + - name: mainline-app + path: examples/app + url: https://git.example.com/mainline/app + - name: lib2 + path: libraries/lib2 + url: https://git.example.com/mainline/lib2 + +If a whitelist had not been used, the ``lib`` project from the mainline +manifest would have been imported. + +.. _west-manifest-ex3.2: + +Example 3.2: Downstream with path whitelist +------------------------------------------- + +Here is an example showing how to whitelist mainline's libraries only, +using ``path-whitelist``. + +.. code-block:: yaml + + # mainline west.yml: + manifest: + projects: + - name: app + path: examples/app + url: https://git.example.com/mainline/app + - name: lib + path: libraries/lib + url: https://git.example.com/mainline/lib + - name: lib2 + path: libraries/lib2 + url: https://git.example.com/mainline/lib2 + + # downstream west.yml: + manifest: + projects: + - name: mainline + url: https://git.example.com/mainline/manifest + import: + path-whitelist: libraries/* + - name: app + url: https://git.example.com/downstream/app + - name: lib3 + path: libraries/lib3 + url: https://git.example.com/downstream/lib3 + +An equivalent manifest in a single file would be: + +.. code-block:: yaml + + manifest: + projects: + - name: lib + path: libraries/lib + url: https://git.example.com/mainline/lib + - name: lib2 + path: libraries/lib2 + url: https://git.example.com/mainline/lib2 + - name: mainline + url: https://git.example.com/mainline/manifest + - name: app + url: https://git.example.com/downstream/app + - name: lib3 + path: libraries/lib3 + url: https://git.example.com/downstream/lib3 + +.. _west-manifest-ex3.3: + +Example 3.3: Downstream with path blacklist +------------------------------------------- + +Here's an example showing how to blacklist all vendor HALs from mainline by +common path prefix in the installation, add your own version for the chip +you're targeting, and keep everything else. + +.. code-block:: yaml + + # mainline west.yml: + manifest: + defaults: + remote: mainline + remotes: + - name: mainline + url-base: https://git.example.com/mainline + projects: + - name: app + - name: lib + path: libraries/lib + - name: lib2 + path: libraries/lib2 + - name: hal_foo + path: modules/hals/foo + - name: hal_bar + path: modules/hals/bar + - name: hal_baz + path: modules/hals/baz + + # downstream west.yml: + manifest: + projects: + - name: mainline + url: https://git.example.com/mainline/manifest + import: + path-blacklist: modules/hals/* + - name: hal_foo + path: modules/hals/foo + url: https://git.example.com/downstream/hal_foo + +An equivalent manifest in a single file would be: + +.. code-block:: yaml + + manifest: + defaults: + remote: mainline + remotes: + - name: mainline + url-base: https://git.example.com/mainline + projects: + - name: app + - name: lib + path: libraries/lib + - name: lib2 + path: libraries/lib2 + - name: mainline + repo-path: https://git.example.com/mainline/manifest + - name: hal_foo + path: modules/hals/foo + url: https://git.example.com/downstream/hal_foo + +.. _west-manifest-import-seq: + +Option 4: Sequence +================== + +The ``import`` key can also contain a sequence of files, directories, +and mappings. + +.. _west-manifest-ex4.1: + +Example 4.1: Downstream with sequence of manifest files +------------------------------------------------------- + +This example manifest is equivalent to the manifest in +:ref:`west-manifest-ex2.2`, with a sequence of explicitly named files. + +.. code-block:: yaml + + # my-repo/west.yml: + manifest: + projects: + - name: zephyr + url: https://github.com/zephyrproject-rtos/zephyr + import: west.yml + self: + import: + - submanifests/01-libraries.yml + - submanifests/02-vendor-hals.yml + - submanifests/03-applications.yml + +.. _west-manifest-ex4.2: + +Example 4.2: Import order illustration +-------------------------------------- + +This more complicated example shows the order that west imports manifest files: + +.. code-block:: yaml + + # my-repo/west.yml + manifest: + # ... + projects: + - name: my-library + - name: my-app + - name: zephyr + import: true + - name: another-manifest-repo + import: submanifests + self: + import: + - submanifests/libraries.yml + - submanifests/vendor-hals.yml + - submanifests/applications.yml + defaults: + remote: my-remote + +For this example, west resolves imports in this order: + +#. the listed files in :file:`my-repo/submanifests` are first, in the order + they occur (e.g. :file:`libraries.yml` comes before + :file:`applications.yml`, since this is a sequence of files), since the + ``self: import:`` is always imported first +#. :file:`my-repo/west.yml` is next (with projects ``my-library`` etc. as long + as they weren't already defined somewhere in :file:`submanifests`) +#. :file:`zephyr/west.yml` is after that, since that's the first ``import`` key + in the ``projects`` list in :file:`my-repo/west.yml` +#. files in :file:`another-manifest-repo/submanifests` are last (sorted by file + name), since that's the final project ``import`` + +.. _west-manifest-formal: + +Manifest Import Details +======================= + +This section describes how west imports a manifest file a bit more formally. + +Overview +-------- + +A west manifest's ``projects`` and ``self`` sections can have ``import`` keys, +like so: + +.. code-block:: yaml + + # Top-level west.yml. + 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 + +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. + +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: + +#. Manifests from ``self-import`` are imported first. +#. The top-level manifest file's ``projects`` are added in next. +#. Manifests from ``import-1``, ..., ``import-N``, are imported in that order. + +This process recurses if necessary. + +Projects are identified by name. If the same name occurs in multiple manifests, +the first definition is used, and subsequent definitions are ignored. For +example, if ``import-1`` contains a project named ``bar``, that is ignored, +because the top-level :file:`west.yml` has already defined a project by that +name. + +The contents of files named by ``import-1`` through ``import-N`` are imported +from Git at the latest ``manifest-rev`` revisions in their projects. These +revisions can be updated to the values ``rev-1`` through ``rev-N`` by running +``west update``. If any ``manifest-rev`` reference is missing or out of date, +``west update`` also fetches project data from the remote fetch URL and updates +the reference. + +Also note that all imported manifests, from the root manifest to the repository +which defines a project ``P``, must be up to date in order for west to update +``P`` itself. For example, this means ``west update P`` would update +``manifest-rev`` in the ``baz`` project if :file:`baz/west.yml` defines ``P``, +as well as updating the ``manifest-rev`` branch in the local git clone of +``P``. Confusingly, the update of ``baz`` may result in the removal of ``P`` +from :file:`baz/west.yml`, which would cause ``west update P`` to fail with an +unrecognized project! + +For this reason, it's usually best to run plain ``west update`` to avoid errors +if you use manifest imports. By default, west won't fetch any project data over +the network if a project's revision is a SHA or tag which is already available +locally, so updating the 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. + +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 @@ -283,6 +1099,29 @@ It takes an action, and action-specific arguments. The following sections describe each action and provides a basic signature for simple uses. Run ``west manifest --help`` for full details on all options. +.. _west-manifest-resolve: + +Resolving Manifests +=================== + +The ``--resolve`` action outputs a single manifest file equivalent to your +current manifest and all its :ref:`imported manifests `: + +.. code-block:: none + + west manifest --resolve [-o outfile] + +The main use for this action is to see the "final" manifest contents after +performing any ``import``\ s. + +To print detailed information about each imported manifest file and how +projects are handled during manifest resolution, set the maximum verbosity +level using ``-v``: + +.. code-block:: console + + west -v manifest --resolve + Freezing Manifests ==================