adding-packages-kconfig.txt 4.2 KB

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