buildroot

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