kumquat-buildroot/docs/manual/using-buildroot-development.txt

84 lines
3.4 KiB
Plaintext
Raw Normal View History

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
manual: use one-line titles instead of two-line titles (trivial) 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>
2014-05-02 07:47:30 +02:00
=== Using Buildroot during development
The normal operation of Buildroot is to download a tarball, extract
it, configure, compile and install the software component found inside
this tarball. The source code is extracted in
+output/build/<package>-<version>+, which is a temporary directory:
whenever +make clean+ is used, this directory is entirely removed, and
re-recreated at the next +make+ invocation. Even when a Git or
Subversion repository is used as the input for the package source
code, Buildroot creates a tarball out of it, and then behaves as it
normally does with tarballs.
This behavior is well-suited when Buildroot is used mainly as an
integration tool, to build and integrate all the components of an
embedded Linux system. However, if one uses Buildroot during the
development of certain components of the system, this behavior is not
very convenient: one would instead like to make a small change to the
source code of one package, and be able to quickly rebuild the system
with Buildroot.
Making changes directly in +output/build/<package>-<version>+ is not
an appropriate solution, because this directory is removed on +make
clean+.
Therefore, Buildroot provides a specific mechanism for this use case:
the +<pkg>_OVERRIDE_SRCDIR+ mechanism. Buildroot reads an _override_
file, which allows the user to tell Buildroot the location of the
source for certain packages. By default this _override_ file is named
+local.mk+ and located in the top directory of the Buildroot source
tree, but a different location can be specified through the
+BR2_PACKAGE_OVERRIDE_FILE+ configuration option.
In this _override_ file, Buildroot expects to find lines of the form:
------------------
<pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources
<pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources
------------------
For example:
------------------
LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/
------------------
When Buildroot finds that for a given package, an
+<pkg>_OVERRIDE_SRCDIR+ has been defined, it will no longer attempt to
download, extract and patch the package. Instead, it will directly use
the source code available in in the specified directory and +make
clean+ will not touch this directory. This allows to point Buildroot
to your own directories, that can be managed by Git, Subversion, or
any other version control system. To achieve this, Buildroot will use
_rsync_ to copy the source code of the component from the specified
+<pkg>_OVERRIDE_SRCDIR+ to +output/build/<package>-custom/+.
This mechanism is best used in conjunction with the +make
<pkg>-rebuild+ and +make <pkg>-reconfigure+ targets. A +make
<pkg>-rebuild all+ sequence will _rsync_ the source code from
+<pkg>_OVERRIDE_SRCDIR+ to +output/build/<package>-custom+ (thanks to
_rsync_, only the modified files are copied), and restart the build
process of just this package.
In the example of the +linux+ package above, the developer can then
make a source code change in +/home/bob/linux+ and then run:
-----------------------
make linux-rebuild all
-----------------------
and in a matter of seconds gets the updated Linux kernel image in
+output/images+. Similarly, a change can be made to the BusyBox source
code in +/home/bob/busybox+, and after:
-----------------------
make busybox-rebuild all
-----------------------
the root filesystem image in +output/images+ contains the updated
BusyBox.