docs/manual/rebuilding-packages.txt

// -*- 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 <package>-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 <package>-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 <package>-reconfigure+. It will restart the
configuration, compilation and installation of the package.

While +<package>-rebuild+ implies +<package>-reinstall+ and
+<package>-reconfigure+ implies +<package>-rebuild+, these targets as well
as +<package>+ 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/<package>-<version>/+ and are named
+.stamp_<step-name>+. 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[].