1.. _kconfig_extensions:
2
3Kconfig extensions
4##################
5
6Zephyr uses the `Kconfiglib <https://github.com/ulfalizer/Kconfiglib>`__
7implementation of `Kconfig
8<https://docs.kernel.org/kbuild/kconfig-language.html>`__,
9which includes some Kconfig extensions:
10
11- Default values can be applied to existing symbols without
12  :ref:`weakening <multiple_symbol_definitions>` the symbols dependencies
13  through the use of ``configdefault``.
14
15  .. code-block:: none
16
17      config FOO
18          bool "FOO"
19          depends on BAR
20
21      configdefault FOO
22          default y if FIZZ
23
24  The statement above is equivalent to:
25
26  .. code-block:: none
27
28      config FOO
29          bool "Foo"
30          default y if FIZZ
31          depends on BAR
32
33  ``configdefault`` symbols cannot contain any fields other than ``default``,
34  however they can be wrapped in ``if`` statements. The two statements below
35  are equivalent:
36
37  .. code-block:: none
38
39      configdefault FOO
40          default y if BAR
41
42      if BAR
43      configdefault FOO
44          default y
45      endif # BAR
46
47- Environment variables in ``source`` statements are expanded directly, meaning
48  no "bounce" symbols with ``option env="ENV_VAR"`` need to be defined.
49
50  .. note::
51
52     ``option env`` has been removed from the C tools as of Linux 4.18 as well.
53
54  The recommended syntax for referencing environment variables is ``$(FOO)``
55  rather than ``$FOO``. This uses the new `Kconfig preprocessor
56  <https://docs.kernel.org/kbuild/kconfig-macro-language.html>`__.
57  The ``$FOO`` syntax for expanding environment variables is only supported for
58  backwards compatibility.
59
60- The ``source`` statement supports glob patterns and includes each matching
61  file. A pattern is required to match at least one file.
62
63  Consider the following example:
64
65  .. code-block:: kconfig
66
67      source "foo/bar/*/Kconfig"
68
69  If the pattern ``foo/bar/*/Kconfig`` matches the files
70  :file:`foo/bar/baz/Kconfig` and :file:`foo/bar/qaz/Kconfig`, the statement
71  above is equivalent to the following two ``source`` statements:
72
73  .. code-block:: kconfig
74
75      source "foo/bar/baz/Kconfig"
76      source "foo/bar/qaz/Kconfig"
77
78  If no files match the pattern, an error is generated.
79
80  The wildcard patterns accepted are the same as for the Python `glob
81  <https://docs.python.org/3/library/glob.html>`__ module.
82
83  For cases where it's okay for a pattern to match no files (or for a plain
84  filename to not exist), a separate ``osource`` (*optional source*) statement
85  is available. ``osource`` is a no-op if no file matches.
86
87  .. note::
88
89      ``source`` and ``osource`` are analogous to ``include`` and
90      ``-include`` in Make.
91
92- An ``rsource`` statement is available for including files specified with a
93  relative path. The path is relative to the directory of the :file:`Kconfig`
94  file that contains the ``rsource`` statement.
95
96  As an example, assume that :file:`foo/Kconfig` is the top-level
97  :file:`Kconfig` file, and that :file:`foo/bar/Kconfig` has the following
98  statements:
99
100  .. code-block:: kconfig
101
102      source "qaz/Kconfig1"
103      rsource "qaz/Kconfig2"
104
105  This will include the two files :file:`foo/qaz/Kconfig1` and
106  :file:`foo/bar/qaz/Kconfig2`.
107
108  ``rsource`` can be used to create :file:`Kconfig` "subtrees" that can be
109  moved around freely.
110
111  ``rsource`` also supports glob patterns.
112
113  A drawback of ``rsource`` is that it can make it harder to figure out where a
114  file gets included, so only use it if you need it.
115
116- An ``orsource`` statement is available that combines ``osource`` and
117  ``rsource``.
118
119  For example, the following statement will include :file:`Kconfig1` and
120  :file:`Kconfig2` from the current directory (if they exist):
121
122  .. code-block:: kconfig
123
124      orsource "Kconfig[12]"
125
126- ``def_int``, ``def_hex``, and ``def_string`` keywords are available,
127  analogous to ``def_bool``. These set the type and add a ``default`` at the
128  same time.
129