Skip to contentSkip to conversation

Pull request for branch sma/doc-update

GIT PULL New Samuel Martin 3 participants 26 messages Oct 18, 2013 – Nov 6, 2013 Kbuild

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

PATCH 1/12 manual generation: check dependencies first

From: Thomas De Schampheleire <[email protected]>

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.

---
 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
docs/manual/make-tips.txt +1 -2
index 31a88bf..0159ffe 100644
@@ -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:
 
docs/manual/manual.mk +31 -1
index d092d3f..fcfe47b 100644
@@ -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
docs/manual/prerequisite.txt +4 -1
index 78ce436..729d64c 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 higher
+** +w3m+
+** +python+ with the +argparse+ module (automatically present in 2.7+ and 3.2+)
+** +dblatex+ (required for the pdf manual only)
support/dependencies/check-host-asciidoc.sh new file +36 -0
new file mode 100755
index 0000000..fc5fcba
@@ -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
Signature · 1 line
1.8.4.1
#2 lore raw

PATCH 2/12 manual generation: rename manual-txt into manual-text

In reply to Samuel Martin

From: Thomas De Schampheleire <[email protected]>

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.

---
 Makefile              | 4 ++--
 docs/manual/manual.mk | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)
Makefile +2 -2
index f266e2d..1496bd7 100644
@@ -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
docs/manual/manual.mk +1 -1
index fcfe47b..aeafd10 100644
@@ -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:
Signature · 1 line
1.8.4.1
#3 lore raw

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

In reply to Samuel Martin

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

---
 support/scripts/gen-manual-lists.py | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)
support/scripts/gen-manual-lists.py +4 -5
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.
 
         """
         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:
Signature · 1 line
1.8.4.1
#5 lore raw

PATCH 4/12 manual: move the manual rsync directory under $(O)/build/

In reply to 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.

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

---
 docs/manual/manual.mk | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)
docs/manual/manual.mk +7 -6
index aeafd10..ffc4e9a 100644
@@ -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
 
Signature · 1 line
1.8.4.1
#6 lore raw

PATCH 5/12 manual: developer-guide.txt: cleanup non-existing source

In reply to Samuel Martin
---
 docs/manual/developer-guide.txt | 2 --
 1 file changed, 2 deletions(-)
docs/manual/developer-guide.txt +0 -2
index 43272f5..8125ad5 100644
@@ -11,5 +11,3 @@ include::adding-packages.txt[]
 include::patch-policy.txt[]
 
 include::download-infra.txt[]
-
-include::board-support.txt[]
Signature · 1 line
1.8.4.1
#8 lore raw

PATCH 6/12 manual: introduction.txt: enhance Buildroot presentation

In reply to Samuel Martin

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

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

---
 docs/manual/introduction.txt | 45 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
docs/manual/introduction.txt +45 -0
index c014565..ff3607f 100644
@@ -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.
Signature · 1 line
1.8.4.1
#10 lore raw

PATCH 7/12 manual: get-involved.txt: fix event order

In reply to Samuel Martin
---
 docs/manual/get-involved.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
docs/manual/get-involved.txt +6 -4
index 8475038..9e492e6 100644
@@ -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[]
Signature · 1 line
1.8.4.1
#13 lore raw

PATCH 8/12 manual: update get-involved section

In reply to 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.

---
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)

---
 docs/manual/get-involved.txt | 162 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 152 insertions(+), 10 deletions(-)
docs/manual/get-involved.txt +152 -10
index 9e492e6..4be73f6 100644
@@ -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]
 
 
Signature · 1 line
1.8.4.1
#16 lore raw

PATCH 9/12 manual: rework Deploying images chapter

In reply to Samuel Martin

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

---
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"

---
 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
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 +291 -0

291 lines not on this page · raw message

docs/manual/manual.txt +2 -2
index 9ae658e..f179199 100644
@@ -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[]
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
Signature · 1 line
1.8.4.1
#19 lore raw

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

In reply to Samuel Martin

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

---
 docs/manual/customize-toolchain.txt | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)
docs/manual/customize-toolchain.txt +9 -4
index 841dbfd..31c9140 100644
@@ -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.
 
Signature · 1 line
1.8.4.1
#21 lore raw

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

In reply to 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.

---
 docs/manual/faq-troubleshooting.txt | 67 +++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
docs/manual/faq-troubleshooting.txt +67 -0
index 4e0612b..e86f73c 100644
@@ -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.
Signature · 1 line
1.8.4.1
#22 lore raw

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

In reply to 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.

---
 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(+)
board/avnet/s6lx9_microboard/readme.txt +10 -0
index 3cb2ce9..2195d72 100644
@@ -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
board/freescale/mpc8315erdb/readme.txt +8 -0
index f7f9c94..bb8d255 100644
@@ -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!
board/freescale/p1010rdb/readme.txt +8 -0
index 5b56873..2af088f 100644
@@ -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!
board/telit/evk-pro3/readme.txt +9 -0
index ace9dd4..c5b0cf3 100644
@@ -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:
Signature · 1 line
1.8.4.1
#4 lore raw

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

In reply to Samuel Martin

Hi Samuel,

Quoted 35 lines · Samuel Martin

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

---
 support/scripts/gen-manual-lists.py | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)
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.
 
         """
         if sub_menu:

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 +2 -4
-            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

#7 lore raw

PATCH 5/12 manual: developer-guide.txt: cleanup non-existing source

In reply to Samuel Martin
Quoted 13 lines · Samuel Martin

---
docs/manual/developer-guide.txt | 2 --

1 file changed, 2 deletions(-)
docs/manual/developer-guide.txt +0 -0
index 43272f5..8125ad5 100644
@@ -11,5 +11,3 @@ include::adding-packages.txt[]

include::patch-policy.txt[]

include::download-infra.txt[]

docs/manual/developer-guide.txt include::adding-packages.txt[] · line 15

Quoted 2 lines
docs/manual/developer-guide.txt +0 -2
-
-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

#23 lore raw

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

In reply to Samuel Martin

Dear Samuel Martin,

Quoted 7 lines · 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.

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

Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
#24 lore raw
In reply to Samuel Martin

Dear Samuel Martin,

Quoted 6 lines · Samuel Martin

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

Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
#9 lore raw

PATCH 6/12 manual: introduction.txt: enhance Buildroot presentation

In reply to Samuel Martin

Dear Samuel Martin,

Quoted 4 lines · Samuel Martin

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

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

Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
#11 lore raw

PATCH 7/12 manual: get-involved.txt: fix event order

In reply to Samuel Martin

Dear Samuel Martin,

Quoted 23 lines · Samuel Martin
---
 docs/manual/get-involved.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
docs/manual/get-involved.txt +6 -0
index 8475038..9e492e6 100644
@@ -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)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

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

Quoted 8 lines
docs/manual/get-involved.txt +0 -4
@@ -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

Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
#14 lore raw

PATCH 8/12 manual: update get-involved section

In reply to Samuel Martin

Dear Samuel Martin,

Quoted 3 lines · 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.

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

Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
#17 lore raw

PATCH 9/12 manual: rework Deploying images chapter

In reply to Samuel Martin

Dear Samuel Martin,

docs/manual/deploying-images.txt line 10

Quoted 7 lines · Samuel Martin

+[[deploying-images]]

docs/manual/deploying-images.txt new file +6 -0
+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.
"""

docs/manual/deploying-images.txt line 13

Quoted 3 lines
docs/manual/deploying-images.txt new file +3 -0
+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.

docs/manual/deploying-images.txt line 22

Quoted 9 lines
docs/manual/deploying-images.txt new file +9 -0
+
+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.

docs/manual/deploying-images.txt line 25

Quoted 2 lines
docs/manual/deploying-images.txt new file +2 -0
+* 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.

docs/manual/deploying-images.txt line 34

Quoted 8 lines
docs/manual/deploying-images.txt new file +8 -0
+* 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.

Quoted 22 lines
docs/manual/deploying-images.txt new file +22 -0
+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

docs/manual/deploying-images.txt line 67

Quoted 10 lines
docs/manual/deploying-images.txt new file +10 -0
+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.

Quoted 52 lines
docs/manual/deploying-images.txt new file +52 -0
+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:

docs/manual/deploying-images.txt line 131

Quoted 10 lines
docs/manual/deploying-images.txt new file +10 -0
+
+* 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?

Quoted 43 lines
docs/manual/deploying-images.txt new file +43 -0
+
+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]).

docs/manual/deploying-images.txt line 184

Quoted 10 lines
docs/manual/deploying-images.txt new file +10 -0
+
+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 :)

docs/manual/deploying-images.txt line 188

Quoted 3 lines
docs/manual/deploying-images.txt new file +3 -0
+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 ?

docs/manual/deploying-images.txt line 193

Quoted 4 lines
docs/manual/deploying-images.txt new file +4 -0
+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.

docs/manual/deploying-images.txt line 196

Quoted 2 lines
docs/manual/deploying-images.txt new file +2 -0
+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.

docs/manual/deploying-images.txt line 198

Quoted 2 lines
docs/manual/deploying-images.txt new file +2 -0
+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.

Quoted 1 line

+Here are some hints on how to setup this:

"set this up" ?

docs/manual/deploying-images.txt

Quoted 8 lines
docs/manual/deploying-images.txt new file +8 -0
+
+* http://www.digitalpeer.com/id/linuxnfs
+
+
+Deploying images on removable media
+-----------------------------------
+
+How the target device is close to the actual hardware, 

Huh?

Quoted 2 lines

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

provides -> provide

"it" ?

docs/manual/deploying-images.txt line 219

Quoted 10 lines
docs/manual/deploying-images.txt new file +10 -0
+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?

Quoted 8 lines
docs/manual/deploying-images.txt new file +8 -0
+
+
+Preparing a bootable raw disk file for virtualization
+-----------------------------------------------------
+
+[NOTE]
+This section is mostly x86 target specific.
+

docs/manual/deploying-images.txt line 237

Quoted 10 lines
docs/manual/deploying-images.txt new file +10 -0
+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.

docs/manual/deploying-images.txt line 244

Quoted 7 lines
docs/manual/deploying-images.txt new file +7 -0
+
+* 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.

Quoted 33 lines
docs/manual/deploying-images.txt new file +33 -0
+
+* 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
+----------------------------

docs/manual/deploying-images.txt line 287

Quoted 10 lines
docs/manual/deploying-images.txt new file +10 -0
+
+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.

Quoted 30 lines
docs/manual/deploying-images.txt new file +3 -0
+* 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 9ae658e..f179199 100644
@@ -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[]
docs/manual/using.txt +0 -0
index de29ad6..783370d 100644

docs/manual/using.txt Buildroot output is stored in a single directory, +output/+. · line 74

Quoted 9 lines
docs/manual/using.txt +2 -1
@@ -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

Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
#25 lore raw
In reply to Thomas Petazzoni

Hi Thomas,

2013/11/1 Thomas Petazzoni <[email protected]>

Quoted 22 lines

Dear Samuel Martin,

Quoted 6 lines · Samuel Martin

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

Quoted 2 lines

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

Ok, thanks.

Regards,

Signature · 4 lines
Samuel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20131101/4c184acb/attachment.html>
#12 lore raw

PATCH 7/12 manual: get-involved.txt: fix event order

In reply to Thomas Petazzoni

Thomas,

2013/11/1 Thomas Petazzoni <[email protected]>

Quoted 41 lines

Dear Samuel Martin,

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

Quoted 10 lines · Samuel Martin
---
 docs/manual/get-involved.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
docs/manual/get-involved.txt +0 -0
index 8475038..9e492e6 100644
@@ -117,6 +117,12 @@ Currently, this page is mainly used as a

_todo-list_.

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

Quoted 7 lines
docs/manual/get-involved.txt +4 -0
 Events
 ------
 
+Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Announcement & agenda thread:

http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]

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

Quoted 1 line
docs/manual/get-involved.txt +1 -0
+* Report:

http://lists.busybox.net/pipermail/buildroot/2012-February/050371.html[]

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

Quoted 2 lines
docs/manual/get-involved.txt +1 -0
+
 Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 -

Barcelona)

Quoted 1 line

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

Quoted 2 lines
docs/manual/get-involved.txt +0 -0
@@ -127,8 +133,4 @@ Buildroot presentation at LSM 2012 (July 12-14, 2012

- Geneva)

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

Quoted 2 lines
docs/manual/get-involved.txt +0 -0
 * Announcement:

http://lists.busybox.net/pipermail/buildroot/2012-May/053845.html[]

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

Quoted 5 lines
docs/manual/get-involved.txt +0 -3
-Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Announcement & agenda thread:

http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]

Quoted 8 lines

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

Quoted 1 line
docs/manual/get-involved.txt +0 -1
-* 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,

Signature · 4 lines
Samuel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20131102/1dd21ee7/attachment.html>
#15 lore raw

PATCH 8/12 manual: update get-involved section

In reply to Thomas Petazzoni

Thomas, all,

2013/11/1 Thomas Petazzoni <[email protected]>

Quoted 8 lines

Dear Samuel Martin,

Quoted 3 lines · 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.

Quoted 9 lines

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,

Signature · 4 lines
Samuel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20131102/dee87501/attachment.html>
#18 lore raw

PATCH 9/12 manual: rework Deploying images chapter

In reply to Samuel Martin

Hi,

Quoted 37 lines · Samuel Martin

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

---
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"

Quoted 9 lines
---
 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