X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fbuild%2Fdocs%2Fmanual%2Frebuilding-packages.txt;fp=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fbuild%2Fdocs%2Fmanual%2Frebuilding-packages.txt;h=6faa67adcb5171bd53c25dd049b87667683fa8bd;hb=b0a0f15dfaa205161a7fcb20cf1b8cd4948c2ef3;hp=0000000000000000000000000000000000000000;hpb=c6ac3cd55ee2da956195eee393b0882105dfad4e;p=packages%2Ftrusty%2Fcirros-testvm.git diff --git a/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/rebuilding-packages.txt b/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/rebuilding-packages.txt new file mode 100644 index 0000000..6faa67a --- /dev/null +++ b/cirros-testvm/src-cirros/buildroot-2015.05/build/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 -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 +-rebuild+, followed by +make+ or +make +. 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 -reconfigure+, followed +by +make+ or +make +. 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/-/+ and are named ++.stamp_+. 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[].