OrgZephyr/zephyr
OrgZephyr
/
zephyr
mirror of https://github.com/zephyrproject-rtos/zephyr.git
1
0
Fork 0
Code Issues Releases Wiki Activity
zephyr/doc/develop/env_vars.rst

233 lines
6.8 KiB
ReStructuredText
Raw Normal View History

doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
.. _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
-------------------
doc: fix incorrect usage of envvar role :envvar: is currently used to tag environment variables, however, :envvar: role expects a matching .. envvar:: directive where the environment variable is defined. This patch fixes some cases by adding envvar directives and by converting certain cases to literals (it doesn't make sense to document all env vars in a list, as some are self-documented by contextual information). Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/ roles.html#role-envvar Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2022-08-19 19:30:43 +08:00
To set the environment variable ``MY_VARIABLE`` to ``foo`` for the
doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
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
doc: fix incorrect usage of envvar role :envvar: is currently used to tag environment variables, however, :envvar: role expects a matching .. envvar:: directive where the environment variable is defined. This patch fixes some cases by adding envvar directives and by converting certain cases to literals (it doesn't make sense to document all env vars in a list, as some are self-documented by contextual information). Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/ roles.html#role-envvar Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2022-08-19 19:30:43 +08:00
new ``cmd.exe`` windows will have ``MY_VARIABLE`` set to ``foo``.
doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
.. 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
doc: fix typos Add missed "space". Add missed "been". Signed-off-by: Andrej Butok <andrey.butok@nxp.com>
2023-11-07 19:39:49 +08:00
your changes by clicking the Save button at top left before exiting. Settings
doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
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:
doc: fix incorrect usage of envvar role :envvar: is currently used to tag environment variables, however, :envvar: role expects a matching .. envvar:: directive where the environment variable is defined. This patch fixes some cases by adding envvar directives and by converting certain cases to literals (it doesn't make sense to document all env vars in a list, as some are self-documented by contextual information). Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/ roles.html#role-envvar Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2022-08-19 19:30:43 +08:00
- set :envvar:`ZEPHYR_BASE` to the location of the zephyr repository
doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
- 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:
doc: fix incorrect usage of envvar role :envvar: is currently used to tag environment variables, however, :envvar: role expects a matching .. envvar:: directive where the environment variable is defined. This patch fixes some cases by adding envvar directives and by converting certain cases to literals (it doesn't make sense to document all env vars in a list, as some are self-documented by contextual information). Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/ roles.html#role-envvar Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2022-08-19 19:30:43 +08:00
- set :envvar:`ZEPHYR_BASE` to the location of the zephyr repository
doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
- adds some Zephyr-specific locations (such as zephyr's :file:`scripts`
doc: fix incorrect usage of envvar role :envvar: is currently used to tag environment variables, however, :envvar: role expects a matching .. envvar:: directive where the environment variable is defined. This patch fixes some cases by adding envvar directives and by converting certain cases to literals (it doesn't make sense to document all env vars in a list, as some are self-documented by contextual information). Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/ roles.html#role-envvar Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2022-08-19 19:30:43 +08:00
directory) to your ``PATH`` environment variable
doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
- 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.
doc: fix incorrect usage of envvar role :envvar: is currently used to tag environment variables, however, :envvar: role expects a matching .. envvar:: directive where the environment variable is defined. This patch fixes some cases by adding envvar directives and by converting certain cases to literals (it doesn't make sense to document all env vars in a list, as some are self-documented by contextual information). Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/ roles.html#role-envvar Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2022-08-19 19:30:43 +08:00
.. 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`.
doc: update Zephyr modules to use EXTRA_ZEPHYR_MODULES Update Zephyr modules documentation to use EXTRA_ZEPHYR_MODULES. This gives a more consistent naming scheme in Zephyr CMake build system. Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
2023-05-17 20:03:54 +08:00
.. envvar:: EXTRA_ZEPHYR_MODULES
doc: fix incorrect usage of envvar role :envvar: is currently used to tag environment variables, however, :envvar: role expects a matching .. envvar:: directive where the environment variable is defined. This patch fixes some cases by adding envvar directives and by converting certain cases to literals (it doesn't make sense to document all env vars in a list, as some are self-documented by contextual information). Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/ roles.html#role-envvar Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2022-08-19 19:30:43 +08:00
See :ref:`important-build-vars`.
.. envvar:: ZEPHYR_MODULES
See :ref:`important-build-vars`.
.. envvar:: ZEPHYR_BOARD_ALIASES
See :ref:`gs-board-aliases`
doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
The following additional environment variables are significant when configuring
the :ref:`toolchain <gs_toolchain>` used to build Zephyr applications.
doc: fix incorrect usage of envvar role :envvar: is currently used to tag environment variables, however, :envvar: role expects a matching .. envvar:: directive where the environment variable is defined. This patch fixes some cases by adding envvar directives and by converting certain cases to literals (it doesn't make sense to document all env vars in a list, as some are self-documented by contextual information). Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/ roles.html#role-envvar Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2022-08-19 19:30:43 +08:00
.. 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.)
doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
doc: gsg: Edit instructions to set SDK env vars Edited the changes added in commit 0a758c3. The changes aim at including the variable info in a note before the OS installation procedure for major visibility. Also added subsections on zephyr_sdk.rst page. Signed-off-by: Grzegorz Ferenc <Grzegorz.Ferenc@nordicsemi.no>
2022-06-08 15:41:02 +08:00
You might need to update some of these variables when you
:ref:`update the Zephyr SDK toolchain <gs_toolchain_update>`.
doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
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
doc: fix incorrect usage of envvar role :envvar: is currently used to tag environment variables, however, :envvar: role expects a matching .. envvar:: directive where the environment variable is defined. This patch fixes some cases by adding envvar directives and by converting certain cases to literals (it doesn't make sense to document all env vars in a list, as some are self-documented by contextual information). Ref. https://www.sphinx-doc.org/en/master/usage/restructuredtext/ roles.html#role-envvar Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2022-08-19 19:30:43 +08:00
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.
doc: restore environment variables page This was moved into the application development guide in commit bf9ceac ("doc: move env_vars into application development"). That commit claimed the following rationale: No reason why we are duplicating this information in a standalone guide when we already talk about env variables in the application developer guide. A github comment later says the duplication was in "Important build system variables": https://github.com/zephyrproject-rtos/zephyr/pull/34364#discussion_r616646517 This is incorrect and a misreading of the application development guide. The application development guide is talking about **cmake** variables. These are not the same thing at all as **environment** variables; treating them as if they are the same is simply wrong and misleading, especially the "option 4" part that is really about CMake variables, not environment variables. In fact, the separate environment variables page was created for a reason, which was to have a single place to explain to people unused to managing their environment how things work, without cluttering things up for people who already understand this. There is nothing wrong with small, self-contained guides and in fact I would argue they are a good thing. Fix this confusing situation by restoring the original, separate page and extricating the portions of it that are not related to environment variables. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-11-13 08:44:59 +08:00
.. _using Chocolatey: https://chocolatey.org/packages/RapidEE