West documentation for v1.14

doc/extensions/only/eager_only.py

@@ -31,7 +31,7 @@ def run(self, *args):
         # Evaluate the condition eagerly, and if false return no nodes right away
         env = self.state.document.settings.env
         env.app.builder.tags.add('TRUE')
-        #print(repr(self.arguments[0]))
+
         if not env.app.builder.tags.eval_condition(self.arguments[0]):
             return []
 
@@ -44,3 +44,13 @@ def run(self, *args):
 
 def setup(app):
     directives.register_directive('only', EagerOnly)
+
+    # The tags.add call above is setting tags.tags['TRUE'] = True.
+    # The operation is idempotent and will have taken effect before
+    # the next eval_condition() which may rely on it so this is thread
+    # safe both for read and writes (all other operations are local to
+    # the local nodes variable).
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+        }

doc/extensions/zephyr/html_redirects.py

@@ -43,6 +43,13 @@ def setup(app):
     app.add_config_value('html_redirect_pages', [], 'html')
     app.connect('build-finished', create_redirect_pages)
 
+    # Since we're just setting up a build-finished hook, which runs
+    # after both reading and writing, this extension is safe for both.
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
 
 def create_redirect_pages(app, docname):
     if not isinstance(app.builder, StandaloneHTMLBuilder):

doc/extensions/zephyr/link-roles.py

@@ -28,6 +28,13 @@ def setup(app):
     app.add_role('zephyr_file', autolink('{}/blob/{}/%s'.format(baseurl, rev)))
     app.add_role('zephyr_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev)))
 
+    # The role just creates new nodes based on information in the
+    # arguments; its behavior doesn't depend on any other documents.
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
 
 def autolink(pattern):
     def role(name, rawtext, text, lineno, inliner, options={}, content=[]):

doc/getting_started/index.rst

@@ -100,10 +100,9 @@ Clone the Zephyr source code repositories from GitHub using the ``west`` tool:
 Running ``west init`` will clone west itself into ``./.west/west`` and
 initialize a local installation. Running ``west update`` will pull all the
 projects referenced by the manifest file (:file:`zephyr/west.yml`) into the
-folders specified in it. See :ref:`west-struct-installation` for additional
-details and a list of the folders and files that west will create as part of
-the process and :ref:`west-multi-repo` for more on how ``west`` helps manage
-multiple repositories.
+folders specified in it. See :ref:`west-multi-repo` for additional details, a
+list of the folders and files that west will create as part of the process,
+and more on how ``west`` helps manage multiple repositories.
 
 .. warning::
 

doc/glossary.rst

@@ -65,6 +65,26 @@ Glossary of Terms
       The set of Zephyr-supplied files that implement the Zephyr kernel,
       including its core services, device drivers, network stack, and so on.
 
+   west
+      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`.
+
+   west manifest
+      A YAML file named :file:`west.yml` which describes projects, or the Git
+      repositories which make up a :term:`west installation`, along with
+      additional metadata. See :ref:`west-multi-repo` for general information
+      and :ref:`west-manifests` for details.
+
+   west manifest repository
+      The Git repository in a :term:`west installation` which contains the
+      :term:`west manifest`. Its location is given by the :ref:`manifest.path
+      configuration option <west-config-index>`. See :ref:`west-multi-repo`.
+
    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

@@ -0,0 +1,152 @@
+.. _west-config:
+
+Configuration
+#############
+
+This page documents west's configuration file system, the ``west config``
+command, and configuration options used by built-in commands. For API
+documentation on the ``west.configuration`` module, see
+:ref:`west-apis-configuration`.
+
+West Configuration Files
+------------------------
+
+West's configuration file syntax is INI-like; here is an example file:
+
+.. code-block:: ini
+
+   [manifest]
+   path = zephyr
+
+   [zephyr]
+   base = zephyr
+
+Above, the ``manifest`` section has option ``path`` set to ``zephyr``. Another
+way to say the same thing is that ``manifest.path`` is ``zephyr`` in this file.
+
+There are three types of configuration file:
+
+1. **System**: Settings in this file affect west's behavior for every user
+   logged in to the computer. Its location depends on the platform:
+
+   - Linux: :file:`/etc/westconfig`
+   - macOS: :file:`/usr/local/etc/westconfig`
+   - Windows: :file:`%PROGRAMDATA%\\west\\config`
+
+2. **Global** (per user): Settings in this file affect how west behaves when
+   run by a particular user on the computer.
+
+   - All platforms: the default is :file:`.westconfig` in the user's home
+     directory.
+   - Linux note: if the environment variable :envvar:`XDG_CONFIG_HOME` is set,
+     then :file:`$XDG_CONFIG_HOME/west/config` is used.
+   - Windows note: the following environment variables are tested to find the
+     home directory: :envvar:`%HOME%`, then :envvar:`%USERPROFILE%`, then a
+     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.
+
+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
+``false``. Similarly, settings in the user configuration file override system
+settings, and so on.
+
+.. _west-config-cmd:
+
+West ``config`` Command
+-----------------------
+
+The built-in ``config`` command can be used to get and set configuration
+values. You can pass ``west config`` the options ``--system``, ``--global``, or
+``--local`` to specify which configuration file to use. Only one of these can
+be used at a time. If none is given, then writes default to ``--local``, and
+reads show the final value after applying overrides.
+
+Some examples for common uses follow; run ``west config -h`` for detailed help,
+and see :ref:`west-config-index` for more details on built-in options.
+
+To set ``manifest.path`` to :file:`some-other-manifest`:
+
+.. code-block:: console
+
+   west config manifest.path 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
+``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):
+
+.. code-block:: console
+
+   west config zephyr.base
+
+You can switch to another zephyr repository without changing ``manifest.path``
+-- and thus the behavior of commands like ``west update`` -- using:
+
+.. code-block:: console
+
+   west config zephyr.base some-other-zephyr
+
+This can be useful if you use commands like ``git worktree`` to create your own
+zephyr directories, and want commands like ``west build`` to use them instead
+of the zephyr repository specified in the manifest. (You can go back to using
+the directory in the upstream manifest by running ``west config zephyr.base
+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:
+
+.. code-block:: console
+
+   west config --global color.ui false
+
+To undo the above change:
+
+.. code-block:: console
+
+   west config --global color.ui true
+
+.. _west-config-index:
+
+Built-in Configuration Options
+------------------------------
+
+The following table documents configuration options supported by west's built-in
+commands.
+
+.. NOTE: docs authors: keep this table sorted by section, then option.
+
+.. list-table::
+   :widths: 10 30
+   :header-rows: 1
+
+   * - Option
+     - Description
+   * - ``color.ui``
+     - Boolean. If ``true`` (the default), then west output is colorized when
+       stdout is a terminal.
+   * - ``commands.allow_extensions``
+     - Boolean, default ``true``, disables :ref:`west-extensions` if ``false``
+   * - ``manifest.path``
+     - String, relative path from the :term:`west installation` root directory
+       to the manifest repository used by ``west update`` and other commands
+       which parse the manifest. Set locally by ``west init``.
+   * - ``zephyr.base``
+     - String, default value to set for the :envvar:`ZEPHYR_BASE` environment
+       variable while the west command is running. By default, this is set to
+       the path to the manifest project with path :file:`zephyr` (if there is
+       one) during ``west init``. If the variable is already set, then this
+       setting is ignored unless ``zephyr.base-prefer`` is ``"configfile"``.
+   * - ``zephyr.base-prefer``
+     - String, one the values ``"env"`` and ``"configfile"``. If set to
+       ``"env"`` (the default), setting :envvar:`ZEPHYR_BASE` in the calling
+       environment overrides the value of the ``zephyr.base`` configuration
+       option. If set to ``"configfile"``, the configuration option wins
+       instead.