// -*- mode:doc -*- ;

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

A full rebuild is achieved by running:

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

In what cases, a full rebuild is mandatory:

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

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

* after removing some libraries from the package selection.

In what cases, a full rebuild is recommended:

* after adding some libraries to the package selection (otherwise,
  some 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 or not 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 currently 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. However, implementing clean package
removal is on the TODO-list of Buildroot developers.

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.

For convenience, most packages support the special make targets
<package>-reconfigure and <package>-rebuild to repeat the configure
and build steps.

However, if you don't want to rebuild the package completely from
scratch, a better understanding of the Buildroot internals is
needed. Internally, to keep track of which steps have been done and
which steps remain to be done, Buildroot maintains stamp files (empty
files that just tell whether this or that action has been done). The
problem is that these stamp files are not uniformly named and handled
by the different packages, so some understanding of the particular
package is needed.

For packages relying on Buildroot packages infrastructures (see
xref:adding-packages[this section] for details), the following stamp
files are relevant:

* +output/build/packagename-version/.stamp_configured+. If removed,
  Buildroot will trigger the recompilation of the package from the
  configuration step (execution of +./configure+).

* +output/build/packagename-version/.stamp_built+. If removed,
  Buildroot will trigger the recompilation of the package from the
  compilation step (execution of +make+).

.Notes
- Since the _Buildroot-2012.11_ release, all packages rely on the
Buildroot infrastructures.
- Only toolchain packages remain using custom makefiles (i.e. do not
use any Buildroot infrastructure).
- Most packages and toolchain packages, if not all, will progressively
be ported over to the generic, autotools or CMake infrastructure,
making it much easier to rebuild individual packages.

Further details about package special make target at the
xref:pkg-build-steps[].