using-buildroot-development.txt 5.0 KB

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