[Buildroot] [pull request] Pull request for branch sma/doc-update

[Buildroot] [pull request] Pull request for branch sma/doc-update

[Samuel Martin]

All,


Another round for the manual update patch series.
This time, I also integrate the pending patches from Thomas DS.

BTW, can someone (who has enough patchwork privileges) mark the
following patch as superseded:
http://patchwork.ozlabs.org/patch/214943/


Yours,

--
Samuel


The following changes since commit f87f067c027261eb8c0ac8ad120fe845570aaae3:

  ngrep: add license information (2013-10-15 15:13:28 +0200)

are available in the git repository at:

  git at github.com:tSed/buildroot.git sma/doc-update

for you to fetch changes up to b67f14903e6e33f2790ff7ee8c82c658f8c12b01:

  board: add warning to readme files explaining how to flash the target (2013-10-18 21:34:54 +0200)

----------------------------------------------------------------
Samuel Martin (10):
      support: trivial fixes (typos and minor rewording) in gen-manual-lists.py
      manual: move the manual rsync directory under $(O)/build/
      manual: developer-guide.txt: cleanup non-existing source
      manual: introduction.txt: enhance Buildroot presentation
      manual: get-involved.txt: fix event order
      manual: update get-involved section
      manual: rework Deploying images chapter
      manual: customize-toolchain.txt: update internal backend section
      manual: faq-troubleshooting.txt: add tips to avoid toolchain build
      board: add warning to readme files explaining how to flash the target

Thomas De Schampheleire (2):
      manual generation: check dependencies first
      manual generation: rename manual-txt into manual-text

 Makefile                                    |   4 +-
 board/avnet/s6lx9_microboard/readme.txt     |  10 +
 board/freescale/mpc8315erdb/readme.txt      |   8 +
 board/freescale/p1010rdb/readme.txt         |   8 +
 board/telit/evk-pro3/readme.txt             |   9 +
 docs/manual/beyond-buildroot.txt            |  41 ----
 docs/manual/customize-toolchain.txt         |  13 +-
 docs/manual/deploying-images.txt            | 291 ++++++++++++++++++++++++++++
 docs/manual/developer-guide.txt             |   2 -
 docs/manual/faq-troubleshooting.txt         |  67 +++++++
 docs/manual/get-involved.txt                | 164 +++++++++++++++-
 docs/manual/introduction.txt                |  45 +++++
 docs/manual/make-tips.txt                   |   3 +-
 docs/manual/manual.mk                       |  47 ++++-
 docs/manual/manual.txt                      |   4 +-
 docs/manual/prerequisite.txt                |   5 +-
 docs/manual/using.txt                       |   3 +-
 support/dependencies/check-host-asciidoc.sh |  36 ++++
 support/scripts/gen-manual-lists.py         |   9 +-
 19 files changed, 691 insertions(+), 78 deletions(-)
 delete mode 100644 docs/manual/beyond-buildroot.txt
 create mode 100644 docs/manual/deploying-images.txt
 create mode 100755 support/dependencies/check-host-asciidoc.sh

[Buildroot] [PATCH 01/12] manual generation: check dependencies first

[Samuel Martin]

From: Thomas De Schampheleire <patrickdepinguin@gmail.com>

To generate the manual, you need a few tools. If these are not present,
pretty cryptic error messages are given.
This patch adds a simple check for these dependencies, before attempting to
build the manual.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/make-tips.txt                   |  3 +--
 docs/manual/manual.mk                       | 32 ++++++++++++++++++++++++-
 docs/manual/prerequisite.txt                |  5 +++-
 support/dependencies/check-host-asciidoc.sh | 36 +++++++++++++++++++++++++++++
 4 files changed, 72 insertions(+), 4 deletions(-)
 create mode 100755 support/dependencies/check-host-asciidoc.sh

diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
index 31a88bf..0159ffe 100644
--- a/docs/manual/make-tips.txt
+++ b/docs/manual/make-tips.txt
@@ -64,9 +64,8 @@ To generate the manual:
 The manual outputs will be generated in 'output/docs/manual'.
 
 .Notes
-- +asciidoc+ is required to build the documentation (see:
+- A few tools are required to build the documentation (see:
   xref:requirement-optional[]).
-- There is a known issue that you can't build it under Debian Squeeze.
 
 .Reseting Buildroot for a new target:
 
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index d092d3f..fcfe47b 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,8 +1,34 @@
-manual-update-lists:
+manual-update-lists: manual-check-dependencies-lists
 	$(Q)$(call MESSAGE,"Updating the manual lists...")
 	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(O)/docs/manual/.build \
 		$(TOPDIR)/support/scripts/gen-manual-lists.py
 
+# we can't use suitable-host-package here because that's not available in
+# the context of 'make release'
+manual-check-dependencies:
+	$(Q)if [ -z "$(shell support/dependencies/check-host-asciidoc.sh)" ]; then \
+		echo "You need a sufficiently recent asciidoc on your host" \
+			"to generate the manual"; \
+		exit 1; \
+	fi
+	$(Q)if [ -z "`which w3m 2>/dev/null`" ]; then \
+		echo "You need w3m on your host to generate the manual"; \
+		exit 1; \
+	fi
+
+manual-check-dependencies-pdf:
+	$(Q)if [ -z "`which dblatex 2>/dev/null`" ]; then \
+		echo "You need dblatex on your host to generate the pdf manual"; \
+		exit 1; \
+	fi
+
+manual-check-dependencies-lists:
+	$(Q)if ! python -c "import argparse" >/dev/null 2>&1 ; then \
+		echo "You need python with argparse on your host to generate" \
+			"the list of packages in the manual"; \
+		exit 1; \
+	fi
+
 ################################################################################
 # GENDOC -- generates the make targets needed to build a specific type of
 #           asciidoc documentation.
@@ -22,8 +48,12 @@ $(1): $(1)-$(3)
 .PHONY: $(1)-$(3)
 $(1)-$(3): $$(O)/docs/$(1)/$(1).$(4)
 
+manual-check-dependencies-$(3):
+
 $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
 			   $$($(call UPPERCASE,$(1))_SOURCES) \
+			   manual-check-dependencies \
+			   manual-check-dependencies-$(3) \
 			   manual-update-lists
 	$(Q)$(call MESSAGE,"Generating $(5) $(1)...")
 	$(Q)mkdir -p $$(@D)/.build
diff --git a/docs/manual/prerequisite.txt b/docs/manual/prerequisite.txt
index 78ce436..729d64c 100644
--- a/docs/manual/prerequisite.txt
+++ b/docs/manual/prerequisite.txt
@@ -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 higher
+** +w3m+
+** +python+ with the +argparse+ module (automatically present in 2.7+ and 3.2+)
+** +dblatex+ (required for the pdf manual only)
diff --git a/support/dependencies/check-host-asciidoc.sh b/support/dependencies/check-host-asciidoc.sh
new file mode 100755
index 0000000..fc5fcba
--- /dev/null
+++ b/support/dependencies/check-host-asciidoc.sh
@@ -0,0 +1,36 @@
+#!/bin/sh
+
+candidate="$1" #ignored
+
+asciidoc=`which asciidoc`
+if [ ! -x "$asciidoc" ]; then
+	# echo nothing: no suitable asciidoc found
+	exit 1
+fi
+
+# Output of 'asciidoc --version' examples:
+# asciidoc 8.6.7
+version=`$asciidoc --version | cut -d\  -f2`
+major=`echo "$version" | cut -d. -f1`
+minor=`echo "$version" | cut -d. -f2`
+bugfix=`echo "$version" | cut -d. -f3`
+
+# To generate the manual, we need asciidoc >= 8.6.3
+major_min=8
+minor_min=6
+bugfix_min=3
+if [ $major -gt $major_min ]; then
+	echo $asciidoc
+else
+	if [ $major -eq $major_min -a $minor -ge $minor_min ]; then
+		echo $asciidoc
+	else
+		if [ $major -eq $major_min -a $minor -eq $minor_min \
+			-a $bugfix -ge $bugfix_min ]; then
+			echo $asciidoc
+		else
+			# echo nothing: no suitable asciidoc found
+			exit 1
+		fi
+	fi
+fi
-- 
1.8.4.1

[Buildroot] [PATCH 02/12] manual generation: rename manual-txt into manual-text

[Samuel Martin]

From: Thomas De Schampheleire <patrickdepinguin@gmail.com>

The output extension and the generation messages refer to 'text', but the make
target was confusingly 'txt'. This patch changes the make target for
consistency.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 Makefile              | 4 ++--
 docs/manual/manual.mk | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index f266e2d..1496bd7 100644
--- a/Makefile
+++ b/Makefile
@@ -797,7 +797,7 @@ endif
 	@echo '  manual-html            - build manual in HTML'
 	@echo '  manual-split-html      - build manual in split HTML'
 	@echo '  manual-pdf             - build manual in PDF'
-	@echo '  manual-txt             - build manual in txt'
+	@echo '  manual-text            - build manual in text'
 	@echo '  manual-epub            - build manual in ePub'
 	@echo
 	@echo 'Miscellaneous:'
@@ -821,7 +821,7 @@ release: OUT=buildroot-$(BR2_VERSION)
 # documentation to the git output
 release:
 	git archive --format=tar --prefix=$(OUT)/ HEAD > $(OUT).tar
-	$(MAKE) O=$(OUT) manual-html manual-txt manual-pdf
+	$(MAKE) O=$(OUT) manual-html manual-text manual-pdf
 	tar rf $(OUT).tar $(OUT)
 	gzip -9 -c < $(OUT).tar > $(OUT).tar.gz
 	bzip2 -9 -c < $(OUT).tar > $(OUT).tar.bz2
diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index fcfe47b..aeafd10 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -75,7 +75,7 @@ define GENDOC
 $(call GENDOC_INNER,$(1),xhtml,html,html,HTML,--xsltproc-opts "--stringparam toc.section.depth 4")
 $(call GENDOC_INNER,$(1),chunked,split-html,chunked,split HTML,--xsltproc-opts "--stringparam toc.section.depth 4")
 $(call GENDOC_INNER,$(1),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
-$(call GENDOC_INNER,$(1),text,txt,text,text)
+$(call GENDOC_INNER,$(1),text,text,text,text)
 $(call GENDOC_INNER,$(1),epub,epub,epub,ePUB)
 clean: $(1)-clean
 $(1)-clean:
-- 
1.8.4.1

[Buildroot] [PATCH 03/12] support: trivial fixes (typos and minor rewording) in gen-manual-lists.py

[Samuel Martin]

Signed-off-by: Samuel Martin <s.martin49@gmail.com>

---
Changes v1 -> v2:
- split patch content
- detail a bit more the commit message

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 support/scripts/gen-manual-lists.py | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/support/scripts/gen-manual-lists.py b/support/scripts/gen-manual-lists.py
index 3568843..5c81e1d 100755
--- a/support/scripts/gen-manual-lists.py
+++ b/support/scripts/gen-manual-lists.py
@@ -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.
 
         """
         if sub_menu:
-            return "| {0:<40} <| {1}\n".format(label, " -> ".join(parents))
+            return "| {0:<40} <| {1}\n".format(item, " -> ".join(parents))
         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:
-- 
1.8.4.1

[Buildroot] [PATCH 03/12] support: trivial fixes (typos and minor rewording) in gen-manual-lists.py

[Thomas De Schampheleire]

Hi Samuel,


On Fri, Oct 18, 2013 at 10:31 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ---
> Changes v1 -> v2:
> - split patch content
> - detail a bit more the commit message
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
> ---
>  support/scripts/gen-manual-lists.py | 9 ++++-----
>  1 file changed, 4 insertions(+), 5 deletions(-)
>
> diff --git a/support/scripts/gen-manual-lists.py b/support/scripts/gen-manual-lists.py
> index 3568843..5c81e1d 100755
> --- a/support/scripts/gen-manual-lists.py
> +++ b/support/scripts/gen-manual-lists.py
> @@ -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.
>
>          """
>          if sub_menu:
> -            return "| {0:<40} <| {1}\n".format(label, " -> ".join(parents))
> +            return "| {0:<40} <| {1}\n".format(item, " -> ".join(parents))
>          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:
> --



Ack on the above changes.

I also spotted a few other typos in that file that could be fixed at
the same time:

- lasst -> last in comment of get_symbol_parents
- consumtion -> consumption  (line 267)
- noticebly -> noticeably (line 269)
- re-scannig -> re-scanning (or even rescanning) (line 269)

Best regards,
Thomas

[Buildroot] [PATCH 04/12] manual: move the manual rsync directory under $(O)/build/

[Samuel Martin]

This patch just moves the manual source/build directory in $(O)/build/
(currently this location is $(O)/docs/manual/.build/, which is removed
at this end of the manual generation).

This location is used to:
- generate the package list files
- rsync the *.txt source from docs/manual/

The output manuals are still generated in $(O)/docs/manual/, so the release
target is unchanged.

Moving the manual source/build directory is more consistent with the rest
of how Buildroot works.
This also avoid to remove the *.txt that are generated and are actually
used by a2x, this is very helpful for investigating
asdciidoc/dblatex/texlive related issues.

Signed-off-by: Samuel Martin <s.martin49@gmail.com>

---
Changes v1 -> v2:
- rebase on top of ThomasDS' patches
- split patch content
- detail a bit more the commit message

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/manual.mk | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/manual/manual.mk b/docs/manual/manual.mk
index aeafd10..ffc4e9a 100644
--- a/docs/manual/manual.mk
+++ b/docs/manual/manual.mk
@@ -1,6 +1,8 @@
+MANUAL_BUILDDIR = $(BUILD_DIR)/buildroot-manual
 manual-update-lists: manual-check-dependencies-lists
 	$(Q)$(call MESSAGE,"Updating the manual lists...")
-	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(O)/docs/manual/.build \
+	$(Q)mkdir -p $(MANUAL_BUILDDIR)
+	$(Q)BR2_DEFCONFIG="" TOPDIR=$(TOPDIR) O=$(MANUAL_BUILDDIR) \
 		$(TOPDIR)/support/scripts/gen-manual-lists.py
 
 # we can't use suitable-host-package here because that's not available in
@@ -56,11 +58,10 @@ $$(O)/docs/$(1)/$(1).$(4): docs/$(1)/$(1).txt \
 			   manual-check-dependencies-$(3) \
 			   manual-update-lists
 	$(Q)$(call MESSAGE,"Generating $(5) $(1)...")
-	$(Q)mkdir -p $$(@D)/.build
-	$(Q)rsync -au docs/$(1)/*.txt $$(@D)/.build
+	$(Q)mkdir -p $$(@D) $(MANUAL_BUILDDIR)
+	$(Q)rsync -au docs/$(1)/*.txt $(MANUAL_BUILDDIR)
 	$(Q)a2x $(6) -f $(2) -d book -L -r $(TOPDIR)/docs/images \
-	        -D $$(@D) $$(@D)/.build/$(1).txt
-	-$(Q)rm -rf $$(@D)/.build
+		-D $$(@D) $(MANUAL_BUILDDIR)/$(1).txt
 endef
 
 ################################################################################
@@ -79,7 +80,7 @@ $(call GENDOC_INNER,$(1),text,text,text,text)
 $(call GENDOC_INNER,$(1),epub,epub,epub,ePUB)
 clean: $(1)-clean
 $(1)-clean:
-	$(Q)$(RM) -rf $(O)/docs/$(1)
+	$(Q)$(RM) -rf $(O)/docs/$(1) $(MANUAL_BUILDDIR)
 .PHONY: $(1) $(1)-clean manual-update-lists
 endef
 
-- 
1.8.4.1

[Buildroot] [PATCH 05/12] manual: developer-guide.txt: cleanup non-existing source

[Samuel Martin]

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/developer-guide.txt | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
index 43272f5..8125ad5 100644
--- a/docs/manual/developer-guide.txt
+++ b/docs/manual/developer-guide.txt
@@ -11,5 +11,3 @@ include::adding-packages.txt[]
 include::patch-policy.txt[]
 
 include::download-infra.txt[]
-
-include::board-support.txt[]
-- 
1.8.4.1

[Buildroot] [PATCH 05/12] manual: developer-guide.txt: cleanup non-existing source

[Thomas De Schampheleire]

Samuel Martin <s.martin49@gmail.com> wrote:
>Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>---
> docs/manual/developer-guide.txt | 2 --
> 1 file changed, 2 deletions(-)
>
>diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt
>index 43272f5..8125ad5 100644
>--- a/docs/manual/developer-guide.txt
>+++ b/docs/manual/developer-guide.txt
>@@ -11,5 +11,3 @@ include::adding-packages.txt[]
> include::patch-policy.txt[]
> 
> include::download-infra.txt[]
>-
>-include::board-support.txt[]

This patch was already acked by ThomasP and myself. I don't see any changes? It's easier for reviewers if you'd take along such acks when sending newer versions.

Best regards,
Thomas

[Buildroot] [PATCH 06/12] manual: introduction.txt: enhance Buildroot presentation

[Samuel Martin]

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

Signed-off-by: Samuel Martin <s.martin49@gmail.com>

---
changes v1 -> v2:
- misc. typo fixes and rewording (ThomasDS)

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/introduction.txt | 45 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/docs/manual/introduction.txt b/docs/manual/introduction.txt
index c014565..ff3607f 100644
--- a/docs/manual/introduction.txt
+++ b/docs/manual/introduction.txt
@@ -25,3 +25,48 @@ comes with default configurations for several boards available
 off-the-shelf. Besides this, a number of third-party projects are based on,
 or develop their BSP footnote:[BSP: Board Support Package] or
 SDK footnote:[SDK: Software Development Kit] on top of Buildroot.
+
+What is Buildroot and what is it not
+------------------------------------
+
+Buildroot is:
+
+* a community-driven project;
+* a tool used in the industry;
+* targeting embedded, rather small, often headless, devices.
+
+
+Buildroot is *not*:
+
+* a _classic Linux-based distribution_, this means:
+
+** Buildroot does not use any package manager to populate the root
+   filesystem, this means there is no way to update only one package
+   of a root filesystem built by Buildroot without regenerating the
+   whole root filesystem;
+** Buildroot does not keep track of each package's content;
+** Buildroot does not provide as many packages as others distributions
+   do; so, some packages may not be available yet because the
+   community does not need them or thinks they are not suitable for
+   embedded targets.
+
+* Root filesystems generated by Buildroot are not intended to be used
+  for native development; so they do not contain any development file
+  (no headers, no static libraries, no native compiler for the
+  target), nor documentation.
+
+Buildroot's principles
+----------------------
+
+* Easy to use
+* Fast to build
+* Small footprint of the generated images footnote:[the smallness of
+  the image footprint mostly depends on the target device and its
+  application(s)]
+* Easy to hack
+* Being generic, but allowing customization:
+
+** Provide support for SoCs, rather than board specific configuration
+   (though Buildroot comes with a set of default configurations for a
+   bunch of boards);
+** Provide default configurations that can be easily overriden.
-- 
1.8.4.1

[Buildroot] [PATCH 06/12] manual: introduction.txt: enhance Buildroot presentation

[Thomas Petazzoni]

Dear Samuel Martin,

On Fri, 18 Oct 2013 22:31:30 +0200, Samuel Martin wrote:
> * add a "What is Buildroot and what is it not" section
> * add a "Buildroot's principles" section
> 
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>

I must say I'm not a big fan of this proposal. I find it a bit weird to
have a section named "What Buildroot is and what it is not". I don't
have a very objective explanation, it's just a general feeling.

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 07/12] manual: get-involved.txt: fix event order

[Samuel Martin]

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/get-involved.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
index 8475038..9e492e6 100644
--- a/docs/manual/get-involved.txt
+++ b/docs/manual/get-involved.txt
@@ -117,6 +117,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)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -127,8 +133,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[]
-- 
1.8.4.1

[Buildroot] [PATCH 07/12] manual: get-involved.txt: fix event order

[Thomas Petazzoni]

Dear Samuel Martin,

On Fri, 18 Oct 2013 22:31:31 +0200, Samuel Martin wrote:
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
> ---
>  docs/manual/get-involved.txt | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
> index 8475038..9e492e6 100644
> --- a/docs/manual/get-involved.txt
> +++ b/docs/manual/get-involved.txt
> @@ -117,6 +117,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)
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> @@ -127,8 +133,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[]

So you make the oldest event appear first? This seems weird: we
generally want the most recent event to appear first, because it's most
likely the one containing the most interesting piece of information for
the current version of Buildroot.

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 07/12] manual: get-involved.txt: fix event order

[Samuel Martin]

Thomas,

2013/11/1 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

> Dear Samuel Martin,
>
> On Fri, 18 Oct 2013 22:31:31 +0200, Samuel Martin wrote:
> > Signed-off-by: Samuel Martin <s.martin49@gmail.com>
> > ---
> >  docs/manual/get-involved.txt | 10 ++++++----
> >  1 file changed, 6 insertions(+), 4 deletions(-)
> >
> > diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
> > index 8475038..9e492e6 100644
> > --- a/docs/manual/get-involved.txt
> > +++ b/docs/manual/get-involved.txt
> > @@ -117,6 +117,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)
> >
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > @@ -127,8 +133,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[]
>
> So you make the oldest event appear first? This seems weird: we
> generally want the most recent event to appear first, because it's most
> likely the one containing the most interesting piece of information for
> the current version of Buildroot.
>
Yup, my bad!
My intention was to list them in a reverse chronological order. I somehow
messed up! :(

Regards,

-- 
Samuel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20131102/1dd21ee7/attachment.html>

[Buildroot] [PATCH 08/12] manual: update get-involved section

[Samuel Martin]

* 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 <s.martin49@gmail.com>

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

TIA,

changes v1 -> v2:
- misc. typos (ThomasDS)
- minor rewording (ThomasDS, Arnout and Ryan)

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/get-involved.txt | 162 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 152 insertions(+), 10 deletions(-)

diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
index 9e492e6..4be73f6 100644
--- a/docs/manual/get-involved.txt
+++ b/docs/manual/get-involved.txt
@@ -117,20 +117,162 @@ Currently, this page is mainly used as a _todo-list_.
 Events
 ------
 
-Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Upcoming events
+~~~~~~~~~~~~~~~
+
+* Buildroot Developer Days
+  co-located with ELC-E 2013 (October 26-27, 2013 - Edinburgh, UK)
++
+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[]
+
+Latest events
+~~~~~~~~~~~~~
+
+* Lightning talks about 'Build system and Buildroot'
+  at Kernel Recipes 2013 (September 24-25, 2013 - Paris, France)
+
+* GSoC participation (Summer 2013)
++
+For the fisrt time of its life, Buildroot will participate to the
+Google 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[]
+
+* Buildroot Developer Days
+  co-located with FOSDEM 2013 (February 4-5, 2012 - Brussels, Belgium)
++
+A report from the recent Buildroot Developers Meeting is now
+http://lists.busybox.net/pipermail/buildroot/2013-February/067105.html[available].
++
+http://emlinews.net[Embedded Linux News] also has a
+http://www.emlinews.net/2013/02/buildroot-developers-meeting-report[writeup
+about the event], including photos.
++
+Announcement and report of the event can also be found on the
+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
+  co-located with ELC-E 2012 (November 3-4, 2012 - Barcelona, Spain)
++
+A report from the recent _Buildroot Developer Days_ meeting in
+Barcelona, Spain is now
+http://lists.busybox.net/pipermail/buildroot/2012-November/061558.html[available].
++
+Many thanks to all the participants, and a special thanks to
+Arnout Vandecappelle from http://mind.be[mind] for taking notes and
+Thomas Petazzoni from http://free-electrons.com[Free Electrons] for
+handling all the practical arrangements, and naturally our sponsors,
+http://www.fluendo.com[Fluendo] and http://www.synopsys.com[Synopsis].
++
+Announcement, report and draft agenda of the event can also be found
+on:
++
+** 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
+  co-located with 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
+  co-located with 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
+  co-located with 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.
++
+This _Developer Day_ took place thanks to the sponsoring of
+http://www.calao-systems.com[Calao Systems] and
+http://www.free-electrons.com[Free Electrons].
+
+[[material]]
+Buildroot material
+------------------
+
+Some regular contributors give talks about their experience with
+Buildroot.
+
+Hereafter is a list of videos or slides or orther material used during
+these presentations.
 
-* Announcement & agenda thread: http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]
-* Report: http://lists.busybox.net/pipermail/buildroot/2012-February/050371.html[]
+[WARNING]
+Keep in mind that the information given in these documents may be
+outdated, refer to this manual for the latest and up-to-date
+information.
 
-Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 - Barcelona)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* ELC 2013: Technical Showcase
+** http://free-electrons.com/~thomas/pub/buildroot-poster.png[Poster]
+** http://free-electrons.com/~thomas/pub/buildroot-slides.pdf[Slides]
 
-* Event page: http://elinux.org/Buildroot:DeveloperDaysELCE2012[]
+* ELC 2012: Buildroot: A nice, simple and efficient embedded Linux
+  build system
+** 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]
+** Videos:
+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]
 
-* Announcement: http://lists.busybox.net/pipermail/buildroot/2012-May/053845.html[]
+* FOSDEM 2010: Build Systems: Present & Future
+** http://send-patches.org/news/20100211-1-FOSDEM-Crossdev-Workshop.pdf[Slides]
+** http://free-electrons.com/pub/video/2010/fosdem/fosdem2010-workshop-cross-build-systems.ogv[Video]
 
 
-- 
1.8.4.1

[Buildroot] [PATCH 08/12] manual: update get-involved section

[Thomas Petazzoni]

Dear Samuel Martin,

On Fri, 18 Oct 2013 22:31:32 +0200, Samuel Martin wrote:
> * 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.

I am not convinced we should mix "Buildroot Developers Meeting"
references with other Buildroot talks. While "Buildroot Developers
Meeting" listing definitely has its place in the "Getting involved"
section, the list of Buildroot talks, with pointers to slides and video
is useful for much more than people willing to get deeply involved in
Buildroot development. For example, the last talk from Peter at
ELCE2013, or the talk "Using Buildroot for real projects" I gave a few
years ago, make sense for users.

Best regards,

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 08/12] manual: update get-involved section

[Samuel Martin]

Thomas, all,

2013/11/1 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

> Dear Samuel Martin,
>
> On Fri, 18 Oct 2013 22:31:32 +0200, Samuel Martin wrote:
> > * 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.
>
> I am not convinced we should mix "Buildroot Developers Meeting"
> references with other Buildroot talks. While "Buildroot Developers
> Meeting" listing definitely has its place in the "Getting involved"
> section, the list of Buildroot talks, with pointers to slides and video
> is useful for much more than people willing to get deeply involved in
> Buildroot development. For example, the last talk from Peter at
> ELCE2013, or the talk "Using Buildroot for real projects" I gave a few
> years ago, make sense for users.
>
I agree.

So, things related to Buildroot internal community (like GSoC, BR dev. days)
should stay in the "Getting involved" section, while the other items,
mostly talks
or presentation of BR should go as appendices maybe.

Then, this appendices could be referred from many place in the manual:
- the "Adding new package to Buildroot" section;
- a to-be-written section dealing with "Workflow with Buildroot" or
something like that;
- ...

Any comments about this?

Regards,

-- 
Samuel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20131102/dee87501/attachment.html>

[Buildroot] [PATCH 09/12] manual: rework Deploying images chapter

[Samuel Martin]

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. <contact@team-ard.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>

---
changes v3 -> v4:
- misc. typo fixes and rewording (Arnout)
- rephrasing (ThomasDS)
- minor rewording
- reorder the chapter (Arnout, ThomasDS)

changes v2 -> v3:
- typos and minor rewordings (ThomasDS and Arnout)
- 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 <s.martin49@gmail.com>
---
 docs/manual/beyond-buildroot.txt |  41 ------
 docs/manual/deploying-images.txt | 291 +++++++++++++++++++++++++++++++++++++++
 docs/manual/manual.txt           |   4 +-
 docs/manual/using.txt            |   3 +-
 4 files changed, 295 insertions(+), 44 deletions(-)
 delete mode 100644 docs/manual/beyond-buildroot.txt
 create mode 100644 docs/manual/deploying-images.txt

diff --git a/docs/manual/beyond-buildroot.txt b/docs/manual/beyond-buildroot.txt
deleted file mode 100644
index a0d4af0..0000000
--- a/docs/manual/beyond-buildroot.txt
+++ /dev/null
@@ -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.
diff --git a/docs/manual/deploying-images.txt b/docs/manual/deploying-images.txt
new file mode 100644
index 0000000..278085c
--- /dev/null
+++ b/docs/manual/deploying-images.txt
@@ -0,0 +1,291 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[deploying-images]]
+Deploying target images built with Buildroot
+============================================
+
+After having run Buildroot, you will have a brand new kernel,
+bootloader and filesystem for your target exported in the
+'output/images' directory.
+The content of this directory depends on the selected options in the
+Buildroot configuration, especially those from the +Kernel+,
++filesystem images+ and +bootloaders+ menus.
+
+You probably want to do one of the following:
+
+* Copy and install the images on the target device to boot and test it.
+
+* Write the images to removable media that can be booted on the target
+  device.
+
+* Boot and test the images...
+
+* deploy and/or install the freshly built images on the target to boot
+  and test it;
+
+* boot and test the images in emulators (http://wiki.qemu.org/Main_Page[Qemu],
+  http://www.linaro.org/engineering/engineering-projects/armv8[Foundation_v8]
+  --- an AArch64 emulator, ...);
+
+* generate a virtual disk to dump to real system or to use in
+  virtualization systems (http://wiki.qemu.org/Main_Page[Qemu],
+  https://www.virtualbox.org/[VirtualBox], ...).
+  This is mostly useful for 'i386' and 'x86_64' targets architecture.
+
+This part of the work is really depending on each project and
+hardware, so we cannot describe every solution here. This is where
+Buildroot's work ends. The rest of this chapter gives some general
+examples and hints about how the images can be deployed to the target
+device. This is _not_ an exact guide and doesn't provide full details.
+Please take the time to have a look to referred projects to get those
+details.
+
+
+Deploying images on the target hardware
+---------------------------------------
+
+Buildroot comes with a set of minimal configurations that allow to
+boot various existing targets, from different vendors.
+
+All these configurations are stored in the 'configs/' directory.
+Most of these configurations also come with a directory
+'board/<vendor name>/<platform name>', for additional resources.
+Some of them also contain a 'readme.txt' file with information about
+flashing and/or booting the given platform.
+
+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.
+
+[WARNING]
+Be careful when flashing the images into the target, *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.
+
+
+Deploying images over the network
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is common to boot the target over the network when dealing with
+embedded devices, whatever the reasons could be:
+
+* to speed-up the in-progress images test during the development
+  phase;
+* to avoid premature wear or the flash memory devices;
+* to deploy the actual production images on the hardware;
+* or because the target is not equipped with memory storage;
+* ...
+
+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:
+
+* TFTP boot
+* NFS boot
+* PXE boot (x86-specific)
+
+
+TFTP boot
+^^^^^^^^^
+
+Depending on the bootloader installed on the target, it may be
+possible to download the kernel image through the network, using the
+TFTP protocol, loading it in RAM, then jump into it.
+
+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
+
+
+NFS boot
+^^^^^^^^
+
+Loading the kernel over NFS
++++++++++++++++++++++++++++
+
+Depending on the bootloader installed on the target, it may be
+possible to download the kernel image through the network, using the
+NFS protocol, loading it in RAM, then jump into it.
+
+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
+
+NFS root filesystem mounted on +/+
+++++++++++++++++++++++++++++++++++
+
+The idea is to mount +/+ using a network shared folder from an
+http://tldp.org/HOWTO/NFS-HOWTO/index.html[NFS] server
+(usually on the host development machine).
+
+To enable the NFS boot, you should select the _tar root filesystem_
+option in the _Filesystem images_ menu.
+
+The target kernel needs at least the following options:
+
+* NFS filesystem support (+CONFIG_NFS_FS+);
+
+* Root filesystem on NFS (+CONFIG_ROOT_NFS+);
+
+* Ethernet (+CONFIG_NET_ETHERNET+);
+
+* The ethernet driver for the target network interface;
+
+* IP: kernel level autoconfiguration. This includes:
+
+  * +CONFIG_IP_PNP+;
+  * +CONFIG_IP_PNP_BOOTTP+;
+  * +CONFIG_IP_PNP_DHCP+.
+
+After a complete build, just run the following command to setup the
+NFS root directory on the server:
+
+-------------------
+sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir
+-------------------
+
+Make sure the NFS root location appears in the +/etc/exports+ file,
+and an NFS daemon is running on the server.
+
+After editing +/etc/exports+, you should run:
+
+-------------------
+sudo exportfs -ra
+-------------------
+
+To boot on a NFS root-filesystem, adjust the kernel command line
+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.
+
+To fully boot on the network you need a network bootloader. This is
+optional and you could use your classic bootloader to mount an NFS
+rootfs.
+
+http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf[PXE]
+is a specification that has been implemented at least by
+http://www.syslinux.org/wiki/index.php/PXELINUX[PXELINUX] and
+http://ipxe.org/[iPXE].
+
+The main idea is to have a DHCP server that provides a link to a
+generic 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
+
+
+Deploying images on removable media
+-----------------------------------
+
+How the target device is close to the actual hardware, so Buildroot
+cannot provides any information how to achieve it for every single
+target. For boards that use the same processor as one of the boards
+supported by Buildroot, the 'readme.txt' can be a good starting point.
+
+In addition, Buildroot provides tools that run on your host that can
+help generating bootable media or booting a device over USB, serial or
+the network.
+
+[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.
+
+If you plan to use virtual machines, or to copy a binary bootable
+image to your target, you may need to create a _disk image_.
+
+To create a bootable raw _disk image_ file, you will need to:
+
+* create an empty file with the +dd+ command;
+
+* edit the partition table of this _disk image_ file using some tools
+  like +fdisk+ (be careful when using +fdisk+; mis-usage can damage
+  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.
+
+
+Deploying images in emulators
+-----------------------------
+
+Buildroot comes with a set of configurations for various
+architectures running in http://wiki.qemu.org/Main_Page['Qemu'], or
+http://www.linaro.org/engineering/engineering-projects/armv8['Foundation_v8']
+(an AArch64 emulator).
+
+These configurations are stored under the 'board/qemu/<target name>'
+and 'board/arm/foundation-v8' directories.
+
+Each of these configurations has a 'defconfig' and comes with a
++readme.txt+ file providing details to use the built images with
+the emulator.
+
+They are regularly tested and maintained by the Buildroot core
+developers.
+
+If you built one of these configurations and have 'Qemu' or
+'Foundation_v8' installed on your host machine, booting the images
+should be straight forward.
+
+
+Chroot'ing into target 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.
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index 9ae658e..f179199 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -21,6 +21,8 @@ include::starting-up.txt[]
 
 include::working-with.txt[]
 
+include::deploying-images.txt[]
+
 include::faq-troubleshooting.txt[]
 
 include::known-issues.txt[]
@@ -31,8 +33,6 @@ include::developer-guide.txt[]
 
 include::legal-notice.txt[]
 
-include::beyond-buildroot.txt[]
-
 include::get-involved.txt[]
 
 include::contribute.txt[]
diff --git a/docs/manual/using.txt b/docs/manual/using.txt
index de29ad6..783370d 100644
--- a/docs/manual/using.txt
+++ b/docs/manual/using.txt
@@ -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
-- 
1.8.4.1

[Buildroot] [PATCH 09/12] manual: rework Deploying images chapter

[Thomas Petazzoni]

Dear Samuel Martin,

On Fri, 18 Oct 2013 22:31:33 +0200, Samuel Martin wrote:

> +[[deploying-images]]
> +Deploying target images built with Buildroot
> +============================================
> +
> +After having run Buildroot, you will have a brand new kernel,
> +bootloader and filesystem for your target exported in the
> +'output/images' directory.

"exported" ? Doesn't make much sense I believe. "available" many?

"""
After having run Buildroot, depending on your configuration, you will
find in the +output/images/+ directory a combination of a kernel image,
one or several bootloader images, and one or several root filesystem
images in various formats.
"""

> +The content of this directory depends on the selected options in the
> +Buildroot configuration, especially those from the +Kernel+,
> ++filesystem images+ and +bootloaders+ menus.

This can be removed if the above formulation is used, I believe.

> +
> +You probably want to do one of the following:
> +
> +* Copy and install the images on the target device to boot and test it.
> +
> +* Write the images to removable media that can be booted on the target
> +  device.
> +
> +* Boot and test the images...

Why do we have "..." at the end of this sentence? Also, I don't see how
this case fits with the other items in this list.

> +* deploy and/or install the freshly built images on the target to boot
> +  and test it;

So the previous items start with a capital letter and end with a dot,
this one starts without a capital letter, and ends with a semi-colon.

I also don't see how it is different from the first item in your list.

> +* boot and test the images in emulators (http://wiki.qemu.org/Main_Page[Qemu],
> +  http://www.linaro.org/engineering/engineering-projects/armv8[Foundation_v8]
> +  --- an AArch64 emulator, ...);
> +
> +* generate a virtual disk to dump to real system or to use in
> +  virtualization systems (http://wiki.qemu.org/Main_Page[Qemu],
> +  https://www.virtualbox.org/[VirtualBox], ...).
> +  This is mostly useful for 'i386' and 'x86_64' targets architecture.

You're already talking about emulation in the previous item.

> +This part of the work is really depending on each project and
> +hardware, so we cannot describe every solution here. This is where
> +Buildroot's work ends. The rest of this chapter gives some general
> +examples and hints about how the images can be deployed to the target
> +device. This is _not_ an exact guide and doesn't provide full details.
> +Please take the time to have a look to referred projects to get those
> +details.
> +
> +
> +Deploying images on the target hardware
> +---------------------------------------
> +
> +Buildroot comes with a set of minimal configurations that allow to
> +boot various existing targets, from different vendors.
> +
> +All these configurations are stored in the 'configs/' directory.
> +Most of these configurations also come with a directory
> +'board/<vendor name>/<platform name>', for additional resources.
> +Some of them also contain a 'readme.txt' file with information about
> +flashing and/or booting the given platform.
> +
> +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.
> +
> +[WARNING]
> +Be careful when flashing the images into the target, *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.

This section is entitled "Deploying images on the hardware", but talks
about Buildroot defconfigs and the fact that for those defconfigs, we
have documentation. This isn't really helping much to deploy Buildroot
on hardware.

> +Deploying images over the network
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +It is common to boot the target over the network when dealing with
> +embedded devices, whatever the reasons could be:
> +
> +* to speed-up the in-progress images test during the development
> +  phase;
> +* to avoid premature wear or the flash memory devices;
> +* to deploy the actual production images on the hardware;
> +* or because the target is not equipped with memory storage;
> +* ...
> +
> +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:
> +
> +* TFTP boot
> +* NFS boot
> +* PXE boot (x86-specific)
> +
> +
> +TFTP boot
> +^^^^^^^^^
> +
> +Depending on the bootloader installed on the target, it may be
> +possible to download the kernel image through the network, using the
> +TFTP protocol, loading it in RAM, then jump into it.
> +
> +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
> +
> +
> +NFS boot
> +^^^^^^^^
> +
> +Loading the kernel over NFS
> ++++++++++++++++++++++++++++
> +
> +Depending on the bootloader installed on the target, it may be
> +possible to download the kernel image through the network, using the
> +NFS protocol, loading it in RAM, then jump into it.
> +
> +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
> +
> +NFS root filesystem mounted on +/+
> +++++++++++++++++++++++++++++++++++

"NFS root filesystem mounted on /" seems a bit redundant, no?

> +
> +The idea is to mount +/+ using a network shared folder from an
> +http://tldp.org/HOWTO/NFS-HOWTO/index.html[NFS] server
> +(usually on the host development machine).
> +
> +To enable the NFS boot, you should select the _tar root filesystem_
> +option in the _Filesystem images_ menu.
> +
> +The target kernel needs at least the following options:
> +
> +* NFS filesystem support (+CONFIG_NFS_FS+);
> +
> +* Root filesystem on NFS (+CONFIG_ROOT_NFS+);
> +
> +* Ethernet (+CONFIG_NET_ETHERNET+);
> +
> +* The ethernet driver for the target network interface;
> +
> +* IP: kernel level autoconfiguration. This includes:
> +
> +  * +CONFIG_IP_PNP+;
> +  * +CONFIG_IP_PNP_BOOTTP+;
> +  * +CONFIG_IP_PNP_DHCP+.
> +
> +After a complete build, just run the following command to setup the
> +NFS root directory on the server:
> +
> +-------------------
> +sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir
> +-------------------
> +
> +Make sure the NFS root location appears in the +/etc/exports+ file,
> +and an NFS daemon is running on the server.
> +
> +After editing +/etc/exports+, you should run:
> +
> +-------------------
> +sudo exportfs -ra
> +-------------------
> +
> +To boot on a NFS root-filesystem, adjust the kernel command line
> +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.

U-Boot has gained PXE support some time ago :)

> +To fully boot on the network you need a network bootloader. This is
> +optional and you could use your classic bootloader to mount an NFS
> +rootfs.

I don't understand this paragraph. How can the bootloader mount an NFS
rootfs ?

> +http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf[PXE]
> +is a specification that has been implemented at least by
> +http://www.syslinux.org/wiki/index.php/PXELINUX[PXELINUX] and
> +http://ipxe.org/[iPXE].

And U-Boot.

> +The main idea is to have a DHCP server that provides a link to a
> +generic boot ROM that is accessible from a TFTP server.

Is DHCP really the protocol used at the root of PXE? I thought it was
BOOTP.

> +Then your target boots with it and comes back to the TFTP server to
> +get the specific stuff (for instance its boot menu).

"the specific stuff" doesn't sound really precise.

> +Here are some hints on how to setup this:

"set this up" ?

> +
> +* http://www.digitalpeer.com/id/linuxnfs
> +
> +
> +Deploying images on removable media
> +-----------------------------------
> +
> +How the target device is close to the actual hardware, 

Huh?

> so Buildroot
> +cannot provides any information how to achieve it for every single

provides -> provide

"it" ?

> +target. For boards that use the same processor as one of the boards
> +supported by Buildroot, the 'readme.txt' can be a good starting point.
> +
> +In addition, Buildroot provides tools that run on your host that can
> +help generating bootable media or booting a device over USB, serial or
> +the network.
> +
> +[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.

source trees of what?

> +
> +
> +Preparing a bootable raw disk file for virtualization
> +-----------------------------------------------------
> +
> +[NOTE]
> +This section is mostly x86 target specific.
> +
> +If you plan to use virtual machines, or to copy a binary bootable
> +image to your target, you may need to create a _disk image_.
> +
> +To create a bootable raw _disk image_ file, you will need to:
> +
> +* create an empty file with the +dd+ command;
> +
> +* edit the partition table of this _disk image_ file using some tools
> +  like +fdisk+ (be careful when using +fdisk+; mis-usage can damage
> +  the host machine. Look at its manpage before using it;

The parenthesis is never closed.

> +
> +* 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];

This isn't clear enough, at least to me.

> +
> +* 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.
> +
> +
> +Deploying images in emulators
> +-----------------------------
> +
> +Buildroot comes with a set of configurations for various
> +architectures running in http://wiki.qemu.org/Main_Page['Qemu'], or
> +http://www.linaro.org/engineering/engineering-projects/armv8['Foundation_v8']
> +(an AArch64 emulator).
> +
> +These configurations are stored under the 'board/qemu/<target name>'
> +and 'board/arm/foundation-v8' directories.
> +
> +Each of these configurations has a 'defconfig' and comes with a
> ++readme.txt+ file providing details to use the built images with
> +the emulator.
> +
> +They are regularly tested and maintained by the Buildroot core
> +developers.
> +
> +If you built one of these configurations and have 'Qemu' or
> +'Foundation_v8' installed on your host machine, booting the images
> +should be straight forward.
> +
> +
> +Chroot'ing into target 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;

A reference would be good here.

> +* Buildroot does not currently provide +host-qemu+ nor +binfmt+
> +  correctly built and set for that kind of use. This usage is beyond
> +  Buildroot scope.
> diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
> index 9ae658e..f179199 100644
> --- a/docs/manual/manual.txt
> +++ b/docs/manual/manual.txt
> @@ -21,6 +21,8 @@ include::starting-up.txt[]
>  
>  include::working-with.txt[]
>  
> +include::deploying-images.txt[]
> +
>  include::faq-troubleshooting.txt[]
>  
>  include::known-issues.txt[]
> @@ -31,8 +33,6 @@ include::developer-guide.txt[]
>  
>  include::legal-notice.txt[]
>  
> -include::beyond-buildroot.txt[]
> -
>  include::get-involved.txt[]
>  
>  include::contribute.txt[]
> diff --git a/docs/manual/using.txt b/docs/manual/using.txt
> index de29ad6..783370d 100644
> --- a/docs/manual/using.txt
> +++ b/docs/manual/using.txt
> @@ -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

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH 09/12] manual: rework Deploying images chapter

[Thomas De Schampheleire]

Hi,

On Fri, Oct 18, 2013 at 10:31 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> 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. <contact@team-ard.com>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ---
> changes v3 -> v4:
> - misc. typo fixes and rewording (Arnout)
> - rephrasing (ThomasDS)
> - minor rewording
> - reorder the chapter (Arnout, ThomasDS)
>
> changes v2 -> v3:
> - typos and minor rewordings (ThomasDS and Arnout)
> - 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 <s.martin49@gmail.com>
> ---
>  docs/manual/beyond-buildroot.txt |  41 ------
>  docs/manual/deploying-images.txt | 291 +++++++++++++++++++++++++++++++++++++++
>  docs/manual/manual.txt           |   4 +-
>  docs/manual/using.txt            |   3 +-
>  4 files changed, 295 insertions(+), 44 deletions(-)
>  delete mode 100644 docs/manual/beyond-buildroot.txt
>  create mode 100644 docs/manual/deploying-images.txt
>

Just noticed this section:
http://buildroot.uclibc.org/downloads/manual/manual.html#faq-why-not-use-target-as-chroot
which I think at a minimum should refer to the chroot section inside
the Deploying chapter. Maybe part of the text should even be moved.

Best regards,
Thomas

[Buildroot] [PATCH 10/12] manual: customize-toolchain.txt: update internal backend section

[Samuel Martin]

Mention all supported C libraries by the internal Buildroot toolchain
backend.

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/customize-toolchain.txt | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/manual/customize-toolchain.txt b/docs/manual/customize-toolchain.txt
index 841dbfd..31c9140 100644
--- a/docs/manual/customize-toolchain.txt
+++ b/docs/manual/customize-toolchain.txt
@@ -31,14 +31,19 @@ set the environment variable BR_DEBUG_WRAPPER to either one of:
 Using the internal Buildroot toolchain backend
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The internal Buildroot toolchain backend *only* allows to generate
-*http://www.uclibc.org/[uClibc]-based toolchains*.
+The internal Buildroot toolchain backend allows to generate toolchains
+based on http://www.uclibc.org/[uClibc],
+https://www.gnu.org/software/libc/[glibc] and
+http://www.eglibc.org/[eglibc].
+Generation of (e)glibc-based toolchains is still experimental in
+Buildroot.
 
-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.
 
-- 
1.8.4.1

[Buildroot] [PATCH 10/12] manual: customize-toolchain.txt: update internal backend section

[Thomas De Schampheleire]

On Fri, Oct 18, 2013 at 10:31 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> Mention all supported C libraries by the internal Buildroot toolchain
> backend.
>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>

Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

[Buildroot] [PATCH 11/12] manual: faq-troubleshooting.txt: add tips to avoid toolchain build

[Samuel Martin]

This new FAQ entry explains how speed-up the build time by avoiding to
build the toolchain (only useful when using the internal Buildroot
toolchain backend); especially how to use a toolchain built by Buildroot
as an external one.

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/faq-troubleshooting.txt | 67 +++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/docs/manual/faq-troubleshooting.txt b/docs/manual/faq-troubleshooting.txt
index 4e0612b..e86f73c 100644
--- a/docs/manual/faq-troubleshooting.txt
+++ b/docs/manual/faq-troubleshooting.txt
@@ -111,3 +111,70 @@ directory as the new root, will most likely fail.
 If you want to run the target filesystem inside a chroot, or as an NFS
 root, then use the tarball image generated in +images/+ and extract it
 as root.
+
+[[faq-how-to-avoid-rebuild-buildroot-toochain]]
+How to avoid rebuilding toolchain after +make clean+?
+-----------------------------------------------------
+
+Buildroot only builds the toolchain from sources when using the
+internal Buildroot toolchain backend.
+When the external toolchain backend is used, Buildroot just used it
+and populate the sysroot and the target tree by copying files from
+the toolchain.
+
+So, the easiest way to avoid rebuilding the toolchain is feeding a
+prebuilt one to the external toolchain backend.
+
+If you want to build and use your own toolchain, we recommend to use
+http://crosstool-ng.org[Crosstool-NG] to do so. Then just feed it as
+the prebuilt toolchain to the Buildroot's external toolchain backend.
+
+Otherwise, to avoid rebuilding the toolchain after executing +make
+clean+ (when using the internal Buildroot toolchain backend), you can
+build the toolchain in one location, then use this prebuilt toolchain.
+To do so, you can build the toolchain in some place, then use this
+prebuilt toolchain as an external toolchain in another Buildroot
+configuration. This section gives step-by-step instructions about how
+to do that:
+
+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 according to the ones set
+  for 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 *not* relocatable, so if you plan to use these toolchains
+on different machines, you will *have to* install it in the same
+location (i.e.: in +/path/to/somewhere+) on every machine.
-- 
1.8.4.1

[Buildroot] [PATCH 12/12] board: add warning to readme files explaining how to flash the target

[Samuel Martin]

Only add a warning message in readme.txt files giving intructions to
flash the target memory device.

All others boards coming with a readme.txt files explain how to
prepare a removable media or how to use the emulator.

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 board/avnet/s6lx9_microboard/readme.txt | 10 ++++++++++
 board/freescale/mpc8315erdb/readme.txt  |  8 ++++++++
 board/freescale/p1010rdb/readme.txt     |  8 ++++++++
 board/telit/evk-pro3/readme.txt         |  9 +++++++++
 4 files changed, 35 insertions(+)

diff --git a/board/avnet/s6lx9_microboard/readme.txt b/board/avnet/s6lx9_microboard/readme.txt
index 3cb2ce9..2195d72 100644
--- a/board/avnet/s6lx9_microboard/readme.txt
+++ b/board/avnet/s6lx9_microboard/readme.txt
@@ -1,3 +1,13 @@
+*************************  /!\ WARNING /!\  *************************
+The following information are given without warranty of any kind.
+
+Please refer to the the instructions provided by the target vendor.
+
+They are contributions from Buildroot users, but Buildroot developers
+do not ensure their correctness, nor maintain them.
+*************************  /!\ WARNING /!\  *************************
+
+
 This is the buildroot board support for the Avnet Spartan6 LX9 MicroBoard.
 
 The Avnet S6LX9 Microboard is a small USB-Stick sized module containing
diff --git a/board/freescale/mpc8315erdb/readme.txt b/board/freescale/mpc8315erdb/readme.txt
index f7f9c94..bb8d255 100644
--- a/board/freescale/mpc8315erdb/readme.txt
+++ b/board/freescale/mpc8315erdb/readme.txt
@@ -1,3 +1,11 @@
+*************************  /!\ WARNING /!\  *************************
+The following information are given without warranty of any kind.
+
+Please refer to the the instructions provided by the target vendor.
+
+They are contributions from Buildroot users, but Buildroot developers
+do not ensure their correctness, nor maintain them.
+*************************  /!\ WARNING /!\  *************************
 
 ******************** WARNING ********************
 The compiled U-Boot binary is intended for NAND flash only!
diff --git a/board/freescale/p1010rdb/readme.txt b/board/freescale/p1010rdb/readme.txt
index 5b56873..2af088f 100644
--- a/board/freescale/p1010rdb/readme.txt
+++ b/board/freescale/p1010rdb/readme.txt
@@ -1,3 +1,11 @@
+*************************  /!\ WARNING /!\  *************************
+The following information are given without warranty of any kind.
+
+Please refer to the the instructions provided by the target vendor.
+
+They are contributions from Buildroot users, but Buildroot developers
+do not ensure their correctness, nor maintain them.
+*************************  /!\ WARNING /!\  *************************
 
 ******************** WARNING ********************
 The compiled U-Boot binary is intended for NOR flash only!
diff --git a/board/telit/evk-pro3/readme.txt b/board/telit/evk-pro3/readme.txt
index ace9dd4..c5b0cf3 100644
--- a/board/telit/evk-pro3/readme.txt
+++ b/board/telit/evk-pro3/readme.txt
@@ -1,3 +1,12 @@
+*************************  /!\ WARNING /!\  *************************
+The following information are given without warranty of any kind.
+
+Please refer to the the instructions provided by the target vendor.
+
+They are contributions from Buildroot users, but Buildroot developers
+do not ensure their correctness, nor maintain them.
+*************************  /!\ WARNING /!\  *************************
+
 Buildroot board support for Telit EVK-PRO3 with Telit GE863-PRO3
 
 Official site:
-- 
1.8.4.1

[Buildroot] [PATCH 12/12] board: add warning to readme files explaining how to flash the target

[Thomas Petazzoni]

Dear Samuel Martin,

On Fri, 18 Oct 2013 22:31:36 +0200, Samuel Martin wrote:
> Only add a warning message in readme.txt files giving intructions to
> flash the target memory device.
> 
> All others boards coming with a readme.txt files explain how to
> prepare a removable media or how to use the emulator.
> 
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>

The current wording is quite scary, and doesn't even explain *why*
those particular board readme.txt files have such a warning. What about
just:

"""
WARNING: the below information will overwrite the platform bootloader.
Therefore, make sure you have a known-working recovery mechanism for
your platform, as we can't guarantee that the new bootloader will work.
"""

Best regards,

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [pull request] Pull request for branch sma/doc-update

[Thomas Petazzoni]

Dear Samuel Martin,

On Fri, 18 Oct 2013 22:31:24 +0200, Samuel Martin wrote:

> Another round for the manual update patch series.
> This time, I also integrate the pending patches from Thomas DS.
> 
> BTW, can someone (who has enough patchwork privileges) mark the
> following patch as superseded:
> http://patchwork.ozlabs.org/patch/214943/

I've applied the following patches from this series to the
for-peter-2013.11 branch:

 [PATCH 01/12] manual generation: check dependencies first
 [PATCH 02/12] manual generation: rename manual-txt into manual-text
 [PATCH 03/12] support: trivial fixes (typos and minor rewording) in gen-manual-lists.py
 [PATCH 05/12] manual: developer-guide.txt: cleanup non-existing source
 [PATCH 10/12] manual: customize-toolchain.txt: update internal backend section

The other patches are non-trivial and did not get any Acked-by so far.

Best regards,

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [pull request] Pull request for branch sma/doc-update

[Samuel Martin]

Hi Thomas,


2013/11/1 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

> Dear Samuel Martin,
>
> On Fri, 18 Oct 2013 22:31:24 +0200, Samuel Martin wrote:
>
> > Another round for the manual update patch series.
> > This time, I also integrate the pending patches from Thomas DS.
> >
> > BTW, can someone (who has enough patchwork privileges) mark the
> > following patch as superseded:
> > http://patchwork.ozlabs.org/patch/214943/
>
> I've applied the following patches from this series to the
> for-peter-2013.11 branch:
>
>  [PATCH 01/12] manual generation: check dependencies first
>  [PATCH 02/12] manual generation: rename manual-txt into manual-text
>  [PATCH 03/12] support: trivial fixes (typos and minor rewording) in
> gen-manual-lists.py
>  [PATCH 05/12] manual: developer-guide.txt: cleanup non-existing source
>  [PATCH 10/12] manual: customize-toolchain.txt: update internal backend
> section
>
> The other patches are non-trivial and did not get any Acked-by so far.
>
Ok, thanks.

Regards,

-- 
Samuel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20131101/4c184acb/attachment.html>

[Buildroot] [pull request] Pull request for branch sma/doc-update

[Samuel Martin]

All,


Here is a couple of fixes (patches 1 to 3, 5 and 7) and
enhancements (patches 4, 6, 8 and 9) for the maunal.


Yours,

Samuel


The following changes since commit 8a67c54c77782936b69fd062d49aa590f4f97bb3:

  netatalk: disable dtrace (2013-10-05 21:12:44 +0200)

are available in the git repository at:

  git at github.com:tSed/buildroot.git sma/doc-update

for you to fetch changes up to a2cb1b7caaa580f341abbb3788d18323c3e2e7c3:

  manual: rework Deploying images chapter (2013-10-05 21:35:55 +0200)

----------------------------------------------------------------
Samuel Martin (9):
      manual: minor update in manual generation
      manual: developer-guide.txt: cleanup non-existing source
      manual: update dependency list to build the documentation
      manual: add information about buildroot toolchain not being relocable and put some hints to use it
      manual: configure: add deprecation warning for Crosstool-NG toolchain backend
      manual: introduction.txt: enhance Buildroot presentation
      manual: get-involved.txt: fix event order
      manual: update get-involved section
      manual: rework Deploying images chapter

 docs/manual/beyond-buildroot.txt    |  41 -----
 docs/manual/configure.txt           |   9 ++
 docs/manual/customize-toolchain.txt |  72 +++++++--
 docs/manual/deploying-images.txt    | 290 ++++++++++++++++++++++++++++++++++++
 docs/manual/developer-guide.txt     |   2 -
 docs/manual/get-involved.txt        | 147 ++++++++++++++++--
 docs/manual/introduction.txt        |  40 +++++
 docs/manual/manual.mk               |  13 +-
 docs/manual/manual.txt              |   4 +-
 docs/manual/prerequisite.txt        |   5 +-
 docs/manual/using.txt               |   3 +-
 support/scripts/gen-manual-lists.py |   9 +-
 12 files changed, 552 insertions(+), 83 deletions(-)
 delete mode 100644 docs/manual/beyond-buildroot.txt
 create mode 100644 docs/manual/deploying-images.txt