kconfig-package: add documentation
PATCH 1/1 kconfig-package: add documentation
This small series accompanies the previously sent series introducing a kconfig-package infrastructure. It provides documentation both as comments in the pkg-kconfig.mk file, and in the manual.
Depending on the feedback received on the previous series, this documentation may need revising.
At the moment of a resend, I will merge two series in one.
Signed-off-by Thomas De Schampheleire <[email protected]>
--- docs/manual/adding-packages-kconfig.txt | 54 +++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + package/pkg-kconfig.mk | 48 ++++++++++++++++++++++++++- 3 files changed, 103 insertions(+), 1 deletions(-)
PATCH 1/1 kconfig-package: add some comments to pkg-kconfig.mk
Clarify what is happening in the kconfig infrastructure by adding some comments.
Signed-off-by Thomas De Schampheleire <[email protected]>
--- package/pkg-kconfig.mk | 48 ++++++++++++++++++++++++++++++++++++++++++++- 1 files changed, 47 insertions(+), 1 deletions(-)
package/pkg-kconfig.mk +47 -1
@@ -1,33 +1,79 @@ +################################################################################ +# Kconfig package infrastructure +# +# This file implements an infrastructure that eases development of +# package .mk files for packages that use kconfig for configuration files. +# +# As this infrastructure only handles the kconfig configuration part, it +# should be used in combination with one of the other package infrastructures, +# like generic-package, autotools-package, ... +# +# See the Buildroot documentation for details on the usage of this +# infrastructure. +# +################################################################################ + +################################################################################ +# inner-kconfig-package -- generates the make targets needed to support a +# kconfig package +# +# argument 1 is the lowercase package name +# argument 2 is the uppercase package name, including a HOST_ prefix +# for host packages +# argument 3 is the uppercase package name, without the HOST_ prefix +# for host packages +# argument 4 is the type (target or host) +# +################################################################################ define inner-kconfig-package +# Default values + $(2)_KCONFIG_EDITORS ?= menuconfig $(2)_KCONFIG_OPT ?= $(2)_KCONFIG_FIXUP_CMDS ?= +# FOO_KCONFIG_FILE is required + ifndef $(2)_KCONFIG_FILE $$(error Internal error: no value specified for $(2)_KCONFIG_FILE) endif +# The .config file is obtained by copying it from the specified source +# configuration file, after the package has been patched. + $$($(2)_DIR)/.config: $$($(2)_KCONFIG_FILE) | $(1)-patch $$(INSTALL) -m 0644 $$($(2)_KCONFIG_FILE) $$($(2)_DIR)/.config +# In order to get a usable, consistent configuration, some fixup may be needed. +# The exact rules are specified by the package .mk file. + $$($(2)_DIR)/.stamp_kconfig_fixup_done: $$($(2)_DIR)/.config $$($(2)_KCONFIG_FIXUP_CMDS) $$(Q)touch $$@ +# Before running configure, the configuration file should be present and fixed + $$($(2)_TARGET_CONFIGURE): $$($(2)_DIR)/.stamp_kconfig_fixup_done -# configuration editors (menuconfig, ...) +# Configuration editors (menuconfig, ...) + $$(addprefix $(1)-,$$($(2)_KCONFIG_EDITORS)): $$($(2)_DIR)/.config $$($(2)_MAKE_ENV) $$(MAKE) -C $$($(2)_DIR) \ $$($(2)_KCONFIG_OPT) $$(subst $(1)-,,$$@) rm -f $$($(2)_DIR)/.stamp_{kconfig_fixup_done,configured,built} rm -f $$($(2)_DIR)/.stamp_{target,staging}_installed +# Target to copy back the configuration to the source configuration file + $(1)-update-config: $$($(2)_DIR)/.stamp_kconfig_fixup_done cp -f $$($(2)_DIR)/.config $$($(2)_KCONFIG_FILE) endef # inner-kconfig-package +################################################################################ +# kconfig-package -- the target generator macro for kconfig packages +################################################################################ + kconfig-package = $(call inner-kconfig-package,$(pkgname),$(call UPPERCASE,$(pkgname)),$(call UPPERCASE,$(pkgname)))
PATCH 1/1 kconfig-package: add documentation to manual
In reply to Thomas De SchampheleireThis patch adds documentation for the new kconfig-package infrastructure to the manual.
Note that due to the simplicity of the infrastructure, the documentation is not split in a 'tutorial' and a 'reference', like for the other infrastructures. Instead, the usage is described in one section.
Signed-off-by Thomas De Schampheleire <[email protected]>
--- docs/manual/adding-packages-kconfig.txt | 54 ++++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 ++ 2 files changed, 56 insertions(+), 0 deletions(-)
docs/manual/adding-packages-kconfig.txt new file +54 -0
@@ -0,0 +1,54 @@ +// -*- 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 +configuration. This infrastructure provides the necessary make logic to +expose the package +menuconfig+ target as +foo-menuconfig+ in Buildroot, and +to handle the copying and copy-back of the configuration file in a +correct way. + +As this infrastructure only handles the kconfig part, it should be used +in combination with one of the other package infrastructures, like ++generic-package+, +autotools-package+, ... + +In order to use the +kconfig-package+ infrastructure for a Buildroot +package, the minimally required lines in the .mk file are: + +------------------------------ +FOO_KCONFIG_FILE = reference-to-source-configuration-file + +$(eval $(kconfig-package)) +------------------------------ + +This snippet will create following make targets: + +* +foo-menuconfig+, which calls the package's +menuconfig+ target + +* +foo-update-config+, which copies back the configuration to the source + configuration file. + +and will ensure that the source configuration file is copied to the build +directory at the right moment. + +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_OPT+: extra options to pass when calling the kconfig + ediftors. This may need to include '$(FOO_MAKE_OPT)', 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.
docs/manual/adding-packages.txt +2 -0
@@ -25,6 +25,8 @@ include::adding-packages-virtual.txt[] +include::adding-packages-kconfig.txt[] + include::adding-packages-hooks.txt[] include::adding-packages-gettext.txt[]