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>

doc/glossary.rst

@@ -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 for a :term:`west workspace` used prior to west 0.7.
-      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`.
 
    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

doc/guides/west/config.rst

@@ -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
+   current :term:`west workspace`. The file is :file:`.west/config`, relative
-   to the installation's root directory.
+   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``

doc/guides/west/extensions.rst

@@ -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
 

doc/guides/west/manifest.rst

@@ -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

doc/guides/west/moving-to-west.rst

@@ -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::

doc/guides/west/repo-tool.rst

@@ -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
+A west workspace is the result of running the ``west init`` command, which
-is described in more detail below. For upstream Zephyr, the installation looks
+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
+``my-zephyr-workspace``, etc.  The file :file:`.west/config` is the
-installation's :ref:`local configuration file <west-config>`.
+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
+the workspace'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
+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

doc/guides/west/troubleshooting.rst

@@ -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
+Then you have an old version of west installed, and are trying to use it in a
-installation that requires a more recent version.
+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.
+variable <env_vars>` to locate a workspace elsewhere on your system.
-This is intentional behavior; it allows you to put your Zephyr applications in
+
-any directory and still use west.
+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.

doc/guides/west/without-west.rst

@@ -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