Merge from bittboy/buildroot@db180c0

docs/manual/rebuilding-packages.txt

@@ -0,0 +1,122 @@
+// -*- 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[].