// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

[[full-rebuild]]
Understanding when a full rebuild is necessary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A full rebuild is achieved by running:

---------------
$ make clean all
---------------

In some cases, a full rebuild is mandatory:

* each time the toolchain properties are changed, this includes:

** after changing any toolchain option under the _Toolchain_ menu (if
   the internal Buildroot backend is used);
** after running +make uclibc-menuconfig+.

* after removing some libraries from the package selection.

In some cases, a full rebuild is recommended:

* after adding some libraries to the package selection (otherwise,
  packages that can be optionally linked against those libraries
  won't be rebuilt, so they won't support those new available
  features).

In other cases, it is up to you to decide if you should run a
full rebuild, but you should know what is impacted and understand what
you are doing anyway.

[[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+, followed by +make+ or +make <package>+. It will
restart the compilation and installation of the package, but not from
scratch: it basically simply 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+, followed
by +make+ or +make <package>+. It will restart the configuration,
compilation and installation of the package.

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[].