diff options
author | Thomas Petazzoni <thomas.petazzoni@free-electrons.com> | 2013-12-05 20:11:13 +0100 |
---|---|---|
committer | Peter Korsgaard <peter@korsgaard.com> | 2013-12-08 23:01:44 +0100 |
commit | 2233f5f8fb40527e6d14939bb79ec24ff2325fc1 (patch) | |
tree | e81b29ee9de437557af208823a58db517db1201c /docs/manual/customize-outside-br.txt | |
parent | ff9d6e306032a680e9db43673d9ab57db7d1bf75 (diff) | |
download | buildroot-2233f5f8fb40527e6d14939bb79ec24ff2325fc1.tar.gz buildroot-2233f5f8fb40527e6d14939bb79ec24ff2325fc1.zip |
docs/manual: add explanations about BR2_EXTERNAL
This commit updates the manual to add details on how to use the
BR2_EXTERNAL feature.
[Peter: minor tweaks, fix asciidoc tag as pointed out by Samuel]
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Acked-by: "Samuel Martin" <s.martin49@gmail.com>
Acked-by: Ryan Barnett <rjbarnet@rockwellcollins.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
Diffstat (limited to 'docs/manual/customize-outside-br.txt')
-rw-r--r-- | docs/manual/customize-outside-br.txt | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt new file mode 100644 index 0000000000..0aabf5a9b5 --- /dev/null +++ b/docs/manual/customize-outside-br.txt @@ -0,0 +1,138 @@ +// -*- 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. + +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 relatively to the main Buildroot source directory, not +the Buildroot output directory. + +Some examples: + +----- + buildroot/ $ make BR2_EXTERNAL=../foobar menuconfig +----- + +Starting from now on, external definitions from the +../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=../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. ++ +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: ++ +------ +menu "<somecompany> packages" + +source "$BR2_EXTERNAL/package/package1/Config.in" +source "$BR2_EXTERNAL/package/package2/Config.in" + +endmenu +------ ++ +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 +------ |