2014-02-23 16:04:38 +01:00
|
|
|
// -*- mode:doc; -*-
|
|
|
|
|
// vim: set syntax=asciidoc:
|
|
|
|
|
|
manual: high-level restructuring
The structure of the buildroot manual is not always clear. There is a large
number of chapters, and some chapters seem to overlap. The distinction
between general usage and developer information is not always clear.
This patch restructures the manual into four large parts:
- getting started
- user guide
- developer guide
- appendix
Except for the names of these parts, the section names are not yet changed.
Content-wise there are no changes yet either. This will be handled in
subsequent patches.
In order to achieve the introduction of a new level 'parts' above
'chapters', the section indicators (=, ==, ===, ...) of several sections
have to be moved one level down. Additionally, the leveloffset indication to
asciidoc has to be removed. Finally, to maintain more or less the same level
of detail in the table of contents, the toc.section.depth attribute is
reduced as well. Note that for some sections, less detail is visible now.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
2014-08-12 22:20:06 +02:00
|
|
|
==== Using Buildroot during development
|
2014-02-23 16:04:38 +01:00
|
|
|
|
|
|
|
|
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
|
2014-02-24 09:58:04 +01:00
|
|
|
an appropriate solution, because this directory is removed on +make
|
2014-02-23 16:04:38 +01:00
|
|
|
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/+.
|
|
|
|
|
|
2014-05-31 10:26:20 +02:00
|
|
|
This mechanism is best used in conjunction with the +make
|
2014-02-23 16:04:38 +01:00
|
|
|
<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
|
2014-05-31 09:55:35 +02:00
|
|
|
+output/images+. Similarly, a change can be made to the BusyBox source
|
2014-02-23 16:04:38 +01:00
|
|
|
code in +/home/bob/busybox+, and after:
|
|
|
|
|
|
|
|
|
|
-----------------------
|
|
|
|
|
make busybox-rebuild all
|
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
|
|
the root filesystem image in +output/images+ contains the updated
|
2014-05-31 09:55:35 +02:00
|
|
|
BusyBox.
|
