doc: west: 'west installation' is now 'west workspace'
This nomenclature change was done in west 0.7 because it seems to be a lot easier for people to understand. Propagate it to all the west documentation. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Martí Bolívar
Johan Hedberg
parent
c3ddea01f2
commit
90edd01644
8 changed files with 61 additions and 55 deletions
|
|
@ -69,10 +69,7 @@ Glossary of Terms
|
|||
A multi-repo meta-tool developed for the Zephyr project. See :ref:`west`.
|
||||
|
||||
west installation
|
||||
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 installation using the
|
||||
``west init`` command. See :ref:`west-multi-repo`.
|
||||
A term for a :term:`west workspace` used prior to west 0.7.
|
||||
|
||||
west manifest
|
||||
A YAML file named :file:`west.yml` which describes projects, or the Git
|
||||
|
|
@ -85,6 +82,12 @@ Glossary of Terms
|
|||
:term:`west manifest`. Its location is given by the :ref:`manifest.path
|
||||
configuration option <west-config-index>`. See :ref:`west-multi-repo`.
|
||||
|
||||
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`.
|
||||
|
||||
XIP
|
||||
(eXecute In Place) a method of executing programs directly from long
|
||||
term storage rather than copying it into RAM, saving writable memory for
|
||||
|
|
|
|||
|
|
@ -45,12 +45,12 @@ There are three types of configuration file:
|
|||
combination of :envvar:`%HOMEDRIVE%` and :envvar:`%HOMEPATH%`.
|
||||
|
||||
3. **Local**: Settings in this file affect west's behavior for the
|
||||
current :term:`west installation`. The file is :file:`.west/config`, relative
|
||||
to the installation's root directory.
|
||||
current :term:`west workspace`. The file is :file:`.west/config`, relative
|
||||
to the workspace's root directory.
|
||||
|
||||
A setting in a file which appears lower down on this list overrides an earlier
|
||||
setting. For example, if ``color.ui`` is ``true`` in the system's configuration
|
||||
file, but ``false`` in the installation's, then the final value is
|
||||
file, but ``false`` in the workspace's, then the final value is
|
||||
``false``. Similarly, settings in the user configuration file override system
|
||||
settings, and so on.
|
||||
|
||||
|
|
@ -76,11 +76,11 @@ To set ``manifest.path`` to :file:`some-other-manifest`:
|
|||
|
||||
Doing the above means that commands like ``west update`` will look for the
|
||||
:term:`west manifest` inside the :file:`some-other-manifest` directory
|
||||
(relative to the installation root directory) instead of the directory given to
|
||||
(relative to the workspace root directory) instead of the directory given to
|
||||
``west init``, so be careful!
|
||||
|
||||
To read ``zephyr.base``, the value which will be used as ``ZEPHYR_BASE`` if it
|
||||
is unset in the calling environment (also relative to the installation root):
|
||||
is unset in the calling environment (also relative to the workspace root):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -101,7 +101,7 @@ zephyr``.)
|
|||
|
||||
To set ``color.ui`` to ``false`` in the global (user-wide) configuration file,
|
||||
so that west will no longer print colored output for that user when run in any
|
||||
installation:
|
||||
workspace:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -136,7 +136,7 @@ commands are documented in the pages for those commands.
|
|||
* - ``commands.allow_extensions``
|
||||
- Boolean, default ``true``, disables :ref:`west-extensions` if ``false``
|
||||
* - ``manifest.path``
|
||||
- String, relative path from the :term:`west installation` root directory
|
||||
- String, relative path from the :term:`west workspace` root directory
|
||||
to the manifest repository used by ``west update`` and other commands
|
||||
which parse the manifest. Set locally by ``west init``.
|
||||
* - ``update.fetch``
|
||||
|
|
|
|||
|
|
@ -41,7 +41,8 @@ globally for whenever you run west, use:
|
|||
|
||||
west config --global commands.allow_extensions false
|
||||
|
||||
If you want to, you can then re-enable them in a particular installation with:
|
||||
If you want to, you can then re-enable them in a particular :term:`west
|
||||
workspace` with:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ introduction and command overview, see :ref:`west-multi-repo`.
|
|||
Multiple Repository Model
|
||||
*************************
|
||||
|
||||
West's view of the repositories in a :term:`west installation`, and their
|
||||
West's view of the repositories in a :term:`west workspace`, and their
|
||||
history, looks like the following figure (though some parts of this example are
|
||||
specific to upstream Zephyr's use of west):
|
||||
|
||||
|
|
@ -32,7 +32,7 @@ specific to upstream Zephyr's use of west):
|
|||
The history of the manifest repository is the line of Git commits which is
|
||||
"floating" on top of the gray plane. Parent commits point to child commits
|
||||
using solid arrows. The plane below contains the Git commit history of the
|
||||
repositories in the installation, with each project repository boxed in by a
|
||||
repositories in the workspace, with each project repository boxed in by a
|
||||
rectangle. Parent/child commit relationships in each repository are also shown
|
||||
with solid arrows.
|
||||
|
||||
|
|
@ -124,7 +124,7 @@ example, you might use ``git@example.com:base1`` if ``remote1`` supported Git
|
|||
over SSH as well. Anything acceptable to Git will work.
|
||||
|
||||
The ``projects`` subsection contains a sequence describing the project
|
||||
repositories in the west installation. Every project has a unique name. You can
|
||||
repositories in the west workspace. Every project has a unique name. You can
|
||||
specify what Git remote URLs to use when cloning and fetching the projects,
|
||||
what revisions to track, and where the project should be stored on the local
|
||||
file system.
|
||||
|
|
@ -157,7 +157,7 @@ In this manifest:
|
|||
with a ``/`` and the project ``name`` to form the URL.
|
||||
|
||||
Locally, this project will be cloned at path ``extra/project-1`` relative to
|
||||
the west installation's root directory, since it has an explicit ``path``
|
||||
the west workspace's root directory, since it has an explicit ``path``
|
||||
attribute with this value.
|
||||
|
||||
Since the project has no ``revision`` specified, ``master`` is used by
|
||||
|
|
@ -208,7 +208,7 @@ The list of project keys and their usage follows. Sometimes we'll refer to the
|
|||
A project revision can be a branch, tag, or SHA. The default ``revision`` is
|
||||
``master`` if not otherwise specified.
|
||||
- ``path``: Optional. Relative path specifying where to clone the repository
|
||||
locally, relative to the top directory in the west installation. If missing,
|
||||
locally, relative to the top directory in the west workspace. If missing,
|
||||
the project's ``name`` is used as a directory name.
|
||||
- ``clone-depth``: Optional. If given, a positive integer which creates a
|
||||
shallow history in the cloned repository limited to the given number of
|
||||
|
|
@ -254,7 +254,7 @@ The ``self`` subsection can be used to control the behavior of the
|
|||
manifest repository itself. Its value is a map with the following keys:
|
||||
|
||||
- ``path``: Optional. The path to clone the manifest repository into, relative
|
||||
to the west installation's root directory. If not given, the basename of the
|
||||
to the west workspace's root directory. If not given, the basename of the
|
||||
path component in the manifest repository URL will be used by default. For
|
||||
example, if the URL is ``https://git.example.com/project-repo``, the manifest
|
||||
repository would be cloned to the directory :file:`project-repo`.
|
||||
|
|
@ -411,7 +411,7 @@ You have a source code repository you want to use with Zephyr v1.14.1 LTS. You
|
|||
want to maintain the whole thing using west. You don't want to modify any of
|
||||
the mainline repositories.
|
||||
|
||||
In other words, the west installation you want looks like this:
|
||||
In other words, the west workspace you want looks like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
|
|
@ -441,7 +441,7 @@ You can do this with the following :file:`my-repo/west.yml`:
|
|||
revision: v1.14.1
|
||||
import: true
|
||||
|
||||
You can then create the installation on your computer like this, assuming
|
||||
You can then create the workspace on your computer like this, assuming
|
||||
``my-repo`` is hosted at ``https://git.example.com/my-repo``:
|
||||
|
||||
.. code-block:: console
|
||||
|
|
@ -480,7 +480,7 @@ master`` for the zephyr repository:
|
|||
revision: master
|
||||
import: true
|
||||
|
||||
You can create the installation in the same way:
|
||||
You can create the workspace in the same way:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -711,7 +711,7 @@ Example 2.3: Continuous Integration overrides
|
|||
---------------------------------------------
|
||||
|
||||
Your continuous integration system needs to fetch and test multiple
|
||||
repositories in your west installation from a developer's forks instead of your
|
||||
repositories in your west workspace from a developer's forks instead of your
|
||||
mainline development trees, to see if the changes all work well together.
|
||||
|
||||
Starting with :ref:`west-manifest-ex2.2`, the CI scripts add a
|
||||
|
|
@ -890,7 +890,7 @@ Example 3.3: Downstream with path blacklist
|
|||
-------------------------------------------
|
||||
|
||||
Here's an example showing how to blacklist all vendor HALs from mainline by
|
||||
common path prefix in the installation, add your own version for the chip
|
||||
common path prefix in the workspace, add your own version for the chip
|
||||
you're targeting, and keep everything else.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
|
|||
|
|
@ -37,13 +37,13 @@ instead. See :ref:`west-troubleshooting` for advice on common issues.
|
|||
The name :file:`zephyrproject` is recommended, but you can choose any name
|
||||
with no spaces anywhere in the path.
|
||||
|
||||
#. Create a :ref:`west installation <west-installation>` using the zephyr
|
||||
#. Create a :ref:`west workspace <west-workspace>` using the zephyr
|
||||
repository as a local manifest repository::
|
||||
|
||||
west init -l zephyr
|
||||
|
||||
This creates :file:`zephyrproject/.west`, marking the root of your
|
||||
installation, and does some other setup. It will not change the contents of
|
||||
workspace, and does some other setup. It will not change the contents of
|
||||
the zephyr repository in any way.
|
||||
|
||||
#. Clone the rest of the repositories used by zephyr::
|
||||
|
|
|
|||
|
|
@ -14,19 +14,20 @@ rationale, and motivation.
|
|||
multi-repo work, not to replace it. For tasks that only operate on one
|
||||
repository, just use plain Git commands.
|
||||
|
||||
.. _west-installation:
|
||||
.. _west-workspace:
|
||||
|
||||
Introduction
|
||||
************
|
||||
|
||||
West's built-in commands allow you to work with projects composed of multiple
|
||||
Git repositories installed under a common parent directory, which we call a
|
||||
*west installation*. This works similarly to `Git Submodules
|
||||
*west workspace* (before west 0.7, this was called a *west installation*). This
|
||||
works similarly to `Git Submodules
|
||||
<https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ and Google's `repo
|
||||
<https://gerrit.googlesource.com/git-repo/>`_.
|
||||
|
||||
A west installation is the result of running the ``west init`` command, which
|
||||
is described in more detail below. For upstream Zephyr, the installation looks
|
||||
A west workspace is the result of running the ``west init`` command, which
|
||||
is described in more detail below. For upstream Zephyr, the workspace looks
|
||||
like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
|
@ -43,34 +44,34 @@ like this:
|
|||
├── net-tools
|
||||
└── [ ... other projects ...]
|
||||
|
||||
Above, :file:`zephyrproject` is the name of the west installation's root
|
||||
Above, :file:`zephyrproject` is the name of the west workspace's root
|
||||
directory. This name is just an example -- it could be anything, like ``z``,
|
||||
``my-zephyr-installation``, etc. The file :file:`.west/config` is the
|
||||
installation's :ref:`local configuration file <west-config>`.
|
||||
``my-zephyr-workspace``, etc. The file :file:`.west/config` is the
|
||||
workspace's :ref:`local configuration file <west-config>`.
|
||||
|
||||
Every west installation contains exactly one *manifest repository*, which is a
|
||||
Every west workspace contains exactly one *manifest repository*, which is a
|
||||
Git repository containing a file named :file:`west.yml`, which is the *west
|
||||
manifest*. The location of the manifest repository is given by the
|
||||
:ref:`manifest.path configuration option <west-config-index>` in the local
|
||||
configuration file. The manifest file, along with west's configuration files,
|
||||
controls the installation's behavior. For upstream Zephyr, :file:`zephyr` is
|
||||
controls the workspace's behavior. For upstream Zephyr, :file:`zephyr` is
|
||||
the manifest repository, but you can configure west to use any Git repository
|
||||
in the installation as the manifest repository. The only requirement is that it
|
||||
in the workspace as the manifest repository. The only requirement is that it
|
||||
contains a valid manifest file. See :ref:`west-manifests` for more details on
|
||||
what this means.
|
||||
|
||||
Both of the :file:`tinycbor` and :file:`net-tools` directories are *projects*
|
||||
managed by west, and configured in the manifest file. A west installation can
|
||||
managed by west, and configured in the manifest file. A west workspace can
|
||||
contain arbitrarily many projects. As shown above, projects can be located
|
||||
anywhere in the installation. They don't have to be subdirectories of the
|
||||
anywhere in the workspace. They don't have to be subdirectories of the
|
||||
manifest directory, and they can be inside of arbitrary subdirectories inside
|
||||
the installation's root directory. By default, the Zephyr build system uses
|
||||
west to get the locations of all the projects in the installation, so any code
|
||||
the workspace's root directory. By default, the Zephyr build system uses
|
||||
west to get the locations of all the projects in the workspace, so any code
|
||||
they contain can be used by applications. This behavior can be overridden using
|
||||
the ``ZEPHYR_MODULES`` CMake variable; see
|
||||
:zephyr_file:`cmake/zephyr_module.cmake` for details.
|
||||
|
||||
Finally, any repository managed by a west installation can contain
|
||||
Finally, any repository managed by a west workspace can contain
|
||||
:ref:`extension commands <west-extensions>`, which are extra west commands
|
||||
provided by that project. This includes the manifest repository and any project
|
||||
repository.
|
||||
|
|
@ -92,7 +93,7 @@ T1: Star topology, zephyr is the manifest repository
|
|||
- Analogy with existing mechanisms: Git submodules with zephyr as the
|
||||
super-project
|
||||
|
||||
This is the default. See :ref:`west-installation` for how mainline Zephyr is an
|
||||
This is the default. See :ref:`west-workspace` for how mainline Zephyr is an
|
||||
example of this topology.
|
||||
|
||||
.. _west-t2:
|
||||
|
|
@ -107,7 +108,7 @@ T2: Star topology, application is the manifest repository
|
|||
- Analogy with existing mechanisms: Git submodules with the application as
|
||||
the super-project, zephyr and other projects as submodules
|
||||
|
||||
An installation using this topology looks like this:
|
||||
A workspace using this topology looks like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
|
|
@ -188,7 +189,7 @@ T3: Forest topology
|
|||
and specifies a list of projects all at the same "level"
|
||||
- Analogy with existing mechanisms: Google repo-based source distribution
|
||||
|
||||
An installation using this topology looks like this:
|
||||
A workspace using this topology looks like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
|
|
@ -303,7 +304,7 @@ The ``west init`` and ``west update`` multi-repo commands are the most
|
|||
important to understand.
|
||||
|
||||
- ``west init [-l] [-m URL] [--mr REVISION] [PATH]``: create a west
|
||||
installation in directory :file:`PATH` (i.e. :file:`.west` etc. will be
|
||||
workspace in directory :file:`PATH` (i.e. :file:`.west` etc. will be
|
||||
created there). If the ``PATH`` argument is not given, the current working
|
||||
directory is used. This command does not clone any of the projects in the
|
||||
manifest; that is done the next time ``west update`` is run.
|
||||
|
|
@ -311,11 +312,11 @@ important to understand.
|
|||
This command can be invoked in two ways:
|
||||
|
||||
1. If you already have a local clone of the zephyr repository and want to
|
||||
create a west installation around it, you can use the ``-l`` switch to
|
||||
create a west workspace around it, you can use the ``-l`` switch to
|
||||
pass its path to west, as in: ``west init -l path/to/zephyr``. This is
|
||||
the only reason to use ``-l``.
|
||||
|
||||
2. Otherwise, omit ``-l`` to create a new installation from a remote manifest
|
||||
2. Otherwise, omit ``-l`` to create a new workspace from a remote manifest
|
||||
repository. You can give the manifest URL using the ``-m`` switch, and its
|
||||
revision using ``--mr``. For example, invoking west with: ``west init -m
|
||||
https://github.com/zephyrproject-rtos/zephyr --mr v1.15.0`` would clone
|
||||
|
|
|
|||
|
|
@ -16,8 +16,8 @@ If you see this error when running ``west init``:
|
|||
(choose from 'init', 'update', 'list', 'manifest', 'diff',
|
||||
'status', 'forall', 'config', 'selfupdate', 'help')
|
||||
|
||||
Then you have an old version of west installed, and are trying to use it in an
|
||||
installation that requires a more recent version.
|
||||
Then you have an old version of west installed, and are trying to use it in a
|
||||
workspace that requires a more recent version.
|
||||
|
||||
The easiest way to resolve this issue is to upgrade west and retry as follows:
|
||||
|
||||
|
|
@ -29,23 +29,24 @@ The easiest way to resolve this issue is to upgrade west and retry as follows:
|
|||
this step.)
|
||||
|
||||
#. Completely remove the :file:`zephyrproject/.west` directory (if you don't,
|
||||
you will get the "already in an installation" error message discussed next).
|
||||
you will get the "already in a workspace" error message discussed next).
|
||||
|
||||
#. Run ``west init`` again.
|
||||
|
||||
"already in an installation"
|
||||
****************************
|
||||
|
||||
You may see this error when running ``west init``:
|
||||
You may see this error when running ``west init`` with west 0.6:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
FATAL ERROR: already in an installation (<some directory>), aborting
|
||||
|
||||
If this is unexpected and you're really trying to create a new installation,
|
||||
If this is unexpected and you're really trying to create a new west workspace,
|
||||
then it's likely that west is using the :envvar:`ZEPHYR_BASE` :ref:`environment
|
||||
variable <env_vars>` to locate a west installation elsewhere on your system.
|
||||
This is intentional behavior; it allows you to put your Zephyr applications in
|
||||
any directory and still use west.
|
||||
variable <env_vars>` to locate a workspace elsewhere on your system.
|
||||
|
||||
This is intentional; it allows you to put your Zephyr applications in
|
||||
any directory and still use west to build, flash, and debug them, for example.
|
||||
|
||||
To resolve this issue, unset :envvar:`ZEPHYR_BASE` and try again.
|
||||
|
|
|
|||
|
|
@ -71,7 +71,7 @@ west commands wrap).
|
|||
|
||||
If you want to use these build system targets but do not want to
|
||||
install west on your system using ``pip``, it is possible to do so
|
||||
by manually creating a :term:`west installation`:
|
||||
by manually creating a :term:`west workspace`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue