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:
# Linux and macOS
export MY_VARIABLE=foo
# Windows
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¶
macOS and Linux:
Add the export MY_VARIABLE=foo
line to your shell’s startup script in your
home directory. For Bash, this is usually ~/.bashrc
on Linux or
~/.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.
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
.
setx MY_VARIABLE foo
To install RapidEE, a freeware graphical environment variable editor, using Chocolatey in an Administrator command prompt:
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.
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.
macOS and Linux:
Create a file named ~/.zephyrrc
if it doesn’t exist, then add this line
to it:
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 ~/.zephyrrc
.
The value will be lost if you close the window, etc.; run source
zephyr-env.sh
again to get it back.
Windows:
Add the line set MY_VARIABLE=foo
to the 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
%userprofile%\zephyrrc.cmd
.
The value will be lost if you close the window, etc.; run zephyr-env.cmd
again to get it back.
Option 4: Using Zephyr Build Configuration CMake package¶
Choose this option if you want to make those variable settings shared among all users of your project.
Using a Zephyr Build Configuration CMake package allows you to commit the shared settings into the repository, so that all users can share them.
It also removes the need for running source zephyr-env.sh
or
zephyr-env.cmd
when opening a new terminal.
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:
# macOS and Linux
source zephyr-env.sh
# Windows
zephyr-env.cmd
These scripts:
set
ZEPHYR_BASE
(see below) to the location of the zephyr repositoryadds some Zephyr-specific locations (such as zephyr’s
scripts
directory) to yourPATH
environment variableloads any settings from the
zephyrrc
files described above in Option 3: Using zephyrrc files.
You can thus use them any time you need any of these settings.
Important Environment Variables¶
Here are some important environment variables and what they contain. This is not a comprehensive index to the environment variables which affect Zephyr’s behavior.
BOARD
: allows set the board when building an application; see Important Build System Variables.CONF_FILE
: allows adding Kconfig fragments to an application build; see Important Build System Variables.DTC_OVERLAY_FILE
: allows adding devicetree overlays to an application build; see Important Build System Variables.ZEPHYR_BASE
: the absolute path to the mainzephyr
repository. This is set whenever you run thezephyr-env.sh
orzephyr-env.cmd
scripts mentioned above.ZEPHYR_TOOLCHAIN_VARIANT
: the current toolchain used to build Zephyr applications.