// -*- mode:doc; -*- // vim: set syntax=asciidoc: [[full-rebuild]] === Understanding when a full rebuild is necessary Buildroot does not attempt to detect what parts of the system should be rebuilt when the system configuration is changed through +make menuconfig+, +make xconfig+ or one of the other configuration tools. In some cases, Buildroot should rebuild the entire system, in some cases, only a specific subset of packages. But detecting this in a completely reliable manner is very difficult, and therefore the Buildroot developers have decided to simply not attempt to do this. Instead, it is the responsibility of the user to know when a full rebuild is necessary. As a hint, here are a few rules of thumb that can help you understand how to work with Buildroot: * When the target architecture configuration is changed, a complete rebuild is needed. Changing the architecture variant, the binary format or the floating point strategy for example has an impact on the entire system. * When the toolchain configuration is changed, a complete rebuild generally is needed. Changing the toolchain configuration often involves changing the compiler version, the type of C library or its configuration, or some other fundamental configuration item, and these changes have an impact on the entire system. * When an additional package is added to the configuration, a full rebuild is not necessarily needed. Buildroot will detect that this package has never been built, and will build it. However, if this package is a library that can optionally be used by packages that have already been built, Buildroot will not automatically rebuild those. Either you know which packages should be rebuilt, and you can rebuild them manually, or you should do a full rebuild. For example, let's suppose you have built a system with the +ctorrent+ package, but without +openssl+. Your system works, but you realize you would like to have SSL support in +ctorrent+, so you enable the +openssl+ package in Buildroot configuration and restart the build. Buildroot will detect that +openssl+ should be built and will be build it, but it will not detect that +ctorrent+ should be rebuilt to benefit from +openssl+ to add OpenSSL support. You will either have to do a full rebuild, or rebuild +ctorrent+ itself. * When a package is removed from the configuration, Buildroot does not do anything special. It does not remove the files installed by this package from the target root filesystem or from the toolchain _sysroot_. A full rebuild is needed to get rid of this package. However, generally you don't necessarily need this package to be removed right now: you can wait for the next lunch break to restart the build from scratch. * When the sub-options of a package are changed, the package is not automatically rebuilt. After making such changes, rebuilding only this package is often sufficient, unless enabling the package sub-option adds some features to the package that are useful for another package which has already been built. Again, Buildroot does not track when a package should be rebuilt: once a package has been built, it is never rebuilt unless explicitly told to do so. * When a change to the root filesystem skeleton is made, a full rebuild is needed. However, when changes to the root filesystem overlay, a post-build script or a post-image script are made, there is no need for a full rebuild: a simple +make+ invocation will take the changes into account. * When a package listed in +FOO_DEPENDENCIES+ is rebuilt or removed, the package +foo+ is not automatically rebuilt. For example, if a package +bar+ is listed in +FOO_DEPENDENCIES+ with +FOO_DEPENDENCIES = bar+ and the configuration of the +bar+ package is changed, the configuration change would not result in a rebuild of package +foo+ automatically. In this scenario, you may need to either rebuild any packages in your build which reference +bar+ in their +DEPENDENCIES+, or perform a full rebuild to ensure any +bar+ dependent packages are up to date. Generally speaking, when you're facing a build error and you're unsure of the potential consequences of the configuration changes you've made, do a full rebuild. If you get the same build error, then you are sure that the error is not related to partial rebuilds of packages, and if this error occurs with packages from the official Buildroot, do not hesitate to report the problem! As your experience with Buildroot progresses, you will progressively learn when a full rebuild is really necessary, and you will save more and more time. For reference, a full rebuild is achieved by running: --------------- $ make clean all --------------- [[rebuild-pkg]] === Understanding how to rebuild packages One of the most common questions asked by Buildroot users is how to rebuild a given package or how to remove a package without rebuilding everything from scratch. Removing a package is unsupported by Buildroot without rebuilding from scratch. This is because Buildroot doesn't keep track of which package installs what files in the +output/staging+ and +output/target+ directories, or which package would be compiled differently depending on the availability of another package. The easiest way to rebuild a single package from scratch is to remove its build directory in +output/build+. Buildroot will then re-extract, re-configure, re-compile and re-install this package from scratch. You can ask buildroot to do this with the +make -dirclean+ command. On the other hand, if you only want to restart the build process of a package from its compilation step, you can run +make -rebuild+. It will restart the compilation and installation of the package, but not from scratch: it basically re-executes +make+ and +make install+ inside the package, so it will only rebuild files that changed. If you want to restart the build process of a package from its configuration step, you can run +make -reconfigure+. It will restart the configuration, compilation and installation of the package. While +-rebuild+ implies +-reinstall+ and +-reconfigure+ implies +-rebuild+, these targets as well as ++ only act on the said package, and do not trigger re-creating the root filesystem image. If re-creating the root filesystem in necessary, one should in addition run +make+ or +make all+. Internally, Buildroot creates so-called _stamp files_ to keep track of which build steps have been completed for each package. They are stored in the package build directory, +output/build/-/+ and are named +.stamp_+. The commands detailed above simply manipulate these stamp files to force Buildroot to restart a specific set of steps of a package build process. Further details about package special make targets are explained in xref:pkg-build-steps[].