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:

export 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

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.

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.

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.

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:

source zephyr-env.sh

These scripts:

  • set ZEPHYR_BASE (see below) to the location of the zephyr repository

  • adds some Zephyr-specific locations (such as zephyr’s scripts directory) to your PATH environment variable

  • loads 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

Some Important Build System Variables can also be set in the environment. Here is a description of some of these important environment variables. This is not a comprehensive list.

  • BOARD

  • CONF_FILE

  • SHIELD

  • ZEPHYR_BASE

  • ZEPHYR_EXTRA_MODULES

  • ZEPHYR_MODULES

The following additional environment variables are significant when configuring the toolchain used to build Zephyr applications.

  • ZEPHYR_TOOLCHAIN_VARIANT: the name of the toolchain to use

  • <TOOLCHAIN>_TOOLCHAIN_PATH: path to the toolchain specified by ZEPHYR_TOOLCHAIN_VARIANT. For example, if ZEPHYR_TOOLCHAIN_VARIANT=llvm, use LLVM_TOOLCHAIN_PATH. (Note the capitalization when forming the environment variable name.)

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.