Manual improvements part 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 after running 'make clean'. By
+following the recommended strategy, you can even use the same Buildroot
+tree to build multiple distinct projects!
 
 include::customize-rootfs.txt[]
 

new file mode 100644
@@ -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.

@@ -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[]

@@ -1,6 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
+[[customize-dir-structure]]
 === Recommended directory structure
 
 When customizing Buildroot for your project, you will be creating one or

143 lines not on this page · raw message

@@ -20,6 +20,14 @@
   (using +BR2_ROOTFS_POST_IMAGE_SCRIPT+)
 - adding project-specific packages
 
+An important note regarding such 'project-specific' customizations:
+please carefully consider which changes are indeed project-specific and
+which changes are also useful to developers outside your project. The
+Buildroot community highly recommends and encourages the upstreaming of
+improvements, packages and board support to the official Buildroot
+project. Of course, it is sometimes not possible or desirable to
+upstream because the changes are highly specific or proprietary.
+
 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 after running 'make clean'. By