kumquat-buildroot/docs/manual/adding-packages-kconfig.txt

94 lines
4.1 KiB
Plaintext
Raw Normal View History

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
=== Infrastructure for packages using kconfig for configuration files
A popular way for a software package to handle user-specified
configuration is +kconfig+. Among others, it is used by the Linux
kernel, Busybox, and Buildroot itself. The presence of a .config file
and a +menuconfig+ target are two well-known symptoms of kconfig being
used.
Buildroot features an infrastructure for packages that use kconfig for
their configuration. This infrastructure provides the necessary logic to
expose the package's +menuconfig+ target as +foo-menuconfig+ in
Buildroot, and to handle the copying back and forth of the configuration
file in a correct way.
The +kconfig-package+ infrastructure is based on the +generic-package+
infrastructure. All variables supported by +generic-package+ are
available in +kconfig-package+ as well. See
xref:generic-package-reference[] for more details.
In order to use the +kconfig-package+ infrastructure for a Buildroot
package, the minimally required lines in the +.mk+ file, in addition to
the variables required by the +generic-package+ infrastructure, are:
------------------------------
FOO_KCONFIG_FILE = reference-to-source-configuration-file
$(eval $(kconfig-package))
------------------------------
This snippet creates the following make targets:
* +foo-menuconfig+, which calls the package's +menuconfig+ target
* +foo-update-config+, which copies the configuration back to the
source configuration file. It is not possible to use this target
when fragment files are set.
* +foo-update-defconfig+, which copies the configuration back to the
source configuration file. The configuration file will only list the
options that differ from the default values. It is not possible to
use this target when fragment files are set.
* +foo-diff-config+, which outputs the differences between the current
configuration and the one defined in the Buildroot configuration for
this kconfig package. The output is useful to identify the
configuration changes that may have to be propagated to
configuration fragments for example.
and ensures that the source configuration file is copied to the build
directory at the right moment.
There are two options to specify a configuration file to use, either
+FOO_KCONFIG_FILE+ (as in the example, above) or +FOO_KCONFIG_DEFCONFIG+.
It is mandatory to provide either, but not both:
* +FOO_KCONFIG_FILE+ specifies the path to a defconfig or full-config file
to be used to configure the package.
* +FOO_KCONFIG_DEFCONFIG+ specifies the defconfig 'make' rule to call to
configure the package.
In addition to these minimally required lines, several optional variables can
be set to suit the needs of the package under consideration:
* +FOO_KCONFIG_EDITORS+: a space-separated list of kconfig editors to
support, for example 'menuconfig xconfig'. By default, 'menuconfig'.
* +FOO_KCONFIG_FRAGMENT_FILES+: a space-separated list of configuration
fragment files that are merged to the main configuration file.
Fragment files are typically used when there is a desire to stay in sync
with an upstream (def)config file, with some minor modifications.
* +FOO_KCONFIG_OPTS+: extra options to pass when calling the kconfig
editors. This may need to include '$(FOO_MAKE_OPTS)', for example. By
default, empty.
* +FOO_KCONFIG_FIXUP_CMDS+: a list of shell commands needed to fixup the
configuration file after copying it or running a kconfig editor. Such
commands may be needed to ensure a configuration consistent with other
configuration of Buildroot, for example. By default, empty.
* +FOO_KCONFIG_DOTCONFIG+: path (with filename) of the +.config+ file,
relative to the package source tree. The default, +.config+, should
be well suited for all packages that use the standard kconfig
infrastructure as inherited from the Linux kernel; some packages use
a derivative of kconfig that use a different location.
core/pkg-kconfig: allow dependencies before configurators Some users of kconfig need some packages to be built before their kconfig infra be used. For example, the linux kernel, starting with 4.16, needs flex and bison to generate the parser code. Furthermore, starting with 4.18, it will also need the cross-compiler before parsing the kconfig stuff, because that calls the compiler to check its features. Currently, this is broken, even the flex/bison ones, even though they are listed, because there is no way to define dependencie that are guaranteed before the (visual) configurators. For example: $ make distclean $ make menuconfig --> enable the linux kernel, choose a defconfig, save, exit $ make linux-menuconfig [...] HOSTCC scripts/basic/fixdep HOSTCC scripts/kconfig/conf.o YACC scripts/kconfig/zconf.tab.c /bin/sh: bison: command not found LEX scripts/kconfig/zconf.lex.c scripts/Makefile.lib:196: recipe for target 'scripts/kconfig/zconf.tab.c' failed make[3]: *** [scripts/kconfig/zconf.tab.c] Error 127 make[3]: *** Waiting for unfinished jobs.... /bin/sh: flex: command not found scripts/Makefile.lib:188: recipe for target 'scripts/kconfig/zconf.lex.c' failed make[3]: *** [scripts/kconfig/zconf.lex.c] Error 127 Makefile:528: recipe for target 'rpc_defconfig' failed make[2]: *** [rpc_defconfig] Error 2 linux/linux.mk:511: recipe for target '/home/ymorin/dev/buildroot/buildroot/output/build/linux-4.17.11/.config' failed make[1]: *** [/home/ymorin/dev/buildroot/buildroot/output/build/linux-4.17.11/.config] Error 2 Makefile:79: recipe for target '_all' failed make: *** [_all] Error 2 So, we introduce a new type of dependencies for kconfig-based packages, that are guaranteed to be built and installed before the (visual) configurators are called. Since those dependencies are phony targets and therefore always out of date, a normal dependency would cause the .config target to be rebuilt on each invocation of make. So we use an order-only pre-requisite, like is done for the patch dependency. Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> Cc: Arnout Vandecappelle <arnout@mind.be> Cc: Thomas Petazzoni <thomas.petazzoni@bootlin.com> Cc: Jan Kundrát <jan.kundrat@cesnet.cz> Tested-by: Jan Kundrát <jan.kundrat@cesnet.cz> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2018-08-17 18:06:49 +02:00
* +FOO_KCONFIG_DEPENDENCIES+: the list of packages (most probably, host
packages) that need to be built before this package's kconfig is
interpreted. Seldom used. By default, empty.