1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4=== Infrastructure for packages using kconfig for configuration files 5 6A popular way for a software package to handle user-specified 7configuration is +kconfig+. Among others, it is used by the Linux 8kernel, Busybox, and Buildroot itself. The presence of a .config file 9and a +menuconfig+ target are two well-known symptoms of kconfig being 10used. 11 12Buildroot features an infrastructure for packages that use kconfig for 13their configuration. This infrastructure provides the necessary logic to 14expose the package's +menuconfig+ target as +foo-menuconfig+ in 15Buildroot, and to handle the copying back and forth of the configuration 16file in a correct way. 17 18The +kconfig-package+ infrastructure is based on the +generic-package+ 19infrastructure. All variables supported by +generic-package+ are 20available in +kconfig-package+ as well. See 21xref:generic-package-reference[] for more details. 22 23In order to use the +kconfig-package+ infrastructure for a Buildroot 24package, the minimally required lines in the +.mk+ file, in addition to 25the variables required by the +generic-package+ infrastructure, are: 26 27------------------------------ 28FOO_KCONFIG_FILE = reference-to-source-configuration-file 29 30$(eval $(kconfig-package)) 31------------------------------ 32 33This snippet creates the following make targets: 34 35* +foo-menuconfig+, which calls the package's +menuconfig+ target 36 37* +foo-update-config+, which copies the configuration back to the 38 source configuration file. It is not possible to use this target 39 when fragment files are set. 40 41* +foo-update-defconfig+, which copies the configuration back to the 42 source configuration file. The configuration file will only list the 43 options that differ from the default values. It is not possible to 44 use this target when fragment files are set. 45 46* +foo-diff-config+, which outputs the differences between the current 47 configuration and the one defined in the Buildroot configuration for 48 this kconfig package. The output is useful to identify the 49 configuration changes that may have to be propagated to 50 configuration fragments for example. 51 52and ensures that the source configuration file is copied to the build 53directory at the right moment. 54 55There are two options to specify a configuration file to use, either 56+FOO_KCONFIG_FILE+ (as in the example, above) or +FOO_KCONFIG_DEFCONFIG+. 57It is mandatory to provide either, but not both: 58 59* +FOO_KCONFIG_FILE+ specifies the path to a defconfig or full-config file 60 to be used to configure the package. 61 62* +FOO_KCONFIG_DEFCONFIG+ specifies the defconfig 'make' rule to call to 63 configure the package. 64 65In addition to these minimally required lines, several optional variables can 66be set to suit the needs of the package under consideration: 67 68* +FOO_KCONFIG_EDITORS+: a space-separated list of kconfig editors to 69 support, for example 'menuconfig xconfig'. By default, 'menuconfig'. 70 71* +FOO_KCONFIG_FRAGMENT_FILES+: a space-separated list of configuration 72 fragment files that are merged to the main configuration file. 73 Fragment files are typically used when there is a desire to stay in sync 74 with an upstream (def)config file, with some minor modifications. 75 76* +FOO_KCONFIG_OPTS+: extra options to pass when calling the kconfig 77 editors. This may need to include '$(FOO_MAKE_OPTS)', for example. By 78 default, empty. 79 80* +FOO_KCONFIG_FIXUP_CMDS+: a list of shell commands needed to fixup the 81 configuration file after copying it or running a kconfig editor. Such 82 commands may be needed to ensure a configuration consistent with other 83 configuration of Buildroot, for example. By default, empty. 84 85* +FOO_KCONFIG_DOTCONFIG+: path (with filename) of the +.config+ file, 86 relative to the package source tree. The default, +.config+, should 87 be well suited for all packages that use the standard kconfig 88 infrastructure as inherited from the Linux kernel; some packages use 89 a derivative of kconfig that use a different location. 90 91* +FOO_KCONFIG_DEPENDENCIES+: the list of packages (most probably, host 92 packages) that need to be built before this package's kconfig is 93 interpreted. Seldom used. By default, empty. 94 95* +FOO_KCONFIG_SUPPORTS_DEFCONFIG+: whether the package's kconfig system 96 supports using defconfig files; few packages do not. By default, 'YES'. 97