Lines Matching +full:url +full:- +full:base
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:
112 The ``remotes`` subsection contains a sequence which specifies the base URLs
115 Each ``remotes`` element has a name and a "URL base". These are used to form
116 the complete Git fetch URL for each project. A project's fetch URL can be set
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
148 Above, two remotes are given, with names ``remote1`` and ``remote2``. Their URL
150 ``https://git.example.com/base2``. You can use SSH URL bases as well; for
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
195 with a ``/`` and the project ``name`` to form the URL.
197 Locally, this project will be cloned at path ``extra/project-1`` relative to
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
207 present, overrides the default ``name`` when forming the fetch URL.
214 - ``proj3`` has an explicit ``url``, so it will be fetched from
215 ``https://github.com/user/project-three``.
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)
245 to form the fetch URL instead.
247 If the project has a ``url``, that's the complete fetch URL for the
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
366 have a ``url`` or ``remote`` key set.
368 * - ``revision``
369 - Optional. This will be used for a project's ``revision`` if it does
380 .. code-block:: yaml
386 west-commands: scripts/west-commands.yml
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
409 repository URL will be used by default. For example, if the URL is
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
964 url: https://git.example.com/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
1007 url: https://git.example.com/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
1054 url: https://git.example.com/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
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
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
1410 point at a newly fetched ``main`` branch tip from the URL
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
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
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
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:
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:
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
1691 .. _west-manifest-ex3.1:
1694 -------------------------------------------
1701 .. code-block:: yaml
1706 - name: mainline-app # included
1708 url: https://git.example.com/mainline/app
1709 - name: lib
1711 url: https://git.example.com/mainline/lib
1712 - name: lib2 # included
1714 url: https://git.example.com/mainline/lib2
1719 - name: mainline
1720 url: https://git.example.com/mainline/manifest
1722 name-allowlist:
1723 - mainline-app
1724 - lib2
1725 - name: downstream-app
1726 url: https://git.example.com/downstream/app
1727 - name: lib3
1729 url: https://git.example.com/downstream/lib3
1733 .. code-block:: yaml
1737 - name: mainline
1738 url: https://git.example.com/mainline/manifest
1739 - name: downstream-app
1740 url: https://git.example.com/downstream/app
1741 - name: lib3
1743 url: https://git.example.com/downstream/lib3
1744 - name: mainline-app # imported
1746 url: https://git.example.com/mainline/app
1747 - name: lib2 # imported
1749 url: https://git.example.com/mainline/lib2
1754 .. _west-manifest-ex3.2:
1757 -------------------------------------------
1760 using ``path-allowlist``.
1762 .. code-block:: yaml
1767 - name: app
1769 url: https://git.example.com/mainline/app
1770 - name: lib
1772 url: https://git.example.com/mainline/lib
1773 - name: lib2
1775 url: https://git.example.com/mainline/lib2
1780 - name: mainline
1781 url: https://git.example.com/mainline/manifest
1783 path-allowlist: libraries/*
1784 - name: app
1785 url: https://git.example.com/downstream/app
1786 - name: lib3
1788 url: https://git.example.com/downstream/lib3
1792 .. code-block:: yaml
1796 - name: lib # imported
1798 url: https://git.example.com/mainline/lib
1799 - name: lib2 # imported
1801 url: https://git.example.com/mainline/lib2
1802 - name: mainline
1803 url: https://git.example.com/mainline/manifest
1804 - name: app
1805 url: https://git.example.com/downstream/app
1806 - name: lib3
1808 url: https://git.example.com/downstream/lib3
1810 .. _west-manifest-ex3.3:
1813 -------------------------------------------
1819 .. code-block:: yaml
1826 - name: mainline
1827 url-base: https://git.example.com/mainline
1829 - name: app
1830 - name: lib
1832 - name: lib2
1834 - name: hal_foo
1836 - name: hal_bar
1838 - name: hal_baz
1844 - name: mainline
1845 url: https://git.example.com/mainline/manifest
1847 path-blocklist: modules/hals/*
1848 - name: hal_foo
1850 url: https://git.example.com/downstream/hal_foo
1854 .. code-block:: yaml
1860 - name: mainline
1861 url-base: https://git.example.com/mainline
1863 - name: app # imported
1864 - name: lib # imported
1866 - name: lib2 # imported
1868 - name: mainline
1869 repo-path: https://git.example.com/mainline/manifest
1870 - name: hal_foo
1872 url: https://git.example.com/downstream/hal_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
1916 url: https://git.example.com/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,
2094 ``west update`` also fetches project data from the remote fetch URL and updates
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:
2240 The ``--path`` action prints the path to the top level manifest file:
2242 .. code-block:: none
2244 west manifest --path