86a415df8a
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
123 lines
6.0 KiB
Plaintext
123 lines
6.0 KiB
Plaintext
// -*- 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[].
|