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      Create a file named :file:`~/.zephyrrc` if it doesn't exist, then add this
92      line to it:
93
94      .. code-block:: console
95
96         export MY_VARIABLE=foo
97
98      To get this value back into your current terminal environment, **you must
99      run** ``source zephyr-env.sh`` from the main ``zephyr`` repository. Among
100      other things, this script sources :file:`~/.zephyrrc`.
101
102      The value will be lost if you close the window, etc.; run ``source
103      zephyr-env.sh`` again to get it back.
104
105   .. group-tab:: Windows
106
107      Add the line ``set MY_VARIABLE=foo`` to the file
108      :file:`%userprofile%\\zephyrrc.cmd` using a text editor such as Notepad to
109      save the value.
110
111      To get this value back into your current terminal environment, **you must
112      run** ``zephyr-env.cmd`` in a ``cmd.exe`` window after changing directory
113      to the main ``zephyr`` repository.  Among other things, this script runs
114      :file:`%userprofile%\\zephyrrc.cmd`.
115
116      The value will be lost if you close the window, etc.; run
117      ``zephyr-env.cmd`` again to get it back.
118
119      These scripts:
120
121      - set :envvar:`ZEPHYR_BASE` to the location of the zephyr repository
122      - adds some Zephyr-specific locations (such as zephyr's :file:`scripts`
123        directory) to your :envvar:`PATH` environment variable
124      - loads any settings from the ``zephyrrc`` files described above in
125        :ref:`env_vars_zephyrrc`.
126
127      You can thus use them any time you need any of these settings.
128
129.. _zephyr-env:
130
131Zephyr Environment Scripts
132**************************
133
134You can use the zephyr repository scripts ``zephyr-env.sh`` (for macOS and
135Linux) and ``zephyr-env.cmd`` (for Windows) to load Zephyr-specific settings
136into your current terminal's environment. To do so, run this command from the
137zephyr repository:
138
139.. tabs::
140
141   .. group-tab:: Linux/macOS
142
143      .. code-block:: console
144
145         source zephyr-env.sh
146
147   .. group-tab:: Windows
148
149      .. code-block:: console
150
151         zephyr-env.cmd
152
153These scripts:
154
155- set :envvar:`ZEPHYR_BASE` to the location of the zephyr repository
156- adds some Zephyr-specific locations (such as zephyr's :file:`scripts`
157  directory) to your ``PATH`` environment variable
158- loads any settings from the ``zephyrrc`` files described above in
159  :ref:`env_vars_zephyrrc`.
160
161You can thus use them any time you need any of these settings.
162
163.. _env_vars_important:
164
165Important Environment Variables
166*******************************
167
168Some :ref:`important-build-vars` can also be set in the environment. Here
169is a description of some of these important environment variables. This is not
170a comprehensive list.
171
172.. envvar:: BOARD
173
174   See :ref:`important-build-vars`.
175
176.. envvar:: CONF_FILE
177
178   See :ref:`important-build-vars`.
179
180.. envvar:: SHIELD
181
182   See :ref:`shields`.
183
184.. envvar:: ZEPHYR_BASE
185
186   See :ref:`important-build-vars`.
187
188.. envvar:: EXTRA_ZEPHYR_MODULES
189
190   See :ref:`important-build-vars`.
191
192.. envvar:: ZEPHYR_MODULES
193
194   See :ref:`important-build-vars`.
195
196.. envvar:: ZEPHYR_BOARD_ALIASES
197
198   See :ref:`gs-board-aliases`
199
200The following additional environment variables are significant when configuring
201the :ref:`toolchain <gs_toolchain>` used to build Zephyr applications.
202
203.. envvar:: ZEPHYR_SDK_INSTALL_DIR
204
205   Path where Zephyr SDK is installed.
206
207.. envvar:: ZEPHYR_TOOLCHAIN_VARIANT
208
209   The name of the toolchain to use.
210
211.. envvar:: {TOOLCHAIN}_TOOLCHAIN_PATH
212
213   Path to the toolchain specified by :envvar:`ZEPHYR_TOOLCHAIN_VARIANT`. For
214   example, if ``ZEPHYR_TOOLCHAIN_VARIANT=llvm``, use ``LLVM_TOOLCHAIN_PATH``.
215   (Note the capitalization when forming the environment variable name.)
216
217You might need to update some of these variables when you
218:ref:`update the Zephyr SDK toolchain <gs_toolchain_update>`.
219
220Emulators and boards may also depend on additional programs. The build system
221will try to locate those programs automatically, but may rely on additional
222CMake or environment variables to do so. Please consult your emulator's or
223board's documentation for more information. The following environment variables
224may be useful in such situations:
225
226.. envvar:: PATH
227
228   ``PATH`` is an environment variable used on Unix-like or Microsoft Windows
229   operating systems to specify a set of directories where executable programs
230   are located.
231
232.. _using Chocolatey: https://chocolatey.org/packages/RapidEE
233