// -*- 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. By default this _override_ file is named
+local.mk+ and located in the top directory of the Buildroot source
tree, but a different location 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 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.