// -*- 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.
  
  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+, followed by +make+ or +make <package>+. 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+, 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[].