aboutsummaryrefslogtreecommitdiff
path: root/docs/manual
diff options
context:
space:
mode:
authorGravatar Romain Naour <romain.naour@openwide.fr>2015-07-14 19:35:15 +0200
committerGravatar Thomas Petazzoni <thomas.petazzoni@free-electrons.com>2015-07-14 23:35:58 +0200
commit509a8368c332ce73af24544d970974deb1a13778 (patch)
tree0ef5bab7cd31aa2cec53baf69305a4b10ee780ac /docs/manual
parent1326e7618571e1a27247e3aa4ef61dcd69f87c3e (diff)
downloadbuildroot-509a8368c332ce73af24544d970974deb1a13778.tar.gz
buildroot-509a8368c332ce73af24544d970974deb1a13778.tar.bz2
docs/manual: add documentation for linux-ext and linux-tools.
[Thomas: misc improvements.] Signed-off-by: Romain Naour <romain.naour@openwide.fr> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Diffstat (limited to 'docs/manual')
-rw-r--r--docs/manual/adding-packages-kernel-module.txt1
-rw-r--r--docs/manual/adding-packages-linux-kernel-spec-infra.txt149
-rw-r--r--docs/manual/adding-packages.txt2
3 files changed, 152 insertions, 0 deletions
diff --git a/docs/manual/adding-packages-kernel-module.txt b/docs/manual/adding-packages-kernel-module.txt
index 0a5ec5b7b7..ffeeef516d 100644
--- a/docs/manual/adding-packages-kernel-module.txt
+++ b/docs/manual/adding-packages-kernel-module.txt
@@ -128,6 +128,7 @@ configure the build of the kernel module:
* +FOO_MODULE_MAKE_OPTS+ may be set to contain extra variable definitions
to pass to the Linux buildsystem.
+[[kernel-variables]]
You may also reference (but you may *not* set!) those variables:
* +LINUX_DIR+ contains the path to where the Linux kernel has been
diff --git a/docs/manual/adding-packages-linux-kernel-spec-infra.txt b/docs/manual/adding-packages-linux-kernel-spec-infra.txt
new file mode 100644
index 0000000000..d394ae67bf
--- /dev/null
+++ b/docs/manual/adding-packages-linux-kernel-spec-infra.txt
@@ -0,0 +1,149 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[linux-kernel-specific-infra]]
+=== Infrastructure specific to the Linux kernel package
+
+The Linux kernel package can use some specific infrastructures based on package
+hooks for building Linux kernel tools or/and building Linux kernel extensions.
+
+[[linux-kernel-tools]]
+==== linux-kernel-tools
+
+Buildroot offers a helper infrastructure to build some userspace tools
+for the target available within the Linux kernel sources. Since their
+source code is part of the kernel source code, it is not very
+practical to use separate packages for them as they often need to be
+built with the same kernel version as the kernel being used on the
+target. The small Linux kernel tools infrastructure is a simplified
+packaging mechanism based on the generic package infrastructure to
+help building those tools.
+
+Let's look at an example of a Linux tool. For a new Linux tool named
++foo+, create a new menu entry in the existing
++linux/Config.tools.in+. This file will contain the option
+descriptions related to each kernel tool that will be used and
+displayed in the configuration tool. It would basically look like:
+
+------------------------------
+01: config BR2_LINUX_KERNEL_TOOL_FOO
+02: bool "foo"
+03: help
+04: This is a comment that explains what foo kernel tool is.
+05:
+06: http://foosoftware.org/foo/
+------------------------------
+
+The name of the option starts with the prefix +BR2_LINUX_KERNEL_TOOL_+,
+followed by the uppercase name of the tool (like is done for packages).
+
+Then for each linux tool, add a new +.mk+ file named +linux/linux-tool-foo.mk+.
+It would basically look like:
+
+------------------------------
+01: ################################################################################
+02: #
+03: # foo
+04: #
+05: ################################################################################
+06:
+07: LINUX_TOOLS += foo
+08:
+09: FOO_DEPENDENCIES = libbbb
+10:
+11: define FOO_BUILD_CMDS
+12: $(TARGET_MAKE_ENV) $(MAKE) -C $(@D)/tools foo
+13: endef
+14:
+15: define FOO_INSTALL_STAGING_CMDS
+16: $(TARGET_MAKE_ENV) $(MAKE) -C $(@D)/tools \
+17: DESTDIR=$(STAGING_DIR) \
+18: foo_install
+19: endef
+20:
+21: define FOO_INSTALL_TARGET_CMDS
+22: $(TARGET_MAKE_ENV) $(MAKE) -C $(@D)/tools \
+23: DESTDIR=$(@D) \
+24: foo_install
+25: endef
+--------------------------------
+
+On line 7, we register the Linux tool +foo+ to the list of available
+Linux tools.
+
+On line 9, we specify the list of dependencies this tool relies on. These
+dependencies are added to the Linux package dependencies list only when the
++foo+ tool is selected.
+
+The rest of the Makefile, lines 11-25 defines what should be done at the
+different steps of the Linux tool build process like for a
+xref:generic-package-tutorial[+generic package+]. They will actually be
+used only when the +foo+ tool is selected. The only supported commands are
++_BUILD_CMDS+, +_INSTALL_STAGING_CMDS+ and +_INSTALL_TARGET_CMDS+.
+
+.Note
+One *must not* call +$(eval $(generic-package))+ or any other
+package infrastructure! Linux tools are not packages by themselves,
+they are part of the +linux+ package.
+
+[[linux-kernel-ext]]
+==== linux-kernel-extensions
+
+Some packages provide new features that require the Linux kernel tree
+to be modified. This can be in the form of patches to be applied on
+the kernel tree, or in the form of new files to be added to the
+tree. The Buildroot's Linux kernel extensions infrastructure provides
+a simple solution to automatically do this, just after the kernel
+sources are extracted and before the kernel patches are
+applied. Examples of extensions packaged using this mechanism are the
+real-time extensions Xenomai and RTAI, as well as the set of
+out-of-tree LCD screens drivers +fbtft+.
+
+Let's look at an example on how to add a new Linux extension +foo+.
+
+First, create the package +foo+ that provides the extension: this
+package is a standard package; see the previous chapters on how to
+create such a package. This package is in charge of downloading the
+sources archive, checking the hash, defining the licence informations
+and building user space tools if any.
+
+Then create the 'Linux extension' proper: create a new menu entry in
+the existing +linux/Config.ext.in+. This file contains the option
+descriptions related to each kernel extension that will be used and
+displayed in the configuration tool. It would basically look like:
+
+------------------------------
+01: config BR2_LINUX_KERNEL_EXT_FOO
+02: bool "foo"
+03: help
+04: This is a comment that explains what foo kernel extension is.
+05:
+06: http://foosoftware.org/foo/
+------------------------------
+
+Then for each linux extension, add a new +.mk+ file named
++linux/linux-ext-foo.mk+. It should basically contain:
+
+------------------------------
+01: ################################################################################
+02: #
+03: # foo
+04: #
+05: ################################################################################
+06:
+07: LINUX_EXTENSIONS += foo
+08:
+09: define FOO_PREPARE_KERNEL
+10: $(FOO_DIR)/prepare-kernel-tree.sh --linux-dir=$(@D)
+11: endef
+--------------------------------
+
+On line 7, we add the Linux extension +foo+ to the list of available
+Linux extensions.
+
+On line 9-11, we define what should be done by the extension to modify
+the Linux kernel tree; this is specific to the linux extension and can
+use the variables defined by the +foo+ package, like: +$(FOO_DIR)+ or
++$(FOO_VERSION)+... as well as all the Linux variables, like:
++$(LINUX_VERSION)+ or +$(LINUX_VERSION_PROBED)+, +$(KERNEL_ARCH)+...
+See the xref:kernel-variables[definition of those kernel variables].
diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
index 721fe396c1..76f90c9a84 100644
--- a/docs/manual/adding-packages.txt
+++ b/docs/manual/adding-packages.txt
@@ -33,6 +33,8 @@ include::adding-packages-kernel-module.txt[]
include::adding-packages-asciidoc.txt[]
+include::adding-packages-linux-kernel-spec-infra.txt[]
+
include::adding-packages-hooks.txt[]
include::adding-packages-gettext.txt[]