doc: west: move advanced content out of 'basics'
With the documentation for west 0.9, the 'basics' page is completely out of control. Reorganize it so it fits in a few pages, moving many details out into other pages for the truly curious. As part of this, create new pages for built-in commands (built-in.rst) and esoteric details about workspaces (workspaces.rst). Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Martí Bolívar
Anas Nashif
parent
fbcdc82067
commit
353efd04b1
|
|
@ -77,19 +77,19 @@ Glossary of Terms
|
|||
west manifest
|
||||
A YAML file, usually named :file:`west.yml`, which describes projects, or
|
||||
the Git repositories which make up a :term:`west workspace`, along with
|
||||
additional metadata. See :ref:`west-multi-repo` for general information
|
||||
additional metadata. See :ref:`west-basics` for general information
|
||||
and :ref:`west-manifests` for details.
|
||||
|
||||
west manifest repository
|
||||
The Git repository in a :term:`west workspace` which contains the
|
||||
:term:`west manifest`. Its location is given by the :ref:`manifest.path
|
||||
configuration option <west-config-index>`. See :ref:`west-multi-repo`.
|
||||
configuration option <west-config-index>`. See :ref:`west-basics`.
|
||||
|
||||
west workspace
|
||||
A directory on your system with a :file:`.west` subdirectory and
|
||||
a :term:`west manifest repository`. You clone the Zephyr source
|
||||
code onto your system by creating a west workspace using the
|
||||
``west init`` command. See :ref:`west-multi-repo`.
|
||||
``west init`` command. See :ref:`west-basics`.
|
||||
|
||||
XIP
|
||||
(eXecute In Place) a method of executing programs directly from long
|
||||
|
|
|
|||
|
|
@ -98,7 +98,7 @@ by Zephyr are found in the parent `GitHub Zephyr project
|
|||
<https://github.com/zephyrproject-rtos/>`_. Because of these
|
||||
dependencies, it's convenient to use the Zephyr-created :ref:`west
|
||||
<west>` tool to fetch and manage the Zephyr and external module source
|
||||
code. See :ref:`west-multi-repo` for more details.
|
||||
code. See :ref:`west-basics` for more details.
|
||||
|
||||
Once your development tools are installed, use :ref:`west` to create,
|
||||
initialize, and download sources from the zephyr and external module
|
||||
|
|
|
|||
|
|
@ -400,7 +400,7 @@ your own.
|
|||
use other Zephyr modules provided by :ref:`west <west>`.
|
||||
This can for example be useful for special test purposes.
|
||||
|
||||
See the section about :ref:`west-multi-repo` for more details.
|
||||
See :ref:`west-basics` for more on west workspaces.
|
||||
|
||||
Finally, you can also specify the list of modules yourself in various ways, or
|
||||
not use modules at all if your application doesn't need them.
|
||||
|
|
@ -753,7 +753,7 @@ Using West
|
|||
|
||||
If west is installed and :makevar:`ZEPHYR_MODULES` is not already set, the
|
||||
build system finds all the modules in your :term:`west installation` and uses
|
||||
those. It does this by running :ref:`west list <west-multi-repo-misc>` to get
|
||||
those. It does this by running :ref:`west list <west-built-in-misc>` to get
|
||||
the paths of all the projects in the installation, then filters the results to
|
||||
just those projects which have the necessary module metadata files.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,19 +1,16 @@
|
|||
.. _west-multi-repo:
|
||||
.. _west-basics:
|
||||
|
||||
Basics
|
||||
######
|
||||
|
||||
This page introduces west's basic concepts and built-in commands along with
|
||||
references to further reading.
|
||||
|
||||
.. _west-workspace:
|
||||
|
||||
Introduction
|
||||
************
|
||||
This page introduces west's basic concepts and provides references to further
|
||||
reading.
|
||||
|
||||
West's built-in commands allow you to work with *projects* (Git
|
||||
repositories) under a common *workspace* directory. You can create a
|
||||
workspace using the :ref:`west-init` command.
|
||||
repositories) under a common *workspace* directory.
|
||||
|
||||
Example workspace
|
||||
*****************
|
||||
|
||||
If you've followed the upstream Zephyr getting started guide, your
|
||||
workspace looks like this:
|
||||
|
|
@ -32,668 +29,168 @@ workspace looks like this:
|
|||
├── net-tools/ # .git/ project
|
||||
└── [ ... other projects ...]
|
||||
|
||||
Above, :file:`zephyrproject` is the name of the workspace's top level
|
||||
directory, or *topdir*. (The name :file:`zephyrproject` is just an example
|
||||
-- it could be anything, like ``z``, ``my-zephyr-workspace``, etc.)
|
||||
.. _west-workspace:
|
||||
|
||||
The topdir contains the :file:`.west` directory. When west needs to find
|
||||
the topdir, it searches for :file:`.west`, and uses its parent directory.
|
||||
The search starts from the current working directory (and starts again from
|
||||
the location in the :envvar:`ZEPHYR_BASE` environment variable as a
|
||||
fallback if that fails). The file :file:`.west/config` is the workspace's
|
||||
:ref:`local configuration file <west-config>`.
|
||||
Workspace concepts
|
||||
******************
|
||||
|
||||
Every west workspace contains exactly one *manifest repository*, which is a
|
||||
Git repository containing a *manifest file*. The location of the manifest
|
||||
repository is given by the :ref:`manifest.path configuration option
|
||||
<west-config-index>` in the local configuration file.
|
||||
Here are the basic concepts you should understand about this structure.
|
||||
Additional details are in :ref:`west-workspaces`.
|
||||
|
||||
For upstream Zephyr, :file:`zephyr` is the manifest repository, but you can
|
||||
configure west to use any Git repository in the workspace as the manifest
|
||||
repository. The only requirement is that it contains a valid manifest file.
|
||||
See :ref:`west-topologies` for information on other options, and
|
||||
:ref:`west-manifests` for details on the manifest file format.
|
||||
topdir
|
||||
Above, :file:`zephyrproject` is the name of the workspace's top level
|
||||
directory, or *topdir*. (The name :file:`zephyrproject` is just an example
|
||||
-- it could be anything, like ``z``, ``my-zephyr-workspace``, etc.)
|
||||
|
||||
The manifest file is a YAML file that defines *projects*, which are the
|
||||
additional Git repositories in the workspace managed by west. The manifest
|
||||
file is named :file:`west.yml` by default; this can be overridden using the
|
||||
``manifest.file`` local configuration option.
|
||||
You'll typically create the topdir and a few other files and directories
|
||||
using :ref:`west init <west-init-basics>`.
|
||||
|
||||
You use the :ref:`west-update` command to update the workspace's projects
|
||||
based on the contents of the manifest file. The manifest file controls
|
||||
things like where the project should be placed within the workspace, what
|
||||
URL to clone it from if it's missing, and what Git revision should be
|
||||
checked out locally.
|
||||
.west directory
|
||||
The topdir contains the :file:`.west` directory. When west needs to find
|
||||
the topdir, it searches for :file:`.west`, and uses its parent directory.
|
||||
The search starts from the current working directory (and starts again from
|
||||
the location in the :envvar:`ZEPHYR_BASE` environment variable as a
|
||||
fallback if that fails).
|
||||
|
||||
Projects can be located anywhere inside the workspace, but they may not
|
||||
"escape" it. Project repositories need not be located in subdirectories of
|
||||
the manifest repository or as immediate subdirectories of the topdir.
|
||||
However, projects must have paths inside the workspace. (You may replace a
|
||||
project's repository directory within the workspace with a symbolic link to
|
||||
elsewhere on your computer, but west will not do this for you.)
|
||||
configuration file
|
||||
The file :file:`.west/config` is the workspace's :ref:`local configuration
|
||||
file <west-config>`.
|
||||
|
||||
A workspace can contain additional Git repositories or other files and
|
||||
directories not managed by west. West basically ignores anything in the
|
||||
workspace except :file:`.west`, the manifest repository, and the projects
|
||||
specified in the manifest file.
|
||||
manifest repository
|
||||
Every west workspace contains exactly one *manifest repository*, which is a
|
||||
Git repository containing a *manifest file*. The location of the manifest
|
||||
repository is given by the :ref:`manifest.path configuration option
|
||||
<west-config-index>` in the local configuration file.
|
||||
|
||||
For upstream Zephyr, ``tinycbor`` and ``net-tools`` are projects. They are
|
||||
specified in the manifest file :file:`zephyr/west.yml`. This file specifies
|
||||
that ``tinycbor`` is located in the :file:`modules/lib/tinycbor` directory
|
||||
beneath the workspace topdir. By default, the Zephyr :ref:`build system
|
||||
<build_overview>` uses west to get the locations of all the projects in the
|
||||
workspace, so any code they contain can be used as :ref:`modules`.
|
||||
For upstream Zephyr, :file:`zephyr` is the manifest repository, but you can
|
||||
configure west to use any Git repository in the workspace as the manifest
|
||||
repository. The only requirement is that it contains a valid manifest file.
|
||||
See :ref:`west-topologies` for information on other options, and
|
||||
:ref:`west-manifests` for details on the manifest file format.
|
||||
|
||||
Finally, any repository managed by a west workspace (either the manifest
|
||||
repository or any project repository) can define :ref:`west-extensions`.
|
||||
Extensions are extra commands not built into west that you can run when
|
||||
using that workspace.
|
||||
manifest file
|
||||
The manifest file is a YAML file that defines *projects*, which are the
|
||||
additional Git repositories in the workspace managed by west. The manifest
|
||||
file is named :file:`west.yml` by default; this can be overridden using the
|
||||
``manifest.file`` local configuration option.
|
||||
|
||||
The zephyr repository uses this feature to provide Zephyr-specific commands
|
||||
like :ref:`west build <west-building>`. Defining these as extensions keeps
|
||||
west's core agnostic to the specifics of any workspace's Zephyr version,
|
||||
etc.
|
||||
You use the :ref:`west update <west-update-basics>` command to update the
|
||||
workspace's projects based on the contents of the manifest file.
|
||||
|
||||
.. _west-struct:
|
||||
projects
|
||||
Projects are Git repositories managed by west. Projects are defined in the
|
||||
manifest file and can be located anywhere inside the workspace. In the above
|
||||
example workspace, ``tinycbor`` and ``net-tools`` are projects.
|
||||
|
||||
Structure
|
||||
*********
|
||||
By default, the Zephyr :ref:`build system <build_overview>` uses west to get
|
||||
the locations of all the projects in the workspace, so any code they contain
|
||||
can be used as :ref:`modules`.
|
||||
|
||||
West's code is distributed via PyPI in a Python package named ``west``.
|
||||
This distribution includes a launcher executable, which is also named
|
||||
``west`` (or ``west.exe`` on Windows).
|
||||
extensions
|
||||
Any repository known to west (either the manifest repository or any project
|
||||
repository) can define :ref:`west-extensions`. Extensions are extra west
|
||||
commands you can run when using that workspace.
|
||||
|
||||
When west is installed, the launcher is placed by :file:`pip3` somewhere in
|
||||
the user's filesystem (exactly where depends on the operating system, but
|
||||
should be on the ``PATH`` :ref:`environment variable <env_vars>`). This
|
||||
launcher is the command-line entry point to running both built-in commmands
|
||||
like ``west init``, ``west update``, along with any extensions discovered
|
||||
in the workspace.
|
||||
The zephyr repository uses this feature to provide Zephyr-specific commands
|
||||
like :ref:`west build <west-building>`. Defining these as extensions keeps
|
||||
west's core agnostic to the specifics of any workspace's Zephyr version,
|
||||
etc.
|
||||
|
||||
In addition to its command-line interface, you can also use west's Python
|
||||
APIs directly. See :ref:`west-apis` for details.
|
||||
ignored files
|
||||
A workspace can contain additional Git repositories or other files and
|
||||
directories not managed by west. West basically ignores anything in the
|
||||
workspace except :file:`.west`, the manifest repository, and the projects
|
||||
specified in the manifest file.
|
||||
|
||||
.. _west-manifest-rev:
|
||||
west init and west update
|
||||
*************************
|
||||
|
||||
The ``manifest-rev`` branch
|
||||
***************************
|
||||
The two most important workspace-related commands are ``west init`` and ``west
|
||||
update``.
|
||||
|
||||
West creates and controls a Git branch named ``manifest-rev`` in each
|
||||
project. This branch points to the revision that the manifest file
|
||||
specified for the project at the time :ref:`west-update` was last run.
|
||||
Other workspace management commands may use ``manifest-rev`` as a reference
|
||||
point for the upstream revision as of this latest update. Among other
|
||||
purposes, the ``manifest-rev`` branch allows the manifest file to use SHAs
|
||||
as project revisions.
|
||||
.. _west-init-basics:
|
||||
|
||||
Although ``manifest-rev`` is a normal Git branch, west will recreate and/or
|
||||
reset it on the next update. For this reason, it is **dangerous**
|
||||
to check it out or otherwise modify it yourself. For instance, any commits
|
||||
you manually add to this branch may be lost the next time you run ``west
|
||||
update``. Instead, check out a local branch with another name, and either
|
||||
rebase it on top of a new ``manifest-rev``, or merge ``manifest-rev`` into
|
||||
it.
|
||||
``west init`` basics
|
||||
--------------------
|
||||
|
||||
.. note::
|
||||
This command creates a west workspace.
|
||||
|
||||
West does not create a ``manifest-rev`` branch in the manifest repository,
|
||||
since west does not manage the manifest repository's branches or revisions.
|
||||
.. important::
|
||||
|
||||
The ``refs/west/*`` Git refs
|
||||
****************************
|
||||
West doesn't change your manifest repository contents after ``west init`` is
|
||||
run. Use ordinary Git commands to pull new versions, etc.
|
||||
|
||||
West also reserves all Git refs that begin with ``refs/west/`` (such as
|
||||
``refs/west/foo``) for itself in local project repositories. Unlike
|
||||
``manifest-rev``, these refs are not regular branches. West's behavior here is
|
||||
an implementation detail; users should not rely on these refs existence or
|
||||
behavior.
|
||||
You will typically run it once, like this:
|
||||
|
||||
.. _west-built-in-cmds:
|
||||
.. code-block:: shell
|
||||
|
||||
Built-in Commands
|
||||
west init -m https://github.com/zephyrproject-rtos/zephyr --mr v2.5.0 zephyrproject
|
||||
|
||||
This will:
|
||||
|
||||
#. Create the topdir, :file:`zephyrproject`, along with
|
||||
:file:`.west` and :file:`.west/config` inside it
|
||||
#. Clone the manifest repository from
|
||||
https://github.com/zephyrproject-rtos/zephyr, placing it into
|
||||
:file:`zephyrproject/zephyr`
|
||||
#. Check out the ``v2.5.0`` git tag in your local zephyr clone
|
||||
#. Set ``manifest.path`` to ``zephyr`` in :file:`.west/config`
|
||||
#. Set ``manifest.file`` to ``west.yml``
|
||||
|
||||
Your workspace is now almost ready to use; you just need to run ``west update``
|
||||
to clone the rest of the projects into the workspace to finish.
|
||||
|
||||
For more details, see :ref:`west-init`.
|
||||
|
||||
.. _west-update-basics:
|
||||
|
||||
``west update`` basics
|
||||
----------------------
|
||||
|
||||
This command makes sure your workspace contains Git repositories matching the
|
||||
projects in the manifest file.
|
||||
|
||||
.. important::
|
||||
|
||||
Whenever you check out a different revision in your manifest repository, you
|
||||
should run ``west update`` to make sure your workspace contains the
|
||||
project repositories the new revision expects.
|
||||
|
||||
The ``west update`` command reads the manifest file's contents by:
|
||||
|
||||
#. Finding the topdir. In the ``west init`` example above, that
|
||||
means finding :file:`zephyrproject`.
|
||||
#. Loading :file:`.west/config` in the topdir to read the ``manifest.path``
|
||||
(e.g. ``zephyr``) and ``manifest.file`` (e.g. ``west.yml``) options.
|
||||
#. Loading the manifest file given by these options (e.g.
|
||||
:file:`zephyrproject/zephyr/west.yml`).
|
||||
|
||||
It then uses the manifest file to decide where missing projects should be
|
||||
placed within the workspace, what URLs to clone them from, and what Git
|
||||
revisions should be checked out locally. Project repositories which already
|
||||
exist are updated in place by fetching and checking out their respective Git
|
||||
revisions in the manifest file.
|
||||
|
||||
For more details, see :ref:`west-update`.
|
||||
|
||||
Other built-in commands
|
||||
***********************
|
||||
|
||||
See :ref:`west-built-in-cmds`.
|
||||
|
||||
.. _west-zephyr-extensions:
|
||||
|
||||
Zephyr Extensions
|
||||
*****************
|
||||
|
||||
This section gives an overview of west's built-in commands.
|
||||
See the following pages for information on Zephyr's extension commands:
|
||||
|
||||
Some commands are related to Git commands with the same name, but operate
|
||||
on the entire workspace. For example, ``west diff`` shows local changes in
|
||||
multiple Git repositories in the workspace.
|
||||
|
||||
Some commands take projects as arguments. These arguments can be project
|
||||
names as specified in the manifest file, or (as a fallback) paths to them
|
||||
on the local file system. Omitting project arguments to commands which
|
||||
accept them (such as ``west list``, ``west forall``, etc.) usually defaults
|
||||
to using all projects in the manifest file plus the manifest repository
|
||||
itself.
|
||||
|
||||
The following documentation does not exhaustively describe all commands.
|
||||
For additional help, run ``west <command> -h`` (e.g. ``west init -h``).
|
||||
|
||||
.. _west-init:
|
||||
|
||||
``west init``
|
||||
=============
|
||||
|
||||
This command creates a west workspace. It can be used in two ways:
|
||||
|
||||
1. Cloning a new manifest repository from a remote URL
|
||||
2. Creating a workspace around an existing local manifest repository
|
||||
|
||||
**Option 1**: to clone a new manifest repository from a remote URL, use:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west init [-m URL] [--mr REVISION] [--mf FILE] [directory]
|
||||
|
||||
The new workspace is created in the given :file:`directory`, creating a new
|
||||
:file:`.west` inside this directory. You can give the manifest URL using
|
||||
the ``-m`` switch, the initial revision to check out using ``--mr``, and
|
||||
the location of the manifest file within the repository using ``--mf``.
|
||||
|
||||
For example, running:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
west init -m https://github.com/zephyrproject-rtos/zephyr --mr v1.14.0 zp
|
||||
|
||||
would clone the upstream official zephyr repository into :file:`zp/zephyr`,
|
||||
and check out the ``v1.14.0`` release. This command creates
|
||||
:file:`zp/.west`, and set the ``manifest.path`` :ref:`configuration option
|
||||
<west-config>` to ``zephyr`` to record the location of the manifest
|
||||
repository in the workspace. The default manifest file location is used.
|
||||
|
||||
The ``-m`` option defaults to
|
||||
``https://github.com/zephyrproject-rtos/zephyr``. The ``--mr`` option
|
||||
defaults to ``master``. The ``--mf`` option defaults to ``west.yml``. If no
|
||||
``directory`` is given, the current working directory is used.
|
||||
|
||||
**Option 2**: to create a workspace around an existing local manifest
|
||||
repository, use:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west init -l [--mf FILE] directory
|
||||
|
||||
This creates :file:`.west` **next to** :file:`directory` in the file
|
||||
system, and sets ``manifest.path`` to ``directory``.
|
||||
|
||||
As above, ``--mf`` defaults to ``west.yml``.
|
||||
|
||||
The ``west init`` command does not clone any of the projects defined in the
|
||||
manifest file, regardless of whether ``-l`` is given. To do that, use
|
||||
``west update``.
|
||||
|
||||
.. _west-update:
|
||||
|
||||
``west update``
|
||||
---------------
|
||||
|
||||
This command clones and updates the projects specified in the :term:`west
|
||||
manifest` file.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west update [-f {always,smart}] [-k] [-r]
|
||||
[--group-filter FILTER] [--stats] [PROJECT ...]
|
||||
|
||||
**Which projects are updated:**
|
||||
|
||||
By default, this command parses the manifest file, usually
|
||||
:file:`west.yml`, and updates each project specified there.
|
||||
If your manifest uses :ref:`project groups <west-manifest-groups>`, then
|
||||
only the active projects are updated.
|
||||
|
||||
To operate on a subset of projects only, give ``PROJECT`` argument(s). Each
|
||||
``PROJECT`` is either a project name as given in the manifest file, or a
|
||||
path that points to the project within the workspace. If you specify
|
||||
projects explicitly, they are updated regardless of whether they are active.
|
||||
|
||||
**Project update procedure:**
|
||||
|
||||
For each project that is updated, this command:
|
||||
|
||||
#. Initializes a local Git repository for the project in the workspace, if
|
||||
it does not already exist
|
||||
#. Inspects the project's ``revision`` field in the manifest, and fetches
|
||||
it from the remote if it is not already available locally
|
||||
#. Sets the project's :ref:`manifest-rev <west-manifest-rev>` branch to the
|
||||
commit specified by the revision in the previous step.
|
||||
#. Checks out ``manifest-rev`` in the local working copy as a `detached
|
||||
HEADs <https://git-scm.com/docs/git-checkout#_detached_head>`_
|
||||
#. If the manifest file specifies a :ref:`submodules
|
||||
<west-manifest-submodules>` key for the project, recursively updates
|
||||
the project's submodules as described below.
|
||||
|
||||
To avoid unnecessary fetches, ``west update`` will not fetch project
|
||||
``revision`` values which are Git SHAs or tags that are already available
|
||||
locally. This is the behavior when the ``-f`` (``--fetch``) option has its
|
||||
default value, ``smart``. To force this command to fetch from project remotes
|
||||
even if the revisions appear to be available locally, either use ``-f always``
|
||||
or set the ``update.fetch`` :ref:`configuration option <west-config>` to
|
||||
``always``. SHAs may be given as unique prefixes as long as they are acceptable
|
||||
to Git [#fetchall]_.
|
||||
|
||||
If the project ``revision`` is a Git ref that is not a tag nor a SHA (i.e.
|
||||
if the project is tracking a branch), ``west update`` always fetches,
|
||||
regardless of ``-f`` and ``update.fetch``.
|
||||
|
||||
Some branch names might look like short SHAs, like ``deadbeef``. You can
|
||||
always disambiguate this situation by prefixing the ``revision`` value with
|
||||
``refs/heads/``, e.g. ``revision: refs/heads/deadbeef``.
|
||||
|
||||
For safety, ``west update`` uses ``git checkout --detach`` to check out a
|
||||
detached ``HEAD`` at the manifest revision for each updated project,
|
||||
leaving behind any branches which were already checked out. This is
|
||||
typically a safe operation that will not modify any of your local branches.
|
||||
|
||||
However, if you had added some local commits onto a previously detached
|
||||
``HEAD`` checked out by west, then git will warn you that you've left
|
||||
behind some commits which are no longer referred to by any branch. These
|
||||
may be garbage-collected and lost at some point in the future. To avoid
|
||||
this if you have local commits in the project, make sure you have a local
|
||||
branch checked out before running ``west update``.
|
||||
|
||||
If you would rather rebase any locally checked out branches instead, use
|
||||
the ``-r`` (``--rebase``) option.
|
||||
|
||||
If you would like ``west update`` to keep local branches checked out as
|
||||
long as they point to commits that are descendants of the new
|
||||
``manifest-rev``, use the ``-k`` (``--keep-descendants``) option.
|
||||
|
||||
.. note::
|
||||
|
||||
``west update --rebase`` will fail in projects that have git conflicts
|
||||
between your branch and new commits brought in by the manifest. You
|
||||
should immediately resolve these conflicts as you usually do with
|
||||
``git``, or you can use ``git -C <project_path> rebase --abort`` to
|
||||
ignore incoming changes for the moment.
|
||||
|
||||
With a clean working tree, a plain ``west update`` never fails
|
||||
because it does not try to hold on to your commits and simply
|
||||
leaves them aside.
|
||||
|
||||
``west update --keep-descendants`` offers an intermediate option that
|
||||
never fails either but does not treat all projects the same:
|
||||
|
||||
- in projects where your branch diverged from the incoming commits, it
|
||||
does not even try to rebase and leaves your branches behind just like a
|
||||
plain ``west update`` does;
|
||||
- in all other projects where no rebase or merge is needed it keeps
|
||||
your branches in place.
|
||||
|
||||
**One-time project group manipulation:**
|
||||
|
||||
The ``--group-filter`` option can be used to change which project groups
|
||||
are enabled or disabled for the duration of a single ``west update`` command.
|
||||
See :ref:`west-manifest-groups` for details on the project group feature.
|
||||
|
||||
The ``west update`` command behaves as if the ``--group-filter`` option's
|
||||
value were appended to the ``manifest.group-filter``
|
||||
:ref:`configuration option <west-config-index>`.
|
||||
|
||||
For example, running ``west update --group-filter=+foo,-bar`` would behave
|
||||
the same way as if you had temporarily appended the string ``"+foo,-bar"``
|
||||
to the value of ``manifest.group-filter``, run ``west update``, then restored
|
||||
``manifest.group-filter`` to its original value.
|
||||
|
||||
Note that using the syntax ``--group-filter=VALUE`` instead of
|
||||
``--group-filter VALUE`` avoids issues parsing command line options
|
||||
if you just want to disable a single group, e.g. ``--group-filter=-bar``.
|
||||
|
||||
**Submodule update procedure:**
|
||||
|
||||
If a project in the manifest has a ``submodules`` key, the submodules are
|
||||
updated as follows, depending on the value of the ``submodules`` key.
|
||||
|
||||
If the project has ``submodules: true``, west runs one of the following in
|
||||
the project repository, depending on whether you run ``west update``
|
||||
with the ``--rebase`` option or without it:
|
||||
|
||||
.. code-block::
|
||||
|
||||
# without --rebase, e.g. "west update":
|
||||
git submodule update init --checkout --recursive
|
||||
|
||||
# with --rebase, e.g. "west update --rebase":
|
||||
git submodule update init --rebase --recursive
|
||||
|
||||
Otherwise, the project has ``submodules: <list-of-submodules>``. In this
|
||||
case, west runs one of the following in the project repository for each
|
||||
submodule path in the list, depending on whether you run ``west update``
|
||||
with the ``--rebase`` option or without it:
|
||||
|
||||
.. code-block::
|
||||
|
||||
# without --rebase, e.g. "west update":
|
||||
git submodule update init --checkout --recursive <submodule-path>
|
||||
|
||||
# with --rebase, e.g. "west update --rebase":
|
||||
git submodule update init --rebase --recursive <submodule-path>
|
||||
|
||||
.. _west-multi-repo-misc:
|
||||
|
||||
Other Repository Management Commands
|
||||
====================================
|
||||
|
||||
West has a few more commands for managing the repositories in the
|
||||
workspace, which are summarized here. Run ``west <command> -h`` for
|
||||
detailed help.
|
||||
|
||||
- ``west list``: print a line of information about each project in the
|
||||
manifest, according to a format string
|
||||
- ``west manifest``: manage the manifest file. See :ref:`west-manifest-cmd`.
|
||||
- ``west diff``: run ``git diff`` in local project repositories
|
||||
- ``west status``: run ``git status`` in local project repositories
|
||||
- ``west forall``: run an arbitrary command in local project repositories
|
||||
|
||||
Additional Commands
|
||||
===================
|
||||
|
||||
Finally, here is a summary of other built-in commands.
|
||||
|
||||
- ``west config``: get or set :ref:`configuration options <west-config>`
|
||||
- ``west topdir``: print the top level directory of the west workspace
|
||||
- ``west help``: get help about a command, or print information about all
|
||||
commands in the workspace, including :ref:`west-extensions`
|
||||
|
||||
.. _west-topologies:
|
||||
|
||||
Topologies supported
|
||||
********************
|
||||
|
||||
The following are example source code topologies supported by west.
|
||||
|
||||
- T1: star topology, zephyr is the manifest repository
|
||||
- T2: star topology, a Zephyr application is the manifest repository
|
||||
- T3: forest topology, freestanding manifest repository
|
||||
|
||||
T1: Star topology, zephyr is the manifest repository
|
||||
====================================================
|
||||
|
||||
- The zephyr repository acts as the central repository and specifies
|
||||
its :ref:`modules` in its :file:`west.yml`
|
||||
- Analogy with existing mechanisms: Git submodules with zephyr as the
|
||||
super-project
|
||||
|
||||
This is the default. See :ref:`west-workspace` for how mainline Zephyr is an
|
||||
example of this topology.
|
||||
|
||||
.. _west-t2:
|
||||
|
||||
T2: Star topology, application is the manifest repository
|
||||
=========================================================
|
||||
|
||||
- Useful for those focused on a single application
|
||||
- A repository containing a Zephyr application acts as the central repository
|
||||
and names other projects required to build it in its :file:`west.yml`. This
|
||||
includes the zephyr repository and any modules.
|
||||
- Analogy with existing mechanisms: Git submodules with the application as
|
||||
the super-project, zephyr and other projects as submodules
|
||||
|
||||
A workspace using this topology looks like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west-workspace/
|
||||
│
|
||||
├── application/ # .git/ │
|
||||
│ ├── CMakeLists.txt │
|
||||
│ ├── prj.conf │ never modified by west
|
||||
│ ├── src/ │
|
||||
│ │ └── main.c │
|
||||
│ └── west.yml # main manifest with optional import(s) and override(s)
|
||||
│ │
|
||||
├── modules/
|
||||
│ └── lib/
|
||||
│ └── tinycbor/ # .git/ project from either the main manifest or some import.
|
||||
│
|
||||
└── zephyr/ # .git/ project
|
||||
└── west.yml # This can be partially imported with lower precedence or ignored.
|
||||
# Only the 'manifest-rev' version can be imported.
|
||||
|
||||
|
||||
Here is an example :file:`application/west.yml` which uses
|
||||
:ref:`west-manifest-import`, available since west 0.7, to import Zephyr v2.2.0
|
||||
and its modules into the application manifest file:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example T2 west.yml, using manifest imports.
|
||||
manifest:
|
||||
remotes:
|
||||
- name: zephyrproject-rtos
|
||||
url-base: https://github.com/zephyrproject-rtos
|
||||
projects:
|
||||
- name: zephyr
|
||||
remote: zephyrproject-rtos
|
||||
revision: v2.2.0
|
||||
import: true
|
||||
self:
|
||||
path: application
|
||||
|
||||
You can still selectively "override" individual Zephyr modules if you use
|
||||
``import:`` in this way; see :ref:`west-manifest-ex1.3` for an example.
|
||||
|
||||
Another way to do the same thing is to copy/paste :file:`zephyr/west.yml`
|
||||
to :file:`application/west.yml`, adding an entry for the zephyr
|
||||
project itself, like this:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Equivalent to the above, but with manually maintained Zephyr modules.
|
||||
manifest:
|
||||
remotes:
|
||||
- name: zephyrproject-rtos
|
||||
url-base: https://github.com/zephyrproject-rtos
|
||||
defaults:
|
||||
remote: zephyrproject-rtos
|
||||
projects:
|
||||
- name: zephyr
|
||||
revision: v2.2.0
|
||||
west-commands: scripts/west-commands.yml
|
||||
- name: net-tools
|
||||
revision: some-sha-goes-here
|
||||
path: tools/net-tools
|
||||
# ... other Zephyr modules go here ...
|
||||
self:
|
||||
path: application
|
||||
|
||||
(The ``west-commands`` is there for :ref:`west-build-flash-debug` and other
|
||||
Zephyr-specific :ref:`west-extensions`. It's not necessary when using
|
||||
``import``.)
|
||||
|
||||
The main advantage to using ``import`` is not having to track the revisions of
|
||||
imported projects separately. In the above example, using ``import`` means
|
||||
Zephyr's :ref:`module <modules>` versions are automatically determined from the
|
||||
:file:`zephyr/west.yml` revision, instead of having to be copy/pasted (and
|
||||
maintained) on their own.
|
||||
|
||||
T3: Forest topology
|
||||
===================
|
||||
|
||||
- Useful for those supporting multiple independent applications or downstream
|
||||
distributions with no "central" repository
|
||||
- A dedicated manifest repository which contains no Zephyr source code,
|
||||
and specifies a list of projects all at the same "level"
|
||||
- Analogy with existing mechanisms: Google repo-based source distribution
|
||||
|
||||
A workspace using this topology looks like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west-workspace/
|
||||
├── app1/ # .git/ project
|
||||
│ ├── CMakeLists.txt
|
||||
│ ├── prj.conf
|
||||
│ └── src/
|
||||
│ └── main.c
|
||||
├── app2/ # .git/ project
|
||||
│ ├── CMakeLists.txt
|
||||
│ ├── prj.conf
|
||||
│ └── src/
|
||||
│ └── main.c
|
||||
├── manifest-repo/ # .git/ never modified by west
|
||||
│ └── west.yml # main manifest with optional import(s) and override(s)
|
||||
├── modules/
|
||||
│ └── lib/
|
||||
│ └── tinycbor/ # .git/ project from either the main manifest or
|
||||
│ # frome some import
|
||||
│
|
||||
└── zephyr/ # .git/ project
|
||||
└── west.yml # This can be partially imported with lower precedence or ignored.
|
||||
# Only the 'manifest-rev' version can be imported.
|
||||
|
||||
|
||||
Here is an example T3 :file:`manifest-repo/west.yml` which uses
|
||||
:ref:`west-manifest-import`, available since west 0.7, to import Zephyr
|
||||
v2.2.0 and its modules, then add the ``app1`` and ``app2`` projects:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
manifest:
|
||||
remotes:
|
||||
- name: zephyrproject-rtos
|
||||
url-base: https://github.com/zephyrproject-rtos
|
||||
- name: your-git-server
|
||||
url-base: https://git.example.com/your-company
|
||||
defaults:
|
||||
remote: your-git-server
|
||||
projects:
|
||||
- name: zephyr
|
||||
remote: zephyrproject-rtos
|
||||
revision: v2.2.0
|
||||
import: true
|
||||
- name: app1
|
||||
revision: SOME_SHA_OR_BRANCH_OR_TAG
|
||||
- name: app2
|
||||
revision: ANOTHER_SHA_OR_BRANCH_OR_TAG
|
||||
self:
|
||||
path: manifest-repo
|
||||
|
||||
You can also do this "by hand" by copy/pasting :file:`zephyr/west.yml`
|
||||
as shown :ref:`above <west-t2>` for the T2 topology, with the same caveats.
|
||||
|
||||
Private repositories
|
||||
********************
|
||||
|
||||
You can use west to fetch from private repositories. There is nothing
|
||||
west-specific about this.
|
||||
|
||||
The ``west update`` command essentially runs ``git fetch YOUR_PROJECT_URL``
|
||||
when a project's ``manifest-rev`` branch must be updated to a newly fetched
|
||||
commit. It's up to your environment to make sure the fetch succeeds.
|
||||
|
||||
You can either enter the password manually or use any of the `credential
|
||||
helpers built in to Git`_. Since Git has credential storage built in, there is
|
||||
no need for a west-specific feature.
|
||||
|
||||
The following sections cover common cases for running ``west update`` without
|
||||
having to enter your password, as well as how to troubleshoot issues.
|
||||
|
||||
.. _credential helpers built in to Git:
|
||||
https://git-scm.com/docs/gitcredentials
|
||||
|
||||
Fetching via HTTPS
|
||||
==================
|
||||
|
||||
On Windows when fetching from GitHub, recent versions of Git prompt you for
|
||||
your GitHub password in a graphical window once, then store it for future use
|
||||
(in a default installation). Passwordless fetching from GitHub should therefore
|
||||
work "out of the box" on Windows after you have done it once.
|
||||
|
||||
In general, you can store your credentials on disk using the "store" git
|
||||
credential helper. See the `git-credential-store`_ manual page for details.
|
||||
|
||||
To use this helper for all the repositories in your workspace, run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
west forall -c "git config credential.helper store"
|
||||
|
||||
To use this helper on just the projects ``foo`` and ``bar``, run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
west forall -c "git config credential.helper store" foo bar
|
||||
|
||||
To use this helper by default on your computer, run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git config --global credential.helper store
|
||||
|
||||
On GitHub, you can set up a `personal access token`_ to use in place of your
|
||||
account password. (This may be required if your account has two-factor
|
||||
authentication enabled, and may be preferable to storing your account password
|
||||
in plain text even if two-factor authentication is disabed.)
|
||||
|
||||
If you don't want to store any credentials on the file system, you can store
|
||||
them in memory temporarily using `git-credential-cache`_ instead.
|
||||
|
||||
.. _git-credential-store:
|
||||
https://git-scm.com/docs/git-credential-store#_examples
|
||||
.. _git-credential-cache:
|
||||
https://git-scm.com/docs/git-credential-cache
|
||||
.. _personal access token:
|
||||
https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
|
||||
|
||||
Fetching via SSH
|
||||
================
|
||||
|
||||
If your SSH key has no password, fetching should just work. If it does have a
|
||||
password, you can avoid entering it manually every time using `ssh-agent`_.
|
||||
|
||||
On GitHub, see `Connecting to GitHub with SSH`_ for details on configuration
|
||||
and key creation.
|
||||
|
||||
.. _ssh-agent:
|
||||
https://www.ssh.com/ssh/agent
|
||||
.. _Connecting to GitHub with SSH:
|
||||
https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh
|
||||
- :ref:`west-build-flash-debug`
|
||||
- :ref:`west-sign`
|
||||
- :ref:`west-zephyr-ext-cmds`
|
||||
- :ref:`west-shell-completion`
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
***************
|
||||
|
||||
One good way to troubleshoot fetching issues is to run ``west update`` in
|
||||
verbose mode, like this:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
west -v update
|
||||
|
||||
The output includes Git commands run by west and their outputs. Look for
|
||||
something like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
=== updating your_project (path/to/your/project):
|
||||
west.manifest: your_project: checking if cloned
|
||||
[...other west.manifest logs...]
|
||||
--- your_project: fetching, need revision SOME_SHA
|
||||
west.manifest: running 'git fetch ... https://github.com/your-username/your_project ...' in /some/directory
|
||||
|
||||
The ``git fetch`` command example in the last line above is what needs to
|
||||
succeed. Go to ``/some/directory``, copy/paste and run the entire ``git fetch``
|
||||
command, then debug from there using the documentation for your credential
|
||||
storage helper.
|
||||
|
||||
If you can get the ``git fetch`` command to run successfully without prompting
|
||||
for a password when you run it directly, you will be able to run ``west
|
||||
update`` without entering your password in that same shell.
|
||||
|
||||
.. _PyPI:
|
||||
https://pypi.org/project/west/
|
||||
|
||||
.. _Zephyr issue #6770:
|
||||
https://github.com/zephyrproject-rtos/zephyr/issues/6770
|
||||
|
||||
.. _namespace package:
|
||||
https://www.python.org/dev/peps/pep-0420/
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#fetchall]
|
||||
|
||||
West may fetch all refs from the Git server when given a SHA as a revision.
|
||||
This is because some Git servers have historically not allowed fetching
|
||||
SHAs directly.
|
||||
See :ref:`west-troubleshooting`.
|
||||
|
|
|
|||
255
doc/guides/west/built-in.rst
Normal file
255
doc/guides/west/built-in.rst
Normal file
|
|
@ -0,0 +1,255 @@
|
|||
.. _west-built-in-cmds:
|
||||
|
||||
Built-in commands
|
||||
#################
|
||||
|
||||
This page describes west's built-in commands, some of which were introduced in
|
||||
:ref:`west-basics`, in more detail.
|
||||
|
||||
Some commands are related to Git commands with the same name, but operate
|
||||
on the entire workspace. For example, ``west diff`` shows local changes in
|
||||
multiple Git repositories in the workspace.
|
||||
|
||||
Some commands take projects as arguments. These arguments can be project
|
||||
names as specified in the manifest file, or (as a fallback) paths to them
|
||||
on the local file system. Omitting project arguments to commands which
|
||||
accept them (such as ``west list``, ``west forall``, etc.) usually defaults
|
||||
to using all projects in the manifest file plus the manifest repository
|
||||
itself.
|
||||
|
||||
For additional help, run ``west <command> -h`` (e.g. ``west init -h``).
|
||||
|
||||
.. _west-init:
|
||||
|
||||
west init
|
||||
*********
|
||||
|
||||
This command creates a west workspace. It can be used in two ways:
|
||||
|
||||
1. Cloning a new manifest repository from a remote URL
|
||||
2. Creating a workspace around an existing local manifest repository
|
||||
|
||||
**Option 1**: to clone a new manifest repository from a remote URL, use:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west init [-m URL] [--mr REVISION] [--mf FILE] [directory]
|
||||
|
||||
The new workspace is created in the given :file:`directory`, creating a new
|
||||
:file:`.west` inside this directory. You can give the manifest URL using
|
||||
the ``-m`` switch, the initial revision to check out using ``--mr``, and
|
||||
the location of the manifest file within the repository using ``--mf``.
|
||||
|
||||
For example, running:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
west init -m https://github.com/zephyrproject-rtos/zephyr --mr v1.14.0 zp
|
||||
|
||||
would clone the upstream official zephyr repository into :file:`zp/zephyr`,
|
||||
and check out the ``v1.14.0`` release. This command creates
|
||||
:file:`zp/.west`, and set the ``manifest.path`` :ref:`configuration option
|
||||
<west-config>` to ``zephyr`` to record the location of the manifest
|
||||
repository in the workspace. The default manifest file location is used.
|
||||
|
||||
The ``-m`` option defaults to
|
||||
``https://github.com/zephyrproject-rtos/zephyr``. The ``--mr`` option
|
||||
defaults to ``master``. The ``--mf`` option defaults to ``west.yml``. If no
|
||||
``directory`` is given, the current working directory is used.
|
||||
|
||||
**Option 2**: to create a workspace around an existing local manifest
|
||||
repository, use:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west init -l [--mf FILE] directory
|
||||
|
||||
This creates :file:`.west` **next to** :file:`directory` in the file
|
||||
system, and sets ``manifest.path`` to ``directory``.
|
||||
|
||||
As above, ``--mf`` defaults to ``west.yml``.
|
||||
|
||||
**Reconfiguring the workspace**:
|
||||
|
||||
If you change your mind later, you are free to change ``manifest.path`` and
|
||||
``manifest.file`` using :ref:`west-config-cmd` after running ``west init``.
|
||||
Just be sure to run ``west update`` afterwards to update your workspace to
|
||||
match the new manifest file.
|
||||
|
||||
.. _west-update:
|
||||
|
||||
west update
|
||||
***********
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west update [-f {always,smart}] [-k] [-r]
|
||||
[--group-filter FILTER] [--stats] [PROJECT ...]
|
||||
|
||||
**Which projects are updated:**
|
||||
|
||||
By default, this command parses the manifest file, usually
|
||||
:file:`west.yml`, and updates each project specified there.
|
||||
If your manifest uses :ref:`project groups <west-manifest-groups>`, then
|
||||
only the active projects are updated.
|
||||
|
||||
To operate on a subset of projects only, give ``PROJECT`` argument(s). Each
|
||||
``PROJECT`` is either a project name as given in the manifest file, or a
|
||||
path that points to the project within the workspace. If you specify
|
||||
projects explicitly, they are updated regardless of whether they are active.
|
||||
|
||||
**Project update procedure:**
|
||||
|
||||
For each project that is updated, this command:
|
||||
|
||||
#. Initializes a local Git repository for the project in the workspace, if
|
||||
it does not already exist
|
||||
#. Inspects the project's ``revision`` field in the manifest, and fetches
|
||||
it from the remote if it is not already available locally
|
||||
#. Sets the project's :ref:`manifest-rev <west-manifest-rev>` branch to the
|
||||
commit specified by the revision in the previous step
|
||||
#. Checks out ``manifest-rev`` in the local working copy as a `detached
|
||||
HEAD <https://git-scm.com/docs/git-checkout#_detached_head>`_
|
||||
#. If the manifest file specifies a :ref:`submodules
|
||||
<west-manifest-submodules>` key for the project, recursively updates
|
||||
the project's submodules as described below.
|
||||
|
||||
To avoid unnecessary fetches, ``west update`` will not fetch project
|
||||
``revision`` values which are Git SHAs or tags that are already available
|
||||
locally. This is the behavior when the ``-f`` (``--fetch``) option has its
|
||||
default value, ``smart``. To force this command to fetch from project remotes
|
||||
even if the revisions appear to be available locally, either use ``-f always``
|
||||
or set the ``update.fetch`` :ref:`configuration option <west-config>` to
|
||||
``always``. SHAs may be given as unique prefixes as long as they are acceptable
|
||||
to Git [#fetchall]_.
|
||||
|
||||
If the project ``revision`` is a Git ref that is neither a tag nor a SHA (i.e.
|
||||
if the project is tracking a branch), ``west update`` always fetches,
|
||||
regardless of ``-f`` and ``update.fetch``.
|
||||
|
||||
Some branch names might look like short SHAs, like ``deadbeef``. West treats
|
||||
these like SHAs. You can disambiguate by prefixing the ``revision`` value with
|
||||
``refs/heads/``, e.g. ``revision: refs/heads/deadbeef``.
|
||||
|
||||
For safety, ``west update`` uses ``git checkout --detach`` to check out a
|
||||
detached ``HEAD`` at the manifest revision for each updated project,
|
||||
leaving behind any branches which were already checked out. This is
|
||||
typically a safe operation that will not modify any of your local branches.
|
||||
|
||||
However, if you had added some local commits onto a previously detached
|
||||
``HEAD`` checked out by west, then git will warn you that you've left
|
||||
behind some commits which are no longer referred to by any branch. These
|
||||
may be garbage-collected and lost at some point in the future. To avoid
|
||||
this if you have local commits in the project, make sure you have a local
|
||||
branch checked out before running ``west update``.
|
||||
|
||||
If you would rather rebase any locally checked out branches instead, use
|
||||
the ``-r`` (``--rebase``) option.
|
||||
|
||||
If you would like ``west update`` to keep local branches checked out as
|
||||
long as they point to commits that are descendants of the new
|
||||
``manifest-rev``, use the ``-k`` (``--keep-descendants``) option.
|
||||
|
||||
.. note::
|
||||
|
||||
``west update --rebase`` will fail in projects that have git conflicts
|
||||
between your branch and new commits brought in by the manifest. You
|
||||
should immediately resolve these conflicts as you usually do with
|
||||
``git``, or you can use ``git -C <project_path> rebase --abort`` to
|
||||
ignore incoming changes for the moment.
|
||||
|
||||
With a clean working tree, a plain ``west update`` never fails
|
||||
because it does not try to hold on to your commits and simply
|
||||
leaves them aside.
|
||||
|
||||
``west update --keep-descendants`` offers an intermediate option that
|
||||
never fails either but does not treat all projects the same:
|
||||
|
||||
- in projects where your branch diverged from the incoming commits, it
|
||||
does not even try to rebase and leaves your branches behind just like a
|
||||
plain ``west update`` does;
|
||||
- in all other projects where no rebase or merge is needed it keeps
|
||||
your branches in place.
|
||||
|
||||
**One-time project group manipulation:**
|
||||
|
||||
The ``--group-filter`` option can be used to change which project groups
|
||||
are enabled or disabled for the duration of a single ``west update`` command.
|
||||
See :ref:`west-manifest-groups` for details on the project group feature.
|
||||
|
||||
The ``west update`` command behaves as if the ``--group-filter`` option's
|
||||
value were appended to the ``manifest.group-filter``
|
||||
:ref:`configuration option <west-config-index>`.
|
||||
|
||||
For example, running ``west update --group-filter=+foo,-bar`` would behave
|
||||
the same way as if you had temporarily appended the string ``"+foo,-bar"``
|
||||
to the value of ``manifest.group-filter``, run ``west update``, then restored
|
||||
``manifest.group-filter`` to its original value.
|
||||
|
||||
Note that using the syntax ``--group-filter=VALUE`` instead of
|
||||
``--group-filter VALUE`` avoids issues parsing command line options
|
||||
if you just want to disable a single group, e.g. ``--group-filter=-bar``.
|
||||
|
||||
**Submodule update procedure:**
|
||||
|
||||
If a project in the manifest has a ``submodules`` key, the submodules are
|
||||
updated as follows, depending on the value of the ``submodules`` key.
|
||||
|
||||
If the project has ``submodules: true``, west runs one of the following in
|
||||
the project repository, depending on whether you run ``west update``
|
||||
with the ``--rebase`` option or without it:
|
||||
|
||||
.. code-block::
|
||||
|
||||
# without --rebase, e.g. "west update":
|
||||
git submodule update init --checkout --recursive
|
||||
|
||||
# with --rebase, e.g. "west update --rebase":
|
||||
git submodule update init --rebase --recursive
|
||||
|
||||
Otherwise, the project has ``submodules: <list-of-submodules>``. In this
|
||||
case, west runs one of the following in the project repository for each
|
||||
submodule path in the list, depending on whether you run ``west update``
|
||||
with the ``--rebase`` option or without it:
|
||||
|
||||
.. code-block::
|
||||
|
||||
# without --rebase, e.g. "west update":
|
||||
git submodule update init --checkout --recursive <submodule-path>
|
||||
|
||||
# with --rebase, e.g. "west update --rebase":
|
||||
git submodule update init --rebase --recursive <submodule-path>
|
||||
|
||||
.. _west-built-in-misc:
|
||||
|
||||
Other project commands
|
||||
**********************
|
||||
|
||||
West has a few more commands for managing the projects in the
|
||||
workspace, which are summarized here. Run ``west <command> -h`` for
|
||||
detailed help.
|
||||
|
||||
- ``west list``: print a line of information about each project in the
|
||||
manifest, according to a format string
|
||||
- ``west manifest``: manage the manifest file. See :ref:`west-manifest-cmd`.
|
||||
- ``west diff``: run ``git diff`` in local project repositories
|
||||
- ``west status``: run ``git status`` in local project repositories
|
||||
- ``west forall``: run an arbitrary command in local project repositories
|
||||
|
||||
Other built-in commands
|
||||
***********************
|
||||
|
||||
Finally, here is a summary of other built-in commands.
|
||||
|
||||
- ``west config``: get or set :ref:`configuration options <west-config>`
|
||||
- ``west topdir``: print the top level directory of the west workspace
|
||||
- ``west help``: get help about a command, or print information about all
|
||||
commands in the workspace, including :ref:`west-extensions`
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#fetchall]
|
||||
|
||||
West may fetch all refs from the Git server when given a SHA as a revision.
|
||||
This is because some Git servers have historically not allowed fetching
|
||||
SHAs directly.
|
||||
|
|
@ -56,8 +56,8 @@ settings, and so on.
|
|||
|
||||
.. _west-config-cmd:
|
||||
|
||||
West ``config`` Command
|
||||
-----------------------
|
||||
west config
|
||||
-----------
|
||||
|
||||
The built-in ``config`` command can be used to get and set configuration
|
||||
values. You can pass ``west config`` the options ``--system``, ``--global``, or
|
||||
|
|
|
|||
|
|
@ -36,6 +36,8 @@ context about the tool.
|
|||
release-notes.rst
|
||||
troubleshooting.rst
|
||||
basics.rst
|
||||
built-in.rst
|
||||
workspaces.rst
|
||||
manifest.rst
|
||||
config.rst
|
||||
extensions.rst
|
||||
|
|
|
|||
|
|
@ -24,6 +24,25 @@ binary and related files were installed.
|
|||
Once west is installed, you can use it to :ref:`clone the Zephyr repositories
|
||||
<clone-zephyr>`.
|
||||
|
||||
.. _west-struct:
|
||||
|
||||
Structure
|
||||
*********
|
||||
|
||||
West's code is distributed via PyPI in a Python package named ``west``.
|
||||
This distribution includes a launcher executable, which is also named
|
||||
``west`` (or ``west.exe`` on Windows).
|
||||
|
||||
When west is installed, the launcher is placed by :file:`pip3` somewhere in
|
||||
the user's filesystem (exactly where depends on the operating system, but
|
||||
should be on the ``PATH`` :ref:`environment variable <env_vars>`). This
|
||||
launcher is the command-line entry point to running both built-in commmands
|
||||
like ``west init``, ``west update``, along with any extensions discovered
|
||||
in the workspace.
|
||||
|
||||
In addition to its command-line interface, you can also use west's Python
|
||||
APIs directly. See :ref:`west-apis` for details.
|
||||
|
||||
.. _west-shell-completion:
|
||||
|
||||
Enabling shell completion
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ West Manifests
|
|||
This page contains detailed information about west's multiple repository model,
|
||||
manifest files, and the ``west manifest`` command. For API documentation on the
|
||||
``west.manifest`` module, see :ref:`west-apis-manifest`. For a more general
|
||||
introduction and command overview, see :ref:`west-multi-repo`.
|
||||
introduction and command overview, see :ref:`west-basics`.
|
||||
|
||||
.. only:: html
|
||||
|
||||
|
|
|
|||
|
|
@ -136,7 +136,7 @@ Additional user-visible changes:
|
|||
- The "west config" command can now be run outside of a workspace, e.g.
|
||||
to run ``west config --global section.key value`` to set a configuration
|
||||
option's value globally.
|
||||
- There is a new :ref:`west topdir <west-multi-repo-misc>` command, which
|
||||
- There is a new :ref:`west topdir <west-built-in-misc>` command, which
|
||||
prints the root directory of the current west workspace.
|
||||
- The ``west -vv init`` command now prints the git operations being performed,
|
||||
and their results.
|
||||
|
|
@ -225,9 +225,9 @@ The user-visible features in this point release are:
|
|||
projects. All of them also now report a nonzero error code from the west
|
||||
process if any of these subprocesses fails (this was previously not true of
|
||||
``west forall`` in particular).
|
||||
- The :ref:`west manifest <west-multi-repo-misc>` command also handles errors
|
||||
- The :ref:`west manifest <west-built-in-misc>` command also handles errors
|
||||
better.
|
||||
- The :ref:`west list <west-multi-repo-misc>` command now works even when the
|
||||
- The :ref:`west list <west-built-in-misc>` command now works even when the
|
||||
projects are not cloned, as long as its format string only requires
|
||||
information which can be read from the manifest file. It still fails if the
|
||||
format string requires data stored in the project repository, e.g. if it
|
||||
|
|
|
|||
|
|
@ -5,6 +5,36 @@ Troubleshooting West
|
|||
|
||||
This page covers common issues with west and how to solve them.
|
||||
|
||||
``west update`` fetching failures
|
||||
*********************************
|
||||
|
||||
One good way to troubleshoot fetching issues is to run ``west update`` in
|
||||
verbose mode, like this:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
west -v update
|
||||
|
||||
The output includes Git commands run by west and their outputs. Look for
|
||||
something like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
=== updating your_project (path/to/your/project):
|
||||
west.manifest: your_project: checking if cloned
|
||||
[...other west.manifest logs...]
|
||||
--- your_project: fetching, need revision SOME_SHA
|
||||
west.manifest: running 'git fetch ... https://github.com/your-username/your_project ...' in /some/directory
|
||||
|
||||
The ``git fetch`` command example in the last line above is what needs to
|
||||
succeed. Go to ``/some/directory``, copy/paste and run the entire ``git fetch``
|
||||
command, then debug from there using the documentation for your credential
|
||||
storage helper.
|
||||
|
||||
If you can get the ``git fetch`` command to run successfully without prompting
|
||||
for a password when you run it directly, you will be able to run ``west
|
||||
update`` without entering your password in that same shell.
|
||||
|
||||
"'west' is not recognized as an internal or external command, operable program or batch file.'
|
||||
**********************************************************************************************
|
||||
|
||||
|
|
|
|||
|
|
@ -79,8 +79,8 @@ repositories in a standardized manner within the project:
|
|||
* Enforcement of modularization of the components
|
||||
* Out-of-tree development based on subsets of the supported boards and SoCs
|
||||
|
||||
See :ref:`west-multi-repo` for a detailed explanation of west's handling of
|
||||
multiple repository management.
|
||||
See :ref:`west-basics` for information on how west workspaces manage multiple
|
||||
git repositories.
|
||||
|
||||
.. _west-design-constraints:
|
||||
|
||||
|
|
|
|||
309
doc/guides/west/workspaces.rst
Normal file
309
doc/guides/west/workspaces.rst
Normal file
|
|
@ -0,0 +1,309 @@
|
|||
.. _west-workspaces:
|
||||
|
||||
Workspaces
|
||||
##########
|
||||
|
||||
This page describes the *west workspace* concept introduced in
|
||||
:ref:`west-basics` in more detail.
|
||||
|
||||
.. _west-manifest-rev:
|
||||
|
||||
The ``manifest-rev`` branch
|
||||
***************************
|
||||
|
||||
West creates and controls a Git branch named ``manifest-rev`` in each
|
||||
project. This branch points to the revision that the manifest file
|
||||
specified for the project at the time :ref:`west-update` was last run.
|
||||
Other workspace management commands may use ``manifest-rev`` as a reference
|
||||
point for the upstream revision as of this latest update. Among other
|
||||
purposes, the ``manifest-rev`` branch allows the manifest file to use SHAs
|
||||
as project revisions.
|
||||
|
||||
Although ``manifest-rev`` is a normal Git branch, west will recreate and/or
|
||||
reset it on the next update. For this reason, it is **dangerous**
|
||||
to check it out or otherwise modify it yourself. For instance, any commits
|
||||
you manually add to this branch may be lost the next time you run ``west
|
||||
update``. Instead, check out a local branch with another name, and either
|
||||
rebase it on top of a new ``manifest-rev``, or merge ``manifest-rev`` into
|
||||
it.
|
||||
|
||||
.. note::
|
||||
|
||||
West does not create a ``manifest-rev`` branch in the manifest repository,
|
||||
since west does not manage the manifest repository's branches or revisions.
|
||||
|
||||
The ``refs/west/*`` Git refs
|
||||
****************************
|
||||
|
||||
West also reserves all Git refs that begin with ``refs/west/`` (such as
|
||||
``refs/west/foo``) for itself in local project repositories. Unlike
|
||||
``manifest-rev``, these refs are not regular branches. West's behavior here is
|
||||
an implementation detail; users should not rely on these refs' existence or
|
||||
behavior.
|
||||
|
||||
Private repositories
|
||||
********************
|
||||
|
||||
You can use west to fetch from private repositories. There is nothing
|
||||
west-specific about this.
|
||||
|
||||
The ``west update`` command essentially runs ``git fetch YOUR_PROJECT_URL``
|
||||
when a project's ``manifest-rev`` branch must be updated to a newly fetched
|
||||
commit. It's up to your environment to make sure the fetch succeeds.
|
||||
|
||||
You can either enter the password manually or use any of the `credential
|
||||
helpers built in to Git`_. Since Git has credential storage built in, there is
|
||||
no need for a west-specific feature.
|
||||
|
||||
The following sections cover common cases for running ``west update`` without
|
||||
having to enter your password, as well as how to troubleshoot issues.
|
||||
|
||||
.. _credential helpers built in to Git:
|
||||
https://git-scm.com/docs/gitcredentials
|
||||
|
||||
Fetching via HTTPS
|
||||
==================
|
||||
|
||||
On Windows when fetching from GitHub, recent versions of Git prompt you for
|
||||
your GitHub password in a graphical window once, then store it for future use
|
||||
(in a default installation). Passwordless fetching from GitHub should therefore
|
||||
work "out of the box" on Windows after you have done it once.
|
||||
|
||||
In general, you can store your credentials on disk using the "store" git
|
||||
credential helper. See the `git-credential-store`_ manual page for details.
|
||||
|
||||
To use this helper for all the repositories in your workspace, run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
west forall -c "git config credential.helper store"
|
||||
|
||||
To use this helper on just the projects ``foo`` and ``bar``, run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
west forall -c "git config credential.helper store" foo bar
|
||||
|
||||
To use this helper by default on your computer, run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git config --global credential.helper store
|
||||
|
||||
On GitHub, you can set up a `personal access token`_ to use in place of your
|
||||
account password. (This may be required if your account has two-factor
|
||||
authentication enabled, and may be preferable to storing your account password
|
||||
in plain text even if two-factor authentication is disabed.)
|
||||
|
||||
If you don't want to store any credentials on the file system, you can store
|
||||
them in memory temporarily using `git-credential-cache`_ instead.
|
||||
|
||||
.. _git-credential-store:
|
||||
https://git-scm.com/docs/git-credential-store#_examples
|
||||
.. _git-credential-cache:
|
||||
https://git-scm.com/docs/git-credential-cache
|
||||
.. _personal access token:
|
||||
https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
|
||||
|
||||
Fetching via SSH
|
||||
================
|
||||
|
||||
If your SSH key has no password, fetching should just work. If it does have a
|
||||
password, you can avoid entering it manually every time using `ssh-agent`_.
|
||||
|
||||
On GitHub, see `Connecting to GitHub with SSH`_ for details on configuration
|
||||
and key creation.
|
||||
|
||||
.. _ssh-agent:
|
||||
https://www.ssh.com/ssh/agent
|
||||
.. _Connecting to GitHub with SSH:
|
||||
https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh
|
||||
|
||||
Project locations
|
||||
*****************
|
||||
|
||||
Projects can be located anywhere inside the workspace, but they may not
|
||||
"escape" it.
|
||||
|
||||
In other words, project repositories need not be located in subdirectories of
|
||||
the manifest repository or as immediate subdirectories of the topdir. However,
|
||||
projects must have paths inside the workspace.
|
||||
|
||||
You may replace a project's repository directory within the workspace with a
|
||||
symbolic link to elsewhere on your computer, but west will not do this for you.
|
||||
|
||||
.. _west-topologies:
|
||||
|
||||
Topologies supported
|
||||
********************
|
||||
|
||||
The following are example source code topologies supported by west.
|
||||
|
||||
- T1: star topology, zephyr is the manifest repository
|
||||
- T2: star topology, a Zephyr application is the manifest repository
|
||||
- T3: forest topology, freestanding manifest repository
|
||||
|
||||
T1: Star topology, zephyr is the manifest repository
|
||||
====================================================
|
||||
|
||||
- The zephyr repository acts as the central repository and specifies
|
||||
its :ref:`modules` in its :file:`west.yml`
|
||||
- Analogy with existing mechanisms: Git submodules with zephyr as the
|
||||
super-project
|
||||
|
||||
This is the default. See :ref:`west-workspace` for how mainline Zephyr is an
|
||||
example of this topology.
|
||||
|
||||
.. _west-t2:
|
||||
|
||||
T2: Star topology, application is the manifest repository
|
||||
=========================================================
|
||||
|
||||
- Useful for those focused on a single application
|
||||
- A repository containing a Zephyr application acts as the central repository
|
||||
and names other projects required to build it in its :file:`west.yml`. This
|
||||
includes the zephyr repository and any modules.
|
||||
- Analogy with existing mechanisms: Git submodules with the application as
|
||||
the super-project, zephyr and other projects as submodules
|
||||
|
||||
A workspace using this topology looks like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west-workspace/
|
||||
│
|
||||
├── application/ # .git/ │
|
||||
│ ├── CMakeLists.txt │
|
||||
│ ├── prj.conf │ never modified by west
|
||||
│ ├── src/ │
|
||||
│ │ └── main.c │
|
||||
│ └── west.yml # main manifest with optional import(s) and override(s)
|
||||
│ │
|
||||
├── modules/
|
||||
│ └── lib/
|
||||
│ └── tinycbor/ # .git/ project from either the main manifest or some import.
|
||||
│
|
||||
└── zephyr/ # .git/ project
|
||||
└── west.yml # This can be partially imported with lower precedence or ignored.
|
||||
# Only the 'manifest-rev' version can be imported.
|
||||
|
||||
|
||||
Here is an example :file:`application/west.yml` which uses
|
||||
:ref:`west-manifest-import`, available since west 0.7, to import Zephyr v2.2.0
|
||||
and its modules into the application manifest file:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example T2 west.yml, using manifest imports.
|
||||
manifest:
|
||||
remotes:
|
||||
- name: zephyrproject-rtos
|
||||
url-base: https://github.com/zephyrproject-rtos
|
||||
projects:
|
||||
- name: zephyr
|
||||
remote: zephyrproject-rtos
|
||||
revision: v2.2.0
|
||||
import: true
|
||||
self:
|
||||
path: application
|
||||
|
||||
You can still selectively "override" individual Zephyr modules if you use
|
||||
``import:`` in this way; see :ref:`west-manifest-ex1.3` for an example.
|
||||
|
||||
Another way to do the same thing is to copy/paste :file:`zephyr/west.yml`
|
||||
to :file:`application/west.yml`, adding an entry for the zephyr
|
||||
project itself, like this:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Equivalent to the above, but with manually maintained Zephyr modules.
|
||||
manifest:
|
||||
remotes:
|
||||
- name: zephyrproject-rtos
|
||||
url-base: https://github.com/zephyrproject-rtos
|
||||
defaults:
|
||||
remote: zephyrproject-rtos
|
||||
projects:
|
||||
- name: zephyr
|
||||
revision: v2.2.0
|
||||
west-commands: scripts/west-commands.yml
|
||||
- name: net-tools
|
||||
revision: some-sha-goes-here
|
||||
path: tools/net-tools
|
||||
# ... other Zephyr modules go here ...
|
||||
self:
|
||||
path: application
|
||||
|
||||
(The ``west-commands`` is there for :ref:`west-build-flash-debug` and other
|
||||
Zephyr-specific :ref:`west-extensions`. It's not necessary when using
|
||||
``import``.)
|
||||
|
||||
The main advantage to using ``import`` is not having to track the revisions of
|
||||
imported projects separately. In the above example, using ``import`` means
|
||||
Zephyr's :ref:`module <modules>` versions are automatically determined from the
|
||||
:file:`zephyr/west.yml` revision, instead of having to be copy/pasted (and
|
||||
maintained) on their own.
|
||||
|
||||
T3: Forest topology
|
||||
===================
|
||||
|
||||
- Useful for those supporting multiple independent applications or downstream
|
||||
distributions with no "central" repository
|
||||
- A dedicated manifest repository which contains no Zephyr source code,
|
||||
and specifies a list of projects all at the same "level"
|
||||
- Analogy with existing mechanisms: Google repo-based source distribution
|
||||
|
||||
A workspace using this topology looks like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
west-workspace/
|
||||
├── app1/ # .git/ project
|
||||
│ ├── CMakeLists.txt
|
||||
│ ├── prj.conf
|
||||
│ └── src/
|
||||
│ └── main.c
|
||||
├── app2/ # .git/ project
|
||||
│ ├── CMakeLists.txt
|
||||
│ ├── prj.conf
|
||||
│ └── src/
|
||||
│ └── main.c
|
||||
├── manifest-repo/ # .git/ never modified by west
|
||||
│ └── west.yml # main manifest with optional import(s) and override(s)
|
||||
├── modules/
|
||||
│ └── lib/
|
||||
│ └── tinycbor/ # .git/ project from either the main manifest or
|
||||
│ # from some import
|
||||
│
|
||||
└── zephyr/ # .git/ project
|
||||
└── west.yml # This can be partially imported with lower precedence or ignored.
|
||||
# Only the 'manifest-rev' version can be imported.
|
||||
|
||||
Here is an example T3 :file:`manifest-repo/west.yml` which uses
|
||||
:ref:`west-manifest-import`, available since west 0.7, to import Zephyr
|
||||
v2.2.0 and its modules, then add the ``app1`` and ``app2`` projects:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
manifest:
|
||||
remotes:
|
||||
- name: zephyrproject-rtos
|
||||
url-base: https://github.com/zephyrproject-rtos
|
||||
- name: your-git-server
|
||||
url-base: https://git.example.com/your-company
|
||||
defaults:
|
||||
remote: your-git-server
|
||||
projects:
|
||||
- name: zephyr
|
||||
remote: zephyrproject-rtos
|
||||
revision: v2.2.0
|
||||
import: true
|
||||
- name: app1
|
||||
revision: SOME_SHA_OR_BRANCH_OR_TAG
|
||||
- name: app2
|
||||
revision: ANOTHER_SHA_OR_BRANCH_OR_TAG
|
||||
self:
|
||||
path: manifest-repo
|
||||
|
||||
You can also do this "by hand" by copy/pasting :file:`zephyr/west.yml`
|
||||
as shown :ref:`above <west-t2>` for the T2 topology, with the same caveats.
|
||||
Loading…
Reference in a new issue