From 534e3e78b7964eaff1052e9583bd0f73e072d8dd Mon Sep 17 00:00:00 2001 From: Ulf Magnusson Date: Wed, 3 Oct 2018 02:00:56 +0200 Subject: Add a 'getting started' section to the README Might make it clearer how the different parts fit together. Also mention that deps/auto.conf can be used as Make input, and that it's preferable to using .config. This is hard to discover on your own. --- README.rst | 47 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index a231b97..bb518b7 100644 --- a/README.rst +++ b/README.rst @@ -8,7 +8,7 @@ Kconfiglib is a `Kconfig `_ implementation in Python 2/3. It started out as a helper library, but now has a enough functionality to also work well as a standalone Kconfig implementation -(including `menuconfig interfaces`_ and `Kconfig extensions`_). +(including `menuconfig interfaces `_ and `Kconfig extensions`_). The entire library is contained in `kconfiglib.py `_. The @@ -108,6 +108,49 @@ Installation for the Linux kernel See the module docstring at the top of `kconfiglib.py `_. +Getting started +--------------- + +1. `Install `_ the library and the utilities. + +2. Write `Kconfig + `_ + files that describe the available configuration options. + +3. Generate an initial configuration with e.g. ``menuconfig`` or + ``alldefconfig``. The configuration is saved as ``.config`` by default. + +4. Run ``genconfig`` to generate a header file. By default, it is saved in + ``config.h``. + + Normally, ``genconfig`` would be run automatically as part of the build. + + Adding new configuration output formats should be relatively straightforward. + See the implementation of ``write_config()`` in `kconfiglib.py + `_. + +5. To update an old ``.config`` file after the Kconfig files have changed (e.g. + to add new options), run ``oldconfig`` (prompts for values for new options) + or ``olddefconfig`` (gives new options their default value). + + Due to Kconfig semantics, simply loading an old ``.config`` file performs an + implicit ``olddefconfig``, so building will normally not be affected by + having an outdated configuration. + +Using ``.config`` files as Make input +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``.config`` files use Make syntax and can be included directly in Makefiles to +read configuration values from there. This is why unset values are written out +as ``# CONFIG_FOO is not set`` (a Make comment) in ``.config``. + +If you make use of this, you might want to pass ``--sync-deps`` to +``genconfig`` and include ``deps/auto.conf`` in your Makefiles instead of +including ``.config`` directly. This has the advantage that ``deps/auto.conf`` +will always be a "full" configuration file, even if ``.config`` is outdated. +Otherwise, it might be necessary to run ``old(def)config`` or ``menuconfig`` +before rebuilding with an outdated configuration. + Library documentation --------------------- @@ -334,8 +377,6 @@ Other features While being simpler to understand and tweak. -.. menuconfig_implementations: - Menuconfig interfaces --------------------- -- cgit v1.2.3