1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4[[linux-kernel-specific-infra]] 5=== Infrastructure specific to the Linux kernel package 6 7The Linux kernel package can use some specific infrastructures based on package 8hooks for building Linux kernel tools or/and building Linux kernel extensions. 9 10[[linux-kernel-tools]] 11==== linux-kernel-tools 12 13Buildroot offers a helper infrastructure to build some userspace tools 14for the target available within the Linux kernel sources. Since their 15source 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 17runs on the target. 18 19Let'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 22descriptions related to each kernel tool that will be used and 23displayed in the configuration tool. It would basically look like: 24 25------------------------------ 2601: config BR2_PACKAGE_LINUX_TOOLS_FOO 2702: bool "foo" 2803: select BR2_PACKAGE_LINUX_TOOLS 2904: help 3005: This is a comment that explains what foo kernel tool is. 3106: 3207: http://foosoftware.org/foo/ 33------------------------------ 34 35The name of the option starts with the prefix +BR2_PACKAGE_LINUX_TOOLS_+, 36followed by the uppercase name of the tool (like is done for packages). 37 38.Note 39Unlike other packages, the +linux-tools+ package options appear in the 40+linux+ kernel menu, under the `Linux Kernel Tools` sub-menu, not under 41the `Target packages` main menu. 42 43Then for each linux tool, add a new +.mk.in+ file named 44+package/linux-tools/linux-tool-foo.mk.in+. It would basically look like: 45 46------------------------------ 4701: ################################################################################ 4802: # 4903: # foo 5004: # 5105: ################################################################################ 5206: 5307: LINUX_TOOLS += foo 5408: 5509: FOO_DEPENDENCIES = libbbb 5610: 5711: define FOO_BUILD_CMDS 5812: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools foo 5913: endef 6014: 6115: define FOO_INSTALL_STAGING_CMDS 6216: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \ 6317: DESTDIR=$(STAGING_DIR) \ 6418: foo_install 6519: endef 6620: 6721: define FOO_INSTALL_TARGET_CMDS 6822: $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \ 6923: DESTDIR=$(TARGET_DIR) \ 7024: foo_install 7125: endef 72-------------------------------- 73 74On line 7, we register the Linux tool +foo+ to the list of available 75Linux tools. 76 77On line 9, we specify the list of dependencies this tool relies on. These 78dependencies are added to the Linux package dependencies list only when the 79+foo+ tool is selected. 80 81The rest of the Makefile, lines 11-25 defines what should be done at the 82different steps of the Linux tool build process like for a 83xref:generic-package-tutorial[+generic package+]. They will actually be 84used 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 88One *must not* call +$(eval $(generic-package))+ or any other 89package infrastructure! Linux tools are not packages by themselves, 90they are part of the +linux-tools+ package. 91 92[[linux-kernel-ext]] 93==== linux-kernel-extensions 94 95Some packages provide new features that require the Linux kernel tree 96to be modified. This can be in the form of patches to be applied on 97the kernel tree, or in the form of new files to be added to the 98tree. The Buildroot's Linux kernel extensions infrastructure provides 99a simple solution to automatically do this, just after the kernel 100sources are extracted and before the kernel patches are 101applied. Examples of extensions packaged using this mechanism are the 102real-time extensions Xenomai and RTAI, as well as the set of 103out-of-tree LCD screens drivers +fbtft+. 104 105Let's look at an example on how to add a new Linux extension +foo+. 106 107First, create the package +foo+ that provides the extension: this 108package is a standard package; see the previous chapters on how to 109create such a package. This package is in charge of downloading the 110sources archive, checking the hash, defining the licence informations 111and building user space tools if any. 112 113Then create the 'Linux extension' proper: create a new menu entry in 114the existing +linux/Config.ext.in+. This file contains the option 115descriptions related to each kernel extension that will be used and 116displayed in the configuration tool. It would basically look like: 117 118------------------------------ 11901: config BR2_LINUX_KERNEL_EXT_FOO 12002: bool "foo" 12103: help 12204: This is a comment that explains what foo kernel extension is. 12305: 12406: http://foosoftware.org/foo/ 125------------------------------ 126 127Then for each linux extension, add a new +.mk+ file named 128+linux/linux-ext-foo.mk+. It should basically contain: 129 130------------------------------ 13101: ################################################################################ 13202: # 13303: # foo 13404: # 13505: ################################################################################ 13606: 13707: LINUX_EXTENSIONS += foo 13808: 13909: define FOO_PREPARE_KERNEL 14010: $(FOO_DIR)/prepare-kernel-tree.sh --linux-dir=$(@D) 14111: endef 142-------------------------------- 143 144On line 7, we add the Linux extension +foo+ to the list of available 145Linux extensions. 146 147On line 9-11, we define what should be done by the extension to modify 148the Linux kernel tree; this is specific to the linux extension and can 149use 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)+... 152See the xref:kernel-variables[definition of those kernel variables]. 153