X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fbuild%2Fdocs%2Fmanual%2Fcustomize-outside-br.txt;fp=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fbuild%2Fdocs%2Fmanual%2Fcustomize-outside-br.txt;h=9ad177d006590fcb5861c2aae24c3b9b828ee649;hb=b0a0f15dfaa205161a7fcb20cf1b8cd4948c2ef3;hp=0000000000000000000000000000000000000000;hpb=c6ac3cd55ee2da956195eee393b0882105dfad4e;p=packages%2Ftrusty%2Fcirros-testvm.git diff --git a/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/customize-outside-br.txt b/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/customize-outside-br.txt new file mode 100644 index 0000000..9ad177d --- /dev/null +++ b/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/customize-outside-br.txt @@ -0,0 +1,109 @@ +// -*- mode:doc -*- ; +// vim: set syntax=asciidoc: + +[[outside-br-custom]] +=== Keeping customizations outside of Buildroot + +As already briefly mentioned in xref:customize-dir-structure[], you can +place project-specific customizations in two locations: + + * directly within the Buildroot tree, typically maintaining them using + 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. + 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. + +.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. + +Some examples: + +----- +buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig +----- + +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+ 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//overlay/+ (to specify a root + filesystem overlay), or the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+ + Buildroot option to + +$(BR2_EXTERNAL)/board//kernel.config+ (to specify the + location of the kernel configuration file). + + * One can store package recipes (i.e. +Config.in+ and + +.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. ++ +.Note +Providing +Config.in+ and +external.mk+ 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+ file 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[]. + If you prefer, you can also group the packages in subdirectories + called 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 + output of +make list-defconfigs+ and allow them to be loaded with the + normal +make _defconfig+ command. They will be visible under the + +User-provided configs+' label in the 'make list-defconfigs' output.