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