adding-packages-linux-kernel-spec-infra.txt 5.6 KB

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