Pull request for branch sma/doc-update

* minor refactoring in gen-manual-list.py
* generate manual in the build tree

support/scripts/gen-manual-lists.py +2 -2

index 3568843..5c81e1d 100755
@@ -107,7 +107,7 @@ def get_symbol_parents(item, root=None, enable_choice=False):
         parent = parent.get_parent()
     if isinstance(root, kconfiglib.Menu) or \
             (enable_choice and isinstance(root, kconfiglib.Choice)):
-        parents.append("") # Dummy empty parrent to get a leading arrow ->
+        parents.append("") # Dummy empty parent to get a leading arrow ->
     parents.reverse()
     return parents
 

@@ -126,15 +126,14 @@ def format_asciidoc_table(root, get_label_func, filter_func=lambda x: True,
     :param sub_menu:       Output the column with the sub-menu path
 
     """
-    def _format_entry(label, parents, sub_menu):
+    def _format_entry(item, parents, sub_menu):
         """ Format an asciidoc table entry.
 
         """

Dear Samuel Martin,

Quoted 2 lines · Samuel Martin

* minor refactoring in gen-manual-list.py
* generate manual in the build tree

Why? This is breaking the "release:" target of the main Makefile, which assumes that the manual is generated in $(O)/docs/manual.

Review

Quoted 1 line

(quoted diff) +0 -0

b/support/scripts/gen-manual-lists.py

support/scripts/gen-manual-lists.py def get_symbol_parents(item, root=None,

Quoted 4 lines

index 3568843..5c81e1d 100755

support/scripts/gen-manual-lists.py +0 -0

@@ -107,7 +107,7 @@ def get_symbol_parents(item, root=None,

enable_choice=False):

support/scripts/gen-manual-lists.py def get_symbol_parents(item, root=None, enable_choice=False):

Quoted 4 lines

support/scripts/gen-manual-lists.py +0 -1

         parent = parent.get_parent()
     if isinstance(root, kconfiglib.Menu) or \
             (enable_choice and isinstance(root, kconfiglib.Choice)):
-        parents.append("") # Dummy empty parrent to get a leading arrow

->

support/scripts/gen-manual-lists.py def get_symbol_parents(item, root=None, · line 110

Quoted 1 line

support/scripts/gen-manual-lists.py +1 -0

+        parents.append("") # Dummy empty parent to get a leading arrow

->

support/scripts/gen-manual-lists.py def format_asciidoc_table(root, get_label_func,

Quoted 4 lines

support/scripts/gen-manual-lists.py +0 -0

     parents.reverse()
     return parents
 

@@ -126,15 +126,14 @@ def format_asciidoc_table(root, get_label_func,

filter_func=lambda x: True,

support/scripts/gen-manual-lists.py def format_asciidoc_table(root, get_label_func, filter_func=lambda x: True,

Quoted 10 lines

support/scripts/gen-manual-lists.py +1 -2

     :param sub_menu:       Output the column with the sub-menu path
 
     """
-    def _format_entry(label, parents, sub_menu):
+    def _format_entry(item, parents, sub_menu):
         """ Format an asciidoc table entry.
 
         """
         if sub_menu:
-            return "| {0:<40} <| {1}\n".format(label, " ->

".join(parents))

support/scripts/gen-manual-lists.py def format_asciidoc_table(root, get_label_func, · line 134

Quoted 1 line

support/scripts/gen-manual-lists.py +1 -0

+            return "| {0:<40} <| {1}\n".format(item, " ->

".join(parents))

support/scripts/gen-manual-lists.py def format_asciidoc_table(root, get_label_func, filter_func=lambda x: True, · line 139

Quoted 7 lines

support/scripts/gen-manual-lists.py +1 -2

         else:
-            return "| {0:<40}\n".format(label)
-
+            return "| {0:<40}\n".format(item)
     lines = []
     for item in get_symbol_subset(root, filter_func):
         if not item.is_symbol() or not item.prompts:

Also, why are those changes mixed with the change of building the manual in $(O)/build ? They seem to be completely unrelated.

Sorry to be a bit harsh, but you're a regular contributor,

so I'd

for each feature or fix, with a more descriptive commit log. We've already suggested you to write more detailed commit logs in the past, I believe.

Signed-off-by Samuel Martin <[email protected]>

---
 docs/manual/developer-guide.txt | 2 --
 1 file changed, 2 deletions(-)

Signed-off-by Samuel Martin <[email protected]>

---
 docs/manual/developer-guide.txt | 2 --
 1 file changed, 2 deletions(-)

docs/manual/developer-guide.txt +0 -0

index 43272f5..8125ad5 100644

Signed-off-by Samuel Martin <[email protected]>

---
 docs/manual/prerequisite.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

Signed-off-by Samuel Martin <[email protected]>

---
 docs/manual/prerequisite.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

docs/manual/prerequisite.txt +4 -2

index 78ce436..74b6a6c 100644
@@ -76,4 +76,7 @@ development context (further details: refer to xref:download-infra[]).
 ** The +jar+ tool
 
 * Documentation generation tools:
-** +asciidoc+
+** +asciidoc+ version 8.6.3 or later
+** +dblatex+
+** +w3m+
+** +python+ with +argparse+ module
--

1.8.4

docs/manual/prerequisite.txt development context (further details: refer to

Quoted 10 lines · Samuel Martin

Signed-off-by Samuel Martin <[email protected]>

---
 docs/manual/prerequisite.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

docs/manual/prerequisite.txt +0 -0

index 78ce436..74b6a6c 100644
@@ -76,4 +76,7 @@ development context (further details: refer to

xref:download-infra[]).

Quoted 2 lines

docs/manual/prerequisite.txt +0 -0

 ** The +jar+ tool
 

Quoted 8 lines

docs/manual/prerequisite.txt +4 -2

 * Documentation generation tools:
-** +asciidoc+
+** +asciidoc+ version 8.6.3 or later
+** +dblatex+
+** +w3m+
+** +python+ with +argparse+ module
--

1.8.4

This change is already part of my patch:
http://patchwork.ozlabs.org/patch/276855/
The patch is not yet committed though, but is in the to-be-applied overview ThomasP sent today...

docs/manual/customize-toolchain.txt +41 -0

+It is possible to only build the toolchain by running:
+
+---------------------------------------
+make toolchain
+---------------------------------------
+
+To avoid to rebuild the toolchain (when using the 'internal Buildroot toolchain
+backend') after executing +make clean+, you can build the toolchain in some
+place, then use this prebuilt toolchain as an 'external toolchain' in another
+buildroot configuration.
+
+1. Configure the toolchain using the 'internal Buildroot toolchain backend'
+  to meet your needs:
++
+---------------------------------------
+make O=/path/to/somewhere menuconfig
+---------------------------------------
++
+1. Build the toolchain:
++
+---------------------------------------
+make O=/path/to/somewhere toolchain
+---------------------------------------
++
+1. Configure target configuration using the prebuilt toolchain as an
+   'external toolchain':
++
+---------------------------------------
+make O=/path/to/somewhere_else menuconfig
+---------------------------------------
++
+In the 'Toolchain' menu, set:
++
+* 'Toolchain type': +External toolchain+ (+BR2_TOOLCHAIN_EXTERNAL+)
+* 'Toolchain': +Custom toolchain+ (+BR2_TOOLCHAIN_EXTERNAL_CUSTOM+)
+* 'Toolchain origin': +Pre-installed toolchain+
+  (+BR2_TOOLCHAIN_EXTERNAL_PREINSTALLED+)
+* 'Toolchain path': +/path/to/somewhere/host/usr+
+  (+BR2_TOOLCHAIN_EXTERNAL_PATH+)
+* and set the external toolchain properties accordingly to the ones set for
+  the prebuilt toolchain.

Dear Samuel Martin,

This commit is again mixing a number of different things: removing details about Crosstool-NG, improving details about the Buildroot backend, and adding informations on re-using a Buildroot built toolchain as an external toolchain.

We'll need to synchronize on the Crosstool-NG bits,

because I have a
patch series that removes the Crosstool-NG backend entirely, and which includes the corresponding update to the manual.

docs/manual/customize-toolchain.txt set the environment variable BR_DEBUG_WRAPPER to either one of:

Quoted 8 lines

docs/manual/customize-toolchain.txt +7 -0

+It is possible to only build the toolchain by running:
+
+---------------------------------------
+make toolchain
+---------------------------------------
+
+To avoid to rebuild the toolchain (when using the 'internal Buildroot

toolchain

Quoted 1 line

+backend') after executing +make clean+, you can build the toolchain in

some

Quoted 1 line

+place, then use this prebuilt toolchain as an 'external toolchain' in

another

docs/manual/customize-toolchain.txt set the environment variable BR_DEBUG_WRAPPER to either one of:

Quoted 3 lines

docs/manual/customize-toolchain.txt +3 -0

+buildroot configuration.
+
+1. Configure the toolchain using the 'internal Buildroot toolchain

backend'

Quoted 18 lines

docs/manual/customize-toolchain.txt +18 -0

+  to meet your needs:
++
+---------------------------------------
+make O=/path/to/somewhere menuconfig
+---------------------------------------
++
+1. Build the toolchain:
++
+---------------------------------------
+make O=/path/to/somewhere toolchain
+---------------------------------------
++
+1. Configure target configuration using the prebuilt toolchain as an
+   'external toolchain':
++
+---------------------------------------
+make O=/path/to/somewhere_else menuconfig
+---------------------------------------

docs/manual/customize-toolchain.txt set the environment variable BR_DEBUG_WRAPPER to either one of:

Quoted 10 lines

docs/manual/customize-toolchain.txt +10 -0

++
+In the 'Toolchain' menu, set:
++
+* 'Toolchain type': +External toolchain+ (+BR2_TOOLCHAIN_EXTERNAL+)
+* 'Toolchain': +Custom toolchain+ (+BR2_TOOLCHAIN_EXTERNAL_CUSTOM+)
+* 'Toolchain origin': +Pre-installed toolchain+
+  (+BR2_TOOLCHAIN_EXTERNAL_PREINSTALLED+)
+* 'Toolchain path': +/path/to/somewhere/host/usr+
+  (+BR2_TOOLCHAIN_EXTERNAL_PATH+)
+* and set the external toolchain properties accordingly to the ones set

for

docs/manual/customize-toolchain.txt set the environment variable BR_DEBUG_WRAPPER to either one of:

Quoted 9 lines

docs/manual/customize-toolchain.txt +9 -0

+  the prebuilt toolchain.
++
+1. Build the target binaries:
++
+---------------------------------------
+make O=/path/to/somewhere_else
+---------------------------------------
+
+Note that toolchains built using the 'internal Buildroot toolchain

backend' are

Quoted 1 line

+*not* relocable, so if you plan to share it with other machines, you

will

Quoted 1 line

+*have to* install it in the same location (i.e.: in

+/path/to/somewhere+).

I am not sure this part should be in the "Customize toolchain" part. I'm actually not sure where to put this information in the manual.

Signed-off-by A.R.D. <[email protected]>

Signed-off-by Samuel Martin <[email protected]>

---
Changes v2 -> v3:
- rephrase how to use buildroot toochain as an external one

Changes v1 -> v2:
- rephrase commit message
- wrap line at 70-80 chars
- misc. typo and formating fixes
- misc. rewordings

Signed-off-by Samuel Martin <[email protected]>

---
 docs/manual/customize-toolchain.txt | 72 +++++++++++++++++++++++++++++--------
 1 file changed, 57 insertions(+), 15 deletions(-)

docs/manual/customize-toolchain.txt +0 -0

index 82ecc28..324afd2 100644

docs/manual/customize-toolchain.txt +3 -13

-However, it allows to tune major settings, such as:
+It allows to tune major settings, such as:
 
 * Linux headers version;
 
-* http://www.uclibc.org/[uClibc] configuration (see xref:uclibc-custom[uClibc]);
+* C library configuration (only available for
+  http://www.uclibc.org/[uClibc], see xref:uclibc-custom[uClibc]);
 
 * Binutils, GCC, Gdb and toolchain options.
 
 These settings are available after selecting the +Buildroot toolchain+ type in
 the menu +Toolchain+.
 
-Using the Crosstool-NG backend
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The http://crosstool-ng.org[crosstool-NG] toolchain backend enables a rather
-limited set of settings under the Buildroot +Toolchain+ menu:
-
-* The http://crosstool-ng.org[crosstool-NG] configuration file
-
-* Gdb and some toolchain options
-
-Then, the toolchain can be fine-tuned by invoking +make ctng-menuconfig+.

docs/manual/customize-toolchain.txt +19 -0

+  to meet your needs:
++
+---------------------------------------
+make O=/path/to/somewhere menuconfig
+---------------------------------------
++
+1. Build the toolchain:
++
+---------------------------------------
+make O=/path/to/somewhere toolchain
+---------------------------------------
++
+1. Configure target configuration using the prebuilt toolchain as an
+   'external toolchain':
++
+---------------------------------------
+make O=/path/to/somewhere_else menuconfig
+---------------------------------------
++

* add a "What is Buildroot and what it is not" section
* add a "Buildroot's principles" section

Signed-off-by Samuel Martin <[email protected]>

---
 docs/manual/introduction.txt | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

docs/manual/introduction.txt +0 -0

index c014565..0838c48 100644

Signed-off-by Samuel Martin <[email protected]>

---
 docs/manual/get-involved.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

docs/manual/get-involved.txt +6 -0

index 8515d34..49ab54c 100644
@@ -84,6 +84,12 @@ Currently, this page is mainly used as a _todo-list_.
 Events
 ------
 
+Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Announcement & agenda thread: http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]
+* Report: http://lists.busybox.net/pipermail/buildroot/2012-February/050371.html[]
+
 Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 - Barcelona)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

Hi Samuel,

Quoted 23 lines · Samuel Martin

Signed-off-by Samuel Martin <[email protected]>

---
  docs/manual/get-involved.txt | 10 ++++++----
  1 file changed, 6 insertions(+), 4 deletions(-)

docs/manual/get-involved.txt +6 -0

index 8515d34..49ab54c 100644
@@ -84,6 +84,12 @@ Currently, this page is mainly used as a _todo-list_.
  Events
  ------
 
+Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Announcement & agenda thread: http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]
+* Report: http://lists.busybox.net/pipermail/buildroot/2012-February/050371.html[]
+
  Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 - Barcelona)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/manual/get-involved.txt Buildroot presentation at LSM 2012 (July 12-14, 2012 - Geneva)

Quoted 9 lines

docs/manual/get-involved.txt +0 -5

@@ -94,8 +100,4 @@ Buildroot presentation at LSM 2012 (July 12-14, 2012 - Geneva)
 
  * Announcement: http://lists.busybox.net/pipermail/buildroot/2012-May/053845.html[]
 
-Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Announcement & agenda thread: http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]
-* Report: http://lists.busybox.net/pipermail/buildroot/2012-February/050371.html[]
--

What is the meaning of 'aside' here ?
For me, aside means 'next to' in a spatial context.
In this case, I think we are rather talking about time, in the sense that BDD are before or after the mentioned conference. I'm not sure if there exists a word like aside/adjacent that can be used in a time context, but otherwise we could use:

... prior to ...
... after ...

Quoted 3 lines

Hi Samuel,

On Sat, Oct 5, 2013 at 9:49 PM, Samuel Martin <[email protected]>

Quoted 6 lines

Review

Quoted 6 lines

Signed-off-by Samuel Martin <[email protected]>

---
  docs/manual/get-involved.txt | 10 ++++++----
  1 file changed, 6 insertions(+), 4 deletions(-)

(quoted diff) +0 -0

Quoted 4 lines

docs/manual/get-involved.txt Currently, this page is mainly used as a

Quoted 4 lines

index 8515d34..49ab54c 100644

docs/manual/get-involved.txt +0 -0

@@ -84,6 +84,12 @@ Currently, this page is mainly used as a 

Quoted 4 lines

docs/manual/get-involved.txt Currently, this page is mainly used as a · line 87

Quoted 4 lines

docs/manual/get-involved.txt +1 -0

  Events
  ------
 
+Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - 

Quoted 1 line

Quoted 1 line

Quoted 2 lines

docs/manual/get-involved.txt

Quoted 2 lines

docs/manual/get-involved.txt +2 -0

+
+* Announcement & agenda thread: http://lists.busybox.net/

pipermail/buildroot/2012-January/049340.html[]

Quoted 1 line

Quoted 1 line

+* Report: http://lists.busybox.net/pipermail/buildroot/2012-

February/050371.html[]

Quoted 2 lines

Quoted 2 lines

+
Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 -

Quoted 1 line

Quoted 1 line

Quoted 2 lines

docs/manual/get-involved.txt Buildroot presentation at LSM 2012 (July 12-14,

Quoted 2 lines

docs/manual/get-involved.txt +0 -0

@@ -94,8 +100,4 @@ Buildroot presentation at LSM 2012 (July 12-14, 

2012 - Geneva)

Quoted 2 lines

docs/manual/get-involved.txt Buildroot presentation at LSM 2012 (July 12-14, · line 100

Quoted 2 lines

docs/manual/get-involved.txt +0 -0

  * Announcement: http://lists.busybox.net/pipermail/buildroot/

2012-May/053845.html[]

Quoted 2 lines

Quoted 2 lines

docs/manual/get-involved.txt +0 -1

-Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - 

Quoted 1 line

Quoted 1 line

Quoted 2 lines

Quoted 2 lines

-* Announcement & agenda thread: http://lists.busybox.net/

pipermail/buildroot/2012-January/049340.html[]

Quoted 1 line

Quoted 1 line

-* Report: http://lists.busybox.net/pipermail/buildroot/2012-

February/050371.html[]

Quoted 9 lines

Quoted 1 line

--

What is the meaning of 'aside' here ?
For me, aside means 'next to' in a spatial context.
In this case, I think we are rather talking about time, in the sense that BDD are before or after the mentioned conference. I'm not sure if there exists a word like aside/adjacent that can be used in a time context, but otherwise we could use:

Quoted 2 lines

... prior to ...
... after ...

I think "alongside" is correct. Any native English speaker who can

Regards,
Arnout

* add events from the html page to the list
* add "Buildroot material" section. This new section references material (video, slides, posters, etc) used during presentations about Buildroot.

Signed-off-by Samuel Martin <[email protected]>

---
Let me know if I miss some events, or if you have some unreferenced material urls or url fixes.

TIA,

Signed-off-by Samuel Martin <[email protected]>

---
 docs/manual/get-involved.txt | 145 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 135 insertions(+), 10 deletions(-)

docs/manual/get-involved.txt +0 -0

index 49ab54c..27603a9 100644

docs/manual/get-involved.txt +6 -0

++
+Announcement and draft agenda of the event can also be found on:
++
+** http://lists.busybox.net/pipermail/buildroot/2013-May/072645.html[]
+** http://lists.busybox.net/pipermail/buildroot/2013-August/076560.html[]
+** http://elinux.org/Buildroot:DeveloperDaysELCE2013[]

docs/manual/get-involved.txt +12 -0

+Summer of Code 2013, by mentoring one student.
++
+This GSoC will mainly deal with improving support for ARM SoC multimedia features.
++
+** GSoC topic ideas: http://elinux.org/Buildroot:GSoC2013Ideas[]
+** GSoC project presentation: http://www.google-melange.com/gsoc/org/google/gsoc2013/buildroot[]
+
+* Buildroot technical showcase at ELC 2013 (February 20-21, 2013 - San Francisco, US)
++
+** Poster: http://free-electrons.com/~thomas/pub/buildroot-poster.png[]
+** Slides: http://free-electrons.com/~thomas/pub/buildroot-slides.pdf[]
+

docs/manual/get-involved.txt +8 -0

+http://elinux.org/Buildroot:DeveloperDaysFOSDEM2013[related Wiki page].
++
+Once again, thanks to all the participants and to http://www.google.com[Google]
+for sponsoring the event.
+
+* Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 - Barcelona, Spain)
++
+A report from the recent _Buildroot Developer Days_ meeting in Barcelona,

docs/manual/get-involved.txt +45 -0

++
+** http://elinux.org/Buildroot:DeveloperDaysELCE2012[]
+** http://elinux.org/Buildroot#Buildroot_Developers_Meeting.2C_3-4_November_2012.2C_Barcelona_Spain[]
+
+* Buildroot presentation at LSM 2012 (July 12-14, 2012 - Geneva, Switzerland)
++
+** Announcement: http://lists.busybox.net/pipermail/buildroot/2012-May/053845.html[]
+
+* Buildroot presentation at ELC 2012 (February 15-17, 2012 - San Francisco, US)
++
+** Slides: http://elinux.org/images/9/9e/Buildroot2.pdf[]
+** Video: http://video.linux.com/videos/buildroot-a-nice-simple-and-efficient-embedded-linux-build-system[]
+
+* Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels, Belgium)
++
+** Announcement:
+*** http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]
+*** http://free-electrons.com/blog/bdd-2012-brussels[]
+** Report: http://lists.busybox.net/pipermail/buildroot/2012-February/050371.html[]
+
+* Buildroot presentation at ELC-E 2011 (October 26-28, 2011- Prague, Czech)
++
+** Slides: http://elinux.org/images/2/2a/Using-buildroot-real-project.pdf[]
+** Video:
+http://free-electrons.com/pub/video/2011/elce/elce-2011-petazzoni-buildroot-for-real-project.webm[full HD],
+ http://free-electrons.com/pub/video/2011/elce/elce-2011-petazzoni-buildroot-for-real-project-450p.webm[450x800]
+
+* Buildroot Developer Day aside ELC-E 2010 (October 29, 2010 - Cambridge, UK)
++
+** Announcement: http://lists.busybox.net/pipermail/buildroot/2010-September/037930.html[]
+
+* Buildroot presentation at FOSDEM 2010 (May 2, 2010 - Brussels, Belgium)
++
+** Presentation: http://fosdem.org/2010/schedule/events/emb_cross_build[Build Systems:
+Present & Future]
+** Slides: http://send-patches.org/news/20100211-1-FOSDEM-Crossdev-Workshop.pdf[]
+** Video: http://free-electrons.com/pub/video/2010/fosdem/fosdem2010-workshop-cross-build-systems.ogv[]
+
+* Buildroot Developer Day aside ELC-E 2009 (October 17, 2009 - Grenoble, France)
++
+The first _Buildroot Developer Day_ took place on Saturday, October 17th in
+Grenoble, France, just the day after Embedded Linux Conference Europe.
++
+This _Developer Day_ aims at allowing Buildroot developers to meet and exchange
+ideas on the project and its future.

docs/manual/get-involved.txt +4 -2

+** http://elinux.org/images/9/9e/Buildroot2.pdf[Slides]
+** http://video.linux.com/videos/buildroot-a-nice-simple-and-efficient-embedded-linux-build-system[Video]
 
-Buildroot presentation at LSM 2012 (July 12-14, 2012 - Geneva)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* ELC-E 2011: Using Buildroot in real projects
+** http://elinux.org/images/2/2a/Using-buildroot-real-project.pdf[Slides]

Add details about how to deploy images generated by Buildroot on real hardware, emulator or VM, over network (TFTP, NFS, PXE).

Signed-off-by A.R.D. <[email protected]>

Signed-off-by Samuel Martin <[email protected]>

---
changes v2 -> v3:
- typos and minor rewordings (Thomas De S. and Arnout V.)
- typos + formating fixes + minor rewordings
- rename beyond-buildroot.txt -> deploying-images.txt
- move booting image chapter as chapter #4
- add missing NFS links
- enhance NFS boot section
- add section about TFTP boot
- add section about preparing custom disk image

changes v1 -> v2 (Samuel):
- split patch
- rephrase commit message
- wrap line at 70-80 chars
- misc. typo and formating fixes
- misc. rewordings
- re-order the "Network boot" section
- add a word about qemu targets
- enhance section about disk image generation
- enhance section about NFS boot + add links
- keep "Beyond Buildroot" at the end of the manual
- add cross-refs to "Beyond Buildroot"

Signed-off-by Samuel Martin <[email protected]>

---
  docs/manual/beyond-buildroot.txt |  41 ------
  docs/manual/deploying-images.txt | 290 +++++++++++++++++++++++++++++++++++++++
  docs/manual/manual.txt           |   4 +-
  docs/manual/using.txt            |   3 +-
  4 files changed, 294 insertions(+), 44 deletions(-)

delete mode 100644 docs/manual/beyond-buildroot.txt create mode 100644 docs/manual/deploying-images.txt

docs/manual/beyond-buildroot.txt deleted +0 -41

deleted file mode 100644
index a0d4af0..0000000
@@ -1,41 +0,0 @@
-// -*- mode:doc; -*-
-// vim: set syntax=asciidoc:
-
-Beyond Buildroot
-================
-
-Boot the generated images
--------------------------
-
-NFS boot
-~~~~~~~~
-
-To achieve NFS-boot, enable _tar root filesystem_ in the _Filesystem
-images_ menu.
-
-After a complete build, just run the following commands to setup the
-NFS-root directory:
-
--------------------
-sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir
--------------------
-
-Remember to add this path to +/etc/exports+.
-
-Then, you can execute a NFS-boot from your target.
-
-Chroot
-------
-
-If you want to chroot in a generated image, then there are few thing
-you should be aware of:
-
-* you should setup the new root from the _tar root filesystem_ image;
-
-* either the selected target architecture is compatible with your host
-  machine, or you should use some +qemu-*+ binary and correctly set it
-  within the +binfmt+ properties to be able to run the binaries built
-  for the target on your host machine;
-
-* Buildroot does not currently provide +host-qemu+ and +binfmt+
-  correctly built and set for that kind of use.

docs/manual/deploying-images.txt new file +0 -0

new file mode 100644
index 0000000..ad77f09

docs/manual/deploying-images.txt new file +4 -0

+
+This part of the work is really depending on each project and
+hardware, so we cannot describe every solutions here. This is where
+Buildroot's work ends.

docs/manual/deploying-images.txt new file +4 -0

+
+Each of these configurations has a 'defconfig' and comes with a
++readme.txt+ file providing details to use the built images with
+'Qemu'.

docs/manual/deploying-images.txt new file +11 -0

+
+[NOTE]
+Some of these tools are not really well documented, you may need to
+browse the source trees to find out how to use them.
+
+
+Preparing a bootable raw disk file for virtualization
+-----------------------------------------------------
+
+[NOTE]
+This section is mostly x86 target specific.

docs/manual/deploying-images.txt new file +16 -0

+  the host machine. Look at its manpage before using it;
+
+* install the MBR;
+
+* create nodes in +/dev+ pointing to the _disk image_ and its
+  partitions (as you will have with +/dev/sda+, +/dev/sda1+,
+  +/dev/sda2+, etc) with
+  http://robert.penz.name/73/kpartx-a-tool-for-mounting-partitions-within-an-image-file/[kpartx];
+
+* mount one or several partitions of the _disk image_ with the +mount+
+  command;
+
+* populate the root partition by extracting into it the
+  root-filesystem tarball generated by Buildroot.
+
+

docs/manual/deploying-images.txt new file +6 -0

+* ...
+
+To achieve network-boot, there are several methods that depend on both
+the facility network infrastructure and the targets. Among these, the
+most common are:
+

docs/manual/deploying-images.txt new file +8 -0

+
+For further information, refer to the bootloader documentation.
+
+Here is some related documentation to TFTP server setup and TFTP boot:
+
+* http://www.linuxhomenetworking.com/wiki/index.php/Quick_HOWTO_:_Ch16_:_Telnet,_TFTP,_and_xinetd#TFTP
+* https://linuxlink.timesys.com/docs/linux_tftp
+* http://www.webune.com/forums/how-to-install-tftp-server-in-linux.html

docs/manual/deploying-images.txt new file +12 -0

+
+For further information, refer to the bootloader documentation.
+
+[[deploying-images-nfs-links]]
+Here is some related documentation to NFS server setup and NFS boot:
+
+* http://tldp.org/HOWTO/NFS-HOWTO/index.html
+* https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt
+* https://wiki.archlinux.org/index.php/NFS
+* http://www.solid-run.com/mw/index.php/Setup_NFS_boot
+* http://wiki.openelec.tv/index.php?title=Network_Boot_-_NFS
+* http://www.armadeus.com/wiki/index.php?title=NFS

docs/manual/deploying-images.txt new file +13 -0

+parameters (see https://www.kernel.org/doc/Documentation/kernel-parameters.txt
+and the xref:deploying-images-nfs-links[above links]).
+
+For further information, refer to the
+xref:deploying-images-nfs-links[above links].
+
+
+Network PXE bootloader
+~~~~~~~~~~~~~~~~~~~~~~
+
+[NOTE]
+This section is mostly x86 target specific.
+

docs/manual/deploying-images.txt new file +25 -0

+boot ROM that is accessible from a TFTP server.
+Then your target boots with it and comes back to the TFTP server to get
+the specific stuff (for instance its boot menu).
+
+Here are some hints on how to setup this:
+
+* http://www.digitalpeer.com/id/linuxnfs
+
+
+Chroot into generated image
+---------------------------
+
+If you want to 'chroot' in a generated image, then there are few things
+you should be aware of:
+
+* you should setup the new root from the _tar root filesystem_ image;
+
+* either the selected target architecture is compatible with your host
+  machine, or you should use some +qemu-*+ binary and correctly set it
+  within the +binfmt+ properties to be able to run the binaries built
+  for the target on your host machine;
+
+* Buildroot does not currently provide +host-qemu+ nor +binfmt+
+  correctly built and set for that kind of use. This usage is beyond
+  Buildroot scope.

docs/manual/manual.txt +2 -2

index 9685667..8fcb2c2 100644
@@ -21,6 +21,8 @@ include::starting-up.txt[]
 
  include::working-with.txt[]
 
+include::deploying-images.txt[]
+
  include::faq-troubleshooting.txt[]
 
  include::going-further.txt[]

@@ -29,8 +31,6 @@ include::developer-guide.txt[]
 
  include::legal-notice.txt[]
 
-include::beyond-buildroot.txt[]
-
  include::get-involved.txt[]
 
  include::contribute.txt[]

docs/manual/using.txt +2 -1

index de29ad6..783370d 100644
@@ -67,7 +67,8 @@ Buildroot output is stored in a single directory, +output/+.
  This directory contains several subdirectories:
 
  * +images/+ where all the images (kernel image, bootloader and root
-  filesystem images) are stored.
+  filesystem images) are stored. For further details for using/booting
+  the images, refer to xref:deploying-images[].
 
  * +build/+ where all the components except for the cross-compilation
    toolchain are built (this includes tools needed to run Buildroot on

Quoted 1 line · Samuel Martin

Quoted 6 lines

docs/manual/deploying-images.txt new file +6 -0

+flashing and/or booting the given platform.
+
+Although, deploying the generated images on the actual hardware
+(flashing and booting the hardware) is very tight to the target
+hardware and can differ a lot from one target to another.
+Buildroot cannot provide information on this part.

docs/manual/deploying-images.txt line 62

Quoted 4 lines

docs/manual/deploying-images.txt new file +4 -0

+
+For deploying images on the actual target, refer to the hardware
+vendor instructions, or the readme file in the _board_ directory if
+any.

I don't like how these two paragraphs are formulated, but I can't readily
think of an improvement.

Hi Samuel, Arnout,

Quoted 2 lines · Arnout Vandecappelle

Quoted 1 line · Samuel Martin

[..]

Quoted 6 lines

Quoted 6 lines

docs/manual/deploying-images.txt new file +6 -0

+flashing and/or booting the given platform.
+
+Although, deploying the generated images on the actual hardware
+(flashing and booting the hardware) is very tight to the target
+hardware and can differ a lot from one target to another.
+Buildroot cannot provide information on this part.

Quoted 9 lines

docs/manual/deploying-images.txt line 62

Quoted 4 lines

docs/manual/deploying-images.txt new file +4 -0

+
+For deploying images on the actual target, refer to the hardware
+vendor instructions, or the readme file in the _board_ directory if
+any.

I don't like how these two paragraphs are formulated, but I can't readily
think of an improvement.

Maybe:
Nevertheless, how to deploy the generated images on actual hardware is very board-specific. Buildroot cannot provide instructions for all boards, or even provide complete instructions for a single board. Please refer to the instructions provided by the target vendor.

[..]

Regarding the section names, currently you have:
4. Deploying target images built with Buildroot 4.1. Deploying images on the target hardware
4.2. Booting images in emulators
4.3. Preparing a raw disk image for customized target layout 4.4. Preparing a bootable raw disk file for virtualization 4.5. Booting the generated image over the network 4.6. Chroot into generated image

While 4 and 4.1 talk about 'deploying' the other sections start using other terminology. Here is a suggestion:
4. Deploying target images built with Buildroot
4.1. Deploying images on the target hardware
4.2. Deploying images in emulators
4.3. Preparing a raw disk image for customized target layout 4.4. Preparing a bootable raw disk file for virtualization 4.5. Deploying images over the network
4.6. Chroot into generated image

In fact, 4.5 also talks about target hardware, so should probably be moved above, or even a subsection of 4.1.
I'm not yet a big fan of the names of 4.3, 4.4 and 4.6 (it's unclear to me what they really do based on the title) but I don't have good suggestions.

On 15/10/13 22:27, Thomas De Schampheleire wrote:

Quoted 21 lines

Regarding the section names, currently you have:
4. Deploying target images built with Buildroot 4.1. Deploying images on the target hardware
4.2. Booting images in emulators
4.3. Preparing a raw disk image for customized target layout 4.4. Preparing a bootable raw disk file for virtualization 4.5. Booting the generated image over the network 4.6. Chroot into generated image

While 4 and 4.1 talk about 'deploying' the other sections start using other terminology. Here is a suggestion:
4. Deploying target images built with Buildroot
4.1. Deploying images on the target hardware
4.2. Deploying images in emulators
4.3. Preparing a raw disk image for customized target layout 4.4. Preparing a bootable raw disk file for virtualization 4.5. Deploying images over the network
4.6. Chroot into generated image

Quoted 5 lines

In fact, 4.5 also talks about target hardware, so should probably be moved above, or even a subsection of 4.1.
I'm not yet a big fan of the names of 4.3, 4.4 and 4.6 (it's unclear to me what they really do based on the title) but I don't have good suggestions.

Right, my attempt: a bit of reordering and more "deploying":

4. Deploying target images built with Buildroot 4.1. Deploying images on the target hardware (includes the network deployment)
4.2. Deploying images on removable media
4.3. Preparing a bootable raw disk file for virtualization 4.4. Deploying images in emulators
4.5. Chroot into generated image

Quoted 1 line · Arnout Vandecappelle

On 15/10/13 22:27, Thomas De Schampheleire wrote:

[..]

Quoted 31 lines

Quoted 21 lines

Regarding the section names, currently you have:
4. Deploying target images built with Buildroot 4.1. Deploying images on the target hardware
4.2. Booting images in emulators
4.3. Preparing a raw disk image for customized target layout 4.4. Preparing a bootable raw disk file for virtualization 4.5. Booting the generated image over the network 4.6. Chroot into generated image

While 4 and 4.1 talk about 'deploying' the other sections start using other terminology. Here is a suggestion:
4. Deploying target images built with Buildroot
4.1. Deploying images on the target hardware
4.2. Deploying images in emulators
4.3. Preparing a raw disk image for customized target layout 4.4. Preparing a bootable raw disk file for virtualization 4.5. Deploying images over the network
4.6. Chroot into generated image

Quoted 5 lines

In fact, 4.5 also talks about target hardware, so should probably be moved above, or even a subsection of 4.1.
I'm not yet a big fan of the names of 4.3, 4.4 and 4.6 (it's unclear to me what they really do based on the title) but I don't have good suggestions.

Right, my attempt: a bit of reordering and more "deploying":

Quoted 7 lines

4. Deploying target images built with Buildroot 4.1. Deploying images on the target hardware (includes the network deployment)
4.2. Deploying images on removable media
4.3. Preparing a bootable raw disk file for virtualization 4.4. Deploying images in emulators
4.5. Chroot into generated image

I like it, except still the 4.5. What is the use case for chroot'ing into such an image? To manipulate the image? Or in the case of the same target/native architecture to actually run stuff? Can we change the section name to reflect the purpose rather than the solution? If 'chroot' is the most clear way to put it in the section name, then I'd change to:
"chroot'ing into a target image"
('ing' to match the other sections, 'a' article to make it read better, and lowercase chroot because it's a special name and capitalizing that reads odd IMO)

Quoted 49 lines

Quoted 2 lines · Arnout Vandecappelle

On 15/10/13 22:27, Thomas De Schampheleire wrote:

[..]

Quoted 32 lines

Quoted 21 lines

Regarding the section names, currently you have:
4. Deploying target images built with Buildroot 4.1. Deploying images on the target hardware
4.2. Booting images in emulators
4.3. Preparing a raw disk image for customized target layout 4.4. Preparing a bootable raw disk file for virtualization 4.5. Booting the generated image over the network 4.6. Chroot into generated image

While 4 and 4.1 talk about 'deploying' the other sections start using other terminology. Here is a suggestion:
4. Deploying target images built with Buildroot
4.1. Deploying images on the target hardware
4.2. Deploying images in emulators
4.3. Preparing a raw disk image for customized target layout 4.4. Preparing a bootable raw disk file for virtualization 4.5. Deploying images over the network
4.6. Chroot into generated image

Quoted 6 lines

In fact, 4.5 also talks about target hardware, so should probably be moved above, or even a subsection of 4.1.
I'm not yet a big fan of the names of 4.3, 4.4 and 4.6 (it's unclear to me what they really do based on the title) but I don't have good suggestions.

Right, my attempt: a bit of reordering and more "deploying":

Quoted 8 lines

4. Deploying target images built with Buildroot 4.1. Deploying images on the target hardware (includes the network deployment)
4.2. Deploying images on removable media
4.3. Preparing a bootable raw disk file for virtualization 4.4. Deploying images in emulators
4.5. Chroot into generated image

Quoted 11 lines

I like it, except still the 4.5. What is the use case for chroot'ing into such an image? To manipulate the image? Or in the case of the same target/native architecture to actually run stuff? Can we change the section name to reflect the purpose rather than the solution? If 'chroot' is the most clear way to put it in the section name, then I'd change to:
"chroot'ing into a target image"
('ing' to match the other sections, 'a' article to make it read better, and lowercase chroot because it's a special name and capitalizing that reads odd IMO)

Ack that.

Quoted 2 lines

[...]

+

docs/manual/deploying-images.txt line 68

Quoted 6 lines

+[WARNING]

docs/manual/deploying-images.txt new file +4 -0

+Be careful, *the _board's_ readme files coming within Buildroot are
+provided without warranty of any kind*.
+They are contributions from Buildroot users, but Buildroot developers
+do not ensure their correctness, nor maintain them.

Is this warning really necessary? Most readme.txt files use removable
media (or emulation), and the few that do write to flash have warnings already. The only exception is the Telit EVK-PRO3, so maybe we should just add a warning there.

Arnout,

2013/10/8 Arnout Vandecappelle <arnout at mind.be <mailto:[email protected]>>

On 10/05/13 21:49, Samuel Martin wrote:

[...]

+
+[WARNING]
+Be careful, *the _board's_ readme files coming within Buildroot are +provided without warranty of any kind*.
+They are contributions from Buildroot users, but Buildroot developers
+do not ensure their correctness, nor maintain them.

Is this warning really necessary? Most readme.txt files use
removable media (or emulation), and the few that do write to flash have warnings already. The only exception is the Telit EVK-PRO3, so maybe we should just add a warning there.

Well, the few boards we are talking about here are:
- Telit EVK-PRO3
- avnet s6lx9_microboard
- freescale mpc8315erdb
- freescale p1010rdb
For the 2 later, there is a warning about the bootloader in the readme.txt files,
for the 2 others, it is not so obvious...

Anyway, I don't mind adding the warning in the readme files. Having it close to the flashing instruction makes sense;
having it in the documentation (as a genreric warning) makes sense too imho.

Regards,

--
Samuel