diff options
Diffstat (limited to 'doc/dev_kconfig_diffs.rst')
| -rw-r--r-- | doc/dev_kconfig_diffs.rst | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/doc/dev_kconfig_diffs.rst b/doc/dev_kconfig_diffs.rst new file mode 100644 index 000000000..5673bd2d2 --- /dev/null +++ b/doc/dev_kconfig_diffs.rst @@ -0,0 +1,79 @@ +.. _kconfig-diffs: + +Kconfig Diffs +------------- + +For packages using Kconfig as their configuration system, PTXdist can generate +their config file from another *reference config file* and a *Kconfig diff* on +the fly. +This mechanism can be used to build configuration variants of a kernel or +barebox package. +For example, a "debug" kernel package can refer to the config file of the +"production" kernel as its reference config file, and its Kconfig diff then +only contains the Kconfig symbols that were changed in the "debug" variant: + ++-----------------------------------+-------------------------------------+-----------------------------------+ +| release config symbol | debug kconfig diff | resulting debug config symbol | ++===================================+=====================================+===================================+ +| CONFIG_LOCALVERSION="release" | CONFIG_LOCALVERSION="debug" | CONFIG_LOCALVERSION="debug" | ++-----------------------------------+-------------------------------------+-----------------------------------+ +| # CONFIG_ARCH_MULTI_V6 is not set | | # CONFIG_ARCH_MULTI_V6 is not set | ++-----------------------------------+-------------------------------------+-----------------------------------+ +| CONFIG_ARCH_MULTI_V7=y | | CONFIG_ARCH_MULTI_V7=y | ++-----------------------------------+-------------------------------------+-----------------------------------+ +| # CONFIG_CGROUP_DEBUG is not set | CONFIG_CGROUP_DEBUG=y | CONFIG_CGROUP_DEBUG=y | ++-----------------------------------+-------------------------------------+-----------------------------------+ +| # CONFIG_DEBUG_PREEMPT is not set | CONFIG_DEBUG_PREEMPT=y | CONFIG_DEBUG_PREEMPT=y | ++-----------------------------------+-------------------------------------+-----------------------------------+ +| CONFIG_WATCHDOG=y | # CONFIG_WATCHDOG is not set | # CONFIG_WATCHDOG is not set | ++-----------------------------------+-------------------------------------+-----------------------------------+ +| CONFIG_WATCHDOG_CORE=y | # CONFIG_WATCHDOG_CORE is undefined | | ++-----------------------------------+-------------------------------------+-----------------------------------+ +| CONFIG_BCM2835_WDT=y | # CONFIG_BCM2835_WDT is undefined | | ++-----------------------------------+-------------------------------------+-----------------------------------+ + +Kconfig does not write symbols to the config file that have unfulfilled dependencies (e.g., in the +above example ``CONFIG_WATCHDOG_CORE`` and ``CONFIG_BCM2835_WDT`` depend on ``CONFIG_WATCHDOG``). +Those symbols that are not present in the resulting debug config file are represented as ``… is +undefined`` in the diff. + +The first line of the Kconfig diff file contains the MD5 sum of the reference config file. +PTXdist uses this checksum to detect when the reference config has changed, +in which case the diff needs to be regenerated from the package's config file, +and to make sure that the diff is applicable to the reference config. + +Using Kconfig diffs +~~~~~~~~~~~~~~~~~~~ + +The main part is setting the ``<PKG>_REF_CONFIG`` variable of a package to the reference config +file, for example:: + + # rules/kernel.make: + KERNEL_CONFIG := $(call ptx/in-platformconfigdir, kernelconfig-release) + +:: + + # rules/kernel-debug.make: + KERNEL_DEBUG_CONFIG := $(call ptx/in-platformconfigdir, kernelconfig-debug) + KERNEL_DEBUG_REF_CONFIG := $(call ptx/in-platformconfigdir, kernelconfig-release) + +PTXdist will now automatically generate ``kernelconfig-debug`` from ``kernelconfig-release`` and +``kernelconfig-debug.diff`` whenever doing and *oldconfig* or *menuconfig* on the *kernel-debug* +package. +If any symbols were changed by that operation, both the ``kernelconfig-debug.diff`` and the +``kernelconfig-debug`` are updated afterwards. + +Kconfig diffs and layers +~~~~~~~~~~~~~~~~~~~~~~~~ + +PTXdist uses the same diff mechanism whenever the config file of a Kconfig-style package is changed +in an inherited layer (see :ref:`layers-in-ptxdist`). +In that case, the diff is calculated between the package's config file in the base layer and the +package's (adapted) config file in the current layer. + +.. note:: + When using both ``<PKG>_REF_CONFIG`` and inter-layer Kconfig diffs, the inter-layer diff takes + precedence, and the reference config file in the inherited layer is ignored. + In the following example, arrows represent the config diff relation: + + .. image:: dev_kconfig_diffs_layer_precedence.svg |