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
|
west manifest
|
||||||
A YAML file, usually named :file:`west.yml`, which describes projects, or
|
A YAML file, usually named :file:`west.yml`, which describes projects, or
|
||||||
the Git repositories which make up a :term:`west workspace`, along with
|
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.
|
and :ref:`west-manifests` for details.
|
||||||
|
|
||||||
west manifest repository
|
west manifest repository
|
||||||
The Git repository in a :term:`west workspace` which contains the
|
The Git repository in a :term:`west workspace` which contains the
|
||||||
:term:`west manifest`. Its location is given by the :ref:`manifest.path
|
: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
|
west workspace
|
||||||
A directory on your system with a :file:`.west` subdirectory and
|
A directory on your system with a :file:`.west` subdirectory and
|
||||||
a :term:`west manifest repository`. You clone the Zephyr source
|
a :term:`west manifest repository`. You clone the Zephyr source
|
||||||
code onto your system by creating a west workspace using the
|
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
|
XIP
|
||||||
(eXecute In Place) a method of executing programs directly from long
|
(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
|
<https://github.com/zephyrproject-rtos/>`_. Because of these
|
||||||
dependencies, it's convenient to use the Zephyr-created :ref:`west
|
dependencies, it's convenient to use the Zephyr-created :ref:`west
|
||||||
<west>` tool to fetch and manage the Zephyr and external module source
|
<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,
|
Once your development tools are installed, use :ref:`west` to create,
|
||||||
initialize, and download sources from the zephyr and external module
|
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>`.
|
use other Zephyr modules provided by :ref:`west <west>`.
|
||||||
This can for example be useful for special test purposes.
|
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
|
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.
|
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
|
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
|
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
|
the paths of all the projects in the installation, then filters the results to
|
||||||
just those projects which have the necessary module metadata files.
|
just those projects which have the necessary module metadata files.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,19 +1,16 @@
|
||||||
.. _west-multi-repo:
|
.. _west-basics:
|
||||||
|
|
||||||
Basics
|
Basics
|
||||||
######
|
######
|
||||||
|
|
||||||
This page introduces west's basic concepts and built-in commands along with
|
This page introduces west's basic concepts and provides references to further
|
||||||
references to further reading.
|
reading.
|
||||||
|
|
||||||
.. _west-workspace:
|
|
||||||
|
|
||||||
Introduction
|
|
||||||
************
|
|
||||||
|
|
||||||
West's built-in commands allow you to work with *projects* (Git
|
West's built-in commands allow you to work with *projects* (Git
|
||||||
repositories) under a common *workspace* directory. You can create a
|
repositories) under a common *workspace* directory.
|
||||||
workspace using the :ref:`west-init` command.
|
|
||||||
|
Example workspace
|
||||||
|
*****************
|
||||||
|
|
||||||
If you've followed the upstream Zephyr getting started guide, your
|
If you've followed the upstream Zephyr getting started guide, your
|
||||||
workspace looks like this:
|
workspace looks like this:
|
||||||
|
|
@ -32,668 +29,168 @@ workspace looks like this:
|
||||||
├── net-tools/ # .git/ project
|
├── net-tools/ # .git/ project
|
||||||
└── [ ... other projects ...]
|
└── [ ... other projects ...]
|
||||||
|
|
||||||
Above, :file:`zephyrproject` is the name of the workspace's top level
|
.. _west-workspace:
|
||||||
directory, or *topdir*. (The name :file:`zephyrproject` is just an example
|
|
||||||
-- it could be anything, like ``z``, ``my-zephyr-workspace``, etc.)
|
|
||||||
|
|
||||||
The topdir contains the :file:`.west` directory. When west needs to find
|
Workspace concepts
|
||||||
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>`.
|
|
||||||
|
|
||||||
Every west workspace contains exactly one *manifest repository*, which is a
|
Here are the basic concepts you should understand about this structure.
|
||||||
Git repository containing a *manifest file*. The location of the manifest
|
Additional details are in :ref:`west-workspaces`.
|
||||||
repository is given by the :ref:`manifest.path configuration option
|
|
||||||
<west-config-index>` in the local configuration file.
|
|
||||||
|
|
||||||
For upstream Zephyr, :file:`zephyr` is the manifest repository, but you can
|
topdir
|
||||||
configure west to use any Git repository in the workspace as the manifest
|
Above, :file:`zephyrproject` is the name of the workspace's top level
|
||||||
repository. The only requirement is that it contains a valid manifest file.
|
directory, or *topdir*. (The name :file:`zephyrproject` is just an example
|
||||||
See :ref:`west-topologies` for information on other options, and
|
-- it could be anything, like ``z``, ``my-zephyr-workspace``, etc.)
|
||||||
:ref:`west-manifests` for details on the manifest file format.
|
|
||||||
|
|
||||||
The manifest file is a YAML file that defines *projects*, which are the
|
You'll typically create the topdir and a few other files and directories
|
||||||
additional Git repositories in the workspace managed by west. The manifest
|
using :ref:`west init <west-init-basics>`.
|
||||||
file is named :file:`west.yml` by default; this can be overridden using the
|
|
||||||
``manifest.file`` local configuration option.
|
|
||||||
|
|
||||||
You use the :ref:`west-update` command to update the workspace's projects
|
.west directory
|
||||||
based on the contents of the manifest file. The manifest file controls
|
The topdir contains the :file:`.west` directory. When west needs to find
|
||||||
things like where the project should be placed within the workspace, what
|
the topdir, it searches for :file:`.west`, and uses its parent directory.
|
||||||
URL to clone it from if it's missing, and what Git revision should be
|
The search starts from the current working directory (and starts again from
|
||||||
checked out locally.
|
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
|
configuration file
|
||||||
"escape" it. Project repositories need not be located in subdirectories of
|
The file :file:`.west/config` is the workspace's :ref:`local configuration
|
||||||
the manifest repository or as immediate subdirectories of the topdir.
|
file <west-config>`.
|
||||||
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.)
|
|
||||||
|
|
||||||
A workspace can contain additional Git repositories or other files and
|
manifest repository
|
||||||
directories not managed by west. West basically ignores anything in the
|
Every west workspace contains exactly one *manifest repository*, which is a
|
||||||
workspace except :file:`.west`, the manifest repository, and the projects
|
Git repository containing a *manifest file*. The location of the manifest
|
||||||
specified in the manifest file.
|
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
|
For upstream Zephyr, :file:`zephyr` is the manifest repository, but you can
|
||||||
specified in the manifest file :file:`zephyr/west.yml`. This file specifies
|
configure west to use any Git repository in the workspace as the manifest
|
||||||
that ``tinycbor`` is located in the :file:`modules/lib/tinycbor` directory
|
repository. The only requirement is that it contains a valid manifest file.
|
||||||
beneath the workspace topdir. By default, the Zephyr :ref:`build system
|
See :ref:`west-topologies` for information on other options, and
|
||||||
<build_overview>` uses west to get the locations of all the projects in the
|
:ref:`west-manifests` for details on the manifest file format.
|
||||||
workspace, so any code they contain can be used as :ref:`modules`.
|
|
||||||
|
|
||||||
Finally, any repository managed by a west workspace (either the manifest
|
manifest file
|
||||||
repository or any project repository) can define :ref:`west-extensions`.
|
The manifest file is a YAML file that defines *projects*, which are the
|
||||||
Extensions are extra commands not built into west that you can run when
|
additional Git repositories in the workspace managed by west. The manifest
|
||||||
using that workspace.
|
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
|
You use the :ref:`west update <west-update-basics>` command to update the
|
||||||
like :ref:`west build <west-building>`. Defining these as extensions keeps
|
workspace's projects based on the contents of the manifest file.
|
||||||
west's core agnostic to the specifics of any workspace's Zephyr version,
|
|
||||||
etc.
|
|
||||||
|
|
||||||
.. _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``.
|
extensions
|
||||||
This distribution includes a launcher executable, which is also named
|
Any repository known to west (either the manifest repository or any project
|
||||||
``west`` (or ``west.exe`` on Windows).
|
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 zephyr repository uses this feature to provide Zephyr-specific commands
|
||||||
the user's filesystem (exactly where depends on the operating system, but
|
like :ref:`west build <west-building>`. Defining these as extensions keeps
|
||||||
should be on the ``PATH`` :ref:`environment variable <env_vars>`). This
|
west's core agnostic to the specifics of any workspace's Zephyr version,
|
||||||
launcher is the command-line entry point to running both built-in commmands
|
etc.
|
||||||
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
|
ignored files
|
||||||
APIs directly. See :ref:`west-apis` for details.
|
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
|
.. _west-init-basics:
|
||||||
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
|
``west init`` basics
|
||||||
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::
|
This command creates a west workspace.
|
||||||
|
|
||||||
West does not create a ``manifest-rev`` branch in the manifest repository,
|
.. important::
|
||||||
since west does not manage the manifest repository's branches or revisions.
|
|
||||||
|
|
||||||
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
|
You will typically run it once, like this:
|
||||||
``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.
|
|
||||||
|
|
||||||
.. _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
|
- :ref:`west-build-flash-debug`
|
||||||
on the entire workspace. For example, ``west diff`` shows local changes in
|
- :ref:`west-sign`
|
||||||
multiple Git repositories in the workspace.
|
- :ref:`west-zephyr-ext-cmds`
|
||||||
|
- :ref:`west-shell-completion`
|
||||||
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
|
|
||||||
|
|
||||||
Troubleshooting
|
Troubleshooting
|
||||||
===============
|
***************
|
||||||
|
|
||||||
One good way to troubleshoot fetching issues is to run ``west update`` in
|
See :ref:`west-troubleshooting`.
|
||||||
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.
|
|
||||||
|
|
|
||||||
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-cmd:
|
||||||
|
|
||||||
West ``config`` Command
|
west config
|
||||||
-----------------------
|
-----------
|
||||||
|
|
||||||
The built-in ``config`` command can be used to get and set configuration
|
The built-in ``config`` command can be used to get and set configuration
|
||||||
values. You can pass ``west config`` the options ``--system``, ``--global``, or
|
values. You can pass ``west config`` the options ``--system``, ``--global``, or
|
||||||
|
|
|
||||||
|
|
@ -36,6 +36,8 @@ context about the tool.
|
||||||
release-notes.rst
|
release-notes.rst
|
||||||
troubleshooting.rst
|
troubleshooting.rst
|
||||||
basics.rst
|
basics.rst
|
||||||
|
built-in.rst
|
||||||
|
workspaces.rst
|
||||||
manifest.rst
|
manifest.rst
|
||||||
config.rst
|
config.rst
|
||||||
extensions.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
|
Once west is installed, you can use it to :ref:`clone the Zephyr repositories
|
||||||
<clone-zephyr>`.
|
<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:
|
.. _west-shell-completion:
|
||||||
|
|
||||||
Enabling shell completion
|
Enabling shell completion
|
||||||
|
|
|
||||||
|
|
@ -6,7 +6,7 @@ West Manifests
|
||||||
This page contains detailed information about west's multiple repository model,
|
This page contains detailed information about west's multiple repository model,
|
||||||
manifest files, and the ``west manifest`` command. For API documentation on the
|
manifest files, and the ``west manifest`` command. For API documentation on the
|
||||||
``west.manifest`` module, see :ref:`west-apis-manifest`. For a more general
|
``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
|
.. only:: html
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -136,7 +136,7 @@ Additional user-visible changes:
|
||||||
- The "west config" command can now be run outside of a workspace, e.g.
|
- 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
|
to run ``west config --global section.key value`` to set a configuration
|
||||||
option's value globally.
|
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.
|
prints the root directory of the current west workspace.
|
||||||
- The ``west -vv init`` command now prints the git operations being performed,
|
- The ``west -vv init`` command now prints the git operations being performed,
|
||||||
and their results.
|
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
|
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
|
process if any of these subprocesses fails (this was previously not true of
|
||||||
``west forall`` in particular).
|
``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.
|
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
|
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
|
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
|
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.
|
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.'
|
"'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
|
* Enforcement of modularization of the components
|
||||||
* Out-of-tree development based on subsets of the supported boards and SoCs
|
* 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
|
See :ref:`west-basics` for information on how west workspaces manage multiple
|
||||||
multiple repository management.
|
git repositories.
|
||||||
|
|
||||||
.. _west-design-constraints:
|
.. _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