kumquat-buildroot/docs/manual/adding-packages-linux-kernel-spec-infra.txt

// -*- 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].