michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: kconfig: Move extension docs from porting guide to user guide

Browse source 
The Kconfiglib Kconfig extensions are documented in the porting guide,
which is a pretty weird place to document them. Document them under a
new page in the Kconfig section of User and Developer Guides instead.

Also remove the section about the old Zephyr Kconfig behavior for
defaults (tried last-to-first instead of first-to-last). The behavior
was changed 16 months ago (and was undocumented before that), so it
might not be that useful to mention anymore.

Piggyback misc. small language cleanups and organization nits.

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This commit is contained in:
Ulf Magnusson 2019-12-03 06:32:31 +01:00 • committed by Carles Cufí
commit 5c7f2a3667
4 changed files with 94 additions and 147 deletions
Download patch file Download diff file Expand all files Collapse all files

3
doc/application/index.rst
View file

@ -1117,8 +1117,7 @@ Make sure to follow these steps in order.
"bounce" symbol. If you use such a symbol, it must have the same name as
the environment variable.
See the :ref:`kconfig_extensions` section in the
:ref:`board_porting_guide` for more information.
See :ref:`kconfig_extensions` for more information.
The :file:`Kconfig` file is automatically detected when placed in
the application directory, but it is also possible for it to be

92
doc/guides/kconfig/extensions.rst Normal file
View file

@ -0,0 +1,92 @@
.. _kconfig_extensions:
Kconfig extensions
##################
Zephyr uses the `Kconfiglib <https://github.com/ulfalizer/Kconfiglib>`__
implementation of `Kconfig
<https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt>`__,
which includes some Kconfig extensions:
- Environment variables in ``source`` statements are expanded directly, meaning
no "bounce" symbols with ``option env="ENV_VAR"`` need to be defined.
.. note::
``option env`` has been removed from the C tools as of Linux 4.18 as well.
The recommended syntax for referencing environment variables is ``$(FOO)``
rather than ``$FOO``. This uses the new `Kconfig preprocessor
<https://raw.githubusercontent.com/torvalds/linux/master/Documentation/kbuild/kconfig-macro-language.txt>`__.
The ``$FOO`` syntax for expanding environment variables is only supported for
backwards compatibility.
- The ``source`` statement supports glob patterns and includes each matching
file. A pattern is required to match at least one file.
Consider the following example:
.. code-block:: none
source "foo/bar/*/Kconfig"
If the pattern ``foo/bar/*/Kconfig`` matches the files
:file:`foo/bar/baz/Kconfig` and :file:`foo/bar/qaz/Kconfig`, the statement
above is equivalent to the following two ``source`` statements:
.. code-block:: none
source "foo/bar/baz/Kconfig"
source "foo/bar/qaz/Kconfig"
If no files match the pattern, an error is generated.
The wildcard patterns accepted are the same as for the Python `glob
<https://docs.python.org/3/library/glob.html>`__ module.
For cases where it's okay for a pattern to match no files (or for a plain
filename to not exist), a separate ``osource`` (*optional source*) statement
is available. ``osource`` is a no-op if no file matches.
.. note::
``source`` and ``osource`` are analogous to ``include`` and
``-include`` in Make.
- An ``rsource`` statement is available for including files specified with a
relative path. The path is relative to the directory of the :file:`Kconfig`
file that contains the ``rsource`` statement.
As an example, assume that :file:`foo/Kconfig` is the top-level
:file:`Kconfig` file, and that :file:`foo/bar/Kconfig` has the following
statements:
.. code-block:: none
source "qaz/Kconfig1"
rsource "qaz/Kconfig2"
This will include the two files :file:`foo/qaz/Kconfig1` and
:file:`foo/bar/qaz/Kconfig2`.
``rsource`` can be used to create :file:`Kconfig` "subtrees" that can be
moved around freely.
``rsource`` also supports glob patterns.
A drawback of ``rsource`` is that it can make it harder to figure out where a
file gets included, so only use it if you need it.
- An ``orsource`` statement is available that combines ``osource`` and
``rsource``.
For example, the following statement will include :file:`Kconfig1` and
:file:`Kconfig2` from the current directory (if they exist):
.. code-block:: none
orsource "Kconfig[12]"
- ``def_int``, ``def_hex``, and ``def_string`` keywords are available,
analogous to ``def_bool``. These set the type and add a ``default`` at the
same time.

1
doc/guides/kconfig/index.rst
View file

@ -6,3 +6,4 @@ Kconfig
tips.rst
preprocessor-functions.rst
extensions.rst

145
doc/guides/porting/board_porting.rst
View file

@ -345,151 +345,6 @@ invisible symbols.
Having fixed settings be user-configurable might be confusing, and would allow
the user to create broken configurations.
.. _kconfig_extensions:
Kconfig extensions
==================
Zephyr uses the `Kconfiglib <https://github.com/ulfalizer/Kconfiglib>`_
implementation of `Kconfig
<https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt>`_, which
includes some Kconfig extensions.
Environment variables in ``source`` statements are expanded directly in
Kconfiglib, meaning no ``option env="ENV_VAR"`` "bounce" symbols need to be
defined. If you need compatibility with the C Kconfig tools for an out-of-tree
Kconfig tree, you can still add such symbols, but they must have the same name
as the corresponding environment variables.
.. note::
``option env`` has been removed from the C tools in Linux 4.18 as well.
The recommended syntax for referencing environment variables is now
``$(FOO)`` rather than ``$FOO``. This uses the new `Kconfig preprocessor
<https://raw.githubusercontent.com/torvalds/linux/master/Documentation/kbuild/kconfig-macro-language.txt>`_.
The following Kconfig extensions are available:
- The ``source`` statement supports glob patterns and includes each matching
file. A pattern is required to match at least one file.
Consider the following example:
.. code-block:: none
source "foo/bar/*/Kconfig"
If the pattern ``foo/bar/*/Kconfig`` matches the files
:file:`foo/bar/baz/Kconfig` and :file:`foo/bar/qaz/Kconfig`, the statement
above is equivalent to the following two ``source`` statements:
.. code-block:: none
source "foo/bar/baz/Kconfig"
source "foo/bar/qaz/Kconfig"
.. note::
The wildcard patterns accepted are the same as for the Python `glob
<https://docs.python.org/3/library/glob.html>`_ module.
If no files match the pattern, an error is generated.
For cases where it's okay for a pattern to match no files (or for a plain
filename to not exist), a separate ``osource`` (*optional source*) statement
is available. ``osource`` is a no-op in case of no matches.
.. note::
``source`` and ``osource`` are analogous to ``include`` and
``-include`` in Make.
- An ``rsource`` statement is available for including files specified with a
relative path. The path is relative to the directory of the :file:`Kconfig`
file that contains the ``rsource`` statement.
As an example, assume that :file:`foo/Kconfig` is the top-level
:file:`Kconfig` file, and that :file:`foo/bar/Kconfig` has the following
statements:
.. code-block:: none
source "qaz/Kconfig1"
rsource "qaz/Kconfig2"
This will include the two files :file:`foo/qaz/Kconfig1` and
:file:`foo/bar/qaz/Kconfig2`.
``rsource`` can be used to create :file:`Kconfig` "subtrees" that can be
moved around freely.
.. note::
``rsource`` also supports glob patterns.
- An ``orsource`` statement, which combines ``osource`` and ``rsource``.
For example, the following statement will include :file:`Kconfig1` and
:file:`Kconfig2` from the current directory (if they exist):
.. code-block:: none
orsource "Kconfig[12]"
- ``def_int``, ``def_hex``, and ``def_string`` keywords, which are analogous to
``def_bool``. These set the type and add a ``default`` at the same time.
Old Zephyr Kconfig behavior for defaults
========================================
Prior to early August 2018 (during development of Zephyr 1.13), Zephyr used a
custom patch that made Kconfig prefer the last ``default`` with a satisfied
condition, instead of the first one. This patch has been removed.
Consider this example:
.. code-block:: none
config FOO
string
default "first" if n
default "second"
default "third" if n
default "fourth"
default "fifth" if n
With the old custom behavior, ``FOO`` got the value ``"fourth"``, from the last
``default`` with a satisfied condition.
With the new behavior, ``FOO`` gets the value ``"second"``, from the first
``default`` with a satisfied condition. This is standard Kconfig behavior.
There are two issues with the old behavior:
1. It's inconsistent with how Kconfig works in other projects, which is
confusing.
2. Due to oversights, earlier ``range`` properties were still preferred, as
well as earlier ``default`` properties on choices.
In addition to being inconsistent, this made it impossible to override
``range`` properties and ``default`` properties on choices if the base
definition of the symbol/choice already had ``range``/``default``
properties.
.. note::
If you're maintaining an external project that has symbols with multiple
``default`` properties, you will need to swap the order of the ``default``
properties to get the same behavior as before.
If your external project is modifying symbols in the base Zephyr
configuration by sourcing ``Kconfig.zephyr`` and adding additional symbol
definitions, you might need to move the ``source`` from before the extra
symbol definitions to after them.
More Kconfig resources
======================