docs/manual/rebuilding-packages.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 [[full-rebuild]]
   5 === Understanding when a full rebuild is necessary
   6
   7 Buildroot does not attempt to detect what parts of the system should
   8 be rebuilt when the system configuration is changed through +make
   9 menuconfig+, +make xconfig+ or one of the other configuration
  10 tools. In some cases, Buildroot should rebuild the entire system, in
  11 some cases, only a specific subset of packages. But detecting this in
  12 a completely reliable manner is very difficult, and therefore the
  13 Buildroot developers have decided to simply not attempt to do this.
  14
  15 Instead, it is the responsibility of the user to know when a full
  16 rebuild is necessary. As a hint, here are a few rules of thumb that
  17 can help you understand how to work with Buildroot:
  18
  19  * When the target architecture configuration is changed, a complete
  20    rebuild is needed. Changing the architecture variant, the binary
  21    format or the floating point strategy for example has an impact on
  22    the entire system.
  23
  24  * When the toolchain configuration is changed, a complete rebuild
  25    generally is needed. Changing the toolchain configuration often
  26    involves changing the compiler version, the type of C library or
  27    its configuration, or some other fundamental configuration item,
  28    and these changes have an impact on the entire system.
  29
  30  * When an additional package is added to the configuration, a full
  31    rebuild is not necessarily needed. Buildroot will detect that this
  32    package has never been built, and will build it. However, if this
  33    package is a library that can optionally be used by packages that
  34    have already been built, Buildroot will not automatically rebuild
  35    those. Either you know which packages should be rebuilt, and you
  36    can rebuild them manually, or you should do a full rebuild. For
  37    example, let's suppose you have built a system with the +ctorrent+
  38    package, but without +openssl+. Your system works, but you realize
  39    you would like to have SSL support in +ctorrent+, so you enable the
  40    +openssl+ package in Buildroot configuration and restart the
  41    build. Buildroot will detect that +openssl+ should be built and
  42    will be build it, but it will not detect that +ctorrent+ should be
  43    rebuilt to benefit from +openssl+ to add OpenSSL support. You will
  44    either have to do a full rebuild, or rebuild +ctorrent+ itself.
  45
  46  * When a package is removed from the configuration, Buildroot does
  47    not do anything special. It does not remove the files installed by
  48    this package from the target root filesystem or from the toolchain
  49    _sysroot_. A full rebuild is needed to get rid of this
  50    package. However, generally you don't necessarily need this package
  51    to be removed right now: you can wait for the next lunch break to
  52    restart the build from scratch.
  53
  54  * When the sub-options of a package are changed, the package is not
  55    automatically rebuilt. After making such changes, rebuilding only
  56    this package is often sufficient, unless enabling the package
  57    sub-option adds some features to the package that are useful for
  58    another package which has already been built. Again, Buildroot does
  59    not track when a package should be rebuilt: once a package has been
  60    built, it is never rebuilt unless explicitly told to do so.
  61
  62  * When a change to the root filesystem skeleton is made, a full
  63    rebuild is needed. However, when changes to the root filesystem
  64    overlay, a post-build script or a post-image script are made,
  65    there is no need for a full rebuild: a simple +make+ invocation
  66    will take the changes into account.
  67
  68 Generally speaking, when you're facing a build error and you're unsure
  69 of the potential consequences of the configuration changes you've
  70 made, do a full rebuild. If you get the same build error, then you are
  71 sure that the error is not related to partial rebuilds of packages,
  72 and if this error occurs with packages from the official Buildroot, do
  73 not hesitate to report the problem! As your experience with Buildroot
  74 progresses, you will progressively learn when a full rebuild is really
  75 necessary, and you will save more and more time.
  76
  77 For reference, a full rebuild is achieved by running:
  78
  79 ---------------
  80 $ make clean all
  81 ---------------
  82
  83 [[rebuild-pkg]]
  84 === Understanding how to rebuild packages
  85
  86 One of the most common questions asked by Buildroot users is how to
  87 rebuild a given package or how to remove a package without rebuilding
  88 everything from scratch.
  89
  90 Removing a package is unsupported by Buildroot without
  91 rebuilding from scratch. This is because Buildroot doesn't keep track
  92 of which package installs what files in the +output/staging+ and
  93 +output/target+ directories, or which package would be compiled differently
  94 depending on the availability of another package.
  95
  96 The easiest way to rebuild a single package from scratch is to remove
  97 its build directory in +output/build+. Buildroot will then re-extract,
  98 re-configure, re-compile and re-install this package from scratch. You
  99 can ask buildroot to do this with the +make <package>-dirclean+ command.
 100
 101 On the other hand, if you only want to restart the build process of a
 102 package from its compilation step, you can run +make
 103 <package>-rebuild+, followed by +make+ or +make <package>+. It will
 104 restart the compilation and installation of the package, but not from
 105 scratch: it basically re-executes +make+ and +make install+
 106 inside the package, so it will only rebuild files that changed.
 107
 108 If you want to restart the build process of a package from its
 109 configuration step, you can run +make <package>-reconfigure+, followed
 110 by +make+ or +make <package>+. It will restart the configuration,
 111 compilation and installation of the package.
 112
 113 Internally, Buildroot creates so-called _stamp files_ to keep track of
 114 which build steps have been completed for each package. They are
 115 stored in the package build directory,
 116 +output/build/<package>-<version>/+ and are named
 117 +.stamp_<step-name>+. The commands detailed above simply manipulate
 118 these stamp files to force Buildroot to restart a specific set of
 119 steps of a package build process.
 120
 121 Further details about package special make targets are explained in
 122 xref:pkg-build-steps[].