123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121 |
- // -*- 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
- ------------------
|