diff options
Diffstat (limited to 'docs/manual/customize-outside-br.txt')
| -rw-r--r-- | docs/manual/customize-outside-br.txt | 140 |
1 files changed, 88 insertions, 52 deletions
diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt index 9ad177d00..f2a83a622 100644 --- a/docs/manual/customize-outside-br.txt +++ b/docs/manual/customize-outside-br.txt @@ -11,25 +11,27 @@ place project-specific customizations in two locations: branches in a version control system so that upgrading to a newer Buildroot release is easy. - * outside of the Buildroot tree, using the +BR2_EXTERNAL+ mechanism. + * outside of the Buildroot tree, using the _br2-external_ mechanism. This mechanism 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. This section - explains 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. Thanks to 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. + having them nicely integrated in the build logic. We call this + location a _br2-external tree_. This section explains how to use + the br2-external mechanism and what to provide in a br2-external + tree. + +One can tell Buildroot to use a br2-external tree by setting the ++BR2_EXTERNAL+ make variable set to the path of the br2-external tree +to use. It can be passed to any Buildroot +make+ invocation. It is +automatically saved in the hidden +.br-external.mk+ file in the output +directory. Thanks to 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* -to the Buildroot output directory. +The path to a br2-external tree can be either absolute or relative. +If it is passed as a relative path, it is important to note that it is +interpreted relative to the main Buildroot source directory, *not* to +the Buildroot output directory. Some examples: @@ -37,73 +39,107 @@ Some examples: buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig ----- -From now on, external definitions from the +/path/to/foobar+ -directory will be used: +From now on, definitions from the +/path/to/foobar+ br2-external tree +will be used: ----- buildroot/ $ make buildroot/ $ make legal-info ----- -We can switch to another external definitions directory at any time: +We can switch to another br2-external tree at any time: ----- buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig ----- -Or disable the usage of external definitions: +Or disable the usage of any br2-external tree: ----- buildroot/ $ make BR2_EXTERNAL= xconfig ----- -+BR2_EXTERNAL+ 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). - - * 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. +A br2-external tree must contain at least those three files: + ++external.desc+:: + That file shall contain the _name_ for the br2-external tree. That name + must only use ASCII characters in the set +[A-Za-z0-9_]+; any other + character is forbidden. The format for this file is a single line with + the keyword 'name:', followed by one or more spaces, followed by the + name. + -.Note -Providing +Config.in+ and +external.mk+ is mandatory, but they can be - empty. +Buildroot sets +BR2_EXTERNAL_$(NAME)_PATH+ to the absolute path of the + br2-external tree, so that you can use it to refer to your br2-external + tree. This variable is available both in Kconfig, so you can use it + to source your Kconfig files (see below) and in the Makefile, so that + you can use it to include other Makefiles (see below) or refer to other + files (like data files) from your br2-external tree. ++ +Example of an +external.desc+ file that declares the name +FOO+: ++ +---- +$ cat external.desc +name: FOO +---- ++ +Examples of names and the corresponding +BR2_EXTERNAL_$(NAME)_PATH+ +variables: ++ + * +FOO+ -> +BR2_EXTERNAL_FOO_PATH+ + * +BAR_42+ -> +BR2_EXTERNAL_BAR_42_PATH+ ++ +In the following examples, it is assumed the name to be set to +BAR_42+. + ++Config.in+:: ++external.mk+:: + Those files (which may each be empty) can be used to define package + recipes, like for packages bundled in Buildroot itself, or other + custom configuration options. + +Using a br2-external tree 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 the location (by + using the +BR2_EXTERNAL_$(NAME)_PATH+ variable). For example, you + could set the paths to a global patch directory, to a rootfs overlay + and to the kernel configuration file as follows (e.g. by running + `make menuconfig` and filling in these options): ++ +---- +BR2_GLOBAL_PATCH_DIR=$(BR2_EXTERNAL_BAR_42_PATH)/patches/ +BR2_ROOTFS_OVERLAY=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/overlay/ +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_FOO)/board/<boardname>/kernel.config +---- + + * One can store package recipes (i.e. +Config.in+ and +<packagename>.mk+), + or even custom configuration options and make logic. Buildroot + automatically includes +Config.in+ to make it appear in the top-level + configuration menu, and includes +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+ file that - looks like: +The main usage of this is to store package recipes. The recommended way + to do this is to write a +Config.in+ file that looks like: + ------ -source "$BR2_EXTERNAL/package/package1/Config.in" -source "$BR2_EXTERNAL/package/package2/Config.in" +source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in" +source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in" ------ + -Then, have a +$(BR2_EXTERNAL)/external.mk+ file that looks like: +Then, have an +external.mk+ file that looks like: + ------ -include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk)) +include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/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[]. +And then in +$(BR2_EXTERNAL_FOO_42_PATH)/package/package1+ and + +$(BR2_EXTERNAL_FOO_42_PATH)/package/package2+ create normal + Buildroot package recipes, as explained in xref:adding-packages[]. If you prefer, you can also group the packages in subdirectories called <boardname> and adapt the above paths accordingly. * One can store Buildroot defconfigs in the +configs+ subdirectory of - +$(BR2_EXTERNAL)+. Buildroot will automatically show them in the + the br2-external tree. Buildroot will automatically show them in the output of +make list-defconfigs+ 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 list-defconfigs' output. |