* [Buildroot] [PATCH 1 of 2] kconfig-package: add some comments to pkg-kconfig.mk
2014-07-24 18:57 [Buildroot] [PATCH 0 of 2] kconfig-package: add documentation Thomas De Schampheleire
@ 2014-07-24 18:57 ` Thomas De Schampheleire
2014-07-24 18:57 ` [Buildroot] [PATCH 2 of 2] kconfig-package: add documentation to manual Thomas De Schampheleire
1 sibling, 0 replies; 3+ messages in thread
From: Thomas De Schampheleire @ 2014-07-24 18:57 UTC (permalink / raw)
To: buildroot
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)))
^ permalink raw reply [flat|nested] 3+ messages in thread* [Buildroot] [PATCH 2 of 2] kconfig-package: add documentation to manual
2014-07-24 18:57 [Buildroot] [PATCH 0 of 2] kconfig-package: add documentation Thomas De Schampheleire
2014-07-24 18:57 ` [Buildroot] [PATCH 1 of 2] kconfig-package: add some comments to pkg-kconfig.mk Thomas De Schampheleire
@ 2014-07-24 18:57 ` Thomas De Schampheleire
1 sibling, 0 replies; 3+ messages in thread
From: Thomas De Schampheleire @ 2014-07-24 18:57 UTC (permalink / raw)
To: buildroot
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[]
^ permalink raw reply [flat|nested] 3+ messages in thread