| // -*- mode:doc -*- ; |
| |
| [[outside-br-custom]] |
| === Keeping customizations outside Buildroot |
| |
| The Buildroot community recommends and encourages upstreaming to the |
| official Buildroot version the packages and board support that are |
| written by developers. However, it is sometimes not possible or |
| desirable because some of these packages or board support are highly |
| specific or proprietary. |
| |
| In this case, Buildroot users are offered two choices: |
| |
| * They can add their packages, board support and configuration files |
| directly within the Buildroot tree, and maintain them by using |
| branches in a version control system. |
| |
| * They can use the +BR2_EXTERNAL+ mechanism, which allows to keep |
| package recipes, board support and configuration files outside of |
| the Buildroot tree, while still having them nicely integrated in |
| the build logic. The following paragraphs give details on how to |
| use +BR2_EXTERNAL+. |
| |
| +BR2_EXTERNAL+ is an environment variable that can be used to point to |
| a directory that contains Buildroot customizations. It can be passed |
| to any Buildroot +make+ invocation. It is automatically saved in the |
| hidden +.br-external+ file in the output directory. By doing this, |
| there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It |
| can however be changed at any time by passing a new value, and can be |
| removed by passing an empty value. |
| |
| *Note:* the +BR2_EXTERNAL+ path can be either an absolute or a relative path, |
| but if it's passed as a relative path, it is important to note that it |
| is interpreted relative to the main Buildroot source directory, *not* |
| the Buildroot output directory. |
| |
| Some examples: |
| |
| ----- |
| buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig |
| ----- |
| |
| Starting from now on, external definitions from the +/path/to/foobar+ |
| directory will be used: |
| |
| ----- |
| buildroot/ $ make |
| buildroot/ $ make legal-info |
| ----- |
| |
| We can switch to another external definitions directory at any time: |
| |
| ----- |
| buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig |
| ----- |
| |
| Or disable the usage of external definitions: |
| |
| ----- |
| buildroot/ $ make BR2_EXTERNAL= xconfig |
| ----- |
| |
| +BR2_EXTERNAL+ then allows three different things: |
| |
| * One can store all the board-specific configuration files there, |
| such as the kernel configuration, the root filesystem overlay, or |
| any other configuration file for which Buildroot allows to set its |
| location. The +BR2_EXTERNAL+ value is available within the |
| Buildroot configuration using +$(BR2_EXTERNAL)+. As an example, one |
| could set the +BR2_ROOTFS_OVERLAY+ Buildroot option to |
| +$(BR2_EXTERNAL)/board/<boardname>/overlay/+ (to specify a root |
| filesystem overlay), or the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+ |
| Buildroot option to |
| +$(BR2_EXTERNAL)/board/<boardname>/kernel.config+ (to specify the |
| location of the kernel configuration file). To achieve this, it is |
| recommended but not mandatory, to store those details in |
| directories called +board/<boardname>/+ under +BR2_EXTERNAL+. This |
| matches the directory structure used within Buildroot. |
| |
| * One can store package recipes (i.e. +Config.in+ and |
| +<packagename>.mk+), or even custom configuration options and make |
| logic. Buildroot automatically includes +BR2_EXTERNAL/Config.in+ to |
| make it appear in the top-level configuration menu, and includes |
| +BR2_EXTERNAL/external.mk+ with the rest of the makefile logic. |
| Providing those two files is mandatory, but they can be empty. |
| + |
| The main usage of this is to store package recipes. The recommended |
| way to do this is to write a +BR2_EXTERNAL/Config.in+ that looks |
| like: |
| + |
| ------ |
| source "$BR2_EXTERNAL/package/package1/Config.in" |
| source "$BR2_EXTERNAL/package/package2/Config.in" |
| ------ |
| + |
| Then, have a +BR2_EXTERNAL/external.mk+ file that looks like: |
| + |
| ------ |
| include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk)) |
| ------ |
| + |
| And then in +BR2_EXTERNAL/package/package1+ and |
| +BR2_EXTERNAL/package/package2+ create normal Buildroot package |
| recipes, as explained in xref:adding-packages[]. |
| |
| * One can store Buildroot defconfigs in the +configs+ subdirectory of |
| +BR2_EXTERNAL+. Buildroot will automatically show them in the |
| output of +make help+ and allow them to be loaded with the normal |
| +make <name>_defconfig+ command. They will be visible under the |
| +User-provided configs:+' label in the 'make help' output. |
| |
| In the end, a typical +BR2_EXTERNAL+ directory organization would |
| generally be: |
| |
| ----- |
| $(BR2_EXTERNAL)/ |
| +-- Config.in |
| +-- external.mk |
| +-- board/ |
| | +-- <boardname>/ |
| | +-- linux.config |
| | +-- overlay/ |
| | +-- etc/ |
| | +-- <some file> |
| +-- configs/ |
| | +-- <boardname>_defconfig |
| +-- package/ |
| +-- package1/ |
| | +-- Config.in |
| | +-- package1.mk |
| +-- package2/ |
| +-- Config.in |
| +-- package2.mk |
| ------ |