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