Lines Matching +full:repo +full:- +full:path
1 .. _west-manifests:
8 ``west.manifest`` module, see :ref:`west-apis-manifest`. For a more general
9 introduction and command overview, see :ref:`west-basics`.
16 .. _west-mr-model:
25 .. figure:: west-mr-model.png
27 :alt: West multi-repo history
28 :figclass: align-center
30 West multi-repo history
48 - Projects can be added (like ``P1`` between manifest repository
52 - Project and manifest repository histories don't have to move
55 - ``P2`` stays the same from ``A → B``, as do ``P1`` and ``P3`` from ``F →
57 - ``P3`` moves forward from ``A → B``.
58 - ``P3`` moves backward from ``C → D``.
63 - Project repository commits can be "skipped": ``P3`` moves forward
66 - In the above diagram, no project repository has two revisions "at
72 .. _west-manifest-files:
77 West manifests are YAML files. Manifests have a top-level ``manifest`` section
80 .. code-block:: yaml
92 version: "<schema-version>"
93 group-filter:
117 by appending a project-specific path onto a remote URL base. (As we'll see
122 .. code-block:: yaml
127 - name: remote1
128 url-base: https://git.example.com/base1
129 - name: remote2
130 url-base: https://git.example.com/base2
134 .. list-table:: remotes keys
135 :header-rows: 1
138 * - Key
139 - Description
141 * - ``name``
142 - Mandatory; a unique name for the remote.
144 * - ``url-base``
145 - A prefix that is prepended to the fetch URL for each
154 .. _west-manifests-projects:
164 <modules-vs-projects>`.
171 .. code-block:: yaml
176 - name: proj1
179 path: extra/project-1
180 - name: proj2
182 A multi-line description of the second example
184 repo-path: my-path
187 - name: proj3
188 url: https://github.com/user/project-three
193 - ``proj1`` has remote ``remote1``, so its Git fetch URL is
194 ``https://git.example.com/base1/proj1``. The remote ``url-base`` is appended
197 Locally, this project will be cloned at path ``extra/project-1`` relative to
198 the west workspace's root directory, since it has an explicit ``path``
205 - ``proj2`` has a ``remote`` and a ``repo-path``, so its fetch URL is
206 ``https://git.example.com/base2/my-path``. The ``repo-path`` attribute, if
209 Since the project has no ``path`` attribute, its ``name`` is used by
214 - ``proj3`` has an explicit ``url``, so it will be fetched from
215 ``https://github.com/user/project-three``.
217 Its local path defaults to its name, ``proj3``. Commit ``abcde413a111`` will
224 .. list-table:: projects elements keys
225 :header-rows: 1
228 * - Key(s)
229 - Description
231 * - ``name``
232 - Mandatory; a unique name for the project. The name cannot be one of the
236 * - ``description``
237 - Optional, an informational description of the project. Added in
240 * - ``remote``, ``url``
241 - Mandatory (one of the two, but not both).
243 If the project has a ``remote``, that remote's ``url-base`` will be
244 combined with the project's ``name`` (or ``repo-path``, if it has one)
254 * - ``repo-path``
255 - Optional. If given, this is concatenated on to the remote's
256 ``url-base`` instead of the project's ``name`` to form its fetch URL.
257 Projects may not have both ``url`` and ``repo-path`` attributes.
259 * - ``revision``
260 - Optional. The Git revision that ``west update`` should
273 * - ``path``
274 - Optional. Relative path specifying where to clone the repository
278 * - ``clone-depth``
279 - Optional. If given, a positive integer which creates a shallow history
283 * - ``west-commands``
284 - Optional. If given, a relative path to a YAML file within the project
286 file is named :file:`west-commands.yml` by convention. See
287 :ref:`west-extensions` for details.
289 * - ``import``
290 - Optional. If ``true``, imports projects from manifest files in the
292 :ref:`west-manifest-import` for details.
294 * - ``groups``
295 - Optional, a list of groups the project belongs to. See
296 :ref:`west-manifest-groups` for details.
298 * - ``submodules``
299 - Optional. You can use this to make ``west update`` also update `Git
301 :ref:`west-manifest-submodules` for details.
303 * - ``userdata``
304 - Optional. The value is an arbitrary YAML value. See
305 :ref:`west-project-userdata`.
317 .. _Git submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules
327 .. code-block:: yaml
335 - name: remote1
336 url-base: https://git.example.com/base1
337 - name: remote2
338 url-base: https://git.example.com/base2
341 - name: proj1
343 path: extra/project-1
345 - name: proj2
347 A multi-line description of the second example
349 repo-path: my-path
351 - name: proj3
352 url: https://github.com/user/project-three
357 .. list-table:: defaults keys
358 :header-rows: 1
361 * - Key
362 - Description
364 * - ``remote``
365 - Optional. This will be used for a project's ``remote`` if it does not
368 * - ``revision``
369 - Optional. This will be used for a project's ``revision`` if it does
380 .. code-block:: yaml
385 path: zephyr
386 west-commands: scripts/west-commands.yml
388 This ensures that the zephyr repository is cloned into path ``zephyr``, though
390 manifest URL, ``https://github.com/zephyrproject-rtos/zephyr``. Since the
392 the location of the corresponding :file:`west-commands.yml` relative to the
397 .. list-table:: self keys
398 :header-rows: 1
401 * - Key
402 - Description
404 * - ``path``
405 - Optional. The path ``west init`` should clone the manifest repository
408 If not given, the basename of the path component in the manifest
410 ``https://git.example.com/project-repo``, the manifest repository would
411 be cloned to the directory :file:`project-repo`.
413 * - ``west-commands``
414 - Optional. This is analogous to the same key in a project sequence
417 * - ``import``
418 - Optional. This is also analogous to the ``projects`` key, but allows
420 :ref:`west-manifest-import`.
422 .. _west-manifest-schema-version:
434 .. code-block:: yaml
445 The pykwalify schema :file:`manifest-schema.yml` in the `west source code
449 https://github.com/zephyrproject-rtos/west
454 .. list-table::
455 :header-rows: 1
458 * - ``version``
459 - New features
461 * - ``"0.7"``
462 - Initial support for the ``version`` feature. All manifest file features
466 * - ``"0.8"``
467 - Support for ``import: path-prefix:`` (:ref:`west-manifest-import-map`)
469 * - ``"0.9"``
470 - **Use of west v0.9.x is discouraged**.
478 * - ``"0.10"``
480 - Support for:
482 - ``submodules:`` in ``projects:`` (:ref:`west-manifest-submodules`)
483 - ``manifest: group-filter:``, and ``groups:`` in ``projects:``
484 (:ref:`west-manifest-groups`)
485 - The ``import:`` feature now supports ``allowlist:`` and
487 older names as part of a general Zephyr-wide inclusive language
489 compatibility. (:ref:`west-manifest-import`,
490 :ref:`west-manifest-import-map`)
492 * - ``"0.12"``
493 - Support for ``userdata:`` in ``projects:`` (:ref:`west-project-userdata`)
495 * - ``"0.13"``
496 - Support for ``self: userdata:`` (:ref:`west-project-userdata`)
498 * - ``"1.0"``
499 - Identical to ``"0.13"``, but available for use by users that
502 * - ``"1.2"``
503 - Support for ``description:`` in ``projects:``
504 (:ref:`west-manifests-projects`)
523 Group-filter
526 See :ref:`west-manifest-groups`.
528 .. _west-active-inactive-projects:
537 :ref:`west-manifest-import` in an inactive project will be ignored by west.
541 1. Using the ``manifest.project-filter`` configuration option. If a project is
544 expression in ``manifest.project-filter`` applies to a project, the
547 See the entry for this option in :ref:`west-config-index` for details.
554 .. _west-manifest-groups:
559 You can use the ``groups`` and ``group-filter`` keys briefly described
560 :ref:`above <west-manifest-files>` to place projects into groups, and to
564 in the group by using ``west forall --group``. This can also let you make
569 :ref:`west-enabled-disabled-groups`. There are some basic examples in
570 :ref:`west-project-group-examples`. Finally, :ref:`west-group-filter-imports`
571 provides a simplified overview of how ``group-filter`` interacts with the
572 :ref:`west-manifest-import` feature.
577 The ``groups:`` and ``group-filter:`` keys appear in the manifest like this:
579 .. code-block:: yaml
583 - name: some-project
585 group-filter: ...
589 You can enable or disable project groups using ``group-filter``. Projects whose
591 ``manifest.project-filter`` configuration option, are inactive.
595 .. code-block:: yaml
599 - name: project-1
601 - groupA
602 - name: project-2
604 - groupB
605 - groupC
606 - name: project-3
610 - ``project-1``: one group, named ``groupA``
611 - ``project-2``: two groups, named ``groupB`` and ``groupC``
612 - ``project-3``: no groups
616 Group names must not begin with a dash (-) or the plus sign (+), but they may
617 contain these characters elsewhere in their names. For example, ``foo-bar`` and
618 ``foo+bar`` are valid groups, but ``-foobar`` and ``+foobar`` are not.
625 .. _west-enabled-disabled-groups:
631 both your manifest file and :ref:`west-config`.
633 Within a manifest file, ``manifest: group-filter:`` is a YAML list of groups to
639 .. code-block:: yaml
642 group-filter: [+groupA]
646 :ref:`west-group-filter-imports` for more information.
648 To disable a group, prefix its name with a dash (-). For example, ``groupA``
651 .. code-block:: yaml
654 group-filter: [-groupA,-groupB]
658 Since ``group-filter`` is a YAML list, you could have written this fragment
661 .. code-block:: yaml
664 group-filter:
665 - -groupA
666 - -groupB
671 disabled using the ``manifest.group-filter`` configuration option. This option
672 is a comma-separated list of groups to enable and/or disable.
675 group, add its name prefixed with ``-``. For example, setting
676 ``manifest.group-filter`` to ``+groupA,-groupB`` enables ``groupA``, and
680 You can think of this as if the ``manifest.group-filter`` configuration option
681 is appended to the ``manifest: group-filter:`` list from YAML, with "last entry
684 .. _west-project-group-examples:
690 projects. The examples use both ``manifest: group-filter:`` YAML lists and
691 ``manifest.group-filter`` configuration lists, to show how they work together.
694 isn't relevant except to make the examples complete and self-contained.
698 In all of the examples that follow, the ``manifest.project-filter`` option
702 -----------------------------
706 .. code-block:: yaml
710 - name: foo
712 - groupA
713 - name: bar
715 - groupA
716 - groupB
717 - name: baz
720 remote: example-remote
722 - name: example-remote
723 url-base: https://git.example.com
725 The ``manifest.group-filter`` configuration option is not set (you can ensure
726 this by running ``west config -D manifest.group-filter``).
733 -------------------------------------------
737 .. code-block:: yaml
741 - name: foo
743 - groupA
744 - name: bar
746 - groupA
747 - groupB
749 group-filter: [-groupA]
752 remote: example-remote
754 - name: example-remote
755 url-base: https://git.example.com
757 The ``manifest.group-filter`` configuration option is not set (you can ensure
758 this by running ``west config -D manifest.group-filter``).
764 -------------------------------------------------
768 .. code-block:: yaml
772 - name: foo
774 - groupA
775 - name: bar
777 - groupA
778 - groupB
780 group-filter: [-groupA,-groupB]
783 remote: example-remote
785 - name: example-remote
786 url-base: https://git.example.com
788 The ``manifest.group-filter`` configuration option is not set (you can ensure
789 this by running ``west config -D manifest.group-filter``).
795 ----------------------------------------------
799 .. code-block:: yaml
803 - name: foo
805 - groupA
806 - name: bar
808 - groupA
809 - groupB
812 remote: example-remote
814 - name: example-remote
815 url-base: https://git.example.com
817 The ``manifest.group-filter`` configuration option is set to ``-groupA`` (you
818 can ensure this by running ``west config manifest.group-filter -- -groupA``;
819 the extra ``--`` is required so the argument parser does not treat ``-groupA``
820 as a command line option ``-g`` with value ``roupA``).
823 ``manifest.group-filter`` configuration option. Project ``bar`` is active
827 --------------------------------------------------------
831 .. code-block:: yaml
835 - name: foo
836 - name: bar
838 - groupA
839 - name: baz
841 - groupA
842 - groupB
844 group-filter: [-groupA]
847 remote: example-remote
849 - name: example-remote
850 url-base: https://git.example.com
852 The ``manifest.group-filter`` configuration option is set to ``+groupA`` (you
853 can ensure this by running ``west config manifest.group-filter +groupA``).
855 In this case, ``groupA`` is enabled: the ``manifest.group-filter``
856 configuration option has higher precedence than the ``manifest: group-filter:
857 [-groupA]`` content in the manifest file.
862 ----------------------------------------------------------------
866 .. code-block:: yaml
870 - name: foo
871 - name: bar
873 - groupA
874 - name: baz
876 - groupA
877 - groupB
879 group-filter: [-groupA,-groupB]
882 remote: example-remote
884 - name: example-remote
885 url-base: https://git.example.com
887 The ``manifest.group-filter`` configuration option is set to
889 manifest.group-filter "+groupA,+groupB"``).
897 ------------------------------------------------------
901 .. code-block:: yaml
905 - name: foo
906 - name: bar
908 - groupA
909 - name: baz
911 - groupA
912 - groupB
915 remote: example-remote
917 - name: example-remote
918 url-base: https://git.example.com
920 The ``manifest.group-filter`` configuration option is set to
921 ``-groupA,-groupB`` (you can ensure this by running ``west config
922 manifest.group-filter -- "-groupA,-groupB"``).
928 .. _west-group-filter-imports:
934 group-filter:`` value behaves when combined with :ref:`west-manifest-import`.
935 For complete details, see :ref:`west-manifest-formal`.
940 are different, and combining ``group-filter`` with ``import`` in west v0.9.x
945 - if you only import one manifest, any groups it disables in its
946 ``group-filter`` are also disabled in your manifest
947 - you can override this in your manifest file's ``manifest: group-filter:``
948 value, your workspace's ``manifest.group-filter`` configuration option, or
954 -----------------------
958 .. code-block:: yaml
963 - name: child
966 - name: project-1
967 url: https://git.example.com/project-1
969 - unstable
973 .. code-block:: yaml
977 group-filter: [-unstable]
979 - name: project-2
980 url: https://git.example.com/project-2
981 - name: project-3
982 url: https://git.example.com/project-3
984 - unstable
986 Only ``child`` and ``project-2`` are active in the resolved manifest.
989 overridden in :file:`parent/west.yml`. Therefore, the final ``group-filter``
990 for the resolved manifest is ``[-unstable]``.
992 Since ``project-1`` and ``project-3`` are in the ``unstable`` group and are not
995 Example 2: overriding an imported ``group-filter`` via manifest
996 ---------------------------------------------------------------
1000 .. code-block:: yaml
1004 group-filter: [+unstable,-optional]
1006 - name: child
1009 - name: project-1
1010 url: https://git.example.com/project-1
1012 - unstable
1016 .. code-block:: yaml
1020 group-filter: [-unstable]
1022 - name: project-2
1023 url: https://git.example.com/project-2
1025 - optional
1026 - name: project-3
1027 url: https://git.example.com/project-3
1029 - unstable
1031 Only the ``child``, ``project-1``, and ``project-3`` projects are active.
1033 The ``[-unstable]`` group filter in :file:`child/west.yml` is overridden in
1035 ``project-1`` and ``project-3`` are in the ``unstable`` group, they are active.
1038 ``project-2`` is inactive.
1041 ``[+unstable,-optional]``.
1043 Example 3: overriding an imported ``group-filter`` via configuration
1044 --------------------------------------------------------------------
1048 .. code-block:: yaml
1053 - name: child
1056 - name: project-1
1057 url: https://git.example.com/project-1
1059 - unstable
1063 .. code-block:: yaml
1067 group-filter: [-unstable]
1069 - name: project-2
1070 url: https://git.example.com/project-2
1072 - optional
1073 - name: project-3
1074 url: https://git.example.com/project-3
1076 - unstable
1080 .. code-block:: shell
1082 west config manifest.group-filter +unstable,-optional
1084 Then only the ``child``, ``project-1``, and ``project-3`` projects are active.
1086 The ``-unstable`` group filter in :file:`child/west.yml` is overridden in the
1087 ``manifest.group-filter`` configuration option, so the ``unstable`` group is
1088 enabled. Since ``project-1`` and ``project-3`` are in the ``unstable`` group,
1091 The same configuration option disables the ``optional`` group, so ``project-2``
1095 ``manifest.group-filter`` configuration option is ``[+unstable,-optional]``.
1097 .. _west-manifest-submodules:
1103 <west-manifest-files>` to force ``west update`` to also handle any `Git
1107 .. code-block:: YAML
1111 - name: some-project
1132 .. code-block:: yaml
1136 - name: foo
1138 - name: bar
1152 The ``path`` key must match exactly the path of one submodule relative
1164 .. code-block:: yaml
1168 - name: foo
1170 - path: path/to/foo-first-sub
1171 - name: foo-second-sub
1172 path: path/to/foo-second-sub
1173 - name: bar
1176 submodules in ``foo`` with paths ``path/to/foo-first-sub`` and
1177 ``path/to/foo-second-sub``. Any submodules in ``bar`` are still ignored.
1179 .. _west-project-userdata:
1189 It is meant for consumption by programs that require user-specific project
1193 accessible to programs using :ref:`west-apis` as the ``userdata`` attribute of
1198 .. code-block:: yaml
1202 - name: foo
1203 - name: bar
1204 userdata: a-string
1205 - name: baz
1213 .. code-block:: python
1220 bar.userdata # 'a-string'
1224 .. _west-manifest-import:
1233 .. code-block:: yaml
1237 - name: some-project
1257 The ``import`` key can be a boolean, path, mapping, or sequence. We'll describe
1260 - :ref:`Boolean <west-manifest-import-bool>`
1261 - :ref:`west-manifest-ex1.1`
1262 - :ref:`west-manifest-ex1.2`
1263 - :ref:`west-manifest-ex1.3`
1264 - :ref:`Relative path <west-manifest-import-path>`
1265 - :ref:`west-manifest-ex2.1`
1266 - :ref:`west-manifest-ex2.2`
1267 - :ref:`west-manifest-ex2.3`
1268 - :ref:`Mapping with additional configuration <west-manifest-import-map>`
1269 - :ref:`west-manifest-ex3.1`
1270 - :ref:`west-manifest-ex3.2`
1271 - :ref:`west-manifest-ex3.3`
1272 - :ref:`west-manifest-ex3.4`
1273 - :ref:`Sequence of paths and mappings <west-manifest-import-seq>`
1274 - :ref:`west-manifest-ex4.1`
1275 - :ref:`west-manifest-ex4.2`
1277 A more :ref:`formal description <west-manifest-formal>` of how this works is
1284 :ref:`resolving your manifest <west-manifest-resolve>` to see the final results
1287 .. _west-manifest-import-bool:
1299 .. code-block:: yaml
1304 - name: p1
1307 - name: p2
1309 - name: p3 # Nothing is imported from p3 either.
1314 .. code-block:: yaml
1321 .. _west-manifest-ex1.1:
1324 -------------------------------------------
1332 .. code-block:: none
1334 my-downstream/
1342 └── my-repo/ # your downstream repository
1346 You can do this with the following :file:`my-repo/west.yml`:
1348 .. code-block:: yaml
1350 # my-repo/west.yml:
1353 - name: zephyrproject-rtos
1354 url-base: https://github.com/zephyrproject-rtos
1356 - name: zephyr
1357 remote: zephyrproject-rtos
1362 ``my-repo`` is hosted at ``https://git.example.com/my-repo``:
1364 .. code-block:: console
1366 west init -m https://git.example.com/my-repo my-downstream
1367 cd my-downstream
1370 After ``west init``, :file:`my-downstream/my-repo` will be cloned.
1374 :file:`my-downstream` as well.
1376 You can add and commit any code to :file:`my-repo` you please at this point,
1379 .. _west-manifest-ex1.2:
1382 ------------------------------------------------
1384 This is similar to :ref:`west-manifest-ex1.1`, except we'll use ``revision:
1387 .. code-block:: yaml
1389 # my-repo/west.yml:
1392 - name: zephyrproject-rtos
1393 url-base: https://github.com/zephyrproject-rtos
1395 - name: zephyr
1396 remote: zephyrproject-rtos
1402 .. code-block:: console
1404 west init -m https://git.example.com/my-repo my-downstream
1405 cd my-downstream
1408 This time, whenever you run ``west update``, the special :ref:`manifest-rev
1409 <west-manifest-rev>` branch in the ``zephyr`` repository will be updated to
1411 https://github.com/zephyrproject-rtos/zephyr.
1413 The contents of :file:`zephyr/west.yml` at the new ``manifest-rev`` will then
1422 ``manifest-rev`` when importing from a project.
1425 repository's working tree. See :ref:`west-manifest-ex2.2` for an example.
1427 .. _west-manifest-ex1.3:
1430 -------------------------------------------------------------
1432 This manifest is similar to the one in :ref:`west-manifest-ex1.1`, except it:
1434 - is a downstream of Zephyr 2.0
1435 - includes a downstream fork of the :file:`modules/hal/nordic`
1438 .. code-block:: yaml
1440 # my-repo/west.yml:
1443 - name: zephyrproject-rtos
1444 url-base: https://github.com/zephyrproject-rtos
1445 - name: my-remote
1446 url-base: https://git.example.com
1448 - name: hal_nordic # higher precedence
1449 remote: my-remote
1450 revision: my-sha
1451 path: modules/hal/nordic
1452 - name: zephyr
1453 remote: zephyrproject-rtos
1460 remote: zephyrproject-rtos
1462 - name: zephyrproject-rtos
1463 url-base: https://github.com/zephyrproject-rtos
1466 - name: hal_nordic # lower precedence, values ignored
1467 path: modules/hal/nordic
1468 revision: another-sha
1472 - is cloned from ``https://git.example.com/hal_nordic`` instead of
1473 ``https://github.com/zephyrproject-rtos/hal_nordic``.
1474 - is updated to commit ``my-sha`` by ``west update``, instead of
1475 the mainline commit ``another-sha``
1477 In other words, when your top-level manifest defines a project, like
1481 This does mean you have to copy the ``path: modules/hal/nordic`` value into
1482 :file:`my-repo/west.yml` when defining ``hal_nordic`` there. The value from
1483 :file:`zephyr/west.yml` is ignored entirely. See :ref:`west-manifest-resolve`
1488 - update zephyr's ``manifest-rev`` to point at the ``v2.0.0`` tag
1489 - import :file:`zephyr/west.yml` at that ``manifest-rev``
1490 - locally check out the ``v2.0.0`` revisions for all zephyr projects except
1492 - update ``hal_nordic`` to ``my-sha`` instead of ``another-sha``
1494 .. _west-manifest-import-path:
1496 Option 2: Relative path
1499 The ``import`` value can also be a relative path to a manifest file or a
1500 directory containing manifest files. The path is relative to the root directory
1505 .. code-block:: yaml
1509 - name: project-1
1512 - name: project-2
1514 import: p2-manifests
1520 - the contents of :file:`project-1/west.yml` at ``manifest-rev``, which points
1522 - any YAML files in the directory tree :file:`project-2/p2-manifests`
1525 - YAML files in :file:`submanifests` in your manifest repository,
1528 Notice how ``projects`` imports get data from Git using ``manifest-rev``, while
1532 .. _west-manifest-ex2.1:
1534 Example 2.1: Downstream of a Zephyr release with explicit path argument
1535 --------------------------------------------------------------
1538 :ref:`west-manifest-ex1.1`.
1540 .. code-block:: yaml
1544 - name: zephyrproject-rtos
1545 url-base: https://github.com/zephyrproject-rtos
1547 - name: zephyr
1548 remote: zephyrproject-rtos
1558 .. _west-manifest-ex2.2:
1561 --------------------------------------------------------
1567 .. code-block:: none
1569 my-repo/
1571 │ ├── 01-libraries.yml
1572 │ ├── 02-vendor-hals.yml
1573 │ └── 03-applications.yml
1576 You want to add all the files in :file:`my-repo/submanifests` to the main
1577 manifest file, :file:`my-repo/west.yml`, in addition to projects in
1583 .. code-block:: yaml
1585 # my-repo/west.yml:
1588 - name: zephyrproject-rtos
1589 url-base: https://github.com/zephyrproject-rtos
1591 - name: zephyr
1592 remote: zephyrproject-rtos
1600 #. :file:`my-repo/submanifests/01-libraries.yml`
1601 #. :file:`my-repo/submanifests/02-vendor-hals.yml`
1602 #. :file:`my-repo/submanifests/03-applications.yml`
1603 #. :file:`my-repo/west.yml`
1615 :file:`my-repo/west.yml` and :file:`zephyr/west.yml`. In general, an ``import``
1619 This means projects defined in :file:`my-repo/submanifests` take highest
1620 precedence. For example, if :file:`01-libraries.yml` defines ``hal_nordic``,
1622 usual, see :ref:`west-manifest-resolve` for troubleshooting advice.
1627 .. _west-manifest-ex2.3:
1630 ---------------------------------------------
1636 Starting with :ref:`west-manifest-ex2.2`, the CI scripts add a
1637 file :file:`00-ci.yml` in :file:`my-repo/submanifests`, with these contents:
1639 .. code-block:: yaml
1641 # my-repo/submanifests/00-ci.yml:
1644 - name: a-vendor-hal
1645 url: https://github.com/a-developer/hal
1646 revision: a-pull-request-branch
1647 - name: an-application
1648 url: https://github.com/a-developer/application
1649 revision: another-pull-request-branch
1652 :file:`my-repo/submanifests`. The projects defined in :file:`00-ci.yml` have
1653 higher precedence than other definitions in :file:`my-repo/submanifests`,
1654 because the name :file:`00-ci.yml` comes before the other file names.
1657 projects named ``a-vendor-hal`` and ``an-application``, even if those same
1660 .. _west-manifest-import-map:
1667 - ``file``: Optional. The name of the manifest file or directory to import.
1669 - ``name-allowlist``: Optional. If present, a name or sequence of project names
1671 - ``path-allowlist``: Optional. If present, a path or sequence of project paths
1672 to match against. This is a shell-style globbing pattern, currently
1675 - ``name-blocklist``: Optional. Like ``name-allowlist``, but contains project
1677 - ``path-blocklist``: Optional. Like ``path-allowlist``, but contains project
1679 - ``path-prefix``: Optional (new in v0.8.0). If given, this will be prepended
1680 to the project's path in the workspace, as well as the paths of any imported
1689 blocked by path, then allowed by name, it will still be imported.
1691 .. _west-manifest-ex3.1:
1694 -------------------------------------------
1701 .. code-block:: yaml
1706 - name: mainline-app # included
1707 path: examples/app
1709 - name: lib
1710 path: libraries/lib
1712 - name: lib2 # included
1713 path: libraries/lib2
1719 - name: mainline
1722 name-allowlist:
1723 - mainline-app
1724 - lib2
1725 - name: downstream-app
1727 - name: lib3
1728 path: libraries/lib3
1733 .. code-block:: yaml
1737 - name: mainline
1739 - name: downstream-app
1741 - name: lib3
1742 path: libraries/lib3
1744 - name: mainline-app # imported
1745 path: examples/app
1747 - name: lib2 # imported
1748 path: libraries/lib2
1754 .. _west-manifest-ex3.2:
1756 Example 3.2: Downstream with path allowlist
1757 -------------------------------------------
1760 using ``path-allowlist``.
1762 .. code-block:: yaml
1767 - name: app
1768 path: examples/app
1770 - name: lib
1771 path: libraries/lib # included
1773 - name: lib2
1774 path: libraries/lib2 # included
1780 - name: mainline
1783 path-allowlist: libraries/*
1784 - name: app
1786 - name: lib3
1787 path: libraries/lib3
1792 .. code-block:: yaml
1796 - name: lib # imported
1797 path: libraries/lib
1799 - name: lib2 # imported
1800 path: libraries/lib2
1802 - name: mainline
1804 - name: app
1806 - name: lib3
1807 path: libraries/lib3
1810 .. _west-manifest-ex3.3:
1812 Example 3.3: Downstream with path blocklist
1813 -------------------------------------------
1816 common path prefix in the workspace, add your own version for the chip
1819 .. code-block:: yaml
1826 - name: mainline
1827 url-base: https://git.example.com/mainline
1829 - name: app
1830 - name: lib
1831 path: libraries/lib
1832 - name: lib2
1833 path: libraries/lib2
1834 - name: hal_foo
1835 path: modules/hals/foo # excluded
1836 - name: hal_bar
1837 path: modules/hals/bar # excluded
1838 - name: hal_baz
1839 path: modules/hals/baz # excluded
1844 - name: mainline
1847 path-blocklist: modules/hals/*
1848 - name: hal_foo
1849 path: modules/hals/foo
1854 .. code-block:: yaml
1860 - name: mainline
1861 url-base: https://git.example.com/mainline
1863 - name: app # imported
1864 - name: lib # imported
1865 path: libraries/lib
1866 - name: lib2 # imported
1867 path: libraries/lib2
1868 - name: mainline
1869 repo-path: https://git.example.com/mainline/manifest
1870 - name: hal_foo
1871 path: modules/hals/foo
1874 .. _west-manifest-ex3.4:
1877 ---------------------------------------
1885 .. code-block:: yaml
1892 - name: example
1893 url-base: https://git.example.com
1895 - name: bar
1896 - name: baz
1899 three project repositories in an :file:`external-code` subdirectory, like this:
1901 .. code-block:: none
1904 └── external-code/
1911 .. code-block:: yaml
1915 - name: foo
1918 path-prefix: external-code
1922 .. code-block:: yaml
1929 - name: example
1930 url-base: https://git.example.com
1932 - name: foo
1933 path: external-code/foo
1934 - name: bar
1935 path: external-code/bar
1936 - name: baz
1937 path: external-code/baz
1939 .. _west-manifest-import-seq:
1947 .. _west-manifest-ex4.1:
1950 -------------------------------------------------------
1953 :ref:`west-manifest-ex2.2`, with a sequence of explicitly named files.
1955 .. code-block:: yaml
1957 # my-repo/west.yml:
1960 - name: zephyr
1961 url: https://github.com/zephyrproject-rtos/zephyr
1965 - submanifests/01-libraries.yml
1966 - submanifests/02-vendor-hals.yml
1967 - submanifests/03-applications.yml
1969 .. _west-manifest-ex4.2:
1972 --------------------------------------
1976 .. code-block:: yaml
1978 # my-repo/west.yml
1982 - name: my-library
1983 - name: my-app
1984 - name: zephyr
1986 - name: another-manifest-repo
1990 - submanifests/libraries.yml
1991 - submanifests/vendor-hals.yml
1992 - submanifests/applications.yml
1994 remote: my-remote
1998 #. the listed files in :file:`my-repo/submanifests` are first, in the order
2002 #. :file:`my-repo/west.yml` is next (with projects ``my-library`` etc. as long
2005 in the ``projects`` list in :file:`my-repo/west.yml`
2006 #. files in :file:`another-manifest-repo/submanifests` are last (sorted by file
2009 .. _west-manifest-formal:
2018 --------
2023 .. code-block:: yaml
2025 # Top-level manifest file.
2028 - name: foo
2030 ... # import-1
2031 - name: bar
2033 ... # import-2
2035 - name: baz
2037 ... # import-N
2040 ... # self-import
2042 Import keys are optional. If any of ``import-1, ..., import-N`` are missing,
2044 ``self-import`` is missing, no additional files in the manifest repository
2045 (beyond the top-level file) are imported.
2049 - a ``projects`` list, which is produced by combining the ``projects`` defined
2050 in the top-level file with those defined in imported files
2052 - a set of extension commands, which are drawn from the ``west-commands``
2053 keys in the top-level file and any imported files
2055 - a ``group-filter`` list, which is produced by combining the top-level and any
2060 #. Manifests from ``self-import`` are imported first.
2061 #. The top-level manifest file's definitions are handled next.
2062 #. Manifests from ``import-1``, ..., ``import-N``, are imported in that order.
2067 - If the value is a relative path naming a directory (or a map whose ``file``
2069 lexicographic order -- i.e., sorted by file name.
2070 - If the value is a sequence, its elements are recursively imported in the
2073 This process recurses if necessary. E.g., if ``import-1`` produces a manifest
2080 --------
2086 example, if ``import-1`` contains a project named ``bar``, that is ignored,
2087 because the top-level :file:`west.yml` has already defined a project by that
2090 The contents of files named by ``import-1`` through ``import-N`` are imported
2091 from Git at the latest ``manifest-rev`` revisions in their projects. These
2092 revisions can be updated to the values ``rev-1`` through ``rev-N`` by running
2093 ``west update``. If any ``manifest-rev`` reference is missing or out of date,
2100 ``manifest-rev`` in the ``baz`` project if :file:`baz/west.yml` defines ``P``,
2101 as well as updating the ``manifest-rev`` branch in the local git clone of
2113 documentation for the :ref:`update.fetch <west-config-index>` configuration
2117 ----------
2119 All extension commands defined using ``west-commands`` keys discovered while
2122 If an imported manifest file has a ``west-commands:`` definition in its
2128 -------------
2130 The resolved manifest has a ``group-filter`` value which is the result of
2131 concatenating the ``group-filter`` values in the top-level manifest and any
2135 and are therefore concatenated later into the final ``group-filter``.
2139 - the submanifest resolved from ``self-import`` have group filter ``self-filter``
2140 - the top-level manifest file have group filter ``top-filter``
2141 - the submanifests resolved from ``import-1`` through ``import-N`` have group
2142 filters ``filter-1`` through ``filter-N`` respectively
2144 The final resolved ``group-filter`` value is then ``filterN + ... + filter-2 +
2145 filter-1 + top-filter + self-filter``, where ``+`` here refers to list
2155 For example, in ``[-foo] + [+foo]``, group ``foo`` is *enabled*.
2156 However, in ``[+foo] + [-foo]``, group ``foo`` is *disabled*.
2160 [-foo]`` could be written more simply as ``[-foo]``, for the reasons given
2161 above. As another example, ``[-foo] + [+foo]`` could be written as the empty
2164 .. _west-manifest-cmd:
2170 It takes an action, and action-specific arguments.
2173 simple uses. Run ``west manifest --help`` for full details on all options.
2175 .. _west-manifest-resolve:
2180 The ``--resolve`` action outputs a single manifest file equivalent to your
2181 current manifest and all its :ref:`imported manifests <west-manifest-import>`:
2183 .. code-block:: none
2185 west manifest --resolve [-o outfile]
2192 level using ``-v``:
2194 .. code-block:: console
2196 west -v manifest --resolve
2201 The ``--freeze`` action outputs a frozen manifest:
2203 .. code-block:: none
2205 west manifest --freeze [-o outfile]
2208 You can use ``--freeze`` to produce a frozen manifest that's equivalent to your
2209 current manifest file. The ``-o`` option specifies an output file; if not
2215 The ``--validate`` action either succeeds if the current manifest file is valid,
2218 .. code-block:: none
2220 west manifest --validate
2228 up the verbosity with ``-v`` is a good way to get detailed information about
2231 .. code-block:: none
2233 west -v manifest --validate
2235 .. _west-manifest-path:
2237 Get the manifest path
2240 The ``--path`` action prints the path to the top level manifest file:
2242 .. code-block:: none
2244 west manifest --path
2246 The output is something like ``/path/to/workspace/west.yml``. The path format