5c7f2a3667
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>
93 lines
3.1 KiB
ReStructuredText
93 lines
3.1 KiB
ReStructuredText
.. _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.
|