Manual improvements part 4
PATCH 1/1 Manual improvements part 4
This short series starts improving the 'Project-specific customizations' chapter in the manual. Subsequent patches are planned (even for 2014.08) but since the release is almost there I'm sending out patches as soon as they are available, to give enough time for review.
Further changes planned:
- streamline explanation on BR2_EXTERNAL after the addition of the new section on directory structure.
- reworking the 'Customizing the generated target filesystem' section to emphasize the recommendations of rootfs-overlay + post-build
- rework the rest of the chapter as there is some duplicate and inconsistent information.
---
Thomas De Schampheleire (2)
manual/user guide/customization: expand introduction text manual/user guide/customization: add section with recommended dir structure
docs/manual/customize-directory-structure.txt | 58 +++++++++++++++++++ docs/manual/customize.txt | 31 ++++++++- 2 files changed, 83 insertions(+), 6 deletions(-)
PATCH 1/1 manual/user guide/customization: expand introduction text
This patch expands the introduction text of chapter 'Project-specific customization' by listing the type of customizations that can be performed by a project.
--- docs/manual/customize.txt | 25 +++++++++++++++++++++---- 1 files changed, 21 insertions(+), 4 deletions(-)
docs/manual/customize.txt +21 -4
@@ -3,11 +3,28 @@ == Project-specific customization -The following sections describe the various way in which you can -customize Buildroot for a given project. +Typical actions you may need to perform for a given project are: -For instructions on how to add new packages to Buildroot, refer to -xref:adding-packages[] +- configuring Buildroot (including build options and toolchain, + bootloader, kernel, package and filesystem image type selection) +- configuring other components, like the Linux kernel and BusyBox +- adding project-specific patches to some packages (using + +BR2_GLOBAL_PATCH_DIR+) +- adding or overwriting files on the target filesystem (using + +BR2_ROOTFS_OVERLAY+) +- modifying or deleting files on the target filesystem (using + +BR2_ROOTFS_POST_BUILD_SCRIPT+) +- running arbitrary commands prior to generating the filesystem image + (using +BR2_ROOTFS_POST_BUILD_SCRIPT+) +- running arbitrary commands after generating the filesystem image + (using +BR2_ROOTFS_POST_IMAGE_SCRIPT+) +- adding project-specific packages + +This chapter describes how to make such project-specific customizations +in Buildroot and how to store them in a way that you can build the same +image in a reproducible way, even from a clean buildroot tree. By +following the recommended strategy, you can even use the same Buildroot +tree to build multiple distinct projects! include::customize-rootfs.txt[]
PATCH 1/1 manual/user guide/customization: expand introduction text
Hi Thomas, all,
Quoted 34 lines · Thomas De Schampheleire
This patch expands the introduction text of chapter 'Project-specific customization' by listing the type of customizations that can be performed by a project.
Signed-off-by Thomas De Schampheleire <[email protected]>--- docs/manual/customize.txt | 25 +++++++++++++++++++++---- 1 files changed, 21 insertions(+), 4 deletions(-)docs/manual/customize.txt +12
-4@@ -3,11 +3,28 @@ == Project-specific customization -The following sections describe the various way in which you can -customize Buildroot for a given project. +Typical actions you may need to perform for a given project are: -For instructions on how to add new packages to Buildroot, refer to -xref:adding-packages[] +- configuring Buildroot (including build options and toolchain, + bootloader, kernel, package and filesystem image type selection) +- configuring other components, like the Linux kernel and BusyBox +- adding project-specific patches to some packages (using + +BR2_GLOBAL_PATCH_DIR+) +- adding or overwriting files on the target filesystem (using + +BR2_ROOTFS_OVERLAY+) +- modifying or deleting files on the target filesystem (using + +BR2_ROOTFS_POST_BUILD_SCRIPT+) +- running arbitrary commands prior to generating the filesystem image + (using +BR2_ROOTFS_POST_BUILD_SCRIPT+)
docs/manual/customize.txt line 28
Quoted 10 lines
docs/manual/customize.txt +9
-0+- running arbitrary commands after generating the filesystem image + (using +BR2_ROOTFS_POST_IMAGE_SCRIPT+) +- adding project-specific packages + +This chapter describes how to make such project-specific customizations +in Buildroot and how to store them in a way that you can build the same +image in a reproducible way, even from a clean buildroot tree. By +following the recommended strategy, you can even use the same Buildroot +tree to build multiple distinct projects!
This is really good, but instead of implying that customization can stay aside of Buildroot tree, I would be clear about this, and maybe add that this location can be used to store non-redistribuable/non-disclosable (I'm not sure about this last adjective ;]) stuff.
docs/manual/customize.txt line 30
Quoted 2 lines
docs/manual/customize.txt +0
-0include::customize-rootfs.txt[]
Regards,
Signature · 1 line
Samuel
PATCH 1/1 manual/user guide/customization: expand introduction text
Quoted 46 lines · Samuel Martin
Hi Thomas, all,
Quoted 42 lines · Thomas De Schampheleire
This patch expands the introduction text of chapter 'Project-specific customization' by listing the type of customizations that can be performed by a project.
Signed-off-by Thomas De Schampheleire <[email protected]>--- docs/manual/customize.txt | 25 +++++++++++++++++++++---- 1 files changed, 21 insertions(+), 4 deletions(-)docs/manual/customize.txt +20
-4@@ -3,11 +3,28 @@ == Project-specific customization -The following sections describe the various way in which you can -customize Buildroot for a given project. +Typical actions you may need to perform for a given project are: -For instructions on how to add new packages to Buildroot, refer to -xref:adding-packages[] +- configuring Buildroot (including build options and toolchain, + bootloader, kernel, package and filesystem image type selection) +- configuring other components, like the Linux kernel and BusyBox +- adding project-specific patches to some packages (using + +BR2_GLOBAL_PATCH_DIR+) +- adding or overwriting files on the target filesystem (using + +BR2_ROOTFS_OVERLAY+) +- modifying or deleting files on the target filesystem (using + +BR2_ROOTFS_POST_BUILD_SCRIPT+) +- running arbitrary commands prior to generating the filesystem image + (using +BR2_ROOTFS_POST_BUILD_SCRIPT+) +- running arbitrary commands after generating the filesystem image + (using +BR2_ROOTFS_POST_IMAGE_SCRIPT+) +- adding project-specific packages + +This chapter describes how to make such project-specific customizations +in Buildroot and how to store them in a way that you can build the same +image in a reproducible way, even from a clean buildroot tree. By +following the recommended strategy, you can even use the same Buildroot
Quoted 8 lines
docs/manual/customize.txt line 28
Quoted 2 lines
docs/manual/customize.txt +1
-0+tree to build multiple distinct projects!This is really good, but instead of implying that customization can stay aside of Buildroot tree, I would be clear about this, and maybe add that this location can be used to store non-redistribuable/non-disclosable (I'm not sure about this last adjective ;]) stuff.
I think I don't fully understand your comment here, could you rephrase?
Thanks,
Thomas
PATCH 1/1 manual/user guide/customization: add section with recommended dir structure
In reply to Thomas De SchampheleireAlthough the user is free to choose where to put project-specific files, the presentation 'Using Buildroot for real projects' [1] first described a certain recommendation.
This patch briefly describes this recommendation in the form of a directory structure overview, the details will be added in subsequent patches.
Since the section on BR2_EXTERNAL is logically connected to the directory structure, this section is moved right after it.
[1] http://elinux.org/images/2/2a/Using-buildroot-real-project.pdf
--- docs/manual/customize-directory-structure.txt | 58 +++++++++++++++++++ docs/manual/customize.txt | 6 +- 2 files changed, 62 insertions(+), 2 deletions(-)
docs/manual/customize-directory-structure.txt new file +58 -0
@@ -0,0 +1,58 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +=== Recommended directory structure + +When customizing Buildroot for your project, you will be creating one or +more project-specific files that need to be stored somewhere. While most +of these files could be placed in _any_ location as their path is to be +specified in the Buildroot configuration, the Buildroot developers +recommend a specific directory structure which is described in this +section. + +Orthogonal to this directory structure, you can choose _where_ you place +this structure itself: either inside the Buildroot tree, or outside of +it using +BR2_EXTERNAL+. Both options are valid, the choice is up to you. + +----- ++-- board/ +| +-- <company>/ +| +-- <boardname>/ +| +-- linux.config +| +-- busybox.config +| +-- <other configuration files> +| +-- post_build.sh +| +-- post_image.sh +| +-- rootfs_overlay/ +| | +-- etc/ +| | +-- <some file> +| +-- patches/ +| +-- foo/ +| | +-- <some patch> +| +-- libbar/ +| +-- <some other patches> +| ++-- configs/ +| +-- <boardname>_defconfig +| ++-- package/ +| +-- <company>/ +| +-- Config.in (if not using BR2_EXTERNAL) +| +-- <company>.mk (if not using BR2_EXTERNAL) +| +-- <boardname>/ +| +-- package1/ +| | +-- Config.in +| | +-- package1.mk +| +-- package2/ +| +-- Config.in +| +-- package2.mk +| ++-- Config.in (if using BR2_EXTERNAL) ++-- external.mk (if using BR2_EXTERNAL) +------ + +Details on the files shown above are given further in this chapter. + +Note: if you choose to place this structure outside of the Buildroot +tree using +BR2_EXTERNAL+, the <company> and possibly <boardname> +components may be superfluous and can be left out.
docs/manual/customize.txt +4 -2
@@ -26,10 +26,12 @@ following the recommended strategy, you can even use the same Buildroot tree to build multiple distinct projects! +include::customize-directory-structure.txt[] + +include::customize-outside-br.txt[] + include::customize-rootfs.txt[] include::customize-store.txt[] include::customize-packages.txt[] - -include::customize-outside-br.txt[]
PATCH 1/1 manual/user guide/customization: add section with recommended dir structure
Hi Thomas, all,
Quoted 67 lines · Thomas De Schampheleire
Although the user is free to choose where to put project-specific files, the presentation 'Using Buildroot for real projects' [1] first described a certain recommendation.
This patch briefly describes this recommendation in the form of a directory structure overview, the details will be added in subsequent patches.Since the section on
BR2_EXTERNALis logically connected to the directory structure, this section is moved right after it.[1] http://elinux.org/images/2/2a/Using-buildroot-real-project.pdf
Signed-off-by Thomas De Schampheleire <[email protected]>--- docs/manual/customize-directory-structure.txt | 58 +++++++++++++++++++ docs/manual/customize.txt | 6 +- 2 files changed, 62 insertions(+), 2 deletions(-)docs/manual/customize-directory-structure.txt new file +43
-0@@ -0,0 +1,58 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +=== Recommended directory structure + +When customizing Buildroot for your project, you will be creating one or +more project-specific files that need to be stored somewhere. While most +of these files could be placed in _any_ location as their path is to be +specified in the Buildroot configuration, the Buildroot developers +recommend a specific directory structure which is described in this +section. + +Orthogonal to this directory structure, you can choose _where_ you place +this structure itself: either inside the Buildroot tree, or outside of +it using +BR2_EXTERNAL+. Both options are valid, the choice is up to you. + +----- ++-- board/ +| +-- <company>/ +| +-- <boardname>/ +| +-- linux.config +| +-- busybox.config +| +-- <other configuration files> +| +-- post_build.sh +| +-- post_image.sh +| +-- rootfs_overlay/ +| | +-- etc/ +| | +-- <some file> +| +-- patches/ +| +-- foo/ +| | +-- <some patch> +| +-- libbar/ +| +-- <some other patches> +| ++-- configs/ +| +-- <boardname>_defconfig +| ++-- package/ +| +-- <company>/ +| +-- Config.in (if not using BR2_EXTERNAL) +| +-- <company>.mk (if not using BR2_EXTERNAL) +| +-- <boardname>/ +| +-- package1/
docs/manual/customize-directory-structure.txt line 53
Quoted 10 lines
docs/manual/customize-directory-structure.txt new file +10
-0+| | +-- Config.in +| | +-- package1.mk +| +-- package2/ +| +-- Config.in +| +-- package2.mk +| ++-- Config.in (if using BR2_EXTERNAL) ++-- external.mk (if using BR2_EXTERNAL) +------ +
This tree is a bit redundant with the one in docs/manual/customize-outside-br.txt.
I think you plan to rework this soon ;)
But having this here give a good overview how one can organize his/her code.
Quoted 13 lines
docs/manual/customize-directory-structure.txt new file +5
-0+Details on the files shown above are given further in this chapter. + +Note: if you choose to place this structure outside of the Buildroot +tree using +BR2_EXTERNAL+, the <company> and possibly <boardname> +components may be superfluous and can be left out.docs/manual/customize.txt +1
-0@@ -26,10 +26,12 @@ following the recommended strategy, you can even use the same Buildroot tree to build multiple distinct projects! +include::customize-directory-structure.txt[]
docs/manual/customize.txt line 35
Quoted 10 lines
docs/manual/customize.txt +3
-2+ +include::customize-outside-br.txt[] + include::customize-rootfs.txt[] include::customize-store.txt[] include::customize-packages.txt[] - -include::customize-outside-br.txt[]
Regards,
Signature · 1 line
Samuel
PATCH 1/1 manual/user guide/customization: add section with recommended dir structure
Quoted 78 lines · Samuel Martin
Hi Thomas, all,
Quoted 74 lines · Thomas De Schampheleire
Although the user is free to choose where to put project-specific files, the presentation 'Using Buildroot for real projects' [1] first described a certain recommendation.
This patch briefly describes this recommendation in the form of a directory structure overview, the details will be added in subsequent patches.Since the section on
BR2_EXTERNALis logically connected to the directory structure, this section is moved right after it.[1] http://elinux.org/images/2/2a/Using-buildroot-real-project.pdf
Signed-off-by Thomas De Schampheleire <[email protected]>--- docs/manual/customize-directory-structure.txt | 58 +++++++++++++++++++ docs/manual/customize.txt | 6 +- 2 files changed, 62 insertions(+), 2 deletions(-)docs/manual/customize-directory-structure.txt new file +50
-0@@ -0,0 +1,58 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +=== Recommended directory structure + +When customizing Buildroot for your project, you will be creating one or +more project-specific files that need to be stored somewhere. While most +of these files could be placed in _any_ location as their path is to be +specified in the Buildroot configuration, the Buildroot developers +recommend a specific directory structure which is described in this +section. + +Orthogonal to this directory structure, you can choose _where_ you place +this structure itself: either inside the Buildroot tree, or outside of +it using +BR2_EXTERNAL+. Both options are valid, the choice is up to you. + +----- ++-- board/ +| +-- <company>/ +| +-- <boardname>/ +| +-- linux.config +| +-- busybox.config +| +-- <other configuration files> +| +-- post_build.sh +| +-- post_image.sh +| +-- rootfs_overlay/ +| | +-- etc/ +| | +-- <some file> +| +-- patches/ +| +-- foo/ +| | +-- <some patch> +| +-- libbar/ +| +-- <some other patches> +| ++-- configs/ +| +-- <boardname>_defconfig +| ++-- package/ +| +-- <company>/ +| +-- Config.in (if not using BR2_EXTERNAL) +| +-- <company>.mk (if not using BR2_EXTERNAL) +| +-- <boardname>/ +| +-- package1/ +| | +-- Config.in +| | +-- package1.mk +| +-- package2/ +| +-- Config.in +| +-- package2.mk +| ++-- Config.in (if using BR2_EXTERNAL)
Quoted 8 lines
docs/manual/customize-directory-structure.txt line 53
Quoted 3 lines
docs/manual/customize-directory-structure.txt new file +3
-0++-- external.mk (if using BR2_EXTERNAL) +------ +This tree is a bit redundant with the one in
docs/manual/customize-outside-br.txt.
I think you plan to rework this soon ;)
But having this here give a good overview how one can organize his/her code.
Yes indeed, rework of that section is planned and will remove the tree there (or at least the part that is already in the above diagram).
Thanks,
Thomas