Atlas - README.rst
Home / ext / kconfiglib
Lines: 1 | Size: 38432 bytes
[Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)] 
[FILE BEGIN]
1.. contents:: Table of contents
2   :backlinks: none
3
4News
5----
6
7Dependency loop with recent linux-next kernels
8~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9
10To fix issues with dependency loops on recent linux-next kernels, apply `this
11patch <https://www.spinics.net/lists/linux-kbuild/msg23455.html>`_. Hopefully,
12it will be in ``linux-next`` soon.
13
14``windows-curses`` is no longer automatically installed on Windows
15~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16
17Starting with Kconfiglib 13.0.0, the `windows-curses
18<https://github.com/zephyrproject-rtos/windows-curses>`__ package is no longer
19automatically installed on Windows, and needs to be installed manually for the
20terminal ``menuconfig`` to work.
21
22This fixes installation of Kconfiglib on MSYS2, which is not compatible with
23``windows-curses``. See `this issue
24<https://github.com/ulfalizer/Kconfiglib/issues/77>`__.
25
26The ``menuconfig`` now shows a hint re. installing ``windows-curses`` when the
27``curses`` module can't be imported on Windows.
28
29Sorry if this change caused problems!
30
31Overview
32--------
33
34Kconfiglib is a `Kconfig
35<https://github.com/torvalds/linux/blob/master/Documentation/kbuild/kconfig-language.rst>`__
36implementation in Python 2/3. It started out as a helper library, but now has a
37enough functionality to also work well as a standalone Kconfig implementation
38(including `terminal and GUI menuconfig interfaces <Menuconfig interfaces_>`_
39and `Kconfig extensions`_).
40
41The entire library is contained in `kconfiglib.py
42<https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_. The
43bundled scripts are implemented on top of it. Implementing your own scripts
44should be relatively easy, if needed.
45
46Kconfiglib is used exclusively by e.g. the `Zephyr
47<https://www.zephyrproject.org/>`__, `esp-idf
48<https://github.com/espressif/esp-idf>`__, and `ACRN
49<https://projectacrn.org/>`__ projects. It is also used for many small helper
50scripts in various projects.
51
52Since Kconfiglib is based around a library, it can be used e.g. to generate a
53`Kconfig cross-reference
54<https://docs.zephyrproject.org/latest/reference/kconfig/index.html>`_, using
55the same robust Kconfig parser used for other Kconfig tools, instead of brittle
56ad-hoc parsing. The documentation generation script can be found `here
57<https://github.com/zephyrproject-rtos/zephyr/blob/master/doc/scripts/genrest.py>`__.
58
59Kconfiglib implements the recently added `Kconfig preprocessor
60<https://github.com/torvalds/linux/blob/master/Documentation/kbuild/kconfig-macro-language.rst>`__.
61For backwards compatibility, environment variables can be referenced both as
62``$(FOO)`` (the new syntax) and as ``$FOO`` (the old syntax). The old syntax is
63deprecated, but will probably be supported for a long time, as it's needed to
64stay compatible with older Linux kernels. The major version will be increased
65if support is ever dropped. Using the old syntax with an undefined environment
66variable keeps the string as is.
67
68Note: See `this issue <https://github.com/ulfalizer/Kconfiglib/issues/47>`__ if
69you run into a "macro expanded to blank string" error with kernel 4.18+.
70
71See `this page
72<https://docs.zephyrproject.org/latest/guides/kconfig/tips.html>`__ for some
73Kconfig tips and best practices.
74
75Installation
76------------
77
78Installation with pip
79~~~~~~~~~~~~~~~~~~~~~
80
81Kconfiglib is available on `PyPI <https://pypi.python.org/pypi/kconfiglib/>`_ and can be
82installed with e.g.
83
84.. code::
85
86    $ pip(3) install kconfiglib
87
88Microsoft Windows is supported.
89
90The ``pip`` installation will give you both the base library and the following
91executables. All but two (``genconfig`` and ``setconfig``) mirror functionality
92available in the C tools.
93
94- `menuconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/menuconfig.py>`_
95
96- `guiconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/guiconfig.py>`_
97
98- `oldconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/oldconfig.py>`_
99
100- `olddefconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/olddefconfig.py>`_
101
102- `savedefconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/savedefconfig.py>`_
103
104- `defconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/defconfig.py>`_
105
106- `alldefconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/alldefconfig.py>`_
107
108- `allnoconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/allnoconfig.py>`_
109
110- `allmodconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/allmodconfig.py>`_
111
112- `allyesconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/allyesconfig.py>`_
113
114- `listnewconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/listnewconfig.py>`_
115
116- `genconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/genconfig.py>`_
117
118- `setconfig <https://github.com/ulfalizer/Kconfiglib/blob/master/setconfig.py>`_
119
120``genconfig`` is intended to be run at build time. It generates a C header from
121the configuration and (optionally) information that can be used to rebuild only
122files that reference Kconfig symbols that have changed value.
123
124Starting with Kconfiglib version 12.2.0, all utilities are compatible with both
125Python 2 and Python 3. Previously, ``menuconfig.py`` only ran under Python 3
126(i.e., it's now more backwards compatible than before).
127
128**Note:** If you install Kconfiglib with ``pip``'s ``--user`` flag, make sure
129that your ``PATH`` includes the directory where the executables end up. You can
130list the installed files with ``pip(3) show -f kconfiglib``.
131
132All releases have a corresponding tag in the git repository, e.g. ``v14.1.0``
133(the latest version).
134
135`Semantic versioning <http://semver.org/>`_ is used. There's been ten small
136changes to the behavior of the API, a Windows packaging change, and a hashbang
137change to use ``python3``
138(`1 <https://github.com/ulfalizer/Kconfiglib/commit/e8b4ecb6ff6ccc1c7be0818314fbccda2ef2b2ee>`_,
139`2 <https://github.com/ulfalizer/Kconfiglib/commit/db633015a4d7b0ba1e882f665e191f350932b2af>`_,
140`3 <https://github.com/ulfalizer/Kconfiglib/commit/8983f7eb297dd614faf0beee3129559bc8ba338e>`_,
141`4 <https://github.com/ulfalizer/Kconfiglib/commit/cbf32e29a130d22bc734b7778e6304ac9df2a3e8>`_,
142`5 <https://github.com/ulfalizer/Kconfiglib/commit/eb6c21a9b33a2d6e2bed9882d4f930d0cab2f03b>`_,
143`6 <https://github.com/ulfalizer/Kconfiglib/commit/c19fc11355b13d75d97286402c7a933fb23d3b70>`_,
144`7 <https://github.com/ulfalizer/Kconfiglib/commit/7a428aa415606820a44291f475248b08e3952c4b>`_,
145`8 <https://github.com/ulfalizer/Kconfiglib/commit/f247ddf618ad29718e5efd3e69f8baf75d4d347b>`_,
146`9 <https://github.com/ulfalizer/Kconfiglib/commit/4fed39d9271ceb68be4157ab3f96a45b94f77dc0>`_,
147`10 <https://github.com/ulfalizer/Kconfiglib/commit/55bc8c380869ea663092212e8fe388ad7abae596>`_,
148`Windows packaging change <https://github.com/ulfalizer/Kconfiglib/commit/21b4c1e3b6e2867b9a0788d21a358f6b1f581d86>`_,
149`Python 3 hashbang change <https://github.com/ulfalizer/Kconfiglib/commit/9e0a8d29fa76adcb3f27bb2e20f16fefc2a8591e>`_),
150which is why the major version is at 14 rather than 2. I do major version bumps
151for all behavior changes, even tiny ones, and most of these were fixes for baby
152issues in the early days of the Kconfiglib 2 API.
153
154Manual installation
155~~~~~~~~~~~~~~~~~~~
156
157Just drop ``kconfiglib.py`` and the scripts you want somewhere. There are no
158third-party dependencies, but the terminal ``menuconfig`` won't work on Windows
159unless a package like `windows-curses
160<https://github.com/zephyrproject-rtos/windows-curses>`__ is installed.
161
162Installation for the Linux kernel
163~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
164
165See the module docstring at the top of `kconfiglib.py <https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_.
166
167Python version compatibility (2.7/3.2+)
168~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
169
170Kconfiglib and all utilities run under both Python 2.7 and Python 3.2 and
171later. The code mostly uses basic Python features and has no third-party
172dependencies, so keeping it backwards-compatible is pretty low effort.
173
174The 3.2 requirement comes from ``argparse``. ``format()`` with unnumbered
175``{}`` is used as well.
176
177A recent Python 3 version is recommended if you have a choice, as it'll give
178you better Unicode handling.
179
180Getting started
181---------------
182
1831. `Install <Installation_>`_ the library and the utilities.
184
1852. Write `Kconfig
186   <https://github.com/torvalds/linux/blob/master/Documentation/kbuild/kconfig-language.rst>`__
187   files that describe the available configuration options. See `this page
188   <https://docs.zephyrproject.org/latest/guides/kconfig/tips.html>`__ for some
189   general Kconfig advice.
190
1913. Generate an initial configuration with e.g. ``menuconfig``/``guiconfig`` or
192   ``alldefconfig``. The configuration is saved as ``.config`` by default.
193
194   For more advanced projects, the ``defconfig`` utility can be used to
195   generate the initial configuration from an existing configuration file.
196   Usually, this existing configuration file would be a minimal configuration
197   file, as generated by e.g. ``savedefconfig``.
198
1994. Run ``genconfig`` to generate a header file. By default, it is saved as
200   ``config.h``.
201
202   Normally, ``genconfig`` would be run automatically as part of the build.
203
204   Before writing a header file or other configuration output, Kconfiglib
205   compares the old contents of the file against the new contents. If there's
206   no change, the write is skipped. This avoids updating file metadata like the
207   modification time, and might save work depending on your build setup.
208   
209   Adding new configuration output formats should be relatively straightforward.
210   See the implementation of ``write_config()`` in `kconfiglib.py
211   <https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_.
212   The documentation for the ``Symbol.config_string`` property has some tips as
213   well.
214   
2155. To update an old ``.config`` file after the Kconfig files have changed (e.g.
216   to add new options), run ``oldconfig`` (prompts for values for new options)
217   or ``olddefconfig`` (gives new options their default value). Entering the
218   ``menuconfig`` or ``guiconfig`` interface and saving the configuration will
219   also update it (the configuration interfaces always prompt for saving
220   on exit if it would modify the contents of the ``.config`` file).
221
222   Due to Kconfig semantics, simply loading an old ``.config`` file performs an
223   implicit ``olddefconfig``, so building will normally not be affected by
224   having an outdated configuration.
225
226Whenever ``.config`` is overwritten, the previous version of the file is saved
227to ``.config.old`` (or, more generally, to ``$KCONFIG_CONFIG.old``).
228
229Using ``.config`` files as Make input
230~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
231
232``.config`` files use Make syntax and can be included directly in Makefiles to
233read configuration values from there. This is why ``n``-valued
234``bool``/``tristate`` values are written out as ``# CONFIG_FOO is not set`` (a
235Make comment) in ``.config``, allowing them to be tested with ``ifdef`` in
236Make.
237
238If you make use of this, you might want to pass ``--config-out <filename>`` to
239``genconfig`` and include the configuration file it generates instead of
240including ``.config`` directly. This has the advantage that the generated
241configuration file will always be a "full" configuration file, even if
242``.config`` is outdated. Otherwise, it might be necessary to run
243``old(def)config`` or ``menuconfig``/``guiconfig`` before rebuilding with an
244outdated ``.config``.
245
246If you use ``--sync-deps`` to generate incremental build information, you can
247include ``deps/auto.conf`` instead, which is also a full configuration file.
248
249Useful helper macros
250~~~~~~~~~~~~~~~~~~~~
251
252The `include/linux/kconfig.h
253<https://github.com/torvalds/linux/blob/master/include/linux/kconfig.h>`_
254header in the Linux kernel defines some useful helper macros for testing
255Kconfig configuration values.
256
257``IS_ENABLED()`` is generally useful, allowing configuration values to be
258tested in ``if`` statements with no runtime overhead.
259
260Incremental building
261~~~~~~~~~~~~~~~~~~~~
262
263See the docstring for ``Kconfig.sync_deps()`` in `kconfiglib.py
264<https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_ for hints
265on implementing incremental builds (rebuilding just source files that reference
266changed configuration values).
267
268Running the ``scripts/basic/fixdep.c`` tool from the kernel on the output of
269``gcc -MD <source file>`` might give you an idea of how it all fits together.
270
271Library documentation
272---------------------
273
274Kconfiglib comes with extensive documentation in the form of docstrings. To view it, run e.g.
275the following command:
276
277.. code:: sh
278
279    $ pydoc(3) kconfiglib
280
281For HTML output, add ``-w``:
282
283.. code:: sh
284
285    $ pydoc(3) -w kconfiglib
286
287This will also work after installing Kconfiglib with ``pip(3)``.
288
289Documentation for other modules can be viewed in the same way (though a plain
290``--help`` will work when they're run as executables):
291
292.. code:: sh
293
294    $ pydoc(3) menuconfig/guiconfig/...
295
296A good starting point for learning the library is to read the module docstring
297(which you could also just read directly at the beginning of `kconfiglib.py
298<https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_). It
299gives an introduction to symbol values, the menu tree, and expressions.
300
301After reading the module docstring, a good next step is to read the ``Kconfig``
302class documentation, and then the documentation for the ``Symbol``, ``Choice``,
303and ``MenuNode`` classes.
304
305Please tell me if something is unclear or can be explained better.
306
307Library features
308----------------
309
310Kconfiglib can do the following, among other things:
311
312- **Programmatically get and set symbol values**
313
314  See `allnoconfig.py
315  <https://github.com/ulfalizer/Kconfiglib/blob/master/allnoconfig.py>`_ and
316  `allyesconfig.py
317  <https://github.com/ulfalizer/Kconfiglib/blob/master/allyesconfig.py>`_,
318  which are automatically verified to produce identical output to the standard
319  ``make allnoconfig`` and ``make allyesconfig``.
320
321- **Read and write .config and defconfig files**
322
323  The generated ``.config`` and ``defconfig`` (minimal configuration) files are
324  character-for-character identical to what the C implementation would generate
325  (except for the header comment). The test suite relies on this, as it
326  compares the generated files.
327  
328- **Write C headers**
329
330  The generated headers use the same format as ``include/generated/autoconf.h``
331  from the Linux kernel. Output for symbols appears in the order that they're
332  defined, unlike in the C tools (where the order depends on the hash table
333  implementation).
334
335- **Implement incremental builds**
336
337  This uses the same scheme as the ``include/config`` directory in the kernel:
338  Symbols are translated into files that are touched when the symbol's value
339  changes between builds, which can be used to avoid having to do a full
340  rebuild whenever the configuration is changed.
341
342  See the ``sync_deps()`` function for more information.
343
344- **Inspect symbols**
345
346  Printing a symbol or other item (which calls ``__str__()``) returns its
347  definition in Kconfig format. This also works for symbols defined in multiple
348  locations.
349
350  A helpful ``__repr__()`` is  on all objects too.
351
352  All ``__str__()`` and ``__repr__()`` methods are deliberately implemented
353  with just public APIs, so all symbol information can be fetched separately as
354  well.
355
356- **Inspect expressions**
357
358  Expressions use a simple tuple-based format that can be processed manually
359  if needed. Expression printing and evaluation functions are provided,
360  implemented with public APIs.
361
362- **Inspect the menu tree**
363
364  The underlying menu tree is exposed, including submenus created implicitly
365  from symbols depending on preceding symbols. This can be used e.g. to
366  implement menuconfig-like functionality.
367  
368  See `menuconfig.py
369  <https://github.com/ulfalizer/Kconfiglib/blob/master/menuconfig.py>`_/`guiconfig.py
370  <https://github.com/ulfalizer/Kconfiglib/blob/master/guiconfig.py>`_ and the
371  minimalistic `menuconfig_example.py
372  <https://github.com/ulfalizer/Kconfiglib/blob/master/examples/menuconfig_example.py>`_
373  example.
374
375Kconfig extensions
376~~~~~~~~~~~~~~~~~~
377
378The following Kconfig extensions are available:
379
380- ``source`` supports glob patterns and includes each matching file. A pattern
381  is required to match at least one file.
382
383  A separate ``osource`` statement is available for cases where it's okay for
384  the pattern to match no files (in which case ``osource`` turns into a no-op).
385  
386- A relative ``source`` statement (``rsource``) is available, where file paths
387  are specified relative to the directory of the current Kconfig file. An
388  ``orsource`` statement is available as well, analogous to ``osource``.
389
390- Preprocessor user functions can be defined in Python, which makes it simple
391  to integrate information from existing Python tools into Kconfig (e.g. to
392  have Kconfig symbols depend on hardware information stored in some other
393  format).
394
395  See the *Kconfig extensions* section in the
396  `kconfiglib.py <https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_
397  module docstring for more information.
398
399- ``def_int``, ``def_hex``, and ``def_string`` are available in addition to
400  ``def_bool`` and ``def_tristate``, allowing ``int``, ``hex``, and ``string``
401  symbols to be given a type and a default at the same time.
402
403  These can be useful in projects that make use of symbols defined in multiple
404  locations, and remove some Kconfig inconsistency.
405  
406- Environment variables are expanded directly in e.g. ``source`` and
407  ``mainmenu`` statements, meaning ``option env`` symbols are redundant.
408
409  This is the standard behavior with the new `Kconfig preprocessor
410  <https://github.com/torvalds/linux/blob/master/Documentation/kbuild/kconfig-macro-language.rst>`__,
411  which Kconfiglib implements.
412
413  ``option env`` symbols are accepted but ignored, which leads the caveat that
414  they must have the same name as the environment variables they reference
415  (Kconfiglib warns if the names differ). This keeps Kconfiglib compatible with
416  older Linux kernels, where the name of the ``option env`` symbol always
417  matched the environment variable. Compatibility with older Linux kernels is
418  the main reason ``option env`` is still supported.
419
420  The C tools have dropped support for ``option env``.
421
422- Two extra optional warnings can be enabled by setting environment variables,
423  covering cases that are easily missed when making changes to Kconfig files:
424
425  * ``KCONFIG_WARN_UNDEF``: If set to ``y``, warnings will be generated for all
426    references to undefined symbols within Kconfig files. The only gotcha is
427    that all hex literals must be prefixed with ``0x`` or ``0X``, to make it
428    possible to distinguish them from symbol references.
429
430    Some projects (e.g. the Linux kernel) use multiple Kconfig trees with many
431    shared Kconfig files, leading to some safe undefined symbol references.
432    ``KCONFIG_WARN_UNDEF`` is useful in projects that only have a single
433    Kconfig tree though.
434
435    ``KCONFIG_STRICT`` is an older alias for this environment variable,
436    supported for backwards compatibility.
437
438  * ``KCONFIG_WARN_UNDEF_ASSIGN``: If set to ``y``, warnings will be generated
439    for all assignments to undefined symbols within ``.config`` files. By
440    default, no such warnings are generated.
441
442    This warning can also be enabled/disabled by setting
443    ``Kconfig.warn_assign_undef`` to ``True``/``False``.
444
445Other features
446--------------
447
448- **Single-file implementation**
449  
450  The entire library is contained in `kconfiglib.py
451  <https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_.
452
453  The tools implemented on top of it are one file each.
454
455- **Robust and highly compatible with the C Kconfig tools**
456  
457  The `test suite <https://github.com/ulfalizer/Kconfiglib/blob/master/testsuite.py>`_
458  automatically compares output from Kconfiglib and the C tools
459  by diffing the generated ``.config`` files for the real kernel Kconfig and
460  defconfig files, for all ARCHes.
461  
462  This currently involves comparing the output for 36 ARCHes and 498 defconfig
463  files (or over 18000 ARCH/defconfig combinations in "obsessive" test suite
464  mode). All tests are expected to pass.
465
466  A comprehensive suite of selftests is included as well.
467
468- **Not horribly slow despite being a pure Python implementation**
469  
470  The `allyesconfig.py
471  <https://github.com/ulfalizer/Kconfiglib/blob/master/allyesconfig.py>`_
472  script currently runs in about 1.3 seconds on the Linux kernel on a Core i7
473  2600K (with a warm file cache), including the ``make`` overhead from ``make
474  scriptconfig``. Note that the Linux kernel Kconfigs are absolutely massive
475  (over 14k symbols for x86) compared to most projects, and also have overhead
476  from running shell commands via the Kconfig preprocessor.
477  
478  Kconfiglib is especially speedy in cases where multiple ``.config`` files
479  need to be processed, because the ``Kconfig`` files will only need to be parsed
480  once.
481
482  For long-running jobs, `PyPy <https://pypy.org/>`_ gives a big performance
483  boost. CPython is faster for short-running jobs as PyPy needs some time to
484  warm up.
485  
486  Kconfiglib also works well with the
487  `multiprocessing <https://docs.python.org/3/library/multiprocessing.html>`_
488  module. No global state is kept.
489
490- **Generates more warnings than the C implementation**
491
492  Generates the same warnings as the C implementation, plus additional ones.
493  Also detects dependency and ``source`` loops.
494
495  All warnings point out the location(s) in the ``Kconfig`` files where a
496  symbol is defined, where applicable.
497
498- **Unicode support**
499
500  Unicode characters in string literals in ``Kconfig`` and ``.config`` files are
501  correctly handled. This support mostly comes for free from Python.
502
503- **Windows support**
504
505  Nothing Linux-specific is used. Universal newlines mode is used for both
506  Python 2 and Python 3.
507  
508  The `Zephyr <https://www.zephyrproject.org/>`_ project uses Kconfiglib to
509  generate ``.config`` files and C headers on Linux as well as Windows.
510
511- **Internals that (mostly) mirror the C implementation**
512  
513  While being simpler to understand and tweak.
514
515Menuconfig interfaces
516---------------------
517
518Three configuration interfaces are currently available:
519
520- `menuconfig.py <https://github.com/ulfalizer/Kconfiglib/blob/master/menuconfig.py>`_
521  is a terminal-based configuration interface implemented using the standard
522  Python ``curses`` module. ``xconfig`` features like showing invisible symbols and
523  showing symbol names are included, and it's possible to jump directly to a symbol
524  in the menu tree (even if it's currently invisible).
525  
526  .. image:: https://raw.githubusercontent.com/ulfalizer/Kconfiglib/screenshots/screenshots/menuconfig.gif
527
528  *There is now also a show-help mode that shows the help text of the currently
529  selected symbol in the help window at the bottom.*
530
531  Starting with Kconfiglib 12.2.0, ``menuconfig.py`` runs under both Python 2
532  and Python 3 (previously, it only ran under Python 3, so this was a
533  backport). Running it under Python 3 provides better support for Unicode text
534  entry (``get_wch()`` is not available in the ``curses`` module on Python 2).
535
536  There are no third-party dependencies on \*nix. On Windows,
537  the ``curses`` modules is not available by default, but support
538  can be added by installing the ``windows-curses`` package:
539  
540  .. code-block:: shell
541
542      $ pip install windows-curses
543
544  This uses wheels built from `this repository
545  <https://github.com/zephyrproject-rtos/windows-curses>`_, which is in turn
546  based on Christoph Gohlke's `Python Extension Packages for Windows
547  <https://www.lfd.uci.edu/~gohlke/pythonlibs/#curses>`_.
548
549  See the docstring at the top of `menuconfig.py
550  <https://github.com/ulfalizer/Kconfiglib/blob/master/menuconfig.py>`_ for
551  more information about the terminal menuconfig implementation.
552
553- `guiconfig.py
554  <https://github.com/ulfalizer/Kconfiglib/blob/master/guiconfig.py>`_ is a
555  graphical configuration interface written in `Tkinter
556  <https://docs.python.org/3/library/tkinter.html>`_. Like ``menuconfig.py``,
557  it supports showing all symbols (with invisible symbols in red) and jumping
558  directly to symbols. Symbol values can also be changed directly from the
559  jump-to dialog.
560
561  When single-menu mode is enabled, a single menu is shown at a time, like in
562  the terminal menuconfig. Only this mode distinguishes between symbols defined
563  with ``config`` and symbols defined with ``menuconfig``.
564
565  ``guiconfig.py`` has been tested on X11, Windows, and macOS, and is
566  compatible with both Python 2 and Python 3.
567
568  Despite being part of the Python standard library, ``tkinter`` often isn't
569  included by default in Python installations on Linux. These commands will
570  install it on a few different distributions:
571
572  - Ubuntu: ``sudo apt install python-tk``/``sudo apt install python3-tk``
573
574  - Fedora: ``dnf install python2-tkinter``/``dnf install python3-tkinter``
575
576  - Arch: ``sudo pacman -S tk``
577
578  - Clear Linux: ``sudo swupd bundle-add python3-tcl``
579
580  Screenshot below, with show-all mode enabled and the jump-to dialog open:
581
582  .. image:: https://raw.githubusercontent.com/ulfalizer/Kconfiglib/screenshots/screenshots/guiconfig.png
583
584  To avoid having to carry around a bunch of GIFs, the image data is embedded
585  in ``guiconfig.py``. To use separate GIF files instead, change
586  ``_USE_EMBEDDED_IMAGES`` to ``False`` in ``guiconfig.py``. The image files
587  can be found in the `screenshots
588  <https://github.com/ulfalizer/Kconfiglib/tree/screenshots/guiconfig>`_
589  branch.
590
591  I did my best with the images, but some are definitely only art adjacent.
592  Touch-ups are welcome. :)
593
594- `pymenuconfig <https://github.com/RomaVis/pymenuconfig>`_, built by `RomaVis
595  <https://github.com/RomaVis>`_, is an older portable Python 2/3 TkInter
596  menuconfig implementation.
597
598  Screenshot below:
599
600  .. image:: https://raw.githubusercontent.com/RomaVis/pymenuconfig/master/screenshot.PNG
601
602  While working on the terminal menuconfig implementation, I added a few APIs
603  to Kconfiglib that turned out to be handy. ``pymenuconfig`` predates
604  ``menuconfig.py`` and ``guiconfig.py``, and so didn't have them available.
605  Blame me for any workarounds.
606
607Examples
608--------
609
610Example scripts
611~~~~~~~~~~~~~~~
612
613The `examples/ <https://github.com/ulfalizer/Kconfiglib/blob/master/examples>`_ directory contains some simple example scripts. Among these are the following ones. Make sure you run them with the latest version of Kconfiglib, as they might make use of newly added features.
614
615- `eval_expr.py <https://github.com/ulfalizer/Kconfiglib/blob/master/examples/eval_expr.py>`_ evaluates an expression in the context of a configuration.
616
617- `find_symbol.py <https://github.com/ulfalizer/Kconfiglib/blob/master/examples/find_symbol.py>`_ searches through expressions to find references to a symbol, also printing a "backtrace" with parents for each reference found.
618
619- `help_grep.py <https://github.com/ulfalizer/Kconfiglib/blob/master/examples/help_grep.py>`_ searches for a string in all help texts.
620
621- `print_tree.py <https://github.com/ulfalizer/Kconfiglib/blob/master/examples/print_tree.py>`_ prints a tree of all configuration items.
622
623- `print_config_tree.py <https://github.com/ulfalizer/Kconfiglib/blob/master/examples/print_config_tree.py>`_ is similar to ``print_tree.py``, but dumps the tree as it would appear in ``menuconfig``, including values. This can be handy for visually diffing between ``.config`` files and different versions of ``Kconfig`` files.
624
625- `list_undefined.py <https://github.com/ulfalizer/Kconfiglib/blob/master/examples/list_undefined.py>`_ finds references to symbols that are not defined by any architecture in the Linux kernel.
626
627- `merge_config.py <https://github.com/ulfalizer/Kconfiglib/blob/master/examples/merge_config.py>`_ merges configuration fragments to produce a complete .config, similarly to ``scripts/kconfig/merge_config.sh`` from the kernel.
628
629- `menuconfig_example.py <https://github.com/ulfalizer/Kconfiglib/blob/master/examples/menuconfig_example.py>`_ implements a configuration interface that uses notation similar to ``make menuconfig``. It's deliberately kept as simple as possible to demonstrate just the core concepts.
630
631Real-world examples
632~~~~~~~~~~~~~~~~~~~
633
634- `kconfig.py
635  <https://github.com/zephyrproject-rtos/zephyr/blob/master/scripts/kconfig/kconfig.py>`_
636  from the `Zephyr <https://www.zephyrproject.org/>`_ project handles
637  ``.config`` and header file generation, also doing configuration fragment
638  merging
639
640- `genrest.py
641  <https://github.com/zephyrproject-rtos/zephyr/blob/master/doc/scripts/genrest.py>`_
642  generates a Kconfig symbol cross-reference, which can be viewed `here
643  <http://docs.zephyrproject.org/reference/kconfig/index.html>`__
644
645- `CMake and IDE integration
646  <https://github.com/espressif/esp-idf/tree/master/tools/kconfig_new>`_ from
647  the ESP-IDF project, via a configuration server program.
648
649- `A script for turning on USB-related options
650  <https://github.com/google/syzkaller/blob/master/dashboard/config/kconfiglib-merge-usb-configs.py>`_,
651  from the `syzkaller <https://github.com/google/syzkaller>`_ project.
652
653- `Various automated checks
654  <https://github.com/zephyrproject-rtos/ci-tools/blob/master/scripts/check_compliance.py>`_,
655  including a check for references to undefined Kconfig symbols in source code.
656  See the ``KconfigCheck`` class.
657
658- `Various utilities
659  <https://github.com/projectacrn/acrn-hypervisor/tree/master/scripts/kconfig>`_
660  from the `ACRN <https://projectacrn.org/>`_ project
661
662These use the older Kconfiglib 1 API, which was clunkier and not as general
663(functions instead of properties, no direct access to the menu structure or
664properties, uglier ``__str__()`` output):
665
666- `genboardscfg.py <http://git.denx.de/?p=u-boot.git;a=blob;f=tools/genboardscfg.py;hb=HEAD>`_ from `Das U-Boot <http://www.denx.de/wiki/U-Boot>`_ generates some sort of legacy board database by pulling information from a newly added Kconfig-based configuration system (as far as I understand it :).
667
668- `gen-manual-lists.py <https://git.busybox.net/buildroot/tree/support/scripts/gen-manual-lists.py?id=5676a2deea896f38123b99781da0a612865adeb0>`_ generated listings for an appendix in the `Buildroot <https://buildroot.org>`_ manual. (The listing has since been removed.)
669
670- `gen_kconfig_doc.py <https://github.com/espressif/esp-idf/blob/master/docs/gen-kconfig-doc.py>`_ from the `esp-idf <https://github.com/espressif/esp-idf>`_ project generates documentation from Kconfig files.
671
672- `SConf <https://github.com/CoryXie/SConf>`_ builds an interactive configuration interface (like ``menuconfig``) on top of Kconfiglib, for use e.g. with `SCons <scons.org>`_.
673
674- `kconfig-diff.py <https://gist.github.com/dubiousjim/5638961>`_ -- a script by `dubiousjim <https://github.com/dubiousjim>`_ that compares kernel configurations.
675
676- Originally, Kconfiglib was used in chapter 4 of my `master's thesis <http://liu.diva-portal.org/smash/get/diva2:473038/FULLTEXT01.pdf>`_ to automatically generate a "minimal" kernel for a given system. Parts of it bother me a bit now, but that's how it goes with old work.
677
678Sample ``make iscriptconfig`` session
679~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
680
681The following log should give some idea of the functionality available in the API:
682
683.. code-block::
684
685    $ make iscriptconfig
686    A Kconfig instance 'kconf' for the architecture x86 has been created.
687    >>> kconf  # Calls Kconfig.__repr__()
688    <configuration with 13711 symbols, main menu prompt "Linux/x86 4.14.0-rc7 Kernel Configuration", srctree ".", config symbol prefix "CONFIG_", warnings enabled, undef. symbol assignment warnings disabled>
689    >>> kconf.mainmenu_text  # Expanded main menu text
690    'Linux/x86 4.14.0-rc7 Kernel Configuration'
691    >>> kconf.top_node  # The implicit top-level menu
692    <menu node for menu, prompt "Linux/x86 4.14.0-rc7 Kernel Configuration" (visibility y), deps y, 'visible if' deps y, has child, Kconfig:5>
693    >>> kconf.top_node.list  # First child menu node
694    <menu node for symbol SRCARCH, deps y, has next, Kconfig:7>
695    >>> print(kconf.top_node.list)  # Calls MenuNode.__str__()
696    config SRCARCH
697    	string
698    	option env="SRCARCH"
699    	default "x86"
700    >>> sym = kconf.top_node.list.next.item  # Item contained in next menu node
701    >>> print(sym)  # Calls Symbol.__str__()
702    config 64BIT
703    	bool "64-bit kernel" if ARCH = "x86"
704    	default ARCH != "i386"
705    	help
706    	  Say yes to build a 64-bit kernel - formerly known as x86_64
707    	  Say no to build a 32-bit kernel - formerly known as i386
708    >>> sym  # Calls Symbol.__repr__()
709    <symbol 64BIT, bool, "64-bit kernel", value y, visibility y, direct deps y, arch/x86/Kconfig:2>
710    >>> sym.assignable  # Currently assignable values (0, 1, 2 = n, m, y)
711    (0, 2)
712    >>> sym.set_value(0)  # Set it to n
713    True
714    >>> sym.tri_value  # Check the new value
715    0
716    >>> sym = kconf.syms["X86_MPPARSE"]  # Look up symbol by name
717    >>> print(sym)
718    config X86_MPPARSE
719    	bool "Enable MPS table" if (ACPI || SFI) && X86_LOCAL_APIC
720    	default y if X86_LOCAL_APIC
721    	help
722    	  For old smp systems that do not have proper acpi support. Newer systems
723    	  (esp with 64bit cpus) with acpi support, MADT and DSDT will override it
724    >>> default = sym.defaults[0]  # Fetch its first default
725    >>> sym = default[1]  # Fetch the default's condition (just a Symbol here)
726    >>> print(sym)
727    config X86_LOCAL_APIC
728    	bool
729    	default y
730    	select IRQ_DOMAIN_HIERARCHY
731    	select PCI_MSI_IRQ_DOMAIN if PCI_MSI
732    	depends on X86_64 || SMP || X86_32_NON_STANDARD || X86_UP_APIC || PCI_MSI
733    >>> sym.nodes  # Show the MenuNode(s) associated with it
734    [<menu node for symbol X86_LOCAL_APIC, deps n, has next, arch/x86/Kconfig:1015>]
735    >>> kconfiglib.expr_str(sym.defaults[0][1])  # Print the default's condition
736    'X86_64 || SMP || X86_32_NON_STANDARD || X86_UP_APIC || PCI_MSI'
737    >>> kconfiglib.expr_value(sym.defaults[0][1])  # Evaluate it (0 = n)
738    0
739    >>> kconf.syms["64BIT"].set_value(2)
740    True
741    >>> kconfiglib.expr_value(sym.defaults[0][1])  # Evaluate it again (2 = y)
742    2
743    >>> kconf.write_config("myconfig")  # Save a .config
744    >>> ^D
745    $ cat myconfig
746    # Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib)
747    CONFIG_64BIT=y
748    CONFIG_X86_64=y
749    CONFIG_X86=y
750    CONFIG_INSTRUCTION_DECODER=y
751    CONFIG_OUTPUT_FORMAT="elf64-x86-64"
752    CONFIG_ARCH_DEFCONFIG="arch/x86/configs/x86_64_defconfig"
753    CONFIG_LOCKDEP_SUPPORT=y
754    CONFIG_STACKTRACE_SUPPORT=y
755    CONFIG_MMU=y
756    ...
757 
758Test suite
759----------
760
761The test suite is run with
762
763.. code::
764
765    $ python(3) Kconfiglib/testsuite.py
766    
767`pypy <https://pypy.org/>`_ works too, and is much speedier for everything except ``allnoconfig.py``/``allnoconfig_simpler.py``/``allyesconfig.py``, where it doesn't have time to warm up since
768the scripts are run via ``make scriptconfig``.
769
770The test suite must be run from the top-level kernel directory. It requires that the
771Kconfiglib git repository has been cloned into it and that the makefile patch has been applied.
772
773To get rid of warnings generated for the kernel ``Kconfig`` files, add ``2>/dev/null`` to the command to
774discard ``stderr``.
775
776**NOTE: Forgetting to apply the Makefile patch will cause some tests that compare generated configurations to fail**
777
778**NOTE: The test suite overwrites .config in the kernel root, so make sure to back it up.**
779
780The test suite consists of a set of selftests and a set of compatibility tests that
781compare configurations generated by Kconfiglib with
782configurations generated by the C tools, for a number of cases. See
783`testsuite.py <https://github.com/ulfalizer/Kconfiglib/blob/master/testsuite.py>`_
784for the available options.
785
786The `tests/reltest <https://github.com/ulfalizer/Kconfiglib/blob/master/tests/reltest>`_ script runs the test suite
787and all the example scripts for both Python 2 and Python 3, verifying that everything works.
788
789Rarely, the output from the C tools is changed slightly (most recently due to a
790`change <https://www.spinics.net/lists/linux-kbuild/msg17074.html>`_ I added).
791If you get test suite failures, try running the test suite again against the
792`linux-next tree <https://www.kernel.org/doc/man-pages/linux-next.html>`_,
793which has all the latest changes. I will make it clear if any
794non-backwards-compatible changes appear.
795
796A lot of time is spent waiting around for ``make`` and the C utilities (which need to reparse all the
797Kconfig files for each defconfig test). Adding some multiprocessing to the test suite would make sense
798too.
799
800Notes
801-----
802
803* This is version 2 of Kconfiglib, which is not backwards-compatible with
804  Kconfiglib 1. A summary of changes between Kconfiglib 1 and Kconfiglib
805  2 can be found `here
806  <https://github.com/ulfalizer/Kconfiglib/blob/screenshots/kconfiglib-2-changes.txt>`__.
807
808* I sometimes see people add custom output formats, which is pretty
809  straightforward to do (see the implementations of ``write_autoconf()`` and
810  ``write_config()`` for a template, and also the documentation of the
811  ``Symbol.config_string`` property). If you come up with something you think
812  might be useful to other people, I'm happy to take it in upstream. Batteries
813  included and all that.
814
815* Kconfiglib assumes the modules symbol is ``MODULES``, which is backwards-compatible.
816  A warning is printed by default if ``option modules`` is set on some other symbol.
817  
818  Let me know if you need proper ``option modules`` support. It wouldn't be that
819  hard to add.
820
821Thanks
822------
823
824- To `RomaVis <https://github.com/RomaVis>`_, for making
825  `pymenuconfig <https://github.com/RomaVis/pymenuconfig>`_ and suggesting
826  the ``rsource`` keyword.
827
828- To `Mitja Horvat <https://github.com/pinkfluid>`_, for adding support
829  for user-defined styles to the terminal menuconfig.
830
831- To `Philip Craig <https://github.com/philipc>`_ for adding
832  support for the ``allnoconfig_y`` option and fixing an obscure issue
833  with ``comment``\s inside ``choice``\s (that didn't affect correctness but
834  made outputs differ). ``allnoconfig_y`` is used to force certain symbols
835  to ``y`` during ``make allnoconfig`` to improve coverage.
836
837License
838-------
839
840See `LICENSE.txt <https://github.com/ulfalizer/Kconfiglib/blob/master/LICENSE.txt>`_. SPDX license identifiers are used in the
841source code.
842
[FILE END]
(C) 2025 0x4248
(C) 2025 4248 Media and 4248 Systems, All part of 0x4248
See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.