doc: fix incorrect usage of envvar role
:envvar: is currently used to tag environment variables, however,
:envvar: role expects a matching .. envvar:: directive where the
environment variable is defined. This patch fixes some cases by adding
envvar directives and by converting certain cases to literals (it
doesn't make sense to document all env vars in a list, as some are
self-documented by contextual information).
Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/
roles.html#role-envvar
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
diff --git a/boards/riscv/rv32m1_vega/doc/index.rst b/boards/riscv/rv32m1_vega/doc/index.rst
index 5b60bf8..7256f3e 100644
--- a/boards/riscv/rv32m1_vega/doc/index.rst
+++ b/boards/riscv/rv32m1_vega/doc/index.rst
@@ -432,7 +432,7 @@
You can put them elsewhere, but be aware:
- If you put the toolchain somewhere else, you will need to change
- the :envvar:`CROSS_COMPILE` value described below accordingly.
+ the ``CROSS_COMPILE`` value described below accordingly.
- If you put OpenOCD somewhere else, you will need to change the
OpenOCD path in the flashing and debugging instructions below.
- Don't use installation directories with spaces anywhere in the path;
@@ -774,9 +774,9 @@
If you set ``<toolchain-installation-dir>`` to
:file:`~/riscv32-unknown-elf-gcc`, you can use the above instructions
-for setting :envvar:`CROSS_COMPILE` when building Zephyr
+for setting ``CROSS_COMPILE`` when building Zephyr
applications. If you set it to something else, you will need to update
-your :envvar:`CROSS_COMPILE` setting accordingly.
+your ``CROSS_COMPILE`` setting accordingly.
.. note::
diff --git a/doc/develop/application/index.rst b/doc/develop/application/index.rst
index 335138c..111cffd 100644
--- a/doc/develop/application/index.rst
+++ b/doc/develop/application/index.rst
@@ -919,7 +919,7 @@
If the (Linux only) :ref:`Zephyr SDK <toolchain_zephyr_sdk>` is installed, the ``run``
target will use the SDK's QEMU binary by default. To use another version of
- QEMU, :ref:`set the environment variable <env_vars>` :envvar:`QEMU_BIN_PATH`
+ QEMU, :ref:`set the environment variable <env_vars>` ``QEMU_BIN_PATH``
to the path of the QEMU binary you want to use instead.
.. note::
@@ -1376,7 +1376,7 @@
- GDB Client Setup
- - Executable path example (use your :envvar:`GNUARMEMB_TOOLCHAIN_PATH`):
+ - Executable path example (use your ``GNUARMEMB_TOOLCHAIN_PATH``):
:file:`C:\\gcc-arm-none-eabi-6_2017-q2-update\\bin\\arm-none-eabi-gdb.exe`
- In the SVD Path tab:
diff --git a/doc/develop/beyond-GSG.rst b/doc/develop/beyond-GSG.rst
index 110eb0f..13ea085 100644
--- a/doc/develop/beyond-GSG.rst
+++ b/doc/develop/beyond-GSG.rst
@@ -71,8 +71,8 @@
You can configure the Zephyr build system to use a specific toolchain by
setting :ref:`environment variables <env_vars>` such as
-:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to a supported value, along with
-additional variable(s) specific to the toolchain variant.
+:envvar:`ZEPHYR_TOOLCHAIN_VARIANT <{TOOLCHAIN}_TOOLCHAIN_PATH>` to a supported
+value, along with additional variable(s) specific to the toolchain variant.
.. _gs_toolchain_update:
@@ -150,6 +150,8 @@
The :ref:`cmake_pkg` can be exported to CMake's user package registry if it has
not already been done as part of :ref:`getting_started`.
+.. _gs-board-aliases:
+
Board Aliases
*************
diff --git a/doc/develop/env_vars.rst b/doc/develop/env_vars.rst
index 868ed62..e5f7269 100644
--- a/doc/develop/env_vars.rst
+++ b/doc/develop/env_vars.rst
@@ -12,7 +12,7 @@
Option 1: Just Once
-------------------
-To set the environment variable :envvar:`MY_VARIABLE` to ``foo`` for the
+To set the environment variable ``MY_VARIABLE`` to ``foo`` for the
lifetime of your current terminal window:
.. tabs::
@@ -56,7 +56,7 @@
program.
To use ``setx``, type this command, then close the terminal window. Any
- new ``cmd.exe`` windows will have :envvar:`MY_VARIABLE` set to ``foo``.
+ new ``cmd.exe`` windows will have ``MY_VARIABLE`` set to ``foo``.
.. code-block:: console
@@ -118,8 +118,7 @@
These scripts:
- - set :envvar:`ZEPHYR_BASE` (see below) to the location of the zephyr
- repository
+ - set :envvar:`ZEPHYR_BASE` to the location of the zephyr repository
- adds some Zephyr-specific locations (such as zephyr's :file:`scripts`
directory) to your :envvar:`PATH` environment variable
- loads any settings from the ``zephyrrc`` files described above in
@@ -153,10 +152,9 @@
These scripts:
-- set :envvar:`ZEPHYR_BASE` (see below) to the location of the zephyr
- repository
+- set :envvar:`ZEPHYR_BASE` to the location of the zephyr repository
- adds some Zephyr-specific locations (such as zephyr's :file:`scripts`
- directory) to your :envvar:`PATH` environment variable
+ directory) to your ``PATH`` environment variable
- loads any settings from the ``zephyrrc`` files described above in
:ref:`env_vars_zephyrrc`.
@@ -171,21 +169,50 @@
is a description of some of these important environment variables. This is not
a comprehensive list.
-- :envvar:`BOARD`
-- :envvar:`CONF_FILE`
-- :envvar:`SHIELD`
-- :envvar:`ZEPHYR_BASE`
-- :envvar:`ZEPHYR_EXTRA_MODULES`
-- :envvar:`ZEPHYR_MODULES`
+.. envvar:: BOARD
+
+ See :ref:`important-build-vars`.
+
+.. envvar:: CONF_FILE
+
+ See :ref:`important-build-vars`.
+
+.. envvar:: SHIELD
+
+ See :ref:`shields`.
+
+.. envvar:: ZEPHYR_BASE
+
+ See :ref:`important-build-vars`.
+
+.. envvar:: ZEPHYR_EXTRA_MODULES
+
+ See :ref:`important-build-vars`.
+
+.. envvar:: ZEPHYR_MODULES
+
+ See :ref:`important-build-vars`.
+
+.. envvar:: ZEPHYR_BOARD_ALIASES
+
+ See :ref:`gs-board-aliases`
The following additional environment variables are significant when configuring
the :ref:`toolchain <gs_toolchain>` used to build Zephyr applications.
-- :envvar:`ZEPHYR_TOOLCHAIN_VARIANT`: the name of the toolchain to use
-- :envvar:`<TOOLCHAIN>_TOOLCHAIN_PATH`: path to the toolchain specified by
- :envvar:`ZEPHYR_TOOLCHAIN_VARIANT`. For example, if
- ``ZEPHYR_TOOLCHAIN_VARIANT=llvm``, use :envvar:`LLVM_TOOLCHAIN_PATH`. (Note
- the capitalization when forming the environment variable name.)
+.. envvar:: ZEPHYR_SDK_INSTALL_DIR
+
+ Path where Zephyr SDK is installed.
+
+.. envvar:: ZEPHYR_TOOLCHAIN_VARIANT
+
+ The name of the toolchain to use.
+
+.. envvar:: {TOOLCHAIN}_TOOLCHAIN_PATH
+
+ Path to the toolchain specified by :envvar:`ZEPHYR_TOOLCHAIN_VARIANT`. For
+ example, if ``ZEPHYR_TOOLCHAIN_VARIANT=llvm``, use ``LLVM_TOOLCHAIN_PATH``.
+ (Note the capitalization when forming the environment variable name.)
You might need to update some of these variables when you
:ref:`update the Zephyr SDK toolchain <gs_toolchain_update>`.
@@ -193,6 +220,13 @@
Emulators and boards may also depend on additional programs. The build system
will try to locate those programs automatically, but may rely on additional
CMake or environment variables to do so. Please consult your emulator's or
-board's documentation for more information.
+board's documentation for more information. The following environment variables
+may be useful in such situations:
+
+.. envvar:: PATH
+
+ ``PATH`` is an environment variable used on Unix-like or Microsoft Windows
+ operating systems to specify a set of directories where executable programs
+ are located.
.. _using Chocolatey: https://chocolatey.org/packages/RapidEE
diff --git a/doc/develop/toolchains/custom_cmake.rst b/doc/develop/toolchains/custom_cmake.rst
index 2cfbdb8..d083ae7 100644
--- a/doc/develop/toolchains/custom_cmake.rst
+++ b/doc/develop/toolchains/custom_cmake.rst
@@ -7,7 +7,7 @@
environment variables <env_vars>`:
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to your toolchain's name
-- Set :envvar:`TOOLCHAIN_ROOT` to the path to the directory containing your
+- Set ``TOOLCHAIN_ROOT`` to the path to the directory containing your
toolchain's CMake configuration files.
Zephyr will then include the toolchain cmake files located in the
@@ -58,7 +58,7 @@
available out-of-tree and it must include the correct header for the custom
toolchain.
A good location for the :file:`other.h` header file, would be a
-directory under the directory specified in :envvar:`TOOLCHAIN_ROOT` as
+directory under the directory specified in ``TOOLCHAIN_ROOT`` as
:file:`include/toolchain`.
To get the toolchain header included in zephyr's build, the
:makevar:`USERINCLUDE` can be set to point to the include directory, as shown
diff --git a/doc/develop/toolchains/other_x_compilers.rst b/doc/develop/toolchains/other_x_compilers.rst
index af2f8a2..6398fcf 100644
--- a/doc/develop/toolchains/other_x_compilers.rst
+++ b/doc/develop/toolchains/other_x_compilers.rst
@@ -4,7 +4,7 @@
######################
This toolchain variant is borrowed from the Linux kernel build system's
-mechanism of using a :envvar:`CROSS_COMPILE` environment variable to set up a
+mechanism of using a ``CROSS_COMPILE`` environment variable to set up a
GNU-based cross toolchain.
Examples of such "other cross compilers" are cross toolchains that your Linux
@@ -32,13 +32,13 @@
#. :ref:`Set these environment variables <env_vars>`:
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``cross-compile``.
- - Set :envvar:`CROSS_COMPILE` to the common path prefix which your
+ - Set ``CROSS_COMPILE`` to the common path prefix which your
toolchain's binaries have, e.g. the path to the directory containing the
compiler binaries plus the target triplet and trailing dash.
#. To check that you have set these variables correctly in your current
environment, follow these example shell sessions (the
- :envvar:`CROSS_COMPILE` value may be different on your system):
+ ``CROSS_COMPILE`` value may be different on your system):
.. code-block:: console
diff --git a/doc/develop/west/build-flash-debug.rst b/doc/develop/west/build-flash-debug.rst
index 2898177..df8fe92 100644
--- a/doc/develop/west/build-flash-debug.rst
+++ b/doc/develop/west/build-flash-debug.rst
@@ -367,7 +367,7 @@
- Description
* - ``build.board``
- String. If given, this the board used by :ref:`west build
- <west-building>` when ``--board`` is not given and :envvar:`BOARD`
+ <west-building>` when ``--board`` is not given and ``BOARD``
is unset in the environment.
* - ``build.board_warn``
- Boolean, default ``true``. If ``false``, disables warnings when
diff --git a/doc/develop/west/config.rst b/doc/develop/west/config.rst
index 93951ad..35b10de 100644
--- a/doc/develop/west/config.rst
+++ b/doc/develop/west/config.rst
@@ -38,11 +38,11 @@
- 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,
+ - Linux note: if the environment variable ``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%`.
+ home directory: ``%HOME%``, then ``%USERPROFILE%``, then a
+ combination of ``%HOMEDRIVE%`` and ``%HOMEPATH%``.
3. **Local**: Settings in this file affect west's behavior for the
current :term:`west workspace`. The file is :file:`.west/config`, relative
diff --git a/doc/develop/west/release-notes.rst b/doc/develop/west/release-notes.rst
index 75b6834..9e7aeba 100644
--- a/doc/develop/west/release-notes.rst
+++ b/doc/develop/west/release-notes.rst
@@ -131,7 +131,7 @@
in a detached HEAD state. This has been fixed by using ``git clone`` internally
instead of ``git init`` and ``git fetch``. See `issue #522`_ for details.
-- The :envvar:`WEST_CONFIG_LOCAL` environment variable now correctly
+- The ``WEST_CONFIG_LOCAL`` environment variable now correctly
overrides the default location, :file:`<workspace topdir>/.west/config`.
- ``west update --fetch=smart`` (``smart`` is the default) now correctly skips
