[Buildroot] [PATCH 0/5] Manual updates

[Buildroot] [PATCH 0/5] Manual updates

[Samuel Martin]

Hi all,

Here is a small patch series about the manual integrating the following
patches for patchwork:
- http://patchwork.ozlabs.org/patch/214943/
- http://patchwork.ozlabs.org/patch/216485/
- http://patchwork.ozlabs.org/patch/232024/

I had to rework some of them to get them cleanly merged the git tree,
the most noticeable thing is the split patch 214943.

Regards,


Samuel

--

A.R.D (2):
  manual: update beyond Buildroot section
  manual: add tips to build manual

Samuel Martin (1):
  manual: minor formating fixes

Stephan Hoffmann (1):
  Docu: Add LIBFOO_EXTRACT_CMDS

Vinicius Tinti (1):
  manual: add patch revision and versioning section

 docs/manual/adding-packages-generic.txt |  18 +++-
 docs/manual/beyond-buildroot.txt        | 162 +++++++++++++++++++++++++++++---
 docs/manual/contribute.txt              |  66 +++++++++++++
 docs/manual/make-tips.txt               |  20 +++-
 docs/manual/using.txt                   |   3 +-
 docs/manual/working-with.txt            |   5 +
 6 files changed, 254 insertions(+), 20 deletions(-)

--
1.8.3.4

[Buildroot] [PATCH 1/5] Docu: Add LIBFOO_EXTRACT_CMDS

[Samuel Martin]

From: Stephan Hoffmann <sho@relinux.de>

[Samuel: add precision about non-tar archive]
Signed-off-by: Stephan Hoffmann <sho@relinux.de>
Acked-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/adding-packages-generic.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
index faf70b1..a6f9565 100644
--- a/docs/manual/adding-packages-generic.txt
+++ b/docs/manual/adding-packages-generic.txt
@@ -358,6 +358,10 @@ LIBFOO_VERSION = 2.32
 Now, the variables that define what should be performed at the
 different steps of the build process.
 
+* +LIBFOO_EXTRACT_CMDS+ lists the actions to be performed to
+  extract the package in case no standard method applies
+  (ie. non-tar archive).
+
 * +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to
   configure the package before its compilation.
 
-- 
1.8.3.4

[Buildroot] [PATCH 2/5] manual: add patch revision and versioning section

[Samuel Martin]

From: Vinicius Tinti <viniciustinti@gmail.com>

Improve the contribute manual section by adding an explanation about patch
review and version.

The section now provides advices in how to respond maintainers requests and how
to proceed on replying them.

[Samuel: minor rewordings + misc. formating fixes]
Signed-off-by: Vinicius Tinti <viniciustinti@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/contribute.txt | 66 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
index 0106df0..6d2cf5b 100644
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -62,6 +62,72 @@ Make sure posted *patches are not line-wrapped*, otherwise they cannot
 easily be applied. In such a case, fix your e-mail client, or better,
 use +git send-email+ to send your patches.
 
+Patch revision
+~~~~~~~~~~~~~~
+
+Sometimes, changes will be requested to your patch before getting merged.
+Whenever it happens, the new revision of the pacthset should include a
+changelog of the modifications between each submission, and being reposted,
+as much as possible, as response to the original thread.
+
+Patch revision changelog
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+When editing your commit, below the +signed-off-by+ section, add +---+, then
+and your changelog below.
+
+Although the changelog will be visible for the reviewers in the mail
+thread, as well as in http://patchwork.buildroot.org[patchwork], +git+
+will automatically ignore lines below +---+ when the patch will be
+merged.
+
+For longer series, a per-patch changelog should be placed in each commit,
+and the cover letter must contain a summary of these changes.
+
+The following suggested layout example is not mandatory.
+
+---------------
+Patch title less than 80-character length
+
+Some paragraph describing what the patch does and why
+
+Signed-off-by John Doe <john.doe@noname.org>
+
+---
+Changes v2 -> v3:
+  - foo bar  (suggested by Jane)
+  - bar buz
+
+Changes v1 -> v2:
+  - alpha bravo  (suggested by John)
+  - charly delta
+---------------
+
+Any patch revision should include the version number. The version number
+is simply composed by the letter +v+ followed by an +integer+ greater or
+equal 2 (two) (i.e. "PATCH v2", "PATCH v3" ...).
+
+This can be easly handle in +git-format-patch+ command by using the option
++--subject-prefix+:
+
+---------------------
+ $ git format-patch --subject-prefix "PATCH v4" -M -n -s -o outgoing origin/master
+---------------------
+
+Keeping patch revision in the same thread
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Mail clients will handle this automatically reply in the same thread but
++git+ won't.
+
+Hence the +--in-reply-to+ option in +git-send-email+ must be used.
+Get the last +Message-ID+ (it can be found your mail client by accessing
+the raw mail). Then use this message id to send your revision patch:
+
+---------------------
+ $ git send-email --to buildroot at busybox.net --in-reply-to mymsgid at noname.org outgoing/*
+---------------------
+
 Reviewing/Testing patches
 -------------------------
 
-- 
1.8.3.4

[Buildroot] [PATCH 2/5] manual: add patch revision and versioning section

[Thomas Petazzoni]

Dear Samuel Martin,

On Tue,  6 Aug 2013 23:36:21 +0200, Samuel Martin wrote:
> From: Vinicius Tinti <viniciustinti@gmail.com>
> 
> Improve the contribute manual section by adding an explanation about patch
> review and version.
> 
> The section now provides advices in how to respond maintainers requests and how
> to proceed on replying them.

I am not entirely happy with the below text, as it doesn't make the
difference between a simple patch, in which the changelog is typically
included below the '---' sign, and a patch series, where there is the
notion of cover letter that usually includes the changelog.

> +Sometimes, changes will be requested to your patch before getting merged.

This is rather strange way of starting this section, me thinks.

> +Whenever it happens, the new revision of the pacthset should include a

patchset.

> +changelog of the modifications between each submission, and being reposted,
> +as much as possible, as response to the original thread.

Except that this clearly isn't the most common practice in the
Buildroot community. We generally post updated versions of patches as a
new thread. I'm not saying this is good or bad, I'm just observing the
current common practice, and I'm seeing that it doesn't match what this
documentation is saying.

> +Patch revision changelog
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +When editing your commit, below the +signed-off-by+ section, add +---+, then

Signed-off-by.

> +and your changelog below.
> +
> +Although the changelog will be visible for the reviewers in the mail
> +thread, as well as in http://patchwork.buildroot.org[patchwork], +git+
> +will automatically ignore lines below +---+ when the patch will be
> +merged.
> +
> +For longer series, a per-patch changelog should be placed in each commit,
> +and the cover letter must contain a summary of these changes.
> +
> +The following suggested layout example is not mandatory.

Why? It *is* mandatory.

> +
> +---------------
> +Patch title less than 80-character length
> +
> +Some paragraph describing what the patch does and why

Some more paragraph giving some more details.

And yet another paragraph giving more details.

> +
> +Signed-off-by John Doe <john.doe@noname.org>
> +
> +---
> +Changes v2 -> v3:
> +  - foo bar  (suggested by Jane)
> +  - bar buz
> +
> +Changes v1 -> v2:
> +  - alpha bravo  (suggested by John)
> +  - charly delta
> +---------------
> +
> +Any patch revision should include the version number. The version number
> +is simply composed by the letter +v+ followed by an +integer+ greater or
> +equal 2 (two) (i.e. "PATCH v2", "PATCH v3" ...).
> +
> +This can be easly handle in +git-format-patch+ command by using the option
> ++--subject-prefix+:
> +
> +---------------------
> + $ git format-patch --subject-prefix "PATCH v4" -M -n -s -o outgoing origin/master
> +---------------------

-n is the default, maybe we could remove it.
-o outgoing is not really needed here

> +Keeping patch revision in the same thread
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Mail clients will handle this automatically reply in the same thread but
> ++git+ won't.
> +
> +Hence the +--in-reply-to+ option in +git-send-email+ must be used.
> +Get the last +Message-ID+ (it can be found your mail client by accessing
> +the raw mail). Then use this message id to send your revision patch:
> +
> +---------------------
> + $ git send-email --to buildroot at busybox.net --in-reply-to mymsgid at noname.org outgoing/*
> +---------------------

See my earlier comment about this.

Thomas
-- 
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com

[Buildroot] [PATCH 2/5] manual: add patch revision and versioning section

[Samuel Martin]

Hi Thomas, all,

2013/8/7 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>:
> Dear Samuel Martin,
>
> On Tue,  6 Aug 2013 23:36:21 +0200, Samuel Martin wrote:
>> From: Vinicius Tinti <viniciustinti@gmail.com>
>>
>> Improve the contribute manual section by adding an explanation about patch
>> review and version.
>>
>> The section now provides advices in how to respond maintainers requests and how
>> to proceed on replying them.
>
> I am not entirely happy with the below text, as it doesn't make the
> difference between a simple patch, in which the changelog is typically
> included below the '---' sign, and a patch series, where there is the
> notion of cover letter that usually includes the changelog.
Right, I'll rework it.

>
>> +Sometimes, changes will be requested to your patch before getting merged.
>
> This is rather strange way of starting this section, me thinks.
Same to me...
I'll see how i can improve this.

>
>> +Whenever it happens, the new revision of the pacthset should include a
>
> patchset.
done

>
>> +changelog of the modifications between each submission, and being reposted,
>> +as much as possible, as response to the original thread.
>
> Except that this clearly isn't the most common practice in the
> Buildroot community. We generally post updated versions of patches as a
> new thread. I'm not saying this is good or bad, I'm just observing the
> current common practice, and I'm seeing that it doesn't match what this
> documentation is saying.
I'm  not sure either.
imho, enforcing this usage will be more useful for some mail clients
(gmail does a
pretty good job sorting mail with the same subject tm) or gmane, than
it will fit or
improve anything in our workflow.

I wonder whether we should keep this part; I don't feel comfortable
rewriting some
git manpages in the BR manual...
For such advanced git options, I tend to redirect people to the git manpages.

>
>> +Patch revision changelog
>> +^^^^^^^^^^^^^^^^^^^^^^^^
>> +
>> +When editing your commit, below the +signed-off-by+ section, add +---+, then
>
> Signed-off-by.
done

>
>> +and your changelog below.
>> +
>> +Although the changelog will be visible for the reviewers in the mail
>> +thread, as well as in http://patchwork.buildroot.org[patchwork], +git+
>> +will automatically ignore lines below +---+ when the patch will be
>> +merged.
>> +
>> +For longer series, a per-patch changelog should be placed in each commit,
>> +and the cover letter must contain a summary of these changes.
>> +
>> +The following suggested layout example is not mandatory.
>
> Why? It *is* mandatory.
Well, how about "the recommended layout"?
This is something we try to setup as standard in the BR community,
but I'm not sure everyone follows it (even me!).

>
>> +
>> +---------------
>> +Patch title less than 80-character length
>> +
>> +Some paragraph describing what the patch does and why
>
> Some more paragraph giving some more details.
>
> And yet another paragraph giving more details.
done

>
>> +
>> +Signed-off-by John Doe <john.doe@noname.org>
>> +
>> +---
>> +Changes v2 -> v3:
>> +  - foo bar  (suggested by Jane)
>> +  - bar buz
>> +
>> +Changes v1 -> v2:
>> +  - alpha bravo  (suggested by John)
>> +  - charly delta
>> +---------------
>> +
>> +Any patch revision should include the version number. The version number
>> +is simply composed by the letter +v+ followed by an +integer+ greater or
>> +equal 2 (two) (i.e. "PATCH v2", "PATCH v3" ...).
>> +
>> +This can be easly handle in +git-format-patch+ command by using the option
>> ++--subject-prefix+:
>> +
>> +---------------------
>> + $ git format-patch --subject-prefix "PATCH v4" -M -n -s -o outgoing origin/master
>> +---------------------
>
> -n is the default, maybe we could remove it.
> -o outgoing is not really needed here
ok for "-n", but I keep "-o ..." to keep consistency with the rest of
the section.

>
>> +Keeping patch revision in the same thread
>> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> +
>> +Mail clients will handle this automatically reply in the same thread but
>> ++git+ won't.
>> +
>> +Hence the +--in-reply-to+ option in +git-send-email+ must be used.
>> +Get the last +Message-ID+ (it can be found your mail client by accessing
>> +the raw mail). Then use this message id to send your revision patch:
>> +
>> +---------------------
>> + $ git send-email --to buildroot at busybox.net --in-reply-to mymsgid at noname.org outgoing/*
>> +---------------------
>
> See my earlier comment about this.
>
> Thomas
> --
> Thomas Petazzoni, Free Electrons
> Kernel, drivers, real-time and embedded Linux
> development, consulting, training and support.
> http://free-electrons.com

Thanks,

Regards,


-- 
Samuel

[Buildroot] [PATCH 2/5] manual: add patch revision and versioning section

[Thomas De Schampheleire]

On Wed, Aug 7, 2013 at 7:41 PM, Samuel Martin <s.martin49@gmail.com> wrote:

>
>>
>>> +changelog of the modifications between each submission, and being reposted,
>>> +as much as possible, as response to the original thread.
>>
>> Except that this clearly isn't the most common practice in the
>> Buildroot community. We generally post updated versions of patches as a
>> new thread. I'm not saying this is good or bad, I'm just observing the
>> current common practice, and I'm seeing that it doesn't match what this
>> documentation is saying.
> I'm  not sure either.
> imho, enforcing this usage will be more useful for some mail clients
> (gmail does a
> pretty good job sorting mail with the same subject tm) or gmane, than
> it will fit or
> improve anything in our workflow.

In fact, when people send new versions of patches as reply to an
earlier version, I find it more annoying in gmail, because the subject
line still shows the old patch version. Hence, one cannot see whether
there is just another remark on the previous patch version, or a new
patch has been posted.

I haven't noticed any of the major contributors use this reply-to for
new patch versions, so I also think this should not be described
as-such in the manual. Unless of course there is a consensus to change
this behavior. From my side, I would only see it as an annoyance, so
would vote against changing it.

Best regards,
Thomas

[Buildroot] [PATCH 2/5] manual: add patch revision and versioning section

[Thomas De Schampheleire]

Hi,

In addition to the spelling changes noticed by Thomas:

Op 6-aug.-2013 23:37 schreef "Samuel Martin" <s.martin49@gmail.com> het
volgende:
>
> From: Vinicius Tinti <viniciustinti@gmail.com>
>
> Improve the contribute manual section by adding an explanation about patch
> review and version.
>
> The section now provides advices in how to respond maintainers requests
and how
> to proceed on replying them.
>
> [Samuel: minor rewordings + misc. formating fixes]
> Signed-off-by: Vinicius Tinti <viniciustinti@gmail.com>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
> ---
>  docs/manual/contribute.txt | 66
++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 66 insertions(+)
>
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> index 0106df0..6d2cf5b 100644
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -62,6 +62,72 @@ Make sure posted *patches are not line-wrapped*,
otherwise they cannot
>  easily be applied. In such a case, fix your e-mail client, or better,
>  use +git send-email+ to send your patches.
>
> +Patch revision
> +~~~~~~~~~~~~~~
> +
> +Sometimes, changes will be requested to your patch before getting merged.
> +Whenever it happens, the new revision of the pacthset should include a
> +changelog of the modifications between each submission, and being
reposted,
> +as much as possible, as response to the original thread.
> +
> +Patch revision changelog
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +When editing your commit, below the +signed-off-by+ section, add +---+,
then
> +and your changelog below.
> +
> +Although the changelog will be visible for the reviewers in the mail
> +thread, as well as in http://patchwork.buildroot.org[patchwork], +git+
> +will automatically ignore lines below +---+ when the patch will be
> +merged.
> +
> +For longer series, a per-patch changelog should be placed in each commit,
> +and the cover letter must contain a summary of these changes.
> +
> +The following suggested layout example is not mandatory.
> +
> +---------------
> +Patch title less than 80-character length
> +
> +Some paragraph describing what the patch does and why
> +
> +Signed-off-by John Doe <john.doe@noname.org>
> +
> +---
> +Changes v2 -> v3:
> +  - foo bar  (suggested by Jane)
> +  - bar buz
> +
> +Changes v1 -> v2:
> +  - alpha bravo  (suggested by John)
> +  - charly delta
> +---------------
> +
> +Any patch revision should include the version number. The version number
> +is simply composed by the letter +v+ followed by an

s/composed by/composed of/

+integer+ greater or
> +equal 2 (two) (i.e. "PATCH v2", "PATCH v3" ...

s/equal/equal to/

> +
> +This can be easly handle in +git-format-patch+ command by using the
option

This can be easily handled with git-format-patch by using the option

> ++--subject-prefix+:
> +
> +---------------------
> + $ git format-patch --subject-prefix "PATCH v4" -M -n -s -o outgoing
origin/master
> +---------------------
> +
> +Keeping patch revision in the same thread
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Mail clients will handle this automatically reply in the same thread but
> ++git+ won't.
> +
> +Hence the +--in-reply-to+ option in +git-send-email+ must be used.
> +Get the last +Message-ID+ (it can be found your mail client by accessing
> +the raw mail). Then use this message id to send your revision patch:

In the past I suggested an alternate phrasing for this, see:

http://lists.busybox.net/pipermail/buildroot/2013-March/070012.html


> +
> +---------------------
> + $ git send-email --to buildroot at busybox.net --in-reply-to
mymsgid at noname.org outgoing/*
> +---------------------
> +
>  Reviewing/Testing patches
>  -------------------------
>

Best regards,

Thomas
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20130807/dcc88306/attachment.html>

[Buildroot] [PATCH 2/5] manual: add patch revision and versioning section

[Samuel Martin]

Hi Thomas, all,

2013/8/7 Thomas De Schampheleire <patrickdepinguin+buildroot@gmail.com>:
All fixed.
Thanks for the review.

Regards,

-- 
Samuel

[Buildroot] [PATCH 3/5] manual: update beyond Buildroot section

[Samuel Martin]

From: "A.R.D" <contact@team-ard.com>

Add details about how to boot images generated by Buildroot
(in VM, over network (NFS/PXE/...).

Signed-off-by: A.R.D. <contact@team-ard.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>

---
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 | 162 +++++++++++++++++++++++++++++++++++----
 docs/manual/using.txt            |   3 +-
 docs/manual/working-with.txt     |   5 ++
 3 files changed, 156 insertions(+), 14 deletions(-)

diff --git a/docs/manual/beyond-buildroot.txt b/docs/manual/beyond-buildroot.txt
index a0d4af0..ec63048 100644
--- a/docs/manual/beyond-buildroot.txt
+++ b/docs/manual/beyond-buildroot.txt
@@ -1,33 +1,169 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
+[[beyond-buildroot]]
 Beyond Buildroot
 ================
 
-Boot the generated images
--------------------------
+After having run Buildroot, you will have a brand new filesystem for
+your target exported in the 'output/images' directory. The content of
+this folder depends of the option you chose during buildroot
+configuration in the +Filesystem images+ submenu.
 
-NFS boot
-~~~~~~~~
+So what's next? You will probably want to :
 
-To achieve NFS-boot, enable _tar root filesystem_ in the _Filesystem
-images_ menu.
+* deploy and/or install the freshly built images on the target to test
+  it;
 
-After a complete build, just run the following commands to setup the
-NFS-root directory:
+* test the images in emulators (http://wiki.qemu.org/Main_Page[Qemu],
+  http://www.linaro.org/engineering/engineering-projects/armv8[Foundation_v8]
+  --- a AArch64 emulator, ...).
+  By default, Buildroot comes with a set of configurations for vairous
+  architectures running in 'Qemu'.
+  These configurations are stored under the 'board/qemu' directory.
+  Each of these configurations comes with a +readme.txt+ file providing
+  details to use the built images with 'Qemu'. They are regularly tested
+  and maintained by the Buildroot core developers;
+
+* generate a virtual disk to dump to real system or to use in
+  virtualisation systems (http://wiki.qemu.org/Main_Page[Qemu],
+  https://www.virtualbox.org/[VirtualBox], ...).
+  This mostly useful for 'x86' and 'x86_64' targets.
+
+
+This stuff is really depending on each project and hardware, so we
+cannot describe every solution here. This is where Buildroot's work
+ends.
+
+The following section aims at guiding new user on what to do next to
+avoid staying in the dark.
+
+This is *not* an exact guide on how to precisely do what is described.
+Please take the time to have a look to refered projets to get those
+details.
+
+
+Prepare a bootable raw disk file for virtualisation
+---------------------------------------------------
+
+If you plan to use virtual machines, or to copy a binary bootable image
+to your target, you may need to create an _disk image_.
+
+To create a bootable raw disk 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+;
+
+* install the MBR;
+
+* create virtual devices in +/dev+ pointing to your virtual disk
+  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 your virtual disk with the +mount+
+  command;
+
+* populate the root partition by extracting into it the rootfs tarball
+  generated by Buildroot;
+
+
+Network boot
+------------
+
+Some device does not have external memory and need to be booted to be
+able to install the rootfs.
+
+A nice way of doing this is booting from network. If the device allows
+you to do that, you will be able to:
+
+* test the *in-progress* rootfs without installing it on your system
+  (it prevents from premature wear of the flash memories);
+
+* create a second Buildroot project with a minimalist installer that
+  will install your production rootfs on the target.
+
+Network bootloaders (PXE,iPXE)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To fully boot on the network you need a network bootloader. This is
+optionnal and you could use your classic bootloader to mount a 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 provide a link to a generic
+boot ROM that is accessible from a simple FTP server (TFTP).
+Then your target boots with it and come back to the TFTP server to get
+the specific stuff (for instance it's boot menu).
+
+Here is some hints on how to setup this:
+http://www.digitalpeer.com/id/linuxnfs
+
+NFS rootfs mount on +/+
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The idea is to mount +/+ using a network shared folder from a
+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_ submenu.
+
+The embedded kernel needs at least the following option:
+
+* NFS filesystem support (CONFIG_NFS_FS);
+
+* Root file system on NFS (CONFIG_ROOT_NFS);
+
+* Ethernet (CONFIG_NET_ETHERNET);
+
+* The ethernet driver for the embedded network card;
+
+* 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
 -------------------
 
-Remember to add this path to +/etc/exports+.
+Make sure this location appears in the +/etc/exports+ file, and a _nfs_
+daemon is running onthe server.
+
+After editing +/etc/exports+, you should run:
+
+-------------------
+sudo exportfs
+-------------------
+
+Then, you can execute a NFS-boot from your target. Here is a documentation hints:
+// FIXME:
+//  - sort links
+http://wiki.openelec.tv/index.php?title=Network_Boot_-_NFS
+http://www.tldp.org/HOWTO/NFS-Root-4.html
+https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt
+http://www.solid-run.com/mw/index.php/Setup_NFS_boot
+http://bill.station51.net/index.php?post/2010/06/16/HOWTO%3A-Booting-from-NFS-using-U-Boot
+https://wiki.archlinux.org/index.php/NFS
+http://www.linux-france.org/article/serveur/doc_concentree/doc_concentree-15.html
+
 
-Then, you can execute a NFS-boot from your target.
 
-Chroot
-------
+Chroot into generated image
+---------------------------
 
-If you want to chroot in a generated image, then there are few thing
+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;
diff --git a/docs/manual/using.txt b/docs/manual/using.txt
index de29ad6..e59a449 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 uisng/booting
+  the images, refer to the xref:beyond-buildroot[].
 
 * +build/+ where all the components except for the cross-compilation
   toolchain are built (this includes tools needed to run Buildroot on
diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
index 4432b54..56fe238 100644
--- a/docs/manual/working-with.txt
+++ b/docs/manual/working-with.txt
@@ -27,3 +27,8 @@ interested in hacking it to add:
 
 * new board support: refer to the
   xref:customize-store-board-support[Developer guide].
+
+Using/Booting Buildroot images
+------------------------------
+
+Refer to the xref:beyond-buildroot[].
-- 
1.8.3.4

[Buildroot] [PATCH 3/5] manual: update beyond Buildroot section

[Thomas De Schampheleire]

On Tue, Aug 6, 2013 at 11:36 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: "A.R.D" <contact@team-ard.com>
>
> Add details about how to boot images generated by Buildroot
> (in VM, over network (NFS/PXE/...).
>
> Signed-off-by: A.R.D. <contact@team-ard.com>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ---
> 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 | 162 +++++++++++++++++++++++++++++++++++----
>  docs/manual/using.txt            |   3 +-
>  docs/manual/working-with.txt     |   5 ++
>  3 files changed, 156 insertions(+), 14 deletions(-)
>
> diff --git a/docs/manual/beyond-buildroot.txt b/docs/manual/beyond-buildroot.txt
> index a0d4af0..ec63048 100644
> --- a/docs/manual/beyond-buildroot.txt
> +++ b/docs/manual/beyond-buildroot.txt
> @@ -1,33 +1,169 @@
>  // -*- mode:doc; -*-
>  // vim: set syntax=asciidoc:
>
> +[[beyond-buildroot]]
>  Beyond Buildroot
>  ================
>
> -Boot the generated images
> --------------------------
> +After having run Buildroot, you will have a brand new filesystem for
> +your target exported in the 'output/images' directory. The content of
> +this folder depends of the option you chose during buildroot
> +configuration in the +Filesystem images+ submenu.
>
> -NFS boot
> -~~~~~~~~
> +So what's next? You will probably want to :
>
> -To achieve NFS-boot, enable _tar root filesystem_ in the _Filesystem
> -images_ menu.
> +* deploy and/or install the freshly built images on the target to test
> +  it;
>
> -After a complete build, just run the following commands to setup the
> -NFS-root directory:
> +* test the images in emulators (http://wiki.qemu.org/Main_Page[Qemu],
> +  http://www.linaro.org/engineering/engineering-projects/armv8[Foundation_v8]
> +  --- a AArch64 emulator, ...).
> +  By default, Buildroot comes with a set of configurations for vairous

various

> +  architectures running in 'Qemu'.
> +  These configurations are stored under the 'board/qemu' directory.
> +  Each of these configurations comes with a +readme.txt+ file providing
> +  details to use the built images with 'Qemu'. They are regularly tested
> +  and maintained by the Buildroot core developers;
> +
> +* generate a virtual disk to dump to real system or to use in
> +  virtualisation systems (http://wiki.qemu.org/Main_Page[Qemu],
> +  https://www.virtualbox.org/[VirtualBox], ...).
> +  This mostly useful for 'x86' and 'x86_64' targets.

This is ...

> +
> +
> +This stuff is really depending on each project and hardware, so we
> +cannot describe every solution here. This is where Buildroot's work
> +ends.
> +
> +The following section aims at guiding new user on what to do next to

users

> +avoid staying in the dark.
> +
> +This is *not* an exact guide on how to precisely do what is described.
> +Please take the time to have a look to refered projets to get those

referred projects

> +details.
> +
> +
> +Prepare a bootable raw disk file for virtualisation
> +---------------------------------------------------
> +
> +If you plan to use virtual machines, or to copy a binary bootable image
> +to your target, you may need to create an _disk image_.

s/an/a/

> +
> +To create a bootable raw disk 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+;
> +
> +* install the MBR;
> +
> +* create virtual devices in +/dev+ pointing to your virtual disk
> +  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 your virtual disk with the +mount+
> +  command;
> +
> +* populate the root partition by extracting into it the rootfs tarball
> +  generated by Buildroot;
> +
> +
> +Network boot
> +------------
> +
> +Some device does not have external memory and need to be booted to be
> +able to install the rootfs.

Some devices do not have ...

> +
> +A nice way of doing this is booting from network. If the device allows

from the network.

> +you to do that, you will be able to:
> +
> +* test the *in-progress* rootfs without installing it on your system
> +  (it prevents from premature wear of the flash memories);
> +
> +* create a second Buildroot project with a minimalist installer that
> +  will install your production rootfs on the target.
> +
> +Network bootloaders (PXE,iPXE)
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +To fully boot on the network you need a network bootloader. This is
> +optionnal and you could use your classic bootloader to mount a NFS

optional
an NFS rootfs   ('NFS' is pronounced 'en-ef-es' and thus needs 'an' iso of 'a')

> +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 provide a link to a generic
> +boot ROM that is accessible from a simple FTP server (TFTP).

I don't really agree with the description of TFTP as a 'simple FTP
server', as these are two unrelated protocols. I would suggest to
simply say: 'from a TFTP server.'

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

s/come/comes/
s/it's/its/

I'm not entirely happy with this explanation.
Is it really conventional to send a boot menu over tftp? The targets
I've seen directly send the executable image over, e.g. a kernel.

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

Here are some hints on how to set this up:

> +http://www.digitalpeer.com/id/linuxnfs
> +
> +NFS rootfs mount on +/+
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The idea is to mount +/+ using a network shared folder from a

an NFS server

> +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_ submenu.
> +
> +The embedded kernel needs at least the following option:

options

> +
> +* NFS filesystem support (CONFIG_NFS_FS);
> +
> +* Root file system on NFS (CONFIG_ROOT_NFS);
> +
> +* Ethernet (CONFIG_NET_ETHERNET);
> +
> +* The ethernet driver for the embedded network card;
> +
> +* 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
>  -------------------
>
> -Remember to add this path to +/etc/exports+.
> +Make sure this location appears in the +/etc/exports+ file, and a _nfs_

an nfs

> +daemon is running onthe server.

on the

> +
> +After editing +/etc/exports+, you should run:
> +
> +-------------------
> +sudo exportfs
> +-------------------
> +
> +Then, you can execute a NFS-boot from your target. Here is a documentation hints:

an NFS boot
Here is some related documentation:

> +// FIXME:
> +//  - sort links
> +http://wiki.openelec.tv/index.php?title=Network_Boot_-_NFS
> +http://www.tldp.org/HOWTO/NFS-Root-4.html
> +https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt
> +http://www.solid-run.com/mw/index.php/Setup_NFS_boot
> +http://bill.station51.net/index.php?post/2010/06/16/HOWTO%3A-Booting-from-NFS-using-U-Boot
> +https://wiki.archlinux.org/index.php/NFS
> +http://www.linux-france.org/article/serveur/doc_concentree/doc_concentree-15.html
> +
>
> -Then, you can execute a NFS-boot from your target.
>
> -Chroot
> -------
> +Chroot into generated image
> +---------------------------
>
> -If you want to chroot in a generated image, then there are few thing
> +If you want to 'chroot' in a generated image, then there are few thing

things

>  you should be aware of:
>
>  * you should setup the new root from the _tar root filesystem_ image;
> diff --git a/docs/manual/using.txt b/docs/manual/using.txt
> index de29ad6..e59a449 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 uisng/booting

using

> +  the images, refer to the xref:beyond-buildroot[].
>
>  * +build/+ where all the components except for the cross-compilation
>    toolchain are built (this includes tools needed to run Buildroot on
> diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt
> index 4432b54..56fe238 100644
> --- a/docs/manual/working-with.txt
> +++ b/docs/manual/working-with.txt
> @@ -27,3 +27,8 @@ interested in hacking it to add:
>
>  * new board support: refer to the
>    xref:customize-store-board-support[Developer guide].
> +
> +Using/Booting Buildroot images
> +------------------------------
> +
> +Refer to the xref:beyond-buildroot[].
> --

Best regards,
Thomas

[Buildroot] [PATCH 3/5] manual: update beyond Buildroot section

[Thomas Petazzoni]

Dear Samuel Martin,

On Tue,  6 Aug 2013 23:36:22 +0200, Samuel Martin wrote:
> From: "A.R.D" <contact@team-ard.com>
> 
> Add details about how to boot images generated by Buildroot
> (in VM, over network (NFS/PXE/...).
> 
> Signed-off-by: A.R.D. <contact@team-ard.com>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>

I must say I don't quite like this patch. It's terribly x86-specific,
without even saying it. I'm not sure "Beyond Buildroot" is really a
good name for the section, etc.

Thomas
-- 
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com

[Buildroot] [PATCH 3/5] manual: update beyond Buildroot section

[Samuel Martin]

Hi Willy, Thomas, all,

2013/8/7 Willy Lambert <lambert.willy@gmail.com>:
>
>
>
> 2013/8/7 Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
>>
>> Dear Samuel Martin,
>>
>> On Tue,  6 Aug 2013 23:36:22 +0200, Samuel Martin wrote:
>> > From: "A.R.D" <contact@team-ard.com>
>> >
>> > Add details about how to boot images generated by Buildroot
>> > (in VM, over network (NFS/PXE/...).
>> >
>> > Signed-off-by: A.R.D. <contact@team-ard.com>
>> > Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>>
>> I must say I don't quite like this patch. It's terribly x86-specific,
I agree.

>
>
> obviously it is because I doesn't know anything else ;p. Feel free to give
> the transverse view to transform this into an arch independent section.
>
>
> I've written this because I did have hard time to do something with what I
> generated from BR with my board. The problem is that there is no clue at all
> in the documentation to help people managing this part. I know that this is
> not the Job of BR, but as BR aims at being integrated in specific embedded
> dev processes, you have to give clues on how you do this. Maybe this could
> be outside BR documentation in things like tutorials or getting started or
> even simply links to other wiki/website/tuto that explain all that.
>
> My aim in doing this was :
> _ prevent other people in my case to spend too much time in this part
> _ start something that experts on the subject could detail.
>
> As the aim of BR is to create something to put on a target, a newbie must be
> able to be guided from the time he doesn't know about BR to the time it is
> printed "Hello with my BR distro" on his target "screen". Some people here
> more or less say that it's not the job of BR to take care of the user on
> this part but I think they are terribly wrong. The aim is not to manage the
> board specific stuff, but to address common best practises to setup an
> embedding development toolchain (that *DOES* include the target programming
> part).
>
> I personnaly think that BR has an hard work to do on user friendlyness, and
> I did see that at first as an expert tool for expert people. These doc
> updates aimed at helping in this way.
> Just FYI, have a look at what is a model about user friendlyness in the same
> domain :
> https://www.yoctoproject.org/
Yeah, true.
Unlike yocto/OE, Buildroot is community driven with officially no
entity behind to support it.
So, we do our best, but obviously it's not enough ;)

Also, IMHO, although we'd like to be as good and do as much as yocto
(for instance)
does; we cannot easily... because we want to keep things KISS, easy to
scratch up,
easy to hack, easy to integrate in everyone's workflow.

>
>
>>
>> without even saying it. I'm not sure "Beyond Buildroot" is really a
>> good name for the section, etc.
>
>
> You may change this, I didn't have enougth experience with BR and its
> documentation to be able to name this correctly.
>
My feeling is:
- right now, we have a generic solution for emulation: qemu targets/defconfigs,
they are certainly not advertised enough in the current documentation;
- the qemu targets boot instructions are available through a readme
aside the defconfig;
- this virtualization stuff reminds me something about disk and device
image generation,
that we agree to provide host-tools for it, maybe post-image sample
scripts too, but
almost nothing more;
- I don't like losing this work. Someone spends time to gather it
because he/she felt
there was a gap to fill and to help others.

I think the "generate an x86 vm" from Buildroot is another specific
case that belongs to
the post-image actions.
So, its right place may not be the manual, but some extended readme
and/or sample
post-image scripts.
What about this?


Regards,

-- 
Samuel

[Buildroot] [PATCH 3/5] manual: update beyond Buildroot section

[Thomas Petazzoni]

Dear Samuel Martin,

On Thu, 8 Aug 2013 14:36:39 +0200, Samuel Martin wrote:
> So, its right place may not be the manual, but some extended readme
> and/or sample
> post-image scripts.
> What about this?

I do believe it has its place into the manual, but it needs to be
written up properly, taking into account the other use cases (booting
on ARM/PowerPC platforms), and find a better place for this.

Best regards,

Thomas
-- 
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com

[Buildroot] [PATCH 3/5] manual: update beyond Buildroot section

[Arnout Vandecappelle]

On 08/08/13 20:01, Thomas Petazzoni wrote:
> Dear Samuel Martin,
>
> On Thu, 8 Aug 2013 14:36:39 +0200, Samuel Martin wrote:
>> So, its right place may not be the manual, but some extended readme
>> and/or sample
>> post-image scripts.
>> What about this?
>
> I do believe it has its place into the manual, but it needs to be
> written up properly, taking into account the other use cases (booting
> on ARM/PowerPC platforms), and find a better place for this.

  However, I think the "needs to be written up properly" aspect should 
not stop a piece of documentation to be added to the manual. Even if it 
is not written up properly, it will be useful for some people.


  Regards,
  Arnout


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F

[Buildroot] [PATCH 3/5] manual: update beyond Buildroot section

[Samuel Martin]

All,

2013/8/13 Arnout Vandecappelle <arnout@mind.be>
>
> On 08/08/13 20:01, Thomas Petazzoni wrote:
>>
>> Dear Samuel Martin,
>>
>> On Thu, 8 Aug 2013 14:36:39 +0200, Samuel Martin wrote:
>>>
>>> So, its right place may not be the manual, but some extended readme
>>> and/or sample
>>> post-image scripts.
>>> What about this?
>>
>>
>> I do believe it has its place into the manual, but it needs to be
>> written up properly, taking into account the other use cases (booting
>> on ARM/PowerPC platforms), and find a better place for this.
>
>
>  However, I think the "needs to be written up properly" aspect should not
stop a piece of documentation to be added to the manual. Even if it is not
written up properly, it will be useful for some people.

Right.

To move forward on this, I'd like to have people's opinion about a couple
of questions:
1- what is the best place in the manual for such a section?
  - between the current chapters 3 - "Working with Buildroot" - and 4 - the
FAQ/troubleshooting;
  - or in the "Beyond Buildroot" chapter
  - or in appendices
  - somewhere else
2- should we put the "network boot" in another section, rather than just
aside the disk image creation? (so, split the main addition of the patch in
2 clearly distinguished section/chapter?)
3- should we add a chapter focus on booting the image?
4- where should the VM disk image creation section belong to?
5- how do you think the manual should be organized about these topics
(which are: "booting images", "generating disk image for device or vm")?
what should be the perimeter these sections?



Eventually, I think the manual needs something right after the chapters 3 -
"Working with Buildroot" - dealing with booting the image (title suggestion
is more than welcome).
This chapter could include:
- generic things about deployment on the actual hardware (rougthly: "refer
to the readme in the board directory of the vendor instructions");
- booting the qemu images;
- boot over nfs (as a way to speed up the development process);
- and redirect to the "Beyond Buildroot" chapter for less common ways
(chroot, etc).

The "Beyond Buildroot" chapter could talk about:
- chroot/binfmt/etc;
- generating disk image for specific device (e.g. a disk image for a RPi,
containing several partitions, and so on. IIRC, Yann quickly talked about
it months ago, maybe he could fill some gaps in the doc or provide sample
scripts...);
- generating disk image for a VM (like Willy already wrote it down).

In this view, I don't know yet to what section/chapter PXE boot belongs to
because it's something rather x86-oriented to me...



Opinions, comments, suggestions, critics?
TIA for your inputs.


Regards,

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

[Buildroot] [PATCH 3/5] manual: update beyond Buildroot section

[Arnout Vandecappelle]

On 15/08/13 21:01, Samuel Martin wrote:
> All,
>
> 2013/8/13 Arnout Vandecappelle <arnout at mind.be <mailto:arnout@mind.be>>
>  >
>  > On 08/08/13 20:01, Thomas Petazzoni wrote:
>  >>
>  >> Dear Samuel Martin,
>  >>
>  >> On Thu, 8 Aug 2013 14:36:39 +0200, Samuel Martin wrote:
>  >>>
>  >>> So, its right place may not be the manual, but some extended readme
>  >>> and/or sample
>  >>> post-image scripts.
>  >>> What about this?
>  >>
>  >>
>  >> I do believe it has its place into the manual, but it needs to be
>  >> written up properly, taking into account the other use cases (booting
>  >> on ARM/PowerPC platforms), and find a better place for this.
>  >
>  >
>  >  However, I think the "needs to be written up properly" aspect should
> not stop a piece of documentation to be added to the manual. Even if it
> is not written up properly, it will be useful for some people.
>
> Right.
>
> To move forward on this, I'd like to have people's opinion about a couple
> of questions:
> 1- what is the best place in the manual for such a section?
>    - between the current chapters 3 - "Working with Buildroot" - and 4 -
> the FAQ/troubleshooting;
>    - or in the "Beyond Buildroot" chapter
>    - or in appendices
>    - somewhere else

  I think 'Beyond buildroot' is the proper place. Only, that chapter 
should be called "Deploying the buildroot images". The introductory text 
you added looks really good. It is just missing the following at the end:

For some of the off-the-shelf boards that buildroot supports, you can 
find a specific explanation in a readme file in the _board_ directory.

> 2- should we put the "network boot" in another section, rather than just
> aside the disk image creation? (so, split the main addition of the patch
> in 2 clearly distinguished section/chapter?)

  No, looks like the right place to me. It is a way of deploying the 
kernel/rootfs to the target.

> 3- should we add a chapter focus on booting the image?

  I think that is part of using/deploying the images, so it is the same 
chapter. Also there is usually a tight relation between how the image is 
installed and how it is booted.

> 4- where should the VM disk image creation section belong to?

  Same chapter.

> 5- how do you think the manual should be organized about these topics
> (which are: "booting images", "generating disk image for device or vm")?
> what should be the perimeter these sections?
>
>
>
> Eventually, I think the manual needs something right after the chapters 3
> - "Working with Buildroot" - dealing with booting the image (title
> suggestion is more than welcome).
> This chapter could include:
> - generic things about deployment on the actual hardware (rougthly:
> "refer to the readme in the board directory of the vendor instructions");

  Exactly :-)

> - booting the qemu images;
> - boot over nfs (as a way to speed up the development process);
> - and redirect to the "Beyond Buildroot" chapter for less common ways
> (chroot, etc).

  I don't see why that shouldn't be in the same chapter.

>
> The "Beyond Buildroot" chapter could talk about:
> - chroot/binfmt/etc;
> - generating disk image for specific device (e.g. a disk image for a RPi,
> containing several partitions, and so on. IIRC, Yann quickly talked about
> it months ago, maybe he could fill some gaps in the doc or provide sample
> scripts...);

  I think if it is really for a specific device, then it belongs in the 
board/ directory.

> - generating disk image for a VM (like Willy already wrote it down).

  Except for binfmt, I think all of this fits in the deployment chapter.

>
> In this view, I don't know yet to what section/chapter PXE boot belongs
> to because it's something rather x86-oriented to me...

  PXE itself is, but after that it's exactly the same as a tftp/nfs boot. 
PXE just adds the step of getting the actual bootloader to the device. So 
maybe it could be rewritten to focus more on the tftp aspect, and just 
mention the three references for more PXE information.


  Regards,
  Arnout

> Opinions, comments, suggestions, critics?
> TIA for your inputs.
>
>
> Regards,
>
> --
> Samuel


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F

[Buildroot] [PATCH 3/5] manual: update beyond Buildroot section

[Thomas De Schampheleire]

Hi Samuel, all,

More than a month after your mail, but:

On Thu, Aug 22, 2013 at 8:03 PM, Arnout Vandecappelle <arnout@mind.be> wrote:
> On 15/08/13 21:01, Samuel Martin wrote:
>>
>> All,
>>
>> 2013/8/13 Arnout Vandecappelle <arnout at mind.be <mailto:arnout@mind.be>>
>>
>>  >
>>  > On 08/08/13 20:01, Thomas Petazzoni wrote:
>>  >>
>>  >> Dear Samuel Martin,
>>  >>
>>  >> On Thu, 8 Aug 2013 14:36:39 +0200, Samuel Martin wrote:
>>  >>>
>>  >>> So, its right place may not be the manual, but some extended readme
>>  >>> and/or sample
>>  >>> post-image scripts.
>>  >>> What about this?
>>  >>
>>  >>
>>  >> I do believe it has its place into the manual, but it needs to be
>>  >> written up properly, taking into account the other use cases (booting
>>  >> on ARM/PowerPC platforms), and find a better place for this.
>>  >
>>  >
>>  >  However, I think the "needs to be written up properly" aspect should
>> not stop a piece of documentation to be added to the manual. Even if it
>> is not written up properly, it will be useful for some people.
>>
>> Right.
>>
>> To move forward on this, I'd like to have people's opinion about a couple
>> of questions:
>> 1- what is the best place in the manual for such a section?
>>    - between the current chapters 3 - "Working with Buildroot" - and 4 -
>> the FAQ/troubleshooting;
>>    - or in the "Beyond Buildroot" chapter
>>    - or in appendices
>>    - somewhere else
>
>
>  I think 'Beyond buildroot' is the proper place. Only, that chapter should
> be called "Deploying the buildroot images". The introductory text you added
> looks really good. It is just missing the following at the end:
>
> For some of the off-the-shelf boards that buildroot supports, you can find a
> specific explanation in a readme file in the _board_ directory.
>
>
>> 2- should we put the "network boot" in another section, rather than just
>> aside the disk image creation? (so, split the main addition of the patch
>> in 2 clearly distinguished section/chapter?)
>
>
>  No, looks like the right place to me. It is a way of deploying the
> kernel/rootfs to the target.
>
>
>> 3- should we add a chapter focus on booting the image?
>
>
>  I think that is part of using/deploying the images, so it is the same
> chapter. Also there is usually a tight relation between how the image is
> installed and how it is booted.
>
>
>> 4- where should the VM disk image creation section belong to?
>
>
>  Same chapter.
>
>
>> 5- how do you think the manual should be organized about these topics
>> (which are: "booting images", "generating disk image for device or vm")?
>> what should be the perimeter these sections?
>>
>>
>>
>> Eventually, I think the manual needs something right after the chapters 3
>> - "Working with Buildroot" - dealing with booting the image (title
>> suggestion is more than welcome).
>> This chapter could include:
>> - generic things about deployment on the actual hardware (rougthly:
>> "refer to the readme in the board directory of the vendor instructions");
>
>
>  Exactly :-)
>
>
>> - booting the qemu images;
>> - boot over nfs (as a way to speed up the development process);
>> - and redirect to the "Beyond Buildroot" chapter for less common ways
>> (chroot, etc).
>
>
>  I don't see why that shouldn't be in the same chapter.
>
>
>>
>> The "Beyond Buildroot" chapter could talk about:
>> - chroot/binfmt/etc;
>> - generating disk image for specific device (e.g. a disk image for a RPi,
>> containing several partitions, and so on. IIRC, Yann quickly talked about
>> it months ago, maybe he could fill some gaps in the doc or provide sample
>> scripts...);
>
>
>  I think if it is really for a specific device, then it belongs in the
> board/ directory.
>
>
>> - generating disk image for a VM (like Willy already wrote it down).
>
>
>  Except for binfmt, I think all of this fits in the deployment chapter.
>
>
>>
>> In this view, I don't know yet to what section/chapter PXE boot belongs
>> to because it's something rather x86-oriented to me...
>
>
>  PXE itself is, but after that it's exactly the same as a tftp/nfs boot. PXE
> just adds the step of getting the actual bootloader to the device. So maybe
> it could be rewritten to focus more on the tftp aspect, and just mention the
> three references for more PXE information.
>


I pretty much agree with Arnout's input on the above questions.
Regarding the title, Arnout's suggestion was
Deploying the buildroot images
which is much better than 'Beyond buildroot', but here are some
variations to consider:

Deploying the target images
Deploying target images built with buildroot
Deploying the output images
Deploying the resulting images on target


I also would like to take this opportunity to thank you for all your
efforts in extending and improving the buildroot manual, and promoting
the work on the manual by other developers. It clearly has resulted in
a much improved manual since before, and I hope we as a community can
continue supporting this activity.

Best regards,
Thomas

[Buildroot] [PATCH 4/5] manual: add tips to build manual

[Samuel Martin]

From: "A.R.D" <contact@team-ard.com>

Signed-off-by: A.R.D. <contact@team-ard.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>

---
Changes v1 -> v2 (Samuel):
- split patch
- rephrase commit message
- wrap line at 70-80 chars
- misc. typo and formating fixes
- misc. rewordings
---
 docs/manual/make-tips.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
index b4a9c12..e1af62a 100644
--- a/docs/manual/make-tips.txt
+++ b/docs/manual/make-tips.txt
@@ -54,6 +54,21 @@ and target trees, the images and the toolchain):
  $ make clean
 --------------------
 
+.Generating the manual:
+
+The present manual sources are located in the 'docs/manual' directory.
+To generate the manual:
+
+---------------------------------
+ $ make manual-clean
+ $ make manual
+---------------------------------
+
+The manual outputs will generated in 'output/docs/manual'.
+
+*Note* : +asciidoc+ is required to build it. There is a known issue
+that you can't build it under Dedian Squeeze.
+
 To delete all build products as well as the configuration:
 
 --------------------
-- 
1.8.3.4

[Buildroot] [PATCH 4/5] manual: add tips to build manual

[Thomas De Schampheleire]

On Tue, Aug 6, 2013 at 11:36 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> From: "A.R.D" <contact@team-ard.com>
>
> Signed-off-by: A.R.D. <contact@team-ard.com>
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
>
> ---
> Changes v1 -> v2 (Samuel):
> - split patch
> - rephrase commit message
> - wrap line at 70-80 chars
> - misc. typo and formating fixes
> - misc. rewordings
> ---
>  docs/manual/make-tips.txt | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
>
> diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
> index b4a9c12..e1af62a 100644
> --- a/docs/manual/make-tips.txt
> +++ b/docs/manual/make-tips.txt
> @@ -54,6 +54,21 @@ and target trees, the images and the toolchain):
>   $ make clean
>  --------------------
>
> +.Generating the manual:
> +
> +The present manual sources are located in the 'docs/manual' directory.
> +To generate the manual:
> +
> +---------------------------------
> + $ make manual-clean
> + $ make manual
> +---------------------------------
> +
> +The manual outputs will generated in 'output/docs/manual'.

will be

> +
> +*Note* : +asciidoc+ is required to build it. There is a known issue
> +that you can't build it under Dedian Squeeze.

(I should have read the patches in order)
This should probably be Debian.

> +
>  To delete all build products as well as the configuration:
>
>  --------------------


Best regards,
Thomas

[Buildroot] [PATCH 5/5] manual: minor formating fixes

[Samuel Martin]

Signed-off-by: Samuel Martin <s.martin49@gmail.com>
---
 docs/manual/adding-packages-generic.txt | 14 ++++++++++----
 docs/manual/make-tips.txt               |  5 +++--
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
index a6f9565..3545598 100644
--- a/docs/manual/adding-packages-generic.txt
+++ b/docs/manual/adding-packages-generic.txt
@@ -99,24 +99,30 @@ of the shell script(s) needing fixing. All these names are relative to
 In addition, the scripts listed in +LIBFOO_CONFIG_SCRIPTS+ are removed
 from +$(TARGET_DIR)/usr/bin+, since they are not needed on the target.
 
-Example 1:
-
+.Config script: 'divine' package
+================================
 Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
 
 So it's fixup would be:
 
+--------------------------------
 DIVINE_CONFIG_SCRIPTS = divine-config
+--------------------------------
+================================
 
-Example 2:
-
+.Config script: 'imagemagick' package:
+================================
 Package imagemagick installs the following scripts:
 '$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
 
 So it's fixup would be:
 
+--------------------------------
 IMAGEMAGICK_CONFIG_SCRIPTS = \
    Magick-config Magick++-config \
    MagickCore-config MagickWand-config Wand-config
+--------------------------------
+================================
 
 On line 14, we specify the list of dependencies this package relies
 on. These dependencies are listed in terms of lower-case package names,
diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
index e1af62a..870c029 100644
--- a/docs/manual/make-tips.txt
+++ b/docs/manual/make-tips.txt
@@ -29,8 +29,7 @@ The result of the search shows the help message of the matching items.
  $ make help
 --------------------
 
-.Not all targets are always available,
-
+Not all targets are always available,
 some settings in the +.config+ file may hide some targets:
 
 * +linux-menuconfig+ and +linux-savedefconfig+ only work when
@@ -69,6 +68,8 @@ The manual outputs will generated in 'output/docs/manual'.
 *Note* : +asciidoc+ is required to build it. There is a known issue
 that you can't build it under Dedian Squeeze.
 
+.Reseting Buildroot for a new target:
+
 To delete all build products as well as the configuration:
 
 --------------------
-- 
1.8.3.4

[Buildroot] [PATCH 5/5] manual: minor formating fixes

[Thomas De Schampheleire]

On Tue, Aug 6, 2013 at 11:36 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> Signed-off-by: Samuel Martin <s.martin49@gmail.com>
> ---
>  docs/manual/adding-packages-generic.txt | 14 ++++++++++----
>  docs/manual/make-tips.txt               |  5 +++--
>  2 files changed, 13 insertions(+), 6 deletions(-)
>
> diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
> index a6f9565..3545598 100644
> --- a/docs/manual/adding-packages-generic.txt
> +++ b/docs/manual/adding-packages-generic.txt
> @@ -99,24 +99,30 @@ of the shell script(s) needing fixing. All these names are relative to
>  In addition, the scripts listed in +LIBFOO_CONFIG_SCRIPTS+ are removed
>  from +$(TARGET_DIR)/usr/bin+, since they are not needed on the target.
>
> -Example 1:
> -
> +.Config script: 'divine' package
> +================================
>  Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
>
>  So it's fixup would be:

Not touched by this patch, but this should be 'its fixup'.

>
> +--------------------------------
>  DIVINE_CONFIG_SCRIPTS = divine-config
> +--------------------------------
> +================================
>
> -Example 2:
> -
> +.Config script: 'imagemagick' package:
> +================================
>  Package imagemagick installs the following scripts:
>  '$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
>
>  So it's fixup would be:
>
> +--------------------------------
>  IMAGEMAGICK_CONFIG_SCRIPTS = \
>     Magick-config Magick++-config \
>     MagickCore-config MagickWand-config Wand-config
> +--------------------------------
> +================================
>
>  On line 14, we specify the list of dependencies this package relies
>  on. These dependencies are listed in terms of lower-case package names,
> diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
> index e1af62a..870c029 100644
> --- a/docs/manual/make-tips.txt
> +++ b/docs/manual/make-tips.txt
> @@ -29,8 +29,7 @@ The result of the search shows the help message of the matching items.
>   $ make help
>  --------------------
>
> -.Not all targets are always available,
> -
> +Not all targets are always available,
>  some settings in the +.config+ file may hide some targets:
>
>  * +linux-menuconfig+ and +linux-savedefconfig+ only work when
> @@ -69,6 +68,8 @@ The manual outputs will generated in 'output/docs/manual'.
>  *Note* : +asciidoc+ is required to build it. There is a known issue
>  that you can't build it under Dedian Squeeze.

I guess you mean Debian here?

>
> +.Reseting Buildroot for a new target:
> +
>  To delete all build products as well as the configuration:
>
>  --------------------

Best regards,
Thomas