docs/manual/using-buildroot-development.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 ==== Using Buildroot during development
   5
   6 The normal operation of Buildroot is to download a tarball, extract
   7 it, configure, compile and install the software component found inside
   8 this tarball. The source code is extracted in
   9 +output/build/<package>-<version>+, which is a temporary directory:
  10 whenever +make clean+ is used, this directory is entirely removed, and
  11 re-created at the next +make+ invocation. Even when a Git or
  12 Subversion repository is used as the input for the package source
  13 code, Buildroot creates a tarball out of it, and then behaves as it
  14 normally does with tarballs.
  15
  16 This behavior is well-suited when Buildroot is used mainly as an
  17 integration tool, to build and integrate all the components of an
  18 embedded Linux system. However, if one uses Buildroot during the
  19 development of certain components of the system, this behavior is not
  20 very convenient: one would instead like to make a small change to the
  21 source code of one package, and be able to quickly rebuild the system
  22 with Buildroot.
  23
  24 Making changes directly in +output/build/<package>-<version>+ is not
  25 an appropriate solution, because this directory is removed on +make
  26 clean+.
  27
  28 Therefore, Buildroot provides a specific mechanism for this use case:
  29 the +<pkg>_OVERRIDE_SRCDIR+ mechanism. Buildroot reads an _override_
  30 file, which allows the user to tell Buildroot the location of the
  31 source for certain packages. By default this _override_ file is named
  32 +local.mk+ and located in the top directory of the Buildroot source
  33 tree, but a different location can be specified through the
  34 +BR2_PACKAGE_OVERRIDE_FILE+ configuration option.
  35
  36 In this _override_ file, Buildroot expects to find lines of the form:
  37
  38 ------------------
  39 <pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources
  40 <pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources
  41 ------------------
  42
  43 For example:
  44
  45 ------------------
  46 LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
  47 BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/
  48 ------------------
  49
  50 When Buildroot finds that for a given package, an
  51 +<pkg>_OVERRIDE_SRCDIR+ has been defined, it will no longer attempt to
  52 download, extract and patch the package. Instead, it will directly use
  53 the source code available in in the specified directory and +make
  54 clean+ will not touch this directory. This allows to point Buildroot
  55 to your own directories, that can be managed by Git, Subversion, or
  56 any other version control system. To achieve this, Buildroot will use
  57 _rsync_ to copy the source code of the component from the specified
  58 +<pkg>_OVERRIDE_SRCDIR+ to +output/build/<package>-custom/+.
  59
  60 This mechanism is best used in conjunction with the +make
  61 <pkg>-rebuild+ and +make <pkg>-reconfigure+ targets. A +make
  62 <pkg>-rebuild all+ sequence will _rsync_ the source code from
  63 +<pkg>_OVERRIDE_SRCDIR+ to +output/build/<package>-custom+ (thanks to
  64 _rsync_, only the modified files are copied), and restart the build
  65 process of just this package.
  66
  67 In the example of the +linux+ package above, the developer can then
  68 make a source code change in +/home/bob/linux+ and then run:
  69
  70 -----------------------
  71 make linux-rebuild all
  72 -----------------------
  73
  74 and in a matter of seconds gets the updated Linux kernel image in
  75 +output/images+. Similarly, a change can be made to the BusyBox source
  76 code in +/home/bob/busybox+, and after:
  77
  78 -----------------------
  79 make busybox-rebuild all
  80 -----------------------
  81
  82 the root filesystem image in +output/images+ contains the updated
  83 BusyBox.