[Buildroot] [PATCH 0 of 2] kconfig-package: add documentation

[Buildroot] [PATCH 0 of 2] kconfig-package: add documentation

[Thomas De Schampheleire]

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 <thomas.de.schampheleire@gmail.com>

---
 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(-)

[Buildroot] [PATCH 1 of 2] kconfig-package: add some comments to pkg-kconfig.mk

[Thomas De Schampheleire]

Clarify what is happening in the kconfig infrastructure by adding some
comments.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 package/pkg-kconfig.mk |  48 ++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 47 insertions(+), 1 deletions(-)

diff -r 4dc6eccbfc41 -r a28bf078ba44 package/pkg-kconfig.mk
--- a/package/pkg-kconfig.mk	Wed Jul 23 20:19:19 2014 +0200
+++ b/package/pkg-kconfig.mk	Thu Jul 24 20:14:00 2014 +0200
@@ -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)))

[Buildroot] [PATCH 2 of 2] kconfig-package: add documentation to manual

[Thomas De Schampheleire]

This 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 <thomas.de.schampheleire@gmail.com>

---
 docs/manual/adding-packages-kconfig.txt |  54 ++++++++++++++++++++++++++++
 docs/manual/adding-packages.txt         |   2 ++
 2 files changed, 56 insertions(+), 0 deletions(-)

diff -r a28bf078ba44 -r a69058f56d21 docs/manual/adding-packages-kconfig.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/manual/adding-packages-kconfig.txt	Thu Jul 24 20:54:50 2014 +0200
@@ -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.
diff -r a28bf078ba44 -r a69058f56d21 docs/manual/adding-packages.txt
--- a/docs/manual/adding-packages.txt	Thu Jul 24 20:14:00 2014 +0200
+++ b/docs/manual/adding-packages.txt	Thu Jul 24 20:54:50 2014 +0200
@@ -25,6 +25,8 @@
 
 include::adding-packages-virtual.txt[]
 
+include::adding-packages-kconfig.txt[]
+
 include::adding-packages-hooks.txt[]
 
 include::adding-packages-gettext.txt[]