Manual updates
cover Manual updates
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
PATCH 1/5 Docu: Add LIBFOO_EXTRACT_CMDS
From: Stephan Hoffmann <[email protected]>
--- docs/manual/adding-packages-generic.txt | 4 ++++ 1 file changed, 4 insertions(+)
docs/manual/adding-packages-generic.txt +4 -0
@@ -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.
Signature · 1 line
1.8.3.4
PATCH 2/5 manual: add patch revision and versioning section
In reply to Samuel MartinFrom: Vinicius Tinti <[email protected]>
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.
--- docs/manual/contribute.txt | 66 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+)
docs/manual/contribute.txt +66 -0
@@ -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 <[email protected]> + +--- +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 -------------------------
Signature · 1 line
1.8.3.4
PATCH 2/5 manual: add patch revision and versioning section
Dear Samuel Martin,
Quoted 7 lines · Samuel Martin
From: Vinicius Tinti <[email protected]>
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.
Quoted 1 line
+Sometimes, changes will be requested to your patch before getting merged.
This is rather strange way of starting this section, me thinks.
Quoted 1 line
+Whenever it happens, the new revision of the pacthset should include a
patchset.
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 71
Quoted 2 lines
docs/manual/contribute.txt +2
-0+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.
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 76
Quoted 4 lines
docs/manual/contribute.txt +4
-0+Patch revision changelog +^^^^^^^^^^^^^^^^^^^^^^^^ + +When editing your commit, below the +signed-off-by+ section, add +---+, then
Signed-off-by.
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 87
Quoted 11 lines
docs/manual/contribute.txt +11
-0+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.
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 92
Quoted 5 lines
docs/manual/contribute.txt +5
-0+ +--------------- +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.
Quoted 13 lines
docs/manual/contribute.txt +13
-0+ +Signed-off-by John Doe <[email protected]> + +--- +Changes v2 -> v3: + - foo bar (suggested by Jane) + - bar buz + +Changes v1 -> v2: + - alpha bravo (suggested by John) + - charly delta +--------------- +
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 115
Quoted 10 lines
docs/manual/contribute.txt +10
-0+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
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 129
Quoted 13 lines
docs/manual/contribute.txt +13
-0+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
Signature · 4 lines
Thomas Petazzoni, Free Electrons Kernel, drivers, real-time and embedded Linux development, consulting, training and support. http://free-electrons.com
PATCH 2/5 manual: add patch revision and versioning section
Hi Thomas, all,
2013/8/7 Thomas Petazzoni <[email protected]>:
Quoted 8 lines
Dear Samuel Martin,
Quoted 5 lines · Samuel Martin
From: Vinicius Tinti <[email protected]>
Improve the contribute manual section by adding an explanation about patch review and version.
Quoted 7 lines
Quoted 2 lines
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.
Quoted 4 lines
Quoted 2 lines
+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.
Quoted 4 lines
Quoted 2 lines
+Whenever it happens, the new revision of the pacthset should include a
patchset.
done
Quoted 9 lines
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 71
Quoted 3 lines
docs/manual/contribute.txt +2
-0+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.
Quoted 7 lines
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 76
Quoted 5 lines
docs/manual/contribute.txt +4
-0+Patch revision changelog +^^^^^^^^^^^^^^^^^^^^^^^^ + +When editing your commit, below the +signed-off-by+ section, add +---+, thenSigned-off-by.
done
Quoted 14 lines
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 87
Quoted 12 lines
docs/manual/contribute.txt +11
-0+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!).
Quoted 10 lines
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 92
Quoted 6 lines
docs/manual/contribute.txt +5
-0+ +--------------- +Patch title less than 80-character length + +Some paragraph describing what the patch does and whySome more paragraph giving some more details.
And yet another paragraph giving more details.
done
Quoted 25 lines
Quoted 24 lines
docs/manual/contribute.txt +23
-0+ +Signed-off-by John Doe <[email protected]> + +--- +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 +---------------------
Review
Quoted 2 lines
(quoted diff) +0
-2-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.
Quoted 17 lines
Quoted 4 lines
docs/manual/contribute.txt +3
-0+Keeping patch revision in the same thread +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 129
Quoted 10 lines
docs/manual/contribute.txt +10
-0+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.
Quoted 6 lines
Thomas
--
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com
Thanks,
Regards,
Signature · 1 line
Samuel
PATCH 2/5 manual: add patch revision and versioning section
Quoted 10 lines · Samuel Martin
Quoted 10 lines
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 71
Quoted 4 lines
docs/manual/contribute.txt +2
-0+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.
Quoted 6 lines
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
PATCH 2/5 manual: add patch revision and versioning section
In reply to Samuel MartinHi,
In addition to the spelling changes noticed by Thomas:
Op 6-aug.-2013 23:37 schreef "Samuel Martin" <[email protected]> het volgende:
Quoted 7 lines
From: Vinicius Tinti <[email protected]>
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
Quoted 7 lines
to proceed on replying them.
[Samuel: minor rewordings + misc. formating fixes]Signed-off-by Vinicius Tinti <[email protected]>Signed-off-by Samuel Martin <[email protected]>--- docs/manual/contribute.txt | 66
++++++++++++++++++++++++++++++++++++++++++++++
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*,
Quoted 7 lines
1 file changed, 66 insertions(+)docs/manual/contribute.txt +0
-0@@ -62,6 +62,72 @@ Make sure posted *patches are not line-wrapped*,
otherwise they cannot
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot
Quoted 9 lines
docs/manual/contribute.txt +6
-0easily 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,
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot
Quoted 6 lines
docs/manual/contribute.txt +6
-0+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
Quoted 21 lines
docs/manual/contribute.txt +21
-0+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 <[email protected]> + +--- +Changes v2 -> v3:
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot
Quoted 10 lines
docs/manual/contribute.txt +10
-0+ - 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
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, · line 108
Quoted 1 line
docs/manual/contribute.txt +1
-0+equal 2 (two) (i.e. "PATCH v2", "PATCH v3" ...
s/equal/equal to/
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, · line 110
Quoted 2 lines
docs/manual/contribute.txt +2
-0+ +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
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot
Quoted 4 lines
docs/manual/contribute.txt +4
-0++--subject-prefix+: + +--------------------- + $ git format-patch --subject-prefix "PATCH v4" -M -n -s -o outgoing
origin/master
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 125
Quoted 11 lines
docs/manual/contribute.txt +11
-0+--------------------- + +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
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot
Quoted 3 lines
docs/manual/contribute.txt +3
-0+ +--------------------- + $ git send-email --to buildroot at busybox.net --in-reply-to
mymsgid at noname.org outgoing/*
docs/manual/contribute.txt Make sure posted *patches are not line-wrapped*, otherwise they cannot · line 133
Quoted 5 lines
docs/manual/contribute.txt +2
-0+--------------------- + 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>
PATCH 2/5 manual: add patch revision and versioning section
Hi Thomas, all,
2013/8/7 Thomas De Schampheleire <[email protected]>:
All fixed.
Thanks for the review.
Regards,
Signature · 1 line
Samuel
PATCH 3/5 manual: update beyond Buildroot section
In reply to Samuel MartinFrom: "A.R.D" <[email protected]>
Add details about how to boot images generated by Buildroot (in VM, over network (NFS/PXE/...).
---
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(-)
docs/manual/beyond-buildroot.txt +149 -13
@@ -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;
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 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
docs/manual/working-with.txt +5 -0
@@ -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[].
Signature · 1 line
1.8.3.4
PATCH 3/5 manual: update beyond Buildroot section
Quoted 51 lines · Samuel Martin
From: "A.R.D" <[email protected]>
Add details about how to boot images generated by Buildroot (in VM, over network (NFS/PXE/...).
Signed-off-by A.R.D. <[email protected]>Signed-off-by Samuel Martin <[email protected]>---
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(-)docs/manual/beyond-buildroot.txt +6
-5@@ -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
docs/manual/beyond-buildroot.txt line 21
Quoted 10 lines
docs/manual/beyond-buildroot.txt +6
-3-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
docs/manual/beyond-buildroot.txt line 31
Quoted 10 lines
docs/manual/beyond-buildroot.txt +10
-0+ 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 ...
docs/manual/beyond-buildroot.txt line 38
Quoted 7 lines
docs/manual/beyond-buildroot.txt +7
-0+ + +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
docs/manual/beyond-buildroot.txt line 42
Quoted 4 lines
docs/manual/beyond-buildroot.txt +4
-0+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
docs/manual/beyond-buildroot.txt line 50
Quoted 8 lines
docs/manual/beyond-buildroot.txt +8
-0+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/
Quoted 17 lines
docs/manual/beyond-buildroot.txt +17
-0+ +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;
docs/manual/beyond-buildroot.txt line 77
Quoted 10 lines
docs/manual/beyond-buildroot.txt +10
-0+ +* 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 ...
docs/manual/beyond-buildroot.txt line 79
Quoted 2 lines
docs/manual/beyond-buildroot.txt +2
-0+ +A nice way of doing this is booting from network. If the device allows
from the network.
docs/manual/beyond-buildroot.txt line 92
Quoted 13 lines
docs/manual/beyond-buildroot.txt +13
-0+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')
docs/manual/beyond-buildroot.txt line 101
Quoted 9 lines
docs/manual/beyond-buildroot.txt +9
-0+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.'
docs/manual/beyond-buildroot.txt line 103
Quoted 2 lines
docs/manual/beyond-buildroot.txt +2
-0+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.
docs/manual/beyond-buildroot.txt line 105
Quoted 2 lines
docs/manual/beyond-buildroot.txt +2
-0+ +Here is some hints on how to setup this:
Here are some hints on how to set this up:
docs/manual/beyond-buildroot.txt line 111
Quoted 6 lines
docs/manual/beyond-buildroot.txt +6
-0+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
docs/manual/beyond-buildroot.txt line 118
Quoted 7 lines
docs/manual/beyond-buildroot.txt +7
-0+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
Quoted 14 lines
docs/manual/beyond-buildroot.txt +14
-0+ +* 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.
docs/manual/beyond-buildroot.txt line 141
Quoted 10 lines
docs/manual/beyond-buildroot.txt +4
-1+ +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
docs/manual/beyond-buildroot.txt line 142
Quoted 1 line
docs/manual/beyond-buildroot.txt +1
-0+daemon is running onthe server.
on the
docs/manual/beyond-buildroot.txt line 150
Quoted 8 lines
docs/manual/beyond-buildroot.txt +8
-0+ +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:
Quoted 10 lines
docs/manual/beyond-buildroot.txt +10
-0+// 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 +
docs/manual/beyond-buildroot.txt line 166
Quoted 10 lines
docs/manual/beyond-buildroot.txt +3
-4-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
docs/manual/using.txt Buildroot output is stored in a single directory, +output/+. · line 70
Quoted 13 lines
docs/manual/beyond-buildroot.txt +0
-0you should be aware of: * you should setup the new root from the _tar root filesystem_ image;docs/manual/using.txt +1
-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 uisng/booting
using
Quoted 9 lines
docs/manual/using.txt +1
-0+ 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 ondocs/manual/working-with.txt +0
-0
docs/manual/working-with.txt interested in hacking it to add:
Quoted 9 lines
docs/manual/working-with.txt +5
-1@@ -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
PATCH 3/5 manual: update beyond Buildroot section
In reply to Samuel MartinDear Samuel Martin,
Quoted 7 lines · Samuel Martin
From: "A.R.D" <[email protected]>
Add details about how to boot images generated by Buildroot (in VM, over network (NFS/PXE/...).
Signed-off-by A.R.D. <[email protected]>Signed-off-by Samuel Martin <[email protected]>
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
Signature · 4 lines
Thomas Petazzoni, Free Electrons Kernel, drivers, real-time and embedded Linux development, consulting, training and support. http://free-electrons.com
A message that is not in the archive (sent off-list or not yet received): CAKvQZ_3UxzreEtWQ3E++3xZ1o4W_Rn1gzKrYQo2CNOnQ_hZpfg@mail.gmail.com
PATCH 3/5 manual: update beyond Buildroot section
Hi Willy, Thomas, all,
2013/8/7 Willy Lambert <[email protected]>:
Quoted 17 lines
2013/8/7 Thomas Petazzoni <[email protected]>
Quoted 13 lines
Dear Samuel Martin,
Quoted 7 lines · Samuel Martin
From: "A.R.D" <[email protected]>
Add details about how to boot images generated by Buildroot (in VM, over network (NFS/PXE/...).
Signed-off-by A.R.D. <[email protected]>Signed-off-by Samuel Martin <[email protected]>I must say I don't quite like this patch. It's terribly x86-specific,
I agree.
Quoted 27 lines
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).
Quoted 6 lines
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.
Quoted 10 lines
Quoted 5 lines
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,
Signature · 1 line
Samuel
PATCH 3/5 manual: update beyond Buildroot section
Dear Samuel Martin,
Quoted 4 lines · Samuel Martin
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
Signature · 4 lines
Thomas Petazzoni, Free Electrons Kernel, drivers, real-time and embedded Linux development, consulting, training and support. http://free-electrons.com
PATCH 3/5 manual: update beyond Buildroot section
Quoted 11 lines · Thomas Petazzoni
Dear Samuel Martin,
Quoted 4 lines · Samuel Martin
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
Signature · 6 lines
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
PATCH 3/5 manual: update beyond Buildroot section
All,
2013/8/13 Arnout Vandecappelle <[email protected]>
Quoted 13 lines · Thomas Petazzoni
Quoted 11 lines
Dear Samuel Martin,
Quoted 5 lines · Samuel Martin
So, its right place may not be the manual, but some extended readme and/or sample
post-image scripts.
What about this?
Quoted 6 lines
Quoted 3 lines
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>
PATCH 3/5 manual: update beyond Buildroot section
Quoted 27 lines · Samuel Martin
All,
2013/8/13 Arnout Vandecappelle <arnout at mind.be <mailto:[email protected]>>
Quoted 13 lines · Thomas Petazzoni
Quoted 11 lines
Dear Samuel Martin,
Quoted 5 lines · Samuel Martin
So, its right place may not be the manual, but some extended readme and/or sample
post-image scripts.
What about this?Quoted 6 lines
Quoted 3 lines
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.
Quoted 8 lines
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.
Quoted 3 lines
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.
Quoted 1 line
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.
Quoted 1 line
4- where should the VM disk image creation section belong to?
Same chapter.
Quoted 6 lines
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?
Quoted 6 lines
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 :-)
Quoted 4 lines
- 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.
Quoted 7 lines
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.
Quoted 1 line
- 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.
Quoted 3 lines
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
Quoted 8 lines
Opinions, comments, suggestions, critics?
TIA for your inputs.Regards,
--
Samuel
Signature · 6 lines
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
PATCH 3/5 manual: update beyond Buildroot section
Hi Samuel, all,
More than a month after your mail, but:
Quoted 117 lines · Arnout Vandecappelle
Quoted 29 lines · Samuel Martin
All,
2013/8/13 Arnout Vandecappelle <arnout at mind.be <mailto:[email protected]>>
Quoted 13 lines · Thomas Petazzoni
Quoted 11 lines
Dear Samuel Martin,
Quoted 5 lines · Samuel Martin
So, its right place may not be the manual, but some extended readme and/or sample
post-image scripts.
What about this?Quoted 6 lines
Quoted 3 lines
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.
Quoted 8 lines
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 elseI 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.
Quoted 3 lines
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.Quoted 1 line
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.Quoted 1 line
4- where should the VM disk image creation section belong to?
Same chapter.
Quoted 6 lines
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?
Quoted 6 lines
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 :-)
Quoted 4 lines
- 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.
Quoted 7 lines
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.Quoted 1 line
- 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.
Quoted 1 line
Quoted 9 lines
Quoted 2 lines
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
PATCH 4/5 manual: add tips to build manual
In reply to Samuel MartinFrom: "A.R.D" <[email protected]>
---
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(+)
docs/manual/make-tips.txt +15 -0
@@ -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: --------------------
Signature · 1 line
1.8.3.4
PATCH 4/5 manual: add tips to build manual
Quoted 25 lines · Samuel Martin
From: "A.R.D" <[email protected]>
Signed-off-by A.R.D. <[email protected]>Signed-off-by Samuel Martin <[email protected]>---
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(+)docs/manual/make-tips.txt +1
-0@@ -54,6 +54,21 @@ and target trees, the images and the toolchain): $ make clean -------------------- +.Generating the manual:
docs/manual/make-tips.txt and target trees, the images and the toolchain): · line 67
Quoted 10 lines
docs/manual/make-tips.txt +10
-0+ +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
docs/manual/make-tips.txt and target trees, the images and the toolchain): · line 70
Quoted 3 lines
docs/manual/make-tips.txt +3
-0+ +*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.
docs/manual/make-tips.txt and target trees, the images and the toolchain): · line 74
Quoted 4 lines
docs/manual/make-tips.txt +1
-0+ To delete all build products as well as the configuration: --------------------
Best regards,
Thomas
PATCH 5/5 manual: minor formating fixes
In reply to Samuel Martin--- docs/manual/adding-packages-generic.txt | 14 ++++++++++---- docs/manual/make-tips.txt | 5 +++-- 2 files changed, 13 insertions(+), 6 deletions(-)
docs/manual/adding-packages-generic.txt +10 -4
@@ -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,
docs/manual/make-tips.txt +3 -2
@@ -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: --------------------
Signature · 1 line
1.8.3.4
PATCH 5/5 manual: minor formating fixes
Quoted 11 lines · Samuel Martin
Signed-off-by Samuel Martin <[email protected]>--- docs/manual/adding-packages-generic.txt | 14 ++++++++++---- docs/manual/make-tips.txt | 5 +++-- 2 files changed, 13 insertions(+), 6 deletions(-)docs/manual/adding-packages-generic.txt +0
-0
docs/manual/adding-packages-generic.txt of the shell script(s) needing fixing. All these names are relative to · line 106
Quoted 10 lines
docs/manual/adding-packages-generic.txt +2
-2@@ -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'.
Quoted 39 lines
docs/manual/adding-packages-generic.txt +8
-2+-------------------------------- 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,docs/manual/make-tips.txt +1
-2@@ -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
docs/manual/make-tips.txt The manual outputs will generated in 'output/docs/manual'. · line 69
Quoted 2 lines
docs/manual/make-tips.txt +0
-0@@ -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?
docs/manual/make-tips.txt The manual outputs will generated in 'output/docs/manual'. · line 75
Quoted 6 lines
docs/manual/make-tips.txt +2
-0+.Reseting Buildroot for a new target: + To delete all build products as well as the configuration: --------------------
Best regards,
Thomas