rebuilding-packages.txt 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. [[full-rebuild]]
  4. === Understanding when a full rebuild is necessary
  5. Buildroot does not attempt to detect what parts of the system should
  6. be rebuilt when the system configuration is changed through +make
  7. menuconfig+, +make xconfig+ or one of the other configuration
  8. tools. In some cases, Buildroot should rebuild the entire system, in
  9. some cases, only a specific subset of packages. But detecting this in
  10. a completely reliable manner is very difficult, and therefore the
  11. Buildroot developers have decided to simply not attempt to do this.
  12. Instead, it is the responsibility of the user to know when a full
  13. rebuild is necessary. As a hint, here are a few rules of thumb that
  14. can help you understand how to work with Buildroot:
  15. * When the target architecture configuration is changed, a complete
  16. rebuild is needed. Changing the architecture variant, the binary
  17. format or the floating point strategy for example has an impact on
  18. the entire system.
  19. * When the toolchain configuration is changed, a complete rebuild
  20. generally is needed. Changing the toolchain configuration often
  21. involves changing the compiler version, the type of C library or
  22. its configuration, or some other fundamental configuration item,
  23. and these changes have an impact on the entire system.
  24. * When an additional package is added to the configuration, a full
  25. rebuild is not necessarily needed. Buildroot will detect that this
  26. package has never been built, and will build it. However, if this
  27. package is a library that can optionally be used by packages that
  28. have already been built, Buildroot will not automatically rebuild
  29. those. Either you know which packages should be rebuilt, and you
  30. can rebuild them manually, or you should do a full rebuild. For
  31. example, let's suppose you have built a system with the +ctorrent+
  32. package, but without +openssl+. Your system works, but you realize
  33. you would like to have SSL support in +ctorrent+, so you enable the
  34. +openssl+ package in Buildroot configuration and restart the
  35. build. Buildroot will detect that +openssl+ should be built and
  36. will be build it, but it will not detect that +ctorrent+ should be
  37. rebuilt to benefit from +openssl+ to add OpenSSL support. You will
  38. either have to do a full rebuild, or rebuild +ctorrent+ itself.
  39. * When a package is removed from the configuration, Buildroot does
  40. not do anything special. It does not remove the files installed by
  41. this package from the target root filesystem or from the toolchain
  42. _sysroot_. A full rebuild is needed to get rid of this
  43. package. However, generally you don't necessarily need this package
  44. to be removed right now: you can wait for the next lunch break to
  45. restart the build from scratch.
  46. * When the sub-options of a package are changed, the package is not
  47. automatically rebuilt. After making such changes, rebuilding only
  48. this package is often sufficient, unless enabling the package
  49. sub-option adds some features to the package that are useful for
  50. another package which has already been built. Again, Buildroot does
  51. not track when a package should be rebuilt: once a package has been
  52. built, it is never rebuilt unless explicitly told to do so.
  53. * When a change to the root filesystem skeleton is made, a full
  54. rebuild is needed. However, when changes to the root filesystem
  55. overlay, a post-build script or a post-image script are made,
  56. there is no need for a full rebuild: a simple +make+ invocation
  57. will take the changes into account.
  58. * When a package listed in +FOO_DEPENDENCIES+ is rebuilt or removed,
  59. the package +foo+ is not automatically rebuilt. For example, if a
  60. package +bar+ is listed in +FOO_DEPENDENCIES+ with +FOO_DEPENDENCIES
  61. = bar+ and the configuration of the +bar+ package is changed, the
  62. configuration change would not result in a rebuild of package +foo+
  63. automatically. In this scenario, you may need to either rebuild any
  64. packages in your build which reference +bar+ in their +DEPENDENCIES+,
  65. or perform a full rebuild to ensure any +bar+ dependent packages are
  66. up to date.
  67. Generally speaking, when you're facing a build error and you're unsure
  68. of the potential consequences of the configuration changes you've
  69. made, do a full rebuild. If you get the same build error, then you are
  70. sure that the error is not related to partial rebuilds of packages,
  71. and if this error occurs with packages from the official Buildroot, do
  72. not hesitate to report the problem! As your experience with Buildroot
  73. progresses, you will progressively learn when a full rebuild is really
  74. necessary, and you will save more and more time.
  75. For reference, a full rebuild is achieved by running:
  76. ---------------
  77. $ make clean all
  78. ---------------
  79. [[rebuild-pkg]]
  80. === Understanding how to rebuild packages
  81. One of the most common questions asked by Buildroot users is how to
  82. rebuild a given package or how to remove a package without rebuilding
  83. everything from scratch.
  84. Removing a package is unsupported by Buildroot without
  85. rebuilding from scratch. This is because Buildroot doesn't keep track
  86. of which package installs what files in the +output/staging+ and
  87. +output/target+ directories, or which package would be compiled differently
  88. depending on the availability of another package.
  89. The easiest way to rebuild a single package from scratch is to remove
  90. its build directory in +output/build+. Buildroot will then re-extract,
  91. re-configure, re-compile and re-install this package from scratch. You
  92. can ask buildroot to do this with the +make <package>-dirclean+ command.
  93. On the other hand, if you only want to restart the build process of a
  94. package from its compilation step, you can run +make <package>-rebuild+. It
  95. will restart the compilation and installation of the package, but not from
  96. scratch: it basically re-executes +make+ and +make install+ inside the package,
  97. so it will only rebuild files that changed.
  98. If you want to restart the build process of a package from its configuration
  99. step, you can run +make <package>-reconfigure+. It will restart the
  100. configuration, compilation and installation of the package.
  101. While +<package>-rebuild+ implies +<package>-reinstall+ and
  102. +<package>-reconfigure+ implies +<package>-rebuild+, these targets as well
  103. as +<package>+ only act on the said package, and do not trigger re-creating
  104. the root filesystem image. If re-creating the root filesystem in necessary,
  105. one should in addition run +make+ or +make all+.
  106. Internally, Buildroot creates so-called _stamp files_ to keep track of
  107. which build steps have been completed for each package. They are
  108. stored in the package build directory,
  109. +output/build/<package>-<version>/+ and are named
  110. +.stamp_<step-name>+. The commands detailed above simply manipulate
  111. these stamp files to force Buildroot to restart a specific set of
  112. steps of a package build process.
  113. Further details about package special make targets are explained in
  114. xref:pkg-build-steps[].