diff --git a/doc/guides/west/manifest.rst b/doc/guides/west/manifest.rst index 6c7bbdeba3b..b3acd0ba9c5 100644 --- a/doc/guides/west/manifest.rst +++ b/doc/guides/west/manifest.rst @@ -409,6 +409,462 @@ Group-filter See :ref:`west-manifest-groups`. +.. _west-manifest-groups: + +Project Groups and Active Projects +********************************** + +You can use the ``groups`` and ``group-filter`` keys briefly described +:ref:`above ` to place projects into groups, and filter +which groups are enabled. These keys appear in the manifest like this: + +.. code-block:: yaml + + manifest: + projects: + - name: some-project + groups: ... + group-filter: ... + +You can enable or disable project groups using ``group-filter``. Projects whose +groups are all disabled are *inactive*; west essentially ignores inactive +projects unless explicitly requested not to. + +The next section introduces project groups; the following sections describe +:ref:`west-enabled-disabled-groups` and :ref:`west-active-inactive-projects`. +Finally, there are :ref:`west-project-group-examples`. + +Project Groups +============== + +Inside ``manifest: projects:``, you can add a project to one or more groups. +The ``groups`` key is a list of group names. Group names are strings. + +For example, in this manifest fragment: + +.. code-block:: yaml + + manifest: + projects: + - name: project-1 + groups: + - groupA + - name: project-2 + groups: + - groupB + - groupC + - name: project-3 + +The projects are in these groups: + +- ``project-1``: one group, named ``groupA`` +- ``project-2``: two groups, named ``groupB`` and ``groupC`` +- ``project-3``: no groups + +Project group names must not contain commas (,), colons (:), or whitespace. + +Group names must not begin with a dash (-) or the plus sign (+), but they may +contain these characters elsewhere in their names. For example, ``foo-bar`` and +``foo+bar`` are valid groups, but ``-foobar`` and ``+foobar`` are not. + +Group names are otherwise arbitrary strings. Group names are case sensitive. + +As a restriction, no project may use both ``import:`` and ``groups:``. (This +avoids some edge cases whose semantics are difficult to specify.) + +.. _west-enabled-disabled-groups: + +Enabled and Disabled Project Groups +=================================== + +You can enable or disable project groups in both your manifest file and +:ref:`west-config`. + +All groups are enabled by default. + +Within the manifest file, the top level ``manifest: group-filter:`` value can +be used to disable project groups. To disable a group, prefix its name with a +dash (-). For example, in this manifest fragment: + +.. code-block:: yaml + + manifest: + group-filter: [-groupA,-groupB] + +The groups named ``groupA`` and ``groupB`` are disabled by this +``group-filter`` value. + +The ``group-filter`` list is an ordinary YAML list, so you could have also +written this fragment like this: + +.. code-block:: yaml + + manifest: + group-filter: + - -groupA + - -groupB + +However, this syntax is harder to read and therefore discouraged. + +Although it's not an error to enable groups within ``manifest: group-filter:``, +like this: + +.. code-block:: yaml + + manifest: + ... + group-filter: [+groupA] + +doing so is redundant since groups are enabled by default. + +Only the **top level manifest file's** ``manifest: group-filter:`` value has +any effect. The ``manifest: group-filter:`` values in any +:ref:`imported manifests ` are ignored. + +In addition to the manifest file, you can control which groups are enabled and +disabled using the ``manifest.group-filter`` configuration option. This option +is a comma-separated list of groups to enable and/or disable. + +To enable a group, add its name to the list prefixed with ``+``. To disable a +group, add its name prefixed with ``-``. For example, setting +``manifest.group-filter`` to ``+groupA,-groupB`` enables ``groupA``, and +disables ``groupB``. + +The value of the configuration option overrides any data in the manifest file. +You can think of this as if the ``manifest.group-filter`` configuration option +is appended to the ``manifest: group-filter:`` list from YAML, with "last entry +wins" semantics. + +.. _west-active-inactive-projects: + +Active and Inactive Projects +============================ + +All projects are *active* by default. Projects with no groups are always +active. A project is *inactive* if all of its groups are disabled. This is the +only way to make a project inactive. + +Most west commands that operate on projects will ignore inactive projects by +default. For example, :ref:`west-update` when run without arguments will not +update inactive projects. As another example, running ``west list`` without +arguments will not print information for inactive projects. + +.. _west-project-group-examples: + +Project Group Examples +====================== + +This section contains example situations involving project groups and active +projects. The examples use both ``manifest: group-filter:`` YAML lists and +``manifest.group-filter`` configuration lists, to show how they work together. + +Note that the ``defaults`` and ``remotes`` data in the following manifests +isn't relevant except to make the examples complete and self-contained. + +Example 1: no disabled groups +----------------------------- + +The entire manifest file is: + +.. code-block:: yaml + + manifest: + projects: + - name: foo + groups: + - groupA + - name: bar + groups: + - groupA + - groupB + - name: baz + + defaults: + remote: example-remote + remotes: + - name: example-remote + url-base: https://git.example.com + +The ``manifest.group-filter`` configuration option is not set (you can ensure +this by running ``west config -D manifest.group-filter``). + +No groups are disabled, because all groups are enabled by default. Therefore, +all three projects (``foo``, ``bar``, and ``baz``) are active. Note that there +is no way to make project ``baz`` inactive, since it has no groups. + +Example 2: Disabling one group via manifest +------------------------------------------- + +The entire manifest file is: + +.. code-block:: yaml + + manifest: + projects: + - name: foo + groups: + - groupA + - name: bar + groups: + - groupA + - groupB + + group-filter: [-groupA] + + defaults: + remote: example-remote + remotes: + - name: example-remote + url-base: https://git.example.com + +The ``manifest.group-filter`` configuration option is not set (you can ensure +this by running ``west config -D manifest.group-filter``). + +Since ``groupA`` is disabled, project ``foo`` is inactive. Project ``bar`` is +active, because ``groupB`` is enabled. + +Example 3: Disabling multiple groups via manifest +------------------------------------------------- + +The entire manifest file is: + +.. code-block:: yaml + + manifest: + projects: + - name: foo + groups: + - groupA + - name: bar + groups: + - groupA + - groupB + + group-filter: [-groupA,-groupB] + + defaults: + remote: example-remote + remotes: + - name: example-remote + url-base: https://git.example.com + +The ``manifest.group-filter`` configuration option is not set (you can ensure +this by running ``west config -D manifest.group-filter``). + +Both ``foo`` and ``bar`` are inactive, because all of their groups are +disabled. + +Example 4: Disabling a group via configuration +---------------------------------------------- + +The entire manifest file is: + +.. code-block:: yaml + + manifest: + projects: + - name: foo + groups: + - groupA + - name: bar + groups: + - groupA + - groupB + + defaults: + remote: example-remote + remotes: + - name: example-remote + url-base: https://git.example.com + +The ``manifest.group-filter`` configuration option is set to ``-groupA`` (you +can ensure this by running ``west config manifest.group-filter -- -groupA``; +the extra ``--`` is required so the argument parser does not treat ``-groupA`` +as a command line option ``-g`` with value ``roupA``). + +Project ``foo`` is inactive because ``groupA`` has been disabled by the +``manifest.group-filter`` configuration option. Project ``bar`` is active +because ``groupB`` is enabled. + +Example 5: Overriding a disabled group via configuration +-------------------------------------------------------- + +The entire manifest file is: + +.. code-block:: yaml + + manifest: + projects: + - name: foo + - name: bar + groups: + - groupA + - name: baz + groups: + - groupA + - groupB + + group-filter: [-groupA] + + defaults: + remote: example-remote + remotes: + - name: example-remote + url-base: https://git.example.com + +The ``manifest.group-filter`` configuration option is set to ``+groupA`` (you +can ensure this by running ``west config manifest.group-filter +groupA``). + +In this case, ``groupA`` is enabled: the ``manifest.group-filter`` +configuration option has higher precedence than the ``manifest: group-filter: +[-groupA]`` content in the manifest file. + +Therefore, projects ``foo`` and ``bar`` are both active. + +Example 6: Overriding multiple disabled groups via configuration +---------------------------------------------------------------- + +The entire manifest file is: + +.. code-block:: yaml + + manifest: + projects: + - name: foo + - name: bar + groups: + - groupA + - name: baz + groups: + - groupA + - groupB + + group-filter: [-groupA,-groupB] + + defaults: + remote: example-remote + remotes: + - name: example-remote + url-base: https://git.example.com + +The ``manifest.group-filter`` configuration option is set to +``+groupA,+groupB`` (you can ensure this by running ``west config +manifest.group-filter "+groupA,+groupB"``). + +In this case, both ``groupA`` and ``groupB`` are enabled, because the +configuration value overrides the manifest file for both groups. + +Therefore, projects ``foo`` and ``bar`` are both active. + +Example 7: Disabling multiple groups via configuration +------------------------------------------------------ + +The entire manifest file is: + +.. code-block:: yaml + + manifest: + projects: + - name: foo + - name: bar + groups: + - groupA + - name: baz + groups: + - groupA + - groupB + + defaults: + remote: example-remote + remotes: + - name: example-remote + url-base: https://git.example.com + +The ``manifest.group-filter`` configuration option is set to +``-groupA,-groupB`` (you can ensure this by running ``west config +manifest.group-filter -- "-groupA,-groupB"``). + +In this case, both ``groupA`` and ``groupB`` are disabled. + +Therefore, projects ``foo`` and ``bar`` are both inactive. + +.. _west-manifest-submodules: + +Git Submodules in Projects +************************** + +You can use the ``submodules`` keys briefly described :ref:`above +` to force ``west update`` to also handle any `Git +submodules`_ configured in project's git repository. The ``submodules`` key can +appear inside ``projects``, like this: + +.. code-block:: YAML + + manifest: + projects: + - name: some-project + submodules: ... + +The ``submodules`` key can be a boolean or a list of mappings. We'll describe +these in order. + +Option 1: Boolean +================= + +This is the easiest way to use ``submodules``. + +If ``submodules`` is ``true`` as a ``projects`` attribute, ``west update`` will +recursively update the project's Git submodules whenever it updates the project +itself. If it's ``false`` or missing, it has no effect. + +For example, let's say you have a source code repository ``foo``, which has +some submodules, and you want ``west update`` to keep all of them them in sync, +along with another project named ``bar`` in the same workspace. + +You can do that with this manifest file: + +.. code-block:: yaml + + manifest: + projects: + - name: foo + submodules: true + - name: bar + +Here, ``west update`` will initialize and update all submodules in ``foo``. If +``bar`` has any submodules, they are ignored, because ``bar`` does not have a +``submodules`` value. + +Option 2: List of mappings +========================== + +The ``submodules`` key may be a list of mappings. Each element in the list +defines the name of the submodule to update, and the path -- relative to the +project's absolute path in the workspace -- to use for the submodule. +The submodule will be updated recursively. + +For example, let's say you have a source code repository ``foo``, which has +many submodules, and you want ``west update`` to keep some but not all of them +in sync, along with another project named ``bar`` in the same workspace. + +You can do that with this manifest file: + +.. code-block:: yaml + + manifest: + projects: + - name: foo + submodules: + - name: foo-first-sub + path: path/to/foo-first-sub + - name: foo-second-sub + path: path/to/foo-second-sub + - name: bar + +Here, ``west update`` will recursively initialize and update just the +submodules in ``foo`` with paths ``path/to/foo-first-sub`` and +``path/to/foo-second-sub``. Any submodules in ``bar`` are still ignored. + .. _west-manifest-import: Manifest Imports @@ -1282,462 +1738,6 @@ processed in this order: - If the value is a sequence, its elements are recursively imported in the order they appear. -.. _west-manifest-groups: - -Project Groups and Active Projects -********************************** - -You can use the ``groups`` and ``group-filter`` keys briefly described -:ref:`above ` to place projects into groups, and filter -which groups are enabled. These keys appear in the manifest like this: - -.. code-block:: yaml - - manifest: - projects: - - name: some-project - groups: ... - group-filter: ... - -You can enable or disable project groups using ``group-filter``. Projects whose -groups are all disabled are *inactive*; west essentially ignores inactive -projects unless explicitly requested not to. - -The next section introduces project groups; the following sections describe -:ref:`west-enabled-disabled-groups` and :ref:`west-active-inactive-projects`. -Finally, there are :ref:`west-project-group-examples`. - -Project Groups -============== - -Inside ``manifest: projects:``, you can add a project to one or more groups. -The ``groups`` key is a list of group names. Group names are strings. - -For example, in this manifest fragment: - -.. code-block:: yaml - - manifest: - projects: - - name: project-1 - groups: - - groupA - - name: project-2 - groups: - - groupB - - groupC - - name: project-3 - -The projects are in these groups: - -- ``project-1``: one group, named ``groupA`` -- ``project-2``: two groups, named ``groupB`` and ``groupC`` -- ``project-3``: no groups - -Project group names must not contain commas (,), colons (:), or whitespace. - -Group names must not begin with a dash (-) or the plus sign (+), but they may -contain these characters elsewhere in their names. For example, ``foo-bar`` and -``foo+bar`` are valid groups, but ``-foobar`` and ``+foobar`` are not. - -Group names are otherwise arbitrary strings. Group names are case sensitive. - -As a restriction, no project may use both ``import:`` and ``groups:``. (This -avoids some edge cases whose semantics are difficult to specify.) - -.. _west-enabled-disabled-groups: - -Enabled and Disabled Project Groups -=================================== - -You can enable or disable project groups in both your manifest file and -:ref:`west-config`. - -All groups are enabled by default. - -Within the manifest file, the top level ``manifest: group-filter:`` value can -be used to disable project groups. To disable a group, prefix its name with a -dash (-). For example, in this manifest fragment: - -.. code-block:: yaml - - manifest: - group-filter: [-groupA,-groupB] - -The groups named ``groupA`` and ``groupB`` are disabled by this -``group-filter`` value. - -The ``group-filter`` list is an ordinary YAML list, so you could have also -written this fragment like this: - -.. code-block:: yaml - - manifest: - group-filter: - - -groupA - - -groupB - -However, this syntax is harder to read and therefore discouraged. - -Although it's not an error to enable groups within ``manifest: group-filter:``, -like this: - -.. code-block:: yaml - - manifest: - ... - group-filter: [+groupA] - -doing so is redundant since groups are enabled by default. - -Only the **top level manifest file's** ``manifest: group-filter:`` value has -any effect. The ``manifest: group-filter:`` values in any -:ref:`imported manifests ` are ignored. - -In addition to the manifest file, you can control which groups are enabled and -disabled using the ``manifest.group-filter`` configuration option. This option -is a comma-separated list of groups to enable and/or disable. - -To enable a group, add its name to the list prefixed with ``+``. To disable a -group, add its name prefixed with ``-``. For example, setting -``manifest.group-filter`` to ``+groupA,-groupB`` enables ``groupA``, and -disables ``groupB``. - -The value of the configuration option overrides any data in the manifest file. -You can think of this as if the ``manifest.group-filter`` configuration option -is appended to the ``manifest: group-filter:`` list from YAML, with "last entry -wins" semantics. - -.. _west-active-inactive-projects: - -Active and Inactive Projects -============================ - -All projects are *active* by default. Projects with no groups are always -active. A project is *inactive* if all of its groups are disabled. This is the -only way to make a project inactive. - -Most west commands that operate on projects will ignore inactive projects by -default. For example, :ref:`west-update` when run without arguments will not -update inactive projects. As another example, running ``west list`` without -arguments will not print information for inactive projects. - -.. _west-project-group-examples: - -Project Group Examples -====================== - -This section contains example situations involving project groups and active -projects. The examples use both ``manifest: group-filter:`` YAML lists and -``manifest.group-filter`` configuration lists, to show how they work together. - -Note that the ``defaults`` and ``remotes`` data in the following manifests -isn't relevant except to make the examples complete and self-contained. - -Example 1: no disabled groups ------------------------------ - -The entire manifest file is: - -.. code-block:: yaml - - manifest: - projects: - - name: foo - groups: - - groupA - - name: bar - groups: - - groupA - - groupB - - name: baz - - defaults: - remote: example-remote - remotes: - - name: example-remote - url-base: https://git.example.com - -The ``manifest.group-filter`` configuration option is not set (you can ensure -this by running ``west config -D manifest.group-filter``). - -No groups are disabled, because all groups are enabled by default. Therefore, -all three projects (``foo``, ``bar``, and ``baz``) are active. Note that there -is no way to make project ``baz`` inactive, since it has no groups. - -Example 2: Disabling one group via manifest -------------------------------------------- - -The entire manifest file is: - -.. code-block:: yaml - - manifest: - projects: - - name: foo - groups: - - groupA - - name: bar - groups: - - groupA - - groupB - - group-filter: [-groupA] - - defaults: - remote: example-remote - remotes: - - name: example-remote - url-base: https://git.example.com - -The ``manifest.group-filter`` configuration option is not set (you can ensure -this by running ``west config -D manifest.group-filter``). - -Since ``groupA`` is disabled, project ``foo`` is inactive. Project ``bar`` is -active, because ``groupB`` is enabled. - -Example 3: Disabling multiple groups via manifest -------------------------------------------------- - -The entire manifest file is: - -.. code-block:: yaml - - manifest: - projects: - - name: foo - groups: - - groupA - - name: bar - groups: - - groupA - - groupB - - group-filter: [-groupA,-groupB] - - defaults: - remote: example-remote - remotes: - - name: example-remote - url-base: https://git.example.com - -The ``manifest.group-filter`` configuration option is not set (you can ensure -this by running ``west config -D manifest.group-filter``). - -Both ``foo`` and ``bar`` are inactive, because all of their groups are -disabled. - -Example 4: Disabling a group via configuration ----------------------------------------------- - -The entire manifest file is: - -.. code-block:: yaml - - manifest: - projects: - - name: foo - groups: - - groupA - - name: bar - groups: - - groupA - - groupB - - defaults: - remote: example-remote - remotes: - - name: example-remote - url-base: https://git.example.com - -The ``manifest.group-filter`` configuration option is set to ``-groupA`` (you -can ensure this by running ``west config manifest.group-filter -- -groupA``; -the extra ``--`` is required so the argument parser does not treat ``-groupA`` -as a command line option ``-g`` with value ``roupA``). - -Project ``foo`` is inactive because ``groupA`` has been disabled by the -``manifest.group-filter`` configuration option. Project ``bar`` is active -because ``groupB`` is enabled. - -Example 5: Overriding a disabled group via configuration --------------------------------------------------------- - -The entire manifest file is: - -.. code-block:: yaml - - manifest: - projects: - - name: foo - - name: bar - groups: - - groupA - - name: baz - groups: - - groupA - - groupB - - group-filter: [-groupA] - - defaults: - remote: example-remote - remotes: - - name: example-remote - url-base: https://git.example.com - -The ``manifest.group-filter`` configuration option is set to ``+groupA`` (you -can ensure this by running ``west config manifest.group-filter +groupA``). - -In this case, ``groupA`` is enabled: the ``manifest.group-filter`` -configuration option has higher precedence than the ``manifest: group-filter: -[-groupA]`` content in the manifest file. - -Therefore, projects ``foo`` and ``bar`` are both active. - -Example 6: Overriding multiple disabled groups via configuration ----------------------------------------------------------------- - -The entire manifest file is: - -.. code-block:: yaml - - manifest: - projects: - - name: foo - - name: bar - groups: - - groupA - - name: baz - groups: - - groupA - - groupB - - group-filter: [-groupA,-groupB] - - defaults: - remote: example-remote - remotes: - - name: example-remote - url-base: https://git.example.com - -The ``manifest.group-filter`` configuration option is set to -``+groupA,+groupB`` (you can ensure this by running ``west config -manifest.group-filter "+groupA,+groupB"``). - -In this case, both ``groupA`` and ``groupB`` are enabled, because the -configuration value overrides the manifest file for both groups. - -Therefore, projects ``foo`` and ``bar`` are both active. - -Example 7: Disabling multiple groups via configuration ------------------------------------------------------- - -The entire manifest file is: - -.. code-block:: yaml - - manifest: - projects: - - name: foo - - name: bar - groups: - - groupA - - name: baz - groups: - - groupA - - groupB - - defaults: - remote: example-remote - remotes: - - name: example-remote - url-base: https://git.example.com - -The ``manifest.group-filter`` configuration option is set to -``-groupA,-groupB`` (you can ensure this by running ``west config -manifest.group-filter -- "-groupA,-groupB"``). - -In this case, both ``groupA`` and ``groupB`` are disabled. - -Therefore, projects ``foo`` and ``bar`` are both inactive. - -.. _west-manifest-submodules: - -Git Submodules in Projects -************************** - -You can use the ``submodules`` keys briefly described :ref:`above -` to force ``west update`` to also handle any `Git -submodules`_ configured in project's git repository. The ``submodules`` key can -appear inside ``projects``, like this: - -.. code-block:: YAML - - manifest: - projects: - - name: some-project - submodules: ... - -The ``submodules`` key can be a boolean or a list of mappings. We'll describe -these in order. - -Option 1: Boolean -================= - -This is the easiest way to use ``submodules``. - -If ``submodules`` is ``true`` as a ``projects`` attribute, ``west update`` will -recursively update the project's Git submodules whenever it updates the project -itself. If it's ``false`` or missing, it has no effect. - -For example, let's say you have a source code repository ``foo``, which has -some submodules, and you want ``west update`` to keep all of them them in sync, -along with another project named ``bar`` in the same workspace. - -You can do that with this manifest file: - -.. code-block:: yaml - - manifest: - projects: - - name: foo - submodules: true - - name: bar - -Here, ``west update`` will initialize and update all submodules in ``foo``. If -``bar`` has any submodules, they are ignored, because ``bar`` does not have a -``submodules`` value. - -Option 2: List of mappings -========================== - -The ``submodules`` key may be a list of mappings. Each element in the list -defines the name of the submodule to update, and the path -- relative to the -project's absolute path in the workspace -- to use for the submodule. -The submodule will be updated recursively. - -For example, let's say you have a source code repository ``foo``, which has -many submodules, and you want ``west update`` to keep some but not all of them -in sync, along with another project named ``bar`` in the same workspace. - -You can do that with this manifest file: - -.. code-block:: yaml - - manifest: - projects: - - name: foo - submodules: - - name: foo-first-sub - path: path/to/foo-first-sub - - name: foo-second-sub - path: path/to/foo-second-sub - - name: bar - -Here, ``west update`` will recursively initialize and update just the -submodules in ``foo`` with paths ``path/to/foo-first-sub`` and -``path/to/foo-second-sub``. Any submodules in ``bar`` are still ignored. - .. _west-manifest-cmd: Manifest Command