Move all to deprecated folder.

deprecated/firmware/buildroot/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/<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.
++
+.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 <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
+   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.