michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: west fixes and updates to manifest.rst

Browse source 
Some of this information is stale and needs to be fixed.

Try to make a few other things clearer while we're here.

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Marti Bolivar 2019-10-07 13:43:35 -07:00 • committed by Anas Nashif
commit 52c7df6014
1 changed files with 90 additions and 106 deletions
Download patch file Download diff file Expand all files Collapse all files

196
doc/guides/west/manifest.rst
View file

@ -67,73 +67,32 @@ Notice the following important details:
Manifest Files Manifest Files
************** **************
A west manifest is a YAML file named :file:`west.yml`. Manifests have two A west manifest is a YAML file named :file:`west.yml`. Manifests have a
top-level "sections", ``west`` and ``manifest``, like this: top-level ``manifest`` section with some subsections, like this:
.. code-block:: yaml
west:
# contents of west section
manifest:
# contents of manifest section
In YAML terms, the manifest file contains a mapping, with two keys relevant to
west at top level. These keys are the scalar strings ``west`` and
``manifest``. Their contents are described next.
West Section
============
.. note::
Support for this feature will be removed in a future version of west, when
the west repository is no longer cloned into the installation.
The ``west`` section specifies the URL and revision of the west repository
which is cloned into the installation. For example:
.. code-block:: yaml
west:
url: https://example.com/west
revision: v0.5.6
This specifies cloning the west repository from URL
``https://example.com/west`` (any URL accepted by ``git clone`` will work), at
revision ``v0.5.6``. The revision can be a Git branch, tag, or SHA.
That is, the west section also contains a mapping, with permitted keys ``url``
and ``revision``. These specify the fetch URL and Git revision for the west
repository to clone into the installation, as described in
:ref:`west-struct`. If not given, the default URL is
https://github.com/zephyrproject-rtos/west, and the default revision is
``master``.
The file :file:`west-schema.yml` in the west source code repository contains a
pykwalify schema for this section's contents.
Manifest Section
================
This is the main section in the manifest file. There are four subsections:
``defaults``, ``remotes``, ``projects``, and ``self``. In YAML terms, the value
of the ``manifest`` key is also a mapping, with these "subsections" as keys.
For example:
.. code-block:: yaml .. code-block:: yaml
manifest: manifest:
defaults: defaults:
# contents of defaults subsection # default project attributes (optional)
remotes: remotes:
# contents of remotes subsection # short names for project URLs (optional)
projects: projects:
# contents of projects subsection # a list of projects managed by west (mandatory)
self: self:
# contents of self subsection # configuration related to the manifest repository itself,
# i.e. the repository containing west.yml (optional)
The ``remotes`` and ``projects`` subsections are the only mandatory ones, so In YAML terms, the manifest file contains a mapping, with a ``manifest``
we'll cover them first. key. Any other keys and their contents are ignored (west v0.5 also required a
``west`` key, but this is ignored starting with v0.6).
There are four subsections: ``defaults``, ``remotes``, ``projects``, and
``self``. In YAML terms, the value of the ``manifest`` key is also a mapping,
with these "subsections" as keys. Only ``projects`` is mandatory: this is the
list of repositories managed by west and their metadata.
We'll cover the ``remotes`` and ``projects`` subsections in detail first.
The ``remotes`` subsection contains a sequence which specifies the base URLs The ``remotes`` subsection contains a sequence which specifies the base URLs
where projects can be fetched from. Each sequence element has a name and a "URL where projects can be fetched from. Each sequence element has a name and a "URL
@ -156,82 +115,105 @@ bases are respectively ``https://example.com/base1`` and
you might use ``git@example.com:base1`` if ``remote1`` supported Git over SSH you might use ``git@example.com:base1`` if ``remote1`` supported Git over SSH
as well. Anything acceptable to Git will work. as well. Anything acceptable to Git will work.
The ``projects`` subsection contains a sequence describing the The ``projects`` subsection contains a sequence describing the project
project repositories in the west installation. Each project has a repositories in the west installation. Every project has a unique name. You can
name and a remote; the project's name is appended to the remote URL specify what Git remote URLs to use when cloning and fetching the projects,
base to form the Git fetch URL west uses to clone the project and keep what revisions to track, and where the project should be stored on the local
it up to date. Here is a simple example; we'll assume the ``remotes`` file system.
given above.
Here is an example. We'll assume the ``remotes`` given above.
.. Note: if you change this example, keep the equivalent manifest below in
sync.
.. code-block:: yaml .. code-block:: yaml
manifest: manifest:
# [...] # [... same remotes as above...]
projects: projects:
- name: proj1 - name: proj1
remote: remote1 remote: remote1
path: extra/project-1 path: extra/project-1
- name: proj2 - name: proj2
remote: remote1 repo-path: my-path
remote: remote2
revision: v1.3 revision: v1.3
- name: proj3 - name: proj3
remote: remote2 url: https://github.com/user/project-three
revision: abcde413a111 revision: abcde413a111
This example has three projects: In this manifest:
- ``proj1`` has remote ``remote1``, so its Git fetch URL is - ``proj1`` has remote ``remote1``, so its Git fetch URL is
``https://example.com/base1/proj1`` (note that west adds the ``/`` between ``https://example.com/base1/proj1``. The remote ``url-base`` is appended with
the URL base and project name). This project will be cloned at path a ``/`` and the project ``name`` to form the URL.
``extra/project-1`` relative to the west installation's root directory.
Since the project has no ``revision``, the current tip of the ``master``
branch will be checked out as a detached ``HEAD``.
- ``proj2`` has the same remote, so its fetch URL is Locally, this project will be cloned at path ``extra/project-1`` relative to
``https://example.com/base1/proj2``. Since the project has no ``path`` the west installation's root directory, since it has an explicit ``path``
specified, it will be cloned at ``proj2`` (i.e. a project's ``name`` is used attribute with this value.
as its default ``path``). The commit pointed to by the ``v1.3`` tag will be
checked out.
- ``proj3`` has fetch URL ``https://example.com/base2/proj3`` and will be Since the project has no ``revision`` specified, ``master`` is used by
cloned at path ``proj3``. Commit ``abcde413a111`` will be checked out. default. The current tip of this branch will be fetched and checked out as a
detached ``HEAD`` when west next updates this project.
Each element in the ``projects`` sequence can contain the following keys. Some - ``proj2`` has a ``remote`` and a ``repo-path``, so its fetch URL is
of the description refers to the ``defaults`` subsection, which will be ``https://example.com/base2/my-path``. The ``repo-path`` attribute, if
described next. present, overrides the default ``name`` when forming the fetch URL.
- ``name``: Mandatory, the name of the project. The fetch URL is formed as Since the project has no ``path`` attribute, its ``name`` is used by
remote url-base + '/' + ``name``. The name cannot be one of the reserved default. It will be cloned into a directory named ``proj2``. The commit
values "west" and "manifest". pointed to by the ``v1.3`` tag will be checked out when west updates the
- ``remote``: The name of the project's remote. If not given, the ``remote`` project.
value in the ``defaults`` subsection is tried next. If both are missing, the
- ``proj3`` has an explicit ``url``, so it will be fetched from
``https://github.com/user/project-three``.
Its local path defaults to its name, ``proj3``. Commit ``abcde413a111`` will
be checked out when it is next updated.
The list of project keys and their usage follows. Sometimes we'll refer to the
``defaults`` subsection; it will be described next.
- ``name``: Mandatory. the name of the project. The name cannot be one of the
reserved values "west" or "manifest". The name must be unique in the manifest
file.
- ``remote`` or ``url``: Mandatory (one of the two, but not both).
If the project has a ``remote``, that remote's ``url-base`` will be combined
with the project's ``name`` (or ``repo-path``, if it has one) to form the
fetch URL instead.
If the project has a ``url``, that's the complete fetch URL for the
remote Git repository.
If the project has neither, the ``defaults`` section must specify a
``remote``, which will be used as the the project's remote. Otherwise, the
manifest is invalid. manifest is invalid.
- ``repo-path``: Optional. If given, this is concatenated on to the remote's - ``repo-path``: Optional. If given, this is concatenated on to the remote's
``url-base`` instead of the project's ``name`` to form its fetch URL. ``url-base`` instead of the project's ``name`` to form its fetch URL.
- ``url``: Optional. If given, this is the project's complete fetch URL. Projects may not have both ``url`` and ``repo-path`` attributes.
It cannot be combined with either ``remote`` or ``repo-path``. Note that this - ``revision``: Optional. The Git revision that ``west update`` should check
overrides any default remote. out. This will be checked out as a detached HEAD by default, to avoid
- ``revision``: Optional. The current project revision used by ``west update``. conflicting with local branch names. If not given, the ``revision`` value
If not given, the value from the ``defaults`` subsection will be used if from the ``defaults`` subsection will be used if present.
present. If both are missing, ``master`` is used. A project revision can be
a branch, tag, or SHA. The names of unqualified branch and tag revisions are A project revision can be a branch, tag, or SHA. The default ``revision`` is
fetched as-is. For qualified refs, like ``refs/heads/foo``, the last ``master`` if not otherwise specified.
component (``foo``) is used. - ``path``: Optional. Relative path specifying where to clone the repository
- ``path``: Optional. Where to clone the repository locally. If missing, it's locally, relative to the top directory in the west installation. If missing,
cloned in the west installation's root subdirectory given by the project's the project's ``name`` is used as a directory name.
name.
- ``clone-depth``: Optional. If given, a positive integer which creates a - ``clone-depth``: Optional. If given, a positive integer which creates a
shallow history in the cloned repository limited to the given number of shallow history in the cloned repository limited to the given number of
commits. commits. This can only be used if the ``revision`` is a branch or tag.
- ``west-commands``: Optional. If given, a relative path to a YAML file within - ``west-commands``: Optional. If given, a relative path to a YAML file within
the project which describes additional west commands provided by that the project which describes additional west commands provided by that
project. This file is named :file:`west-commands.yml` by convention. See project. This file is named :file:`west-commands.yml` by convention. See
:ref:`west-extensions` for details. :ref:`west-extensions` for details.
The ``defaults`` subsection can provide default values for project-related The ``defaults`` subsection can provide default values for project
values. In particular, the default remote name and revision can be specified attributes. In particular, the default remote name and revision can be
here. Another way to write the same manifest we have been describing so far specified here. Another way to write the same manifest we have been describing
using ``defaults`` is: so far using ``defaults`` is:
.. code-block:: yaml .. code-block:: yaml
@ -251,8 +233,10 @@ using ``defaults`` is:
path: extra/project-1 path: extra/project-1
revision: master revision: master
- name: proj2 - name: proj2
- name: proj3 repo-path: my-path
remote: remote2 remote: remote2
- name: proj3
url: https://github.com/user/project-three
revision: abcde413a111 revision: abcde413a111
Finally, the ``self`` subsection can be used to control the behavior of the Finally, the ``self`` subsection can be used to control the behavior of the