233 lines
6.8 KiB
ReStructuredText
233 lines
6.8 KiB
ReStructuredText
.. _env_vars:
|
|
|
|
Environment Variables
|
|
=====================
|
|
|
|
Various pages in this documentation refer to setting Zephyr-specific
|
|
environment variables. This page describes how.
|
|
|
|
Setting Variables
|
|
*****************
|
|
|
|
Option 1: Just Once
|
|
-------------------
|
|
|
|
To set the environment variable ``MY_VARIABLE`` to ``foo`` for the
|
|
lifetime of your current terminal window:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: Linux/macOS
|
|
|
|
.. code-block:: console
|
|
|
|
export MY_VARIABLE=foo
|
|
|
|
.. group-tab:: Windows
|
|
|
|
.. code-block:: console
|
|
|
|
set MY_VARIABLE=foo
|
|
|
|
.. warning::
|
|
|
|
This is best for experimentation. If you close your terminal window, use
|
|
another terminal window or tab, restart your computer, etc., this setting
|
|
will be lost forever.
|
|
|
|
Using options 2 or 3 is recommended if you want to keep using the setting.
|
|
|
|
Option 2: In all Terminals
|
|
--------------------------
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: Linux/macOS
|
|
|
|
Add the ``export MY_VARIABLE=foo`` line to your shell's startup script in
|
|
your home directory. For Bash, this is usually :file:`~/.bashrc` on Linux
|
|
or :file:`~/.bash_profile` on macOS. Changes in these startup scripts
|
|
don't affect shell instances already started; try opening a new terminal
|
|
window to get the new settings.
|
|
|
|
.. group-tab:: Windows
|
|
|
|
You can use the ``setx`` program in ``cmd.exe`` or the third-party RapidEE
|
|
program.
|
|
|
|
To use ``setx``, type this command, then close the terminal window. Any
|
|
new ``cmd.exe`` windows will have ``MY_VARIABLE`` set to ``foo``.
|
|
|
|
.. code-block:: console
|
|
|
|
setx MY_VARIABLE foo
|
|
|
|
To install RapidEE, a freeware graphical environment variable editor,
|
|
`using Chocolatey`_ in an Administrator command prompt:
|
|
|
|
.. code-block:: console
|
|
|
|
choco install rapidee
|
|
|
|
You can then run ``rapidee`` from your terminal to launch the program and set
|
|
environment variables. Make sure to use the "User" environment variables area
|
|
-- otherwise, you have to run RapidEE as administrator. Also make sure to save
|
|
your changes by clicking the Save button at top left before exiting. Settings
|
|
you make in RapidEE will be available whenever you open a new terminal window.
|
|
|
|
.. _env_vars_zephyrrc:
|
|
|
|
Option 3: Using ``zephyrrc`` files
|
|
----------------------------------
|
|
|
|
Choose this option if you don't want to make the variable's setting available
|
|
to all of your terminals, but still want to save the value for loading into
|
|
your environment when you are using Zephyr.
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: Linux/macOS
|
|
|
|
Create a file named :file:`~/.zephyrrc` if it doesn't exist, then add this
|
|
line to it:
|
|
|
|
.. code-block:: console
|
|
|
|
export MY_VARIABLE=foo
|
|
|
|
To get this value back into your current terminal environment, **you must
|
|
run** ``source zephyr-env.sh`` from the main ``zephyr`` repository. Among
|
|
other things, this script sources :file:`~/.zephyrrc`.
|
|
|
|
The value will be lost if you close the window, etc.; run ``source
|
|
zephyr-env.sh`` again to get it back.
|
|
|
|
.. group-tab:: Windows
|
|
|
|
Add the line ``set MY_VARIABLE=foo`` to the file
|
|
:file:`%userprofile%\\zephyrrc.cmd` using a text editor such as Notepad to
|
|
save the value.
|
|
|
|
To get this value back into your current terminal environment, **you must
|
|
run** ``zephyr-env.cmd`` in a ``cmd.exe`` window after changing directory
|
|
to the main ``zephyr`` repository. Among other things, this script runs
|
|
:file:`%userprofile%\\zephyrrc.cmd`.
|
|
|
|
The value will be lost if you close the window, etc.; run
|
|
``zephyr-env.cmd`` again to get it back.
|
|
|
|
These scripts:
|
|
|
|
- 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
|
|
:ref:`env_vars_zephyrrc`.
|
|
|
|
You can thus use them any time you need any of these settings.
|
|
|
|
.. _zephyr-env:
|
|
|
|
Zephyr Environment Scripts
|
|
**************************
|
|
|
|
You can use the zephyr repository scripts ``zephyr-env.sh`` (for macOS and
|
|
Linux) and ``zephyr-env.cmd`` (for Windows) to load Zephyr-specific settings
|
|
into your current terminal's environment. To do so, run this command from the
|
|
zephyr repository:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: Linux/macOS
|
|
|
|
.. code-block:: console
|
|
|
|
source zephyr-env.sh
|
|
|
|
.. group-tab:: Windows
|
|
|
|
.. code-block:: console
|
|
|
|
zephyr-env.cmd
|
|
|
|
These scripts:
|
|
|
|
- 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 ``PATH`` environment variable
|
|
- loads any settings from the ``zephyrrc`` files described above in
|
|
:ref:`env_vars_zephyrrc`.
|
|
|
|
You can thus use them any time you need any of these settings.
|
|
|
|
.. _env_vars_important:
|
|
|
|
Important Environment Variables
|
|
*******************************
|
|
|
|
Some :ref:`important-build-vars` can also be set in the environment. Here
|
|
is a description of some of these important environment variables. This is not
|
|
a comprehensive list.
|
|
|
|
.. 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:: EXTRA_ZEPHYR_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_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>`.
|
|
|
|
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. 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
|