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>
This commit is contained in:
Martí Bolívar
Carles Cufí
parent
92e317c158
commit
71f17bcbc2
4 changed files with 214 additions and 145 deletions
|
|
@ -253,146 +253,8 @@ Zephyr.)
|
|||
|
||||
``include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)``
|
||||
is still supported for backward compatibility with older applications.
|
||||
Including ``boilerplate.cmake`` directly in the sample still requires to run
|
||||
``source zephyr-env.sh`` or execute ``zephyr-env.cmd`` before building the
|
||||
application.
|
||||
|
||||
|
||||
.. _env_vars:
|
||||
|
||||
Setting Variables
|
||||
*****************
|
||||
|
||||
Option 1: Just Once
|
||||
====================
|
||||
|
||||
To set the environment variable :envvar:`MY_VARIABLE` to ``foo`` for the
|
||||
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
|
||||
new ``cmd.exe`` windows will have :envvar:`MY_VARIABLE` set to ``foo``.
|
||||
|
||||
.. 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
|
||||
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.
|
||||
|
||||
.. _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:
|
||||
|
||||
- set :envvar:`ZEPHYR_BASE` (see below) to the location of the zephyr
|
||||
repository
|
||||
- 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.
|
||||
|
||||
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 :ref:`cmake_build_config_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.
|
||||
|
||||
Including ``boilerplate.cmake`` directly in the sample still requires using
|
||||
:ref:`zephyr-env` before building the application.
|
||||
|
||||
.. _important-build-vars:
|
||||
|
||||
|
|
@ -442,10 +304,21 @@ should know about.
|
|||
See :ref:`set-devicetree-overlays` for examples and :ref:`devicetree-intro`
|
||||
for information about devicetree and Zephyr.
|
||||
|
||||
* :makevar:`SHIELD`: see :ref:`shields`
|
||||
|
||||
* :makevar:`ZEPHYR_MODULES`: A CMake list containing absolute paths of
|
||||
additional directories with source code, Kconfig, etc. that should be used in
|
||||
the application build. See :ref:`modules` for details.
|
||||
the application build. See :ref:`modules` for details. If you set this
|
||||
variable, it must be a complete list of all modules to use, as the build
|
||||
system will not automatically pick up any modules from west.
|
||||
|
||||
* :makevar:`ZEPHYR_EXTRA_MODULES`: Like :makevar:`ZEPHYR_MODULES`, except these
|
||||
will be added to the list of modules found via west, instead of replacing it.
|
||||
|
||||
.. note::
|
||||
|
||||
You can use a :ref:`cmake_build_config_package` to share common settings for
|
||||
these variables.
|
||||
|
||||
Application CMakeLists.txt
|
||||
**************************
|
||||
|
|
|
|||
195
doc/guides/env_vars.rst
Normal file
195
doc/guides/env_vars.rst
Normal file
|
|
@ -0,0 +1,195 @@
|
|||
.. _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
|
||||
-------------------
|
||||
|
||||
To set the environment variable :envvar:`MY_VARIABLE` to ``foo`` for the
|
||||
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
|
||||
new ``cmd.exe`` windows will have :envvar:`MY_VARIABLE` set to ``foo``.
|
||||
|
||||
.. 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
|
||||
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.
|
||||
|
||||
.. _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:
|
||||
|
||||
- set :envvar:`ZEPHYR_BASE` (see below) to the location of the zephyr
|
||||
repository
|
||||
- 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:
|
||||
|
||||
- set :envvar:`ZEPHYR_BASE` (see below) to the location of the zephyr
|
||||
repository
|
||||
- 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.
|
||||
|
||||
.. _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.
|
||||
|
||||
- :envvar:`BOARD`
|
||||
- :envvar:`CONF_FILE`
|
||||
- :envvar:`SHIELD`
|
||||
- :envvar:`ZEPHYR_BASE`
|
||||
- :envvar:`ZEPHYR_EXTRA_MODULES`
|
||||
- :envvar:`ZEPHYR_MODULES`
|
||||
|
||||
The following additional environment variables are significant when configuring
|
||||
the :ref:`toolchain <gs_toolchain>` used to build Zephyr applications.
|
||||
|
||||
- :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 :envvar:`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.
|
||||
|
||||
.. _using Chocolatey: https://chocolatey.org/packages/RapidEE
|
||||
|
|
@ -17,6 +17,7 @@ User and Developer Guides
|
|||
debug_tools/index
|
||||
device_mgmt/index
|
||||
dts/index
|
||||
env_vars.rst
|
||||
pinctrl/index
|
||||
pm/index
|
||||
emulator/index.rst
|
||||
|
|
|
|||
|
|
@ -389,10 +389,10 @@ Zephyr Build Configuration CMake package
|
|||
The Zephyr Build Configuration CMake package provides a possibility for a Zephyr based project to
|
||||
control Zephyr build settings in a generic way.
|
||||
|
||||
It is similar to the use of ``.zephyrrc`` but with the possibility to automatically allow all users
|
||||
to share the build configuration through the project repository.
|
||||
But it also allows more advanced use cases than a ``.zephyrrc``-file, such as loading of additional
|
||||
CMake boilerplate code.
|
||||
It is similar to the per-user ``.zephyrrc`` file that can be used to set :ref:`env_vars`, but it
|
||||
sets CMake variables instead. It also allows you to automatically share the build configuration
|
||||
among all users through the project repository. It also allows more advanced use cases, such as loading
|
||||
of additional CMake boilerplate code.
|
||||
|
||||
The Zephyr Build Configuration CMake package will be loaded in the Zephyr boilerplate code after
|
||||
initial properties and ``ZEPHYR_BASE`` has been defined, but before CMake code execution.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue