1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4==== Using Buildroot during development 5 6The normal operation of Buildroot is to download a tarball, extract 7it, configure, compile and install the software component found inside 8this tarball. The source code is extracted in 9+output/build/<package>-<version>+, which is a temporary directory: 10whenever +make clean+ is used, this directory is entirely removed, and 11re-created at the next +make+ invocation. Even when a Git or 12Subversion repository is used as the input for the package source 13code, Buildroot creates a tarball out of it, and then behaves as it 14normally does with tarballs. 15 16This behavior is well-suited when Buildroot is used mainly as an 17integration tool, to build and integrate all the components of an 18embedded Linux system. However, if one uses Buildroot during the 19development of certain components of the system, this behavior is not 20very convenient: one would instead like to make a small change to the 21source code of one package, and be able to quickly rebuild the system 22with Buildroot. 23 24Making changes directly in +output/build/<package>-<version>+ is not 25an appropriate solution, because this directory is removed on +make 26clean+. 27 28Therefore, Buildroot provides a specific mechanism for this use case: 29the +<pkg>_OVERRIDE_SRCDIR+ mechanism. Buildroot reads an _override_ 30file, which allows the user to tell Buildroot the location of the 31source for certain packages. 32 33The default location of the override file is +$(CONFIG_DIR)/local.mk+, 34as defined by the +BR2_PACKAGE_OVERRIDE_FILE+ configuration option. 35+$(CONFIG_DIR)+ is the location of the Buildroot +.config+ file, so 36+local.mk+ by default lives side-by-side with the +.config+ file, 37which means: 38 39* In the top-level Buildroot source directory for in-tree builds 40 (i.e., when +O=+ is not used) 41* In the out-of-tree directory for out-of-tree builds (i.e., when 42 +O=+ is used) 43 44If a different location than these defaults is required, it can be 45specified through the +BR2_PACKAGE_OVERRIDE_FILE+ configuration 46option. 47 48In this _override_ file, Buildroot expects to find lines of the form: 49 50------------------ 51<pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources 52<pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources 53------------------ 54 55For example: 56 57------------------ 58LINUX_OVERRIDE_SRCDIR = /home/bob/linux/ 59BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/ 60------------------ 61 62When Buildroot finds that for a given package, an 63+<pkg>_OVERRIDE_SRCDIR+ has been defined, it will no longer attempt to 64download, extract and patch the package. Instead, it will directly use 65the source code available in the specified directory and +make clean+ 66will not touch this directory. This allows to point Buildroot to your 67own directories, that can be managed by Git, Subversion, or any other 68version control system. To achieve this, Buildroot will use _rsync_ to 69copy the source code of the component from the specified 70+<pkg>_OVERRIDE_SRCDIR+ to +output/build/<package>-custom/+. 71 72This mechanism is best used in conjunction with the +make 73<pkg>-rebuild+ and +make <pkg>-reconfigure+ targets. A +make 74<pkg>-rebuild all+ sequence will _rsync_ the source code from 75+<pkg>_OVERRIDE_SRCDIR+ to +output/build/<package>-custom+ (thanks to 76_rsync_, only the modified files are copied), and restart the build 77process of just this package. 78 79In the example of the +linux+ package above, the developer can then 80make a source code change in +/home/bob/linux+ and then run: 81 82----------------------- 83make linux-rebuild all 84----------------------- 85 86and in a matter of seconds gets the updated Linux kernel image in 87+output/images+. Similarly, a change can be made to the BusyBox source 88code in +/home/bob/busybox+, and after: 89 90----------------------- 91make busybox-rebuild all 92----------------------- 93 94the root filesystem image in +output/images+ contains the updated 95BusyBox. 96 97Source trees for big projects often contain hundreds or thousands of 98files which are not needed for building, but will slow down the process 99of copying the sources with _rsync_. Optionally, it is possible define 100+<pkg>_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS+ to skip syncing certain files 101from the source tree. For example, when working on the +webkitgtk+ 102package, the following will exclude the tests and in-tree builds from 103a local WebKit source tree: 104 105------------------ 106WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit 107WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \ 108 --exclude JSTests --exclude ManualTests --exclude PerformanceTests \ 109 --exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \ 110 --exclude WebKit.xcworkspace --exclude Websites --exclude Examples 111------------------ 112 113By default, Buildroot skips syncing of VCS artifacts (e.g., the *.git* and 114*.svn* directories). Some packages prefer to have these VCS directories 115available during build, for example for automatically determining a precise 116commit reference for version information. To undo this built-in filtering at a 117cost of a slower speed, add these directories back: 118 119------------------ 120LINUX_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = --include .git 121------------------ 122