Commit 569db405 authored by Thomas De Schampheleire's avatar Thomas De Schampheleire Committed by Thomas Petazzoni
Browse files

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: default avatarThomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: default avatarThomas Petazzoni <thomas.petazzoni@free-electrons.com>
parent 7fa43f91

docs/manual/advanced.txt

+1 −1
Original line number Diff line number Diff line 
// -*- mode:doc; -*-

// vim: set syntax=asciidoc:



== Advanced usage

=== Advanced usage



include::using-buildroot-toolchain.txt[]

docs/manual/appendix.txt

+0 −2
Original line number Diff line number Diff line 
// -*- mode:doc; -*-

// vim: set syntax=asciidoc:



= Appendix



include::makedev-syntax.txt[]

include::makeusers-syntax.txt[]

docs/manual/beyond-buildroot.txt

+4 −4
Original line number Diff line number Diff line 
// -*- mode:doc; -*-

// vim: set syntax=asciidoc:



= Beyond Buildroot

== Beyond Buildroot



== Boot the generated images

=== Boot the generated images



=== NFS boot

==== NFS boot



To achieve NFS-boot, enable _tar root filesystem_ in the _Filesystem

images_ menu.
@@ -21,7 +21,7 @@ Remember to add this path to +/etc/exports+. 


Then, you can execute a NFS-boot from your target.



== Chroot

=== Chroot



If you want to chroot in a generated image, then there are few thing

you should be aware of:

docs/manual/ccache-support.txt

+1 −1
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ 
// vim: set syntax=asciidoc:



[[ccache]]

=== Using +ccache+ in Buildroot

==== Using +ccache+ in Buildroot



http://ccache.samba.org[ccache] is a compiler cache. It stores the

object files resulting from each compilation process, and is able to

docs/manual/contribute.txt

+9 −9
Original line number Diff line number Diff line 
// -*- mode:doc; -*-

// vim: set syntax=asciidoc:



= Contributing to Buildroot

== Contributing to Buildroot



There are many ways in which you can contribute to Buildroot: analyzing

and fixing bugs, analyzing and fixing package build failures detected by
@@ -22,7 +22,7 @@ source code tarball. Git is the easiest way to develop from and directly 
send your patches to the mailing list. Refer to xref:getting-buildroot[]

for more information on obtaining a Buildroot git tree.



== Reproducing, analyzing and fixing bugs

=== Reproducing, analyzing and fixing bugs



A first way of contributing is to have a look at the open bug reports in

the https://bugs.busybox.net/buglist.cgi?product=buildroot[Buildroot bug
@@ -31,7 +31,7 @@ help in reproducing, analyzing and fixing reported bugs is more than 
welcome. Don't hesitate to add a comment to bug reports reporting your

findings, even if you don't yet see the full picture.



== Analyzing and fixing autobuild failures

=== Analyzing and fixing autobuild failures



The Buildroot autobuilders are a set of build machines that continuously

run Buildroot builds based on random configurations. This is done for
@@ -76,7 +76,7 @@ basically two things that can be done: 
Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069

---------------------



== Reviewing and testing patches

=== Reviewing and testing patches



With the amount of patches sent to the mailing list each day, the

maintainer has a very hard job to judge which patches are ready to apply
@@ -142,7 +142,7 @@ Buildroot's Patchwork website can be used to pull in patches for testing 
purposes. Please see xref:apply-patches-patchwork[] for more

information on using Buildroot's Patchwork website to apply patches.



== Work on items from the TODO list

=== Work on items from the TODO list



If you want to contribute to Buildroot but don't know where to start,

and you don't like any of the above topics, you can always work on items
@@ -152,7 +152,7 @@ Do edit the wiki to indicate when you start working on an item, so we 
avoid duplicate efforts.



[[submitting-patches]]

== Submitting patches

=== Submitting patches



[NOTE]

_Please, do not attach patches to bugs, send them to the mailing list
@@ -196,7 +196,7 @@ If you do not use +git send-email+, make sure posted *patches are not 
line-wrapped*, otherwise they cannot easily be applied. In such a case,

fix your e-mail client, or better yet, learn to use +git send-email+.



=== Cover letter

==== Cover letter



If you want to present the whole patch set in a separate mail, add

+--cover-letter+ to the +git format-patch+ command (see +man
@@ -215,7 +215,7 @@ in the following cases: 
* whenever you feel it will help presenting your work, your choices,

  the review process, etc.



=== Patch revision changelog

==== Patch revision changelog



When improvements are requested, the new revision of each commit

should include a changelog of the modifications between each
@@ -276,7 +276,7 @@ $ git format-patch --subject-prefix "PATCH v4" \ 
---------------------



[[reporting-bugs]]

== Reporting issues/bugs or getting help

=== Reporting issues/bugs or getting help



Before reporting any issue, please check

xref:mailing-list-subscribe[the mailing list archive] in case someone has