customize-outside-br.txt 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446
  1. // -*- mode:doc -*- ;
  2. // vim: set syntax=asciidoc:
  3. [[outside-br-custom]]
  4. === Keeping customizations outside of Buildroot
  5. As already briefly mentioned in xref:customize-dir-structure[], you can
  6. place project-specific customizations in two locations:
  7. * directly within the Buildroot tree, typically maintaining them using
  8. branches in a version control system so that upgrading to a newer
  9. Buildroot release is easy.
  10. * outside of the Buildroot tree, using the _br2-external_ mechanism.
  11. This mechanism allows to keep package recipes, board support and
  12. configuration files outside of the Buildroot tree, while still
  13. having them nicely integrated in the build logic. We call this
  14. location a _br2-external tree_. This section explains how to use
  15. the br2-external mechanism and what to provide in a br2-external
  16. tree.
  17. One can tell Buildroot to use one or more br2-external trees by setting
  18. the +BR2_EXTERNAL+ make variable set to the path(s) of the br2-external
  19. tree(s) to use. It can be passed to any Buildroot +make+ invocation. It
  20. is automatically saved in the hidden +.br2-external.mk+ file in the output
  21. directory. Thanks to this, there is no need to pass +BR2_EXTERNAL+ at
  22. every +make+ invocation. It can however be changed at any time by
  23. passing a new value, and can be removed by passing an empty value.
  24. .Note
  25. The path to a br2-external tree can be either absolute or relative.
  26. If it is passed as a relative path, it is important to note that it is
  27. interpreted relative to the main Buildroot source directory, *not* to
  28. the Buildroot output directory.
  29. .Note:
  30. If using an br2-external tree from before Buildroot 2016.11, you need to
  31. convert it before you can use it with Buildroot 2016.11 onward. See
  32. xref:br2-external-converting[] for help on doing so.
  33. Some examples:
  34. -----
  35. buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig
  36. -----
  37. From now on, definitions from the +/path/to/foo+ br2-external tree
  38. will be used:
  39. -----
  40. buildroot/ $ make
  41. buildroot/ $ make legal-info
  42. -----
  43. We can switch to another br2-external tree at any time:
  44. -----
  45. buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig
  46. -----
  47. We can also use multiple br2-external trees:
  48. ----
  49. buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/where/we/have/bar menuconfig
  50. ----
  51. Or disable the usage of any br2-external tree:
  52. -----
  53. buildroot/ $ make BR2_EXTERNAL= xconfig
  54. -----
  55. ==== Layout of a br2-external tree
  56. A br2-external tree must contain at least those three files, described
  57. in the following chapters:
  58. * +external.desc+
  59. * +external.mk+
  60. * +Config.in+
  61. Apart from those mandatory files, there may be additional and optional
  62. content that may be present in a br2-external tree, like the +configs/+
  63. or +provides/+ directories. They are described in the following chapters
  64. as well.
  65. A complete example br2-external tree layout is also described later.
  66. ===== The +external.desc+ file
  67. That file describes the br2-external tree: the _name_ and _description_
  68. for that br2-external tree.
  69. The format for this file is line based, with each line starting by a
  70. keyword, followed by a colon and one or more spaces, followed by the
  71. value assigned to that keyword. There are two keywords currently
  72. recognised:
  73. * +name+, mandatory, defines the name for that br2-external tree. That
  74. name must only use ASCII characters in the set +[A-Za-z0-9_]+; any
  75. other character is forbidden. Buildroot sets the variable
  76. +BR2_EXTERNAL_$(NAME)_PATH+ to the absolute path of the br2-external
  77. tree, so that you can use it to refer to your br2-external tree. This
  78. variable is available both in Kconfig, so you can use it to source your
  79. Kconfig files (see below) and in the Makefile, so that you can use it
  80. to include other Makefiles (see below) or refer to other files (like
  81. data files) from your br2-external tree.
  82. +
  83. .Note:
  84. Since it is possible to use multiple br2-external trees at once, this
  85. name is used by Buildroot to generate variables for each of those trees.
  86. That name is used to identify your br2-external tree, so try to come up
  87. with a name that really describes your br2-external tree, in order for
  88. it to be relatively unique, so that it does not clash with another name
  89. from another br2-external tree, especially if you are planning on
  90. somehow sharing your br2-external tree with third parties or using
  91. br2-external trees from third parties.
  92. * +desc+, optional, provides a short description for that br2-external
  93. tree. It shall fit on a single line, is mostly free-form (see below),
  94. and is used when displaying information about a br2-external tree (e.g.
  95. above the list of defconfig files, or as the prompt in the menuconfig);
  96. as such, it should relatively brief (40 chars is probably a good upper
  97. limit). The description is available in the +BR2_EXTERNAL_$(NAME)_DESC+
  98. variable.
  99. Examples of names and the corresponding +BR2_EXTERNAL_$(NAME)_PATH+
  100. variables:
  101. * +FOO+ -> +BR2_EXTERNAL_FOO_PATH+
  102. * +BAR_42+ -> +BR2_EXTERNAL_BAR_42_PATH+
  103. In the following examples, it is assumed the name to be set to +BAR_42+.
  104. .Note:
  105. Both +BR2_EXTERNAL_$(NAME)_PATH+ and `BR2_EXTERNAL_$(NAME)_DESC` are
  106. available in the Kconfig files and the Makefiles. They are also
  107. exported in the environment so are available in post-build, post-image
  108. and in-fakeroot scripts.
  109. ===== The +Config.in+ and +external.mk+ files
  110. Those files (which may each be empty) can be used to define package
  111. recipes (i.e. +foo/Config.in+ and +foo/foo.mk+ like for packages bundled
  112. in Buildroot itself) or other custom configuration options or make logic.
  113. Buildroot automatically includes the +Config.in+ from each br2-external
  114. tree to make it appear in the top-level configuration menu, and includes
  115. the +external.mk+ from each br2-external tree with the rest of the
  116. makefile logic.
  117. The main usage of this is to store package recipes. The recommended way
  118. to do this is to write a +Config.in+ file that looks like:
  119. ------
  120. source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in"
  121. source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in"
  122. ------
  123. Then, have an +external.mk+ file that looks like:
  124. ------
  125. include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
  126. ------
  127. And then in +$(BR2_EXTERNAL_BAR_42_PATH)/package/package1+ and
  128. +$(BR2_EXTERNAL_BAR_42_PATH)/package/package2+ create normal
  129. Buildroot package recipes, as explained in xref:adding-packages[].
  130. If you prefer, you can also group the packages in subdirectories
  131. called <boardname> and adapt the above paths accordingly.
  132. You can also define custom configuration options in +Config.in+ and
  133. custom make logic in +external.mk+.
  134. ===== The +configs/+ directory
  135. One can store Buildroot defconfigs in the +configs+ subdirectory of
  136. the br2-external tree. Buildroot will automatically show them in the
  137. output of +make list-defconfigs+ and allow them to be loaded with the
  138. normal +make <name>_defconfig+ command. They will be visible in the
  139. 'make list-defconfigs' output, below an +External configs+ label that
  140. contains the name of the br2-external tree they are defined in.
  141. .Note:
  142. If a defconfig file is present in more than one br2-external tree, then
  143. the one from the last br2-external tree is used. It is thus possible
  144. to override a defconfig bundled in Buildroot or another br2-external
  145. tree.
  146. ===== The +provides/+ directory
  147. For some packages, Buildroot provides a choice between two (or more)
  148. implementations of API-compatible such packages. For example, there is
  149. a choice to choose either libjpeg ot jpeg-turbo; there is one between
  150. openssl or libressl; there is one to select one of the known,
  151. pre-configured toolchains...
  152. It is possible for a br2-external to extend those choices, by providing
  153. a set of files that define those alternatives:
  154. * +provides/toolchains.in+ defines the pre-configured toolchains, which
  155. will then be listed in the toolchain selection;
  156. * +provides/jpeg.in+ defines the alternative libjpeg implementations;
  157. * +provides/openssl.in+ defines the alternative openssl implementations;
  158. * +provides/skeleton.in+ defines the alternative skeleton implementations;
  159. * +provides/init.in+ defines the alternative init system implementations, this
  160. can be used to select a default skeleton for your init.
  161. ===== Free-form content
  162. One can store all the board-specific configuration files there, such
  163. as the kernel configuration, the root filesystem overlay, or any other
  164. configuration file for which Buildroot allows to set the location (by
  165. using the +BR2_EXTERNAL_$(NAME)_PATH+ variable). For example, you
  166. could set the paths to a global patch directory, to a rootfs overlay
  167. and to the kernel configuration file as follows (e.g. by running
  168. `make menuconfig` and filling in these options):
  169. ----
  170. BR2_GLOBAL_PATCH_DIR=$(BR2_EXTERNAL_BAR_42_PATH)/patches/
  171. BR2_ROOTFS_OVERLAY=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/overlay/
  172. BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/kernel.config
  173. ----
  174. ===== Additional Linux kernel extensions
  175. Additional Linux kernel extensions (see xref:linux-kernel-ext[]) can
  176. be added by storing them in the `linux/` directory at the root of a
  177. br2-external tree.
  178. ===== Example layout
  179. Here is an example layout using all features of br2-external (the sample
  180. content is shown for the file above it, when it is relevant to explain
  181. the br2-external tree; this is all entirely made up just for the sake of
  182. illustration, of course):
  183. ----
  184. /path/to/br2-ext-tree/
  185. |- external.desc
  186. | |name: BAR_42
  187. | |desc: Example br2-external tree
  188. | `----
  189. |
  190. |- Config.in
  191. | |source "$BR2_EXTERNAL_BAR_42_PATH/toolchain/toolchain-external-mine/Config.in.options"
  192. | |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-1/Config.in"
  193. | |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-2/Config.in"
  194. | |source "$BR2_EXTERNAL_BAR_42_PATH/package/my-jpeg/Config.in"
  195. | |
  196. | |config BAR_42_FLASH_ADDR
  197. | | hex "my-board flash address"
  198. | | default 0x10AD
  199. | `----
  200. |
  201. |- external.mk
  202. | |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
  203. | |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/toolchain/*/*.mk))
  204. | |
  205. | |flash-my-board:
  206. | | $(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/flash-image \
  207. | | --image $(BINARIES_DIR)/image.bin \
  208. | | --address $(BAR_42_FLASH_ADDR)
  209. | `----
  210. |
  211. |- package/pkg-1/Config.in
  212. | |config BR2_PACKAGE_PKG_1
  213. | | bool "pkg-1"
  214. | | help
  215. | | Some help about pkg-1
  216. | `----
  217. |- package/pkg-1/pkg-1.hash
  218. |- package/pkg-1/pkg-1.mk
  219. | |PKG_1_VERSION = 1.2.3
  220. | |PKG_1_SITE = /some/where/to/get/pkg-1
  221. | |PKG_1_LICENSE = blabla
  222. | |
  223. | |define PKG_1_INSTALL_INIT_SYSV
  224. | | $(INSTALL) -D -m 0755 $(PKG_1_PKGDIR)/S99my-daemon \
  225. | | $(TARGET_DIR)/etc/init.d/S99my-daemon
  226. | |endef
  227. | |
  228. | |$(eval $(autotools-package))
  229. | `----
  230. |- package/pkg-1/S99my-daemon
  231. |
  232. |- package/pkg-2/Config.in
  233. |- package/pkg-2/pkg-2.hash
  234. |- package/pkg-2/pkg-2.mk
  235. |
  236. |- provides/jpeg.in
  237. | |config BR2_PACKAGE_MY_JPEG
  238. | | bool "my-jpeg"
  239. | `----
  240. |- package/my-jpeg/Config.in
  241. | |config BR2_PACKAGE_PROVIDES_JPEG
  242. | | default "my-jpeg" if BR2_PACKAGE_MY_JPEG
  243. | `----
  244. |- package/my-jpeg/my-jpeg.mk
  245. | |# This is a normal package .mk file
  246. | |MY_JPEG_VERSION = 1.2.3
  247. | |MY_JPEG_SITE = https://example.net/some/place
  248. | |MY_JPEG_PROVIDES = jpeg
  249. | |$(eval $(autotools-package))
  250. | `----
  251. |
  252. |- provides/init.in
  253. | |config BR2_INIT_MINE
  254. | | bool "my custom init"
  255. | | select BR2_PACKAGE_MY_INIT
  256. | | select BR2_PACKAGE_SKELETON_INIT_MINE if BR2_ROOTFS_SKELETON_DEFAULT
  257. | `----
  258. |
  259. |- provides/skeleton.in
  260. | |config BR2_ROOTFS_SKELETON_MINE
  261. | | bool "my custom skeleton"
  262. | | select BR2_PACKAGE_SKELETON_MINE
  263. | `----
  264. |- package/skeleton-mine/Config.in
  265. | |config BR2_PACKAGE_SKELETON_MINE
  266. | | bool
  267. | | select BR2_PACKAGE_HAS_SKELETON
  268. | |
  269. | |config BR2_PACKAGE_PROVIDES_SKELETON
  270. | | default "skeleton-mine" if BR2_PACKAGE_SKELETON_MINE
  271. | `----
  272. |- package/skeleton-mine/skeleton-mine.mk
  273. | |SKELETON_MINE_ADD_TOOLCHAIN_DEPENDENCY = NO
  274. | |SKELETON_MINE_ADD_SKELETON_DEPENDENCY = NO
  275. | |SKELETON_MINE_PROVIDES = skeleton
  276. | |SKELETON_MINE_INSTALL_STAGING = YES
  277. | |$(eval $(generic-package))
  278. | `----
  279. |
  280. |- provides/toolchains.in
  281. | |config BR2_TOOLCHAIN_EXTERNAL_MINE
  282. | | bool "my custom toolchain"
  283. | | depends on BR2_some_arch
  284. | | select BR2_INSTALL_LIBSTDCPP
  285. | `----
  286. |- toolchain/toolchain-external-mine/Config.in.options
  287. | |if BR2_TOOLCHAIN_EXTERNAL_MINE
  288. | |config BR2_TOOLCHAIN_EXTERNAL_PREFIX
  289. | | default "arch-mine-linux-gnu"
  290. | |config BR2_PACKAGE_PROVIDES_TOOLCHAIN_EXTERNAL
  291. | | default "toolchain-external-mine"
  292. | |endif
  293. | `----
  294. |- toolchain/toolchain-external-mine/toolchain-external-mine.mk
  295. | |TOOLCHAIN_EXTERNAL_MINE_SITE = https://example.net/some/place
  296. | |TOOLCHAIN_EXTERNAL_MINE_SOURCE = my-toolchain.tar.gz
  297. | |$(eval $(toolchain-external-package))
  298. | `----
  299. |
  300. |- linux/Config.ext.in
  301. | |config BR2_LINUX_KERNEL_EXT_EXAMPLE_DRIVER
  302. | | bool "example-external-driver"
  303. | | help
  304. | | Example external driver
  305. | |---
  306. |- linux/linux-ext-example-driver.mk
  307. |
  308. |- configs/my-board_defconfig
  309. | |BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_BAR_42_PATH)/patches/"
  310. | |BR2_ROOTFS_OVERLAY="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/overlay/"
  311. | |BR2_ROOTFS_POST_IMAGE_SCRIPT="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/post-image.sh"
  312. | |BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/kernel.config"
  313. | `----
  314. |
  315. |- patches/linux/0001-some-change.patch
  316. |- patches/linux/0002-some-other-change.patch
  317. |- patches/busybox/0001-fix-something.patch
  318. |
  319. |- board/my-board/kernel.config
  320. |- board/my-board/overlay/var/www/index.html
  321. |- board/my-board/overlay/var/www/my.css
  322. |- board/my-board/flash-image
  323. `- board/my-board/post-image.sh
  324. |#!/bin/sh
  325. |generate-my-binary-image \
  326. | --root ${BINARIES_DIR}/rootfs.tar \
  327. | --kernel ${BINARIES_DIR}/zImage \
  328. | --dtb ${BINARIES_DIR}/my-board.dtb \
  329. | --output ${BINARIES_DIR}/image.bin
  330. `----
  331. ----
  332. The br2-external tree will then be visible in the menuconfig (with
  333. the layout expanded):
  334. ----
  335. External options --->
  336. *** Example br2-external tree (in /path/to/br2-ext-tree/)
  337. [ ] pkg-1
  338. [ ] pkg-2
  339. (0x10AD) my-board flash address
  340. ----
  341. If you are using more than one br2-external tree, it would look like
  342. (with the layout expanded and the second one with name +FOO_27+ but no
  343. +desc:+ field in +external.desc+):
  344. ----
  345. External options --->
  346. Example br2-external tree --->
  347. *** Example br2-external tree (in /path/to/br2-ext-tree)
  348. [ ] pkg-1
  349. [ ] pkg-2
  350. (0x10AD) my-board flash address
  351. FOO_27 --->
  352. *** FOO_27 (in /path/to/another-br2-ext)
  353. [ ] foo
  354. [ ] bar
  355. ----
  356. Additionally, the jpeg provider will be visible in the jpeg choice:
  357. ----
  358. Target packages --->
  359. Libraries --->
  360. Graphics --->
  361. [*] jpeg support
  362. jpeg variant () --->
  363. ( ) jpeg
  364. ( ) jpeg-turbo
  365. *** jpeg from: Example br2-external tree ***
  366. (X) my-jpeg
  367. *** jpeg from: FOO_27 ***
  368. ( ) another-jpeg
  369. ----
  370. And similarly for the toolchains:
  371. ----
  372. Toolchain --->
  373. Toolchain () --->
  374. ( ) Custom toolchain
  375. *** Toolchains from: Example br2-external tree ***
  376. (X) my custom toolchain
  377. ----
  378. .Note
  379. The toolchain options in +toolchain/toolchain-external-mine/Config.in.options+
  380. will not appear in the `Toolchain` menu. They must be explicitly included
  381. from within the br2-external's top-level +Config.in+ and will thus appear
  382. in the `External options` menu.