// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

==== Using Buildroot during development

The normal operation of Buildroot is to download a tarball, extract
it, configure, compile and install the software component found inside
this tarball. The source code is extracted in
+output/build/<package>-<version>+, which is a temporary directory:
whenever +make clean+ is used, this directory is entirely removed, and
re-created at the next +make+ invocation. Even when a Git or
Subversion repository is used as the input for the package source
code, Buildroot creates a tarball out of it, and then behaves as it
normally does with tarballs.

This behavior is well-suited when Buildroot is used mainly as an
integration tool, to build and integrate all the components of an
embedded Linux system. However, if one uses Buildroot during the
development of certain components of the system, this behavior is not
very convenient: one would instead like to make a small change to the
source code of one package, and be able to quickly rebuild the system
with Buildroot.

Making changes directly in +output/build/<package>-<version>+ is not
an appropriate solution, because this directory is removed on +make
clean+.

Therefore, Buildroot provides a specific mechanism for this use case:
the +<pkg>_OVERRIDE_SRCDIR+ mechanism. Buildroot reads an _override_
file, which allows the user to tell Buildroot the location of the
source for certain packages.

The default location of the override file is +$(CONFIG_DIR)/local.mk+,
as defined by the +BR2_PACKAGE_OVERRIDE_FILE+ configuration option.
+$(CONFIG_DIR)+ is the location of the Buildroot +.config+ file, so
+local.mk+ by default lives side-by-side with the +.config+ file,
which means:

* In the top-level Buildroot source directory for in-tree builds
  (i.e., when +O=+ is not used)
* In the out-of-tree directory for out-of-tree builds (i.e., when
  +O=+ is used)

If a different location than these defaults is required, it can be
specified through the +BR2_PACKAGE_OVERRIDE_FILE+ configuration
option.

In this _override_ file, Buildroot expects to find lines of the form:

------------------
<pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources
<pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources
------------------

For example:

------------------
LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/
------------------

When Buildroot finds that for a given package, an
+<pkg>_OVERRIDE_SRCDIR+ has been defined, it will no longer attempt to
download, extract and patch the package. Instead, it will directly use
the source code available in the specified directory and +make clean+
will not touch this directory. This allows to point Buildroot to your
own directories, that can be managed by Git, Subversion, or any other
version control system. To achieve this, Buildroot will use _rsync_ to
copy the source code of the component from the specified
+<pkg>_OVERRIDE_SRCDIR+ to +output/build/<package>-custom/+.

This mechanism is best used in conjunction with the +make
<pkg>-rebuild+ and +make <pkg>-reconfigure+ targets. A +make
<pkg>-rebuild all+ sequence will _rsync_ the source code from
+<pkg>_OVERRIDE_SRCDIR+ to +output/build/<package>-custom+ (thanks to
_rsync_, only the modified files are copied), and restart the build
process of just this package.

In the example of the +linux+ package above, the developer can then
make a source code change in +/home/bob/linux+ and then run:

-----------------------
make linux-rebuild all
-----------------------

and in a matter of seconds gets the updated Linux kernel image in
+output/images+. Similarly, a change can be made to the BusyBox source
code in +/home/bob/busybox+, and after:

-----------------------
make busybox-rebuild all
-----------------------

the root filesystem image in +output/images+ contains the updated
BusyBox.

Source trees for big projects often contain hundreds or thousands of
files which are not needed for building, but will slow down the process
of copying the sources with _rsync_. Optionally, it is possible define
+<pkg>_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS+ to skip syncing certain files
from the source tree. For example, when working on the +webkitgtk+
package, the following will exclude the tests and in-tree builds from
a local WebKit source tree:

------------------
WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit
WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \
	--exclude JSTests --exclude ManualTests --exclude PerformanceTests \
	--exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \
	--exclude WebKit.xcworkspace --exclude Websites --exclude Examples
------------------

By default, Buildroot skips syncing of VCS artifacts (e.g., the *.git* and
*.svn* directories). Some packages prefer to have these VCS directories
available during build, for example for automatically determining a precise
commit reference for version information. To undo this built-in filtering at a
cost of a slower speed, add these directories back:

------------------
LINUX_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = --include .git
------------------