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

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 [[linux-kernel-specific-infra]]
   5 === Infrastructure specific to the Linux kernel package
   6
   7 The Linux kernel package can use some specific infrastructures based on package
   8 hooks for building Linux kernel tools or/and building Linux kernel extensions.
   9
  10 [[linux-kernel-tools]]
  11 ==== linux-kernel-tools
  12
  13 Buildroot offers a helper infrastructure to build some userspace tools
  14 for the target available within the Linux kernel sources. Since their
  15 source code is part of the kernel source code, a special package,
  16 +linux-tools+, exists and re-uses the sources of the Linux kernel that
  17 runs on the target.
  18
  19 Let's look at an example of a Linux tool. For a new Linux tool named
  20 +foo+, create a new menu entry in the existing
  21 +package/linux-tools/Config.in+.  This file will contain the option
  22 descriptions related to each kernel tool that will be used and
  23 displayed in the configuration tool. It would basically look like:
  24
  25 ------------------------------
  26 01: config BR2_PACKAGE_LINUX_TOOLS_FOO
  27 02:     bool "foo"
  28 03:     select BR2_PACKAGE_LINUX_TOOLS
  29 04:     help
  30 05:       This is a comment that explains what foo kernel tool is.
  31 06:
  32 07:       http://foosoftware.org/foo/
  33 ------------------------------
  34
  35 The name of the option starts with the prefix +BR2_PACKAGE_LINUX_TOOLS_+,
  36 followed by the uppercase name of the tool (like is done for packages).
  37
  38 .Note
  39 Unlike other packages, the +linux-tools+ package options appear in the
  40 +linux+ kernel menu, under the `Linux Kernel Tools` sub-menu, not under
  41 the `Target packages` main menu.
  42
  43 Then for each linux tool, add a new +.mk+ file named
  44 +package/linux-tools/linux-tool-foo.mk+. It would basically look like:
  45
  46 ------------------------------
  47 01: ################################################################################
  48 02: #
  49 03: # foo
  50 04: #
  51 05: ################################################################################
  52 06:
  53 07: LINUX_TOOLS += foo
  54 08:
  55 09: FOO_DEPENDENCIES = libbbb
  56 10:
  57 11: define FOO_BUILD_CMDS
  58 12:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools foo
  59 13: endef
  60 14:
  61 15: define FOO_INSTALL_STAGING_CMDS
  62 16:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
  63 17:             DESTDIR=$(STAGING_DIR) \
  64 18:             foo_install
  65 19: endef
  66 20:
  67 21: define FOO_INSTALL_TARGET_CMDS
  68 22:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
  69 23:             DESTDIR=$(TARGET_DIR) \
  70 24:             foo_install
  71 25: endef
  72 --------------------------------
  73
  74 On line 7, we register the Linux tool +foo+ to the list of available
  75 Linux tools.
  76
  77 On line 9, we specify the list of dependencies this tool relies on. These
  78 dependencies are added to the Linux package dependencies list only when the
  79 +foo+ tool is selected.
  80
  81 The rest of the Makefile, lines 11-25 defines what should be done at the
  82 different steps of the Linux tool build process like for a
  83 xref:generic-package-tutorial[+generic package+]. They will actually be
  84 used only when the +foo+ tool is selected. The only supported commands are
  85 +_BUILD_CMDS+, +_INSTALL_STAGING_CMDS+ and +_INSTALL_TARGET_CMDS+.
  86
  87 .Note
  88 One *must not* call +$(eval $(generic-package))+ or any other
  89 package infrastructure! Linux tools are not packages by themselves,
  90 they are part of the +linux-tools+ package.
  91
  92 [[linux-kernel-ext]]
  93 ==== linux-kernel-extensions
  94
  95 Some packages provide new features that require the Linux kernel tree
  96 to be modified. This can be in the form of patches to be applied on
  97 the kernel tree, or in the form of new files to be added to the
  98 tree. The Buildroot's Linux kernel extensions infrastructure provides
  99 a simple solution to automatically do this, just after the kernel
 100 sources are extracted and before the kernel patches are
 101 applied. Examples of extensions packaged using this mechanism are the
 102 real-time extensions Xenomai and RTAI, as well as the set of
 103 out-of-tree LCD screens drivers +fbtft+.
 104
 105 Let's look at an example on how to add a new Linux extension +foo+.
 106
 107 First, create the package +foo+ that provides the extension: this
 108 package is a standard package; see the previous chapters on how to
 109 create such a package. This package is in charge of downloading the
 110 sources archive, checking the hash, defining the licence informations
 111 and building user space tools if any.
 112
 113 Then create the 'Linux extension' proper: create a new menu entry in
 114 the existing +linux/Config.ext.in+. This file contains the option
 115 descriptions related to each kernel extension that will be used and
 116 displayed in the configuration tool. It would basically look like:
 117
 118 ------------------------------
 119 01: config BR2_LINUX_KERNEL_EXT_FOO
 120 02:     bool "foo"
 121 03:     help
 122 04:       This is a comment that explains what foo kernel extension is.
 123 05:
 124 06:       http://foosoftware.org/foo/
 125 ------------------------------
 126
 127 Then for each linux extension, add a new +.mk+ file named
 128 +linux/linux-ext-foo.mk+. It should basically contain:
 129
 130 ------------------------------
 131 01: ################################################################################
 132 02: #
 133 03: # foo
 134 04: #
 135 05: ################################################################################
 136 06:
 137 07: LINUX_EXTENSIONS += foo
 138 08:
 139 09: define FOO_PREPARE_KERNEL
 140 10:     $(FOO_DIR)/prepare-kernel-tree.sh --linux-dir=$(@D)
 141 11: endef
 142 --------------------------------
 143
 144 On line 7, we add the Linux extension +foo+ to the list of available
 145 Linux extensions.
 146
 147 On line 9-11, we define what should be done by the extension to modify
 148 the Linux kernel tree; this is specific to the linux extension and can
 149 use the variables defined by the +foo+ package, like: +$(FOO_DIR)+ or
 150 +$(FOO_VERSION)+... as well as all the Linux variables, like:
 151 +$(LINUX_VERSION)+ or +$(LINUX_VERSION_PROBED)+, +$(KERNEL_ARCH)+...
 152 See the xref:kernel-variables[definition of those kernel variables].