137 lines
6.9 KiB
Plaintext
137 lines
6.9 KiB
Plaintext
// -*- 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[].
|