123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136 |
- // -*- 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[].
|