1.. _env_vars:
2
3Environment Variables
4=====================
5
6Various pages in this documentation refer to setting Zephyr-specific
7environment variables. This page describes how.
8
9Setting Variables
10*****************
11
12Option 1: Just Once
13-------------------
14
15To set the environment variable ``MY_VARIABLE`` to ``foo`` for the
16lifetime of your current terminal window:
17
18.. tabs::
19
20   .. group-tab:: Linux/macOS
21
22      .. code-block:: console
23
24         export MY_VARIABLE=foo
25
26   .. group-tab:: Windows
27
28      .. code-block:: console
29
30         set MY_VARIABLE=foo
31
32.. warning::
33
34  This is best for experimentation. If you close your terminal window, use
35  another terminal window or tab, restart your computer, etc., this setting
36  will be lost forever.
37
38  Using options 2 or 3 is recommended if you want to keep using the setting.
39
40Option 2: In all Terminals
41--------------------------
42
43.. tabs::
44
45   .. group-tab:: Linux/macOS
46
47      Add the ``export MY_VARIABLE=foo`` line to your shell's startup script in
48      your home directory. For Bash, this is usually :file:`~/.bashrc` on Linux
49      or :file:`~/.bash_profile` on macOS.  Changes in these startup scripts
50      don't affect shell instances already started; try opening a new terminal
51      window to get the new settings.
52
53   .. group-tab:: Windows
54
55      You can use the ``setx`` program in ``cmd.exe`` or the third-party RapidEE
56      program.
57
58      To use ``setx``, type this command, then close the terminal window. Any
59      new ``cmd.exe`` windows will have ``MY_VARIABLE`` set to ``foo``.
60
61      .. code-block:: console
62
63         setx MY_VARIABLE foo
64
65      To install RapidEE, a freeware graphical environment variable editor,
66      `using Chocolatey`_ in an Administrator command prompt:
67
68      .. code-block:: console
69
70         choco install rapidee
71
72      You can then run ``rapidee`` from your terminal to launch the program and set
73      environment variables. Make sure to use the "User" environment variables area
74      -- otherwise, you have to run RapidEE as administrator. Also make sure to save
75      your changes by clicking the Save button at top left before exiting. Settings
76      you make in RapidEE will be available whenever you open a new terminal window.
77
78.. _env_vars_zephyrrc:
79
80Option 3: Using ``zephyrrc`` files
81----------------------------------
82
83Choose this option if you don't want to make the variable's setting available
84to all of your terminals, but still want to save the value for loading into
85your environment when you are using Zephyr.
86
87.. tabs::
88
89   .. group-tab:: Linux/macOS
90
91      Zephyr supports multiple locations for your :file:`zephyrrc` file,
92      following the XDG Base Directory Specification when possible. Create a
93      zephyrrc file in one of the following locations (they will be checked in
94      order):
95
96      #. :file:`$XDG_CONFIG_HOME/zephyr/zephyrrc`
97      #. :file:`$HOME/.config/zephyr/zephyrrc`
98      #. :file:`$HOME/.zephyrrc`
99
100      Add this line to the file in your preferred location:
101
102      .. code-block:: console
103
104         export MY_VARIABLE=foo
105
106      To get this value back into your current terminal environment, **you must
107      run** ``source zephyr-env.sh`` from the main ``zephyr`` repository. Among
108      other things, this script sources your :file:`zephyrrc` (the first one it
109      finds from the list of locations above).
110
111      The value will be lost if you close the window, etc.; run ``source
112      zephyr-env.sh`` again to get it back.
113
114   .. group-tab:: Windows
115
116      Add the line ``set MY_VARIABLE=foo`` to the file
117      :file:`%userprofile%\\zephyrrc.cmd` using a text editor such as Notepad to
118      save the value.
119
120      To get this value back into your current terminal environment, **you must
121      run** ``zephyr-env.cmd`` in a ``cmd.exe`` window after changing directory
122      to the main ``zephyr`` repository.  Among other things, this script runs
123      :file:`%userprofile%\\zephyrrc.cmd`.
124
125      The value will be lost if you close the window, etc.; run
126      ``zephyr-env.cmd`` again to get it back.
127
128      These scripts:
129
130      - set :envvar:`ZEPHYR_BASE` to the location of the zephyr repository
131      - adds some Zephyr-specific locations (such as zephyr's :file:`scripts`
132        directory) to your :envvar:`PATH` environment variable
133      - loads any settings from the ``zephyrrc`` files described above in
134        :ref:`env_vars_zephyrrc`.
135
136      You can thus use them any time you need any of these settings.
137
138.. _zephyr-env:
139
140Zephyr Environment Scripts
141**************************
142
143You can use the zephyr repository scripts ``zephyr-env.sh`` (for macOS and
144Linux) and ``zephyr-env.cmd`` (for Windows) to load Zephyr-specific settings
145into your current terminal's environment. To do so, run this command from the
146zephyr repository:
147
148.. tabs::
149
150   .. group-tab:: Linux/macOS
151
152      .. code-block:: console
153
154         source zephyr-env.sh
155
156   .. group-tab:: Windows
157
158      .. code-block:: console
159
160         zephyr-env.cmd
161
162These scripts:
163
164- set :envvar:`ZEPHYR_BASE` to the location of the zephyr repository
165- adds some Zephyr-specific locations (such as zephyr's :file:`scripts`
166  directory) to your ``PATH`` environment variable
167- loads any settings from the ``zephyrrc`` files described above in
168  :ref:`env_vars_zephyrrc`.
169
170You can thus use them any time you need any of these settings.
171
172.. _env_vars_important:
173
174Important Environment Variables
175*******************************
176
177Some :ref:`important-build-vars` can also be set in the environment. Here
178is a description of some of these important environment variables. This is not
179a comprehensive list.
180
181.. envvar:: BOARD
182
183   See :ref:`important-build-vars`.
184
185.. envvar:: CONF_FILE
186
187   See :ref:`important-build-vars`.
188
189.. envvar:: SHIELD
190
191   See :ref:`shields`.
192
193.. envvar:: ZEPHYR_BASE
194
195   See :ref:`important-build-vars`.
196
197.. envvar:: EXTRA_ZEPHYR_MODULES
198
199   See :ref:`important-build-vars`.
200
201.. envvar:: ZEPHYR_MODULES
202
203   See :ref:`important-build-vars`.
204
205.. envvar:: ZEPHYR_BOARD_ALIASES
206
207   See :ref:`gs-board-aliases`
208
209The following additional environment variables are significant when configuring
210the :ref:`toolchain <gs_toolchain>` used to build Zephyr applications.
211
212.. envvar:: ZEPHYR_SDK_INSTALL_DIR
213
214   Path where Zephyr SDK is installed.
215
216.. envvar:: ZEPHYR_TOOLCHAIN_VARIANT
217
218   The name of the toolchain to use.
219
220.. envvar:: {TOOLCHAIN}_TOOLCHAIN_PATH
221
222   Path to the toolchain specified by :envvar:`ZEPHYR_TOOLCHAIN_VARIANT`. For
223   example, if ``ZEPHYR_TOOLCHAIN_VARIANT=llvm``, use ``LLVM_TOOLCHAIN_PATH``.
224   (Note the capitalization when forming the environment variable name.)
225
226You might need to update some of these variables when you
227:ref:`update the Zephyr SDK toolchain <gs_toolchain_update>`.
228
229Emulators and boards may also depend on additional programs. The build system
230will try to locate those programs automatically, but may rely on additional
231CMake or environment variables to do so. Please consult your emulator's or
232board's documentation for more information. The following environment variables
233may be useful in such situations:
234
235.. envvar:: PATH
236
237   ``PATH`` is an environment variable used on Unix-like or Microsoft Windows
238   operating systems to specify a set of directories where executable programs
239   are located.
240
241.. _using Chocolatey: https://chocolatey.org/packages/RapidEE
242