Skip to content
Permalink
Browse files

doc: unify documentation on setting environment variables

There are a few different places where alternatives for setting
environment variables are described. None of them is 100% complete, so
the results are likely to be confusing.

Make a single page on setting environment variables, how the zephyrrc
files work, how the zephyr-env scripts work, and some of the important
environment variables, with appropriate references elsewhere. (This is
inspired by the Arch wiki's excellent page on installing programs.)

Link to it from the getting started and application development pages
instead of repeating the information. This has the benefit of
shortening the getting started guide a bit more.

Add some concrete advice on checking the toolchain environment
variables in particular. This is a stumbling block for beginners.

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
  • Loading branch information...
mbolivar authored and nashif committed May 7, 2019
1 parent b587909 commit 5edb6d5def80322759222d514418b84c00b8c7ed
@@ -260,8 +260,7 @@ should know about.

* As a parameter to the ``cmake`` invocation via the ``-D`` command-line
switch
* As an environment variables (``export`` on Linux/macOS and ``set`` on
Windows)
* As :ref:`env_vars`.
* As a ``set(<VARIABLE> <VALUE>)`` statement in your :file:`CMakeLists.txt`

* :makevar:`ZEPHYR_BASE`: Sets the path to the directory containing Zephyr,
@@ -504,8 +503,9 @@ again.

.. note:: The ``run`` target will use the QEMU binary available from the Zephyr
SDK by default. To use an alternate version of QEMU, for example the
version installed on your host or a custom version, set the
environment variable ``QEMU_BIN_PATH`` to the alternate path.
version installed on your host or a custom version, :ref:`set the
environment variable <env_vars>` ``QEMU_BIN_PATH`` to the alternate
path.

.. _application_debugging:
.. _custom_board_definition:
@@ -737,7 +737,8 @@ The :file:`.gdbinit` file contains the following lines:
.. note::

Substitute ZEPHYR_BASE for the current kernel's root directory.
Substitute the correct :ref:`ZEPHYR_BASE <env_vars_important>` for your
system.

Execute the application to debug from the same directory that you chose for
the :file:`gdbinit` file. The command can include the ``--tui`` option
@@ -813,8 +814,8 @@ Set Up the Eclipse Development Environment
Generate and Import an Eclipse Project
======================================

#. At a command line, configure your environment to use the GCC ARM Embedded
compiler as shown in :ref:`third_party_x_compilers`.
#. Set up a GNU Arm Embedded toolchain as described in
:ref:`third_party_x_compilers`.

#. Navigate to a folder outside of the Zephyr tree to build your application.

@@ -877,7 +878,7 @@ Create a Debugger Configuration

- GDB Client Setup

- Executable path:
- Executable path example (use your :envvar:`GNUARMEMB_TOOLCHAIN_PATH`):
:file:`C:\\gcc-arm-none-eabi-6_2017-q2-update\\bin\\arm-none-eabi-gdb.exe`

- In the SVD Path tab:
@@ -973,7 +974,8 @@ Make sure to follow these steps in order.
- Any value given on the CMake command line using ``-DBOARD=YOUR_BOARD``
will be checked for and used next.

- If an environment variable ``BOARD`` is set, its value will then be used.
- If an :ref:`environment variable <env_vars>` ``BOARD`` is set, its value
will then be used.

- Finally, if you set ``BOARD`` in your application :file:`CMakeLists.txt`
as described in this step, this value will be used.
@@ -1436,8 +1438,8 @@ follows:
passed to the the CMake command line, or present in the CMake variable cache,
takes precedence.

- The environment variable :envvar:`DTC_OVERLAY_FILE` is checked
next. This mechanism is now deprecated; users should set this
- The :ref:`environment variable <env_vars>` :envvar:`DTC_OVERLAY_FILE` is
checked next. This mechanism is now deprecated; users should set this
variable using CMake instead of the environment.

- If the file :file:`BOARD.overlay` exists in your application directory,
@@ -50,9 +50,9 @@ See :ref:`west-install` for additional details on installing west. See
`Installing Packages`_ in the Python Packaging User Guide for more information
about pip\ [#pip]_, including this `information on -\\-user`_.

- On Linux, verify that ``~/.local/bin`` is on your :envvar:`PATH` environment
variable, or programs installed with this option (like west) won't be
found\ [#linux_user]_.
- On Linux, make sure ``~/.local/bin`` is on your :envvar:`PATH`
:ref:`environment variable <env_vars>`, or programs installed with ``--user``
-- like west -- won't be found\ [#linux_user]_.

- On macOS, `Homebrew disables -\\-user`_.

@@ -97,6 +97,8 @@ Install Python packages required by Zephyr:
# macOS and Windows
pip3 install -r zephyr/scripts/requirements.txt

.. _gs_toolchain:

Set Up a Toolchain
******************

@@ -106,9 +108,9 @@ Toolchains are *installed* in the usual ways you get programs: with installer
programs or system package managers, by downloading and extracting a zip
archive, etc.

You *configure* the toolchain to use by setting environment variables. You need
to set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to a supported value, along with
additional variable(s) specific to the toolchain variant.
You *configure* the toolchain to use by setting :ref:`environment variables
<env_vars>`. You need to set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to a supported
value, along with additional variable(s) specific to the toolchain variant.

The following choices are available. If you're not sure what to use, check your
:ref:`board-level documentation <boards>`. If you're targeting an Arm Cortex-M,
@@ -125,16 +127,6 @@ you set up the :ref:`Zephyr SDK <zephyr_sdk>` toolchains or if you want to
toolchain_host.rst
toolchain_custom_cmake.rst

To use the same toolchain in new sessions in the future, make sure the
variables are set persistently.

On macOS and Linux, you can set the variables by putting the ``export`` lines
setting environment variables in a file :file:`~/.zephyrrc`. On Windows, you
can put the ``set`` lines in :file:`%userprofile%\\zephyrrc.cmd`. These files
are used to modify your environment when you run ``zephyr-env.sh`` (Linux,
macOS) and ``zephyr-env.cmd`` (Windows), which you will learn about in the next
step.

.. _getting_started_run_sample:

Build and Run an Application
@@ -169,13 +169,14 @@ Follow these steps to install the Zephyr SDK:
Zephyr's dependencies were installed as described in `Install Requirements
and Dependencies`_.

#. To use the Zephyr SDK, export the following environment variables and
use the target location where SDK was installed:
#. Set these :ref:`environment variables <env_vars>`:

.. code-block:: console
- set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``zephyr``
- set :envvar:`ZEPHYR_SDK_INSTALL_DIR` to :file:`$HOME/zephyr-sdk-0.10.0`
(or wherever you chose to install the SDK)

export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
If you ever want to uninstall the SDK, just remove the directory where you
installed it and unset these environment variables.

.. _sdkless_builds:

@@ -26,24 +26,29 @@ GNU ARM Embedded
has a `critical bug <https://github.com/zephyrproject-rtos/zephyr/issues/12257>`_
and should not be used. Toolchain version **7-2018-q2-update** is known to work.

#. Configure the environment variables needed to inform the Zephyr build system
to use this toolchain:
#. :ref:`Set these environment variables <env_vars>`:

- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``gnuarmemb``.
- Set :envvar:`GNUARMEMB_TOOLCHAIN_PATH` to the toolchain installation
directory.

For example:
#. To check that you have set these variables correctly in your current
environment, follow these example shell sessions (the
:envvar:`GNUARMEMB_TOOLCHAIN_PATH` values may be different on your system):

.. code-block:: console

# Linux or macOS
export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
export GNUARMEMB_TOOLCHAIN_PATH="~/gnu_arm_embedded"
# Linux, macOS:
$ echo $ZEPHYR_TOOLCHAIN_VARIANT
gnuarmemb
$ echo $GNUARMEMB_TOOLCHAIN_PATH
/home/you/Downloads/gnu_arm_embedded

# Windows in cmd.exe
set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
set GNUARMEMB_TOOLCHAIN_PATH=C:\gnu_arm_embedded
# Windows
> echo %ZEPHYR_TOOLCHAIN_VARIANT%
gnuarmemb
> echo %GNUARMEMB_TOOLCHAIN_PATH%
C:\gnu_arm_embedded

Intel ISSM
**********
@@ -65,24 +70,29 @@ Intel ISSM
Like the Zephyr repository, do not install the toolchain in a directory
with spaces anywhere in the path.

#. Configure the environment variables needed to inform the Zephyr build system
to use this toolchain:
#. :ref:`Set these environment variables <env_vars>`:

- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``issm``.
- Set :envvar:`ISSM_INSTALLATION_PATH` to the directory containing the
extracted files.

For example:
#. To check that you have set these variables correctly in your current
environment, follow these example shell sessions (the
:envvar:`ISSM_INSTALLATION_PATH` values may be different on your system):

.. code-block:: console

# Linux
export ZEPHYR_TOOLCHAIN_VARIANT=issm
export ISSM_INSTALLATION_PATH=/home/you/Downloads/issm0-toolchain-windows-2017-02-07
$ echo $ZEPHYR_TOOLCHAIN_VARIANT
issm
$ echo $ISSM_INSTALLATION_PATH
/home/you/Downloads/issm0-toolchain-windows-2017-02-07

# Windows in cmd.exe
set ZEPHYR_TOOLCHAIN_VARIANT=issm
set ISSM_INSTALLATION_PATH=c:\issm0-toolchain-windows-2017-01-25
# Windows
> echo %ZEPHYR_TOOLCHAIN_VARIANT%
issm
> echo %ISSM_INSTALLATION_PATH%
c:\issm0-toolchain-windows-2017-01-25

.. _xtools_x_compilers:

@@ -109,18 +119,22 @@ You can build toolchains from source code using crosstool-NG.

Currently, only i586 and Arm toolchain builds are verified.

#. Configure the environment variables needed to inform the Zephyr build system
to use this toolchain:
#. :ref:`Set these environment variables <env_vars>`:

- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``xtools``.
- Set :envvar:`XTOOLS_TOOLCHAIN_PATH` to the toolchain build directory.

For example:
#. To check that you have set these variables correctly in your current
environment, follow these example shell sessions (the
:envvar:`XTOOLS_TOOLCHAIN_PATH` values may be different on your system):

.. code-block:: console

export ZEPHYR_TOOLCHAIN_VARIANT=xtools
export XTOOLS_TOOLCHAIN_PATH=/Volumes/CrossToolNGNew/build/output/
# Linux, macOS:
$ echo $ZEPHYR_TOOLCHAIN_VARIANT
xtools
$ echo $XTOOLS_TOOLCHAIN_PATH
/Volumes/CrossToolNGNew/build/output/

.. _GNU ARM Embedded: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm
.. _ISSM Toolchain: https://software.intel.com/en-us/articles/issm-toolchain-only-download
@@ -3,25 +3,29 @@
Custom CMake Toolchains
#######################

To use a custom toolchain defined in an external CMake file, export the
following environment variables:
To use a custom toolchain defined in an external CMake file, :ref:`set these
environment variables <env_vars>`:

.. code-block:: console
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to your toolchain's name
- Set :envvar:`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
:file:`TOOLCHAIN_ROOT` directory:

# Linux and macOS
export ZEPHYR_TOOLCHAIN_VARIANT=<toolchain name>
export TOOLCHAIN_ROOT=<path to toolchain>
- :file:`cmake/toolchain/generic.cmake`: configures the toolchain for "generic"
use (mostly to run the C preprocessor on the generated :ref:`device-tree`
file).
- :file:`cmake/toolchain/target.cmake`: configures the toolchain for use
building Zephyr and your application's source code.

# Windows
set ZEPHYR_TOOLCHAIN_VARIANT=<toolchain name>
set TOOLCHAIN_ROOT=<path to toolchain>
See the zephyr files :zephyr_file:`cmake/generic_toolchain.cmake` and
:zephyr_file:`cmake/target_toolchain.cmake` for more details on what your
:file:`generic.cmake` and :file:`target.cmake` files should contain.

You can also set them as CMake variables when generating a build
system for a Zephyr application, like so:
You can also set ``ZEPHYR_TOOLCHAIN_VARIANT`` and ``TOOLCHAIN_ROOT`` as CMake
variables when generating a build system for a Zephyr application, like so:

.. code-block:: console

cmake -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=...

Zephyr will then include the toolchain cmake file located in:
``<path to toolchain>/cmake/toolchain/<toolchain name>.cmake``.
@@ -29,20 +29,24 @@ Follow these steps to use one of these toolchains.
# On Fedora or Red Hat
sudo dnf install arm-none-eabi-newlib

#. Configure the environment variables needed to inform the Zephyr build system
to use this toolchain:
#. :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
toolchain's binaries have, e.g. the path to the directory containing the
compiler binaries plus the target triplet and trailing dash.

Continuing the above Debian or Ubuntu example:
#. 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):

.. code-block:: console

export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
# Linux, macOS:
$ echo $ZEPHYR_TOOLCHAIN_VARIANT
cross-compile
$ echo $CROSS_COMPILE
/usr/bin/arm-none-eabi-

You can also set ``CROSS_COMPILE`` as a CMake variable.

0 comments on commit 5edb6d5

Please sign in to comment.
You can’t perform that action at this time.