1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
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[].
|
