* [Buildroot] [PATCH 01 of 13] manual: move 'Creating your own board support' from User to Developer guide
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 02 of 13] manual/developer guide: minor rework of 'adding board support' section Thomas De Schampheleire
` (13 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
Section 'Creating your own board support' is seemingly written in the
mindset of adding support for public boards. Therefore, it is more suited in
the Developer guide, rather than in the User guide.
Adding support for custom non-public boards falls under the
'Project-specific customizations' category and will be described in that
section.
This patch moves the unchanged text into a separate file, included from the
Developer guide. The next patch will make some minor changes to the text
itself.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/adding-board-support.txt | 37 ++++++++++++++++++++++++++++
docs/manual/customize-store.txt | 36 ---------------------------
docs/manual/manual.txt | 2 +
3 files changed, 39 insertions(+), 36 deletions(-)
diff --git a/docs/manual/adding-board-support.txt b/docs/manual/adding-board-support.txt
new file mode 100644
--- /dev/null
+++ b/docs/manual/adding-board-support.txt
@@ -0,0 +1,37 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[customize-store-board-support]]
+== Creating your own board support
+
+Creating your own board support in Buildroot allows users of a
+particular hardware platform to easily build a system that is known to
+work.
+
+To do so, you need to create a normal Buildroot configuration that
+builds a basic system for the hardware: toolchain, kernel, bootloader,
+filesystem and a simple BusyBox-only userspace. No specific package
+should be selected: the configuration should be as minimal as
+possible, and should only build a working basic BusyBox system for the
+target platform. You can of course use more complicated configurations
+for your internal projects, but the Buildroot project will only
+integrate basic board configurations. This is because package
+selections are highly application-specific.
+
+Once you have a known working configuration, run +make
+savedefconfig+. This will generate a minimal +defconfig+ file at the
+root of the Buildroot source tree. Move this file into the +configs/+
+directory, and rename it +<boardname>_defconfig+.
+
+It is recommended to use as much as possible upstream versions of the
+Linux kernel and bootloaders, and to use as much as possible default
+kernel and bootloader configurations. If they are incorrect for your
+board, or no default exists, we encourage you to send fixes to the
+corresponding upstream projects.
+
+However, in the mean time, you may want to store kernel or bootloader
+configuration or patches specific to your target platform. To do so,
+create a directory +board/<manufacturer>+ and a subdirectory
++board/<manufacturer>/<boardname>+. You can then store your patches
+and configurations in these directories, and reference them from the main
+Buildroot configuration.
diff --git a/docs/manual/customize-store.txt b/docs/manual/customize-store.txt
--- a/docs/manual/customize-store.txt
+++ b/docs/manual/customize-store.txt
@@ -66,42 +66,6 @@
file manually to +BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE+.
-[[customize-store-board-support]]
-=== Creating your own board support
-
-Creating your own board support in Buildroot allows users of a
-particular hardware platform to easily build a system that is known to
-work.
-
-To do so, you need to create a normal Buildroot configuration that
-builds a basic system for the hardware: toolchain, kernel, bootloader,
-filesystem and a simple BusyBox-only userspace. No specific package
-should be selected: the configuration should be as minimal as
-possible, and should only build a working basic BusyBox system for the
-target platform. You can of course use more complicated configurations
-for your internal projects, but the Buildroot project will only
-integrate basic board configurations. This is because package
-selections are highly application-specific.
-
-Once you have a known working configuration, run +make
-savedefconfig+. This will generate a minimal +defconfig+ file at the
-root of the Buildroot source tree. Move this file into the +configs/+
-directory, and rename it +<boardname>_defconfig+.
-
-It is recommended to use as much as possible upstream versions of the
-Linux kernel and bootloaders, and to use as much as possible default
-kernel and bootloader configurations. If they are incorrect for your
-board, or no default exists, we encourage you to send fixes to the
-corresponding upstream projects.
-
-However, in the mean time, you may want to store kernel or bootloader
-configuration or patches specific to your target platform. To do so,
-create a directory +board/<manufacturer>+ and a subdirectory
-+board/<manufacturer>/<boardname>+. You can then store your patches
-and configurations in these directories, and reference them from the main
-Buildroot configuration.
-
-
=== Step-by-step instructions for storing configuration
To store the configuration for a specific product, device or
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -52,6 +52,8 @@
include::writing-rules.txt[]
+include::adding-board-support.txt[]
+
include::adding-packages.txt[]
include::patch-policy.txt[]
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 02 of 13] manual/developer guide: minor rework of 'adding board support' section
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 01 of 13] manual: move 'Creating your own board support' from User to Developer guide Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 03 of 13] manual/user guide/customization: move section on storing configuration Thomas De Schampheleire
` (12 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
Minor rework of the section 'Creating your own board support', as follows:
- Rename section into 'Adding support for a particular board'
- Modify introduction
- Refer to Project-specific customizations chapter
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/adding-board-support.txt | 13 +++++++------
docs/manual/customize.txt | 1 +
2 files changed, 8 insertions(+), 6 deletions(-)
diff --git a/docs/manual/adding-board-support.txt b/docs/manual/adding-board-support.txt
--- a/docs/manual/adding-board-support.txt
+++ b/docs/manual/adding-board-support.txt
@@ -1,12 +1,13 @@
// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
-[[customize-store-board-support]]
-== Creating your own board support
+[[adding-board-support]]
+== Adding support for a particular board
-Creating your own board support in Buildroot allows users of a
-particular hardware platform to easily build a system that is known to
-work.
+Buildroot contains basic configurations for several publicly available
+hardware boards, so that users of such a board can easily build a system
+that is known to work. You are welcome to add support for other boards
+to Buildroot too.
To do so, you need to create a normal Buildroot configuration that
builds a basic system for the hardware: toolchain, kernel, bootloader,
@@ -34,4 +35,4 @@
create a directory +board/<manufacturer>+ and a subdirectory
+board/<manufacturer>/<boardname>+. You can then store your patches
and configurations in these directories, and reference them from the main
-Buildroot configuration.
+Buildroot configuration. Refer to xref:customize[] for more details.
diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -1,6 +1,7 @@
// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
+[[customize]]
== Project-specific customization
Typical actions you may need to perform for a given project are:
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 03 of 13] manual/user guide/customization: move section on storing configuration
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 01 of 13] manual: move 'Creating your own board support' from User to Developer guide Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 02 of 13] manual/developer guide: minor rework of 'adding board support' section Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 04 of 13] manual/user guide/customization: rework " Thomas De Schampheleire
` (11 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
This patch moves the section 'Basics for storing the configuration' to a
separate file and upwards in the manual section order, to line up with the
listing of customization actions in the introduction of the chapter. The
text itself is currently unchanged, this will be handled in the next patch.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize-configuration.txt | 68 +++++++++++++++++++++++++
docs/manual/customize-store.txt | 65 -----------------------
docs/manual/customize.txt | 2 +
3 files changed, 70 insertions(+), 65 deletions(-)
diff --git a/docs/manual/customize-configuration.txt b/docs/manual/customize-configuration.txt
new file mode 100644
--- /dev/null
+++ b/docs/manual/customize-configuration.txt
@@ -0,0 +1,68 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[customize-store-basics]]
+=== Basics for storing the configuration
+
+When you have a buildroot configuration that you are satisfied with and
+you want to share it with others, put it under revision control or move
+on to a different buildroot project, you need to store the configuration
+so it can be rebuilt later. The configuration that needs to be stored
+consists of the buildroot configuration, the configuration files for
+packages that you use (kernel, busybox, uClibc, ...), and your rootfs
+modifications.
+
+[[customize-store-buildroot-config]]
+==== Buildroot configuration
+
+For storing the buildroot configuration itself, buildroot offers the
+following command: +make savedefconfig+.
+
+This strips the buildroot configuration down by removing configuration
+options that are at their default value. The result is stored in a file
+called +defconfig+. If you want to save it in another place, change
+the +BR2_DEFCONFIG+ option, or call make with +make savedefconfig
+BR2_DEFCONFIG=<path-to-defconfig>+. The usual place is
++configs/<boardname>_defconfig+. The configuration can then be rebuilt by
+running +make <boardname>_defconfig+.
+
+Alternatively, you can copy the file to any other place and rebuild with
++make defconfig BR2_DEFCONFIG=<path-to-defconfig-file>+.
+
+
+[[customize-store-package-config]]
+==== Other package configuration
+
+The configuration files for busybox, the linux kernel, barebox and
+uClibc should be stored as well if changed. For each of these, a
+buildroot configuration option exists to point to an input
+configuration file, e.g. +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+. To
+save their configuration, set those configuration options to a path
+outside your output directory,
+e.g. +board/<manufacturer>/<boardname>/linux.config+. Then, copy the
+configuration files to that path.
+
+Make sure that you create a configuration file 'before' changing
+the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+ etc. options. Otherwise,
+buildroot will try to access this config file, which doesn't exist
+yet, and will fail. You can create the configuration file by running
++make linux-menuconfig+ etc.
+
+Buildroot provides a few helper targets to make the saving of
+configuration files easier.
+
+* +make linux-update-defconfig+ saves the linux configuration to the
+ path specified by +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+. It
+ simplifies the config file by removing default values. However,
+ this only works with kernels starting from 2.6.33. For earlier
+ kernels, use +make linux-update-config+.
+* +make busybox-update-config+ saves the busybox configuration to the
+ path specified by +BR2_PACKAGE_BUSYBOX_CONFIG+.
+* +make uclibc-update-config+ saves the uClibc configuration to the
+ path specified by +BR2_UCLIBC_CONFIG+.
+* +make barebox-update-defconfig+ saves the barebox configuration to the
+ path specified by +BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE+.
+* For at91bootstrap3, no helper exists so you have to copy the config
+ file manually to +BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE+.
+
+
diff --git a/docs/manual/customize-store.txt b/docs/manual/customize-store.txt
--- a/docs/manual/customize-store.txt
+++ b/docs/manual/customize-store.txt
@@ -1,71 +1,6 @@
// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
-[[customize-store-basics]]
-=== Basics for storing the configuration
-
-When you have a buildroot configuration that you are satisfied with and
-you want to share it with others, put it under revision control or move
-on to a different buildroot project, you need to store the configuration
-so it can be rebuilt later. The configuration that needs to be stored
-consists of the buildroot configuration, the configuration files for
-packages that you use (kernel, busybox, uClibc, ...), and your rootfs
-modifications.
-
-[[customize-store-buildroot-config]]
-==== Buildroot configuration
-
-For storing the buildroot configuration itself, buildroot offers the
-following command: +make savedefconfig+.
-
-This strips the buildroot configuration down by removing configuration
-options that are at their default value. The result is stored in a file
-called +defconfig+. If you want to save it in another place, change
-the +BR2_DEFCONFIG+ option, or call make with +make savedefconfig
-BR2_DEFCONFIG=<path-to-defconfig>+. The usual place is
-+configs/<boardname>_defconfig+. The configuration can then be rebuilt by
-running +make <boardname>_defconfig+.
-
-Alternatively, you can copy the file to any other place and rebuild with
-+make defconfig BR2_DEFCONFIG=<path-to-defconfig-file>+.
-
-
-[[customize-store-package-config]]
-==== Other package configuration
-
-The configuration files for busybox, the linux kernel, barebox and
-uClibc should be stored as well if changed. For each of these, a
-buildroot configuration option exists to point to an input
-configuration file, e.g. +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+. To
-save their configuration, set those configuration options to a path
-outside your output directory,
-e.g. +board/<manufacturer>/<boardname>/linux.config+. Then, copy the
-configuration files to that path.
-
-Make sure that you create a configuration file 'before' changing
-the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+ etc. options. Otherwise,
-buildroot will try to access this config file, which doesn't exist
-yet, and will fail. You can create the configuration file by running
-+make linux-menuconfig+ etc.
-
-Buildroot provides a few helper targets to make the saving of
-configuration files easier.
-
-* +make linux-update-defconfig+ saves the linux configuration to the
- path specified by +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+. It
- simplifies the config file by removing default values. However,
- this only works with kernels starting from 2.6.33. For earlier
- kernels, use +make linux-update-config+.
-* +make busybox-update-config+ saves the busybox configuration to the
- path specified by +BR2_PACKAGE_BUSYBOX_CONFIG+.
-* +make uclibc-update-config+ saves the uClibc configuration to the
- path specified by +BR2_UCLIBC_CONFIG+.
-* +make barebox-update-defconfig+ saves the barebox configuration to the
- path specified by +BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE+.
-* For at91bootstrap3, no helper exists so you have to copy the config
- file manually to +BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE+.
-
-
=== Step-by-step instructions for storing configuration
To store the configuration for a specific product, device or
diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -39,6 +39,8 @@
include::customize-outside-br.txt[]
+include::customize-configuration.txt[]
+
include::customize-rootfs.txt[]
include::customize-post-image.txt[]
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 04 of 13] manual/user guide/customization: rework section on storing configuration
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (2 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 03 of 13] manual/user guide/customization: move section on storing configuration Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 05 of 13] manual/user guide/customization: re-order introduction Thomas De Schampheleire
` (10 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
This patch promotes the sections on Buildroot configuration and the
configuration of other components to top-level sections, to match the
overview in the introduction of the chapter. The introduction of the
original section is removed as it does not bring additional info anymore.
Some rewording is done as well.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize-configuration.txt | 56 +++++++++++-------------
1 files changed, 25 insertions(+), 31 deletions(-)
diff --git a/docs/manual/customize-configuration.txt b/docs/manual/customize-configuration.txt
--- a/docs/manual/customize-configuration.txt
+++ b/docs/manual/customize-configuration.txt
@@ -1,50 +1,44 @@
// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
-[[customize-store-basics]]
-=== Basics for storing the configuration
+[[customize-store-buildroot-config]]
+=== Storing the Buildroot configuration
-When you have a buildroot configuration that you are satisfied with and
-you want to share it with others, put it under revision control or move
-on to a different buildroot project, you need to store the configuration
-so it can be rebuilt later. The configuration that needs to be stored
-consists of the buildroot configuration, the configuration files for
-packages that you use (kernel, busybox, uClibc, ...), and your rootfs
-modifications.
+The Buildroot configuration can be stored using the command
+ +make savedefconfig+.
-[[customize-store-buildroot-config]]
-==== Buildroot configuration
+This strips the Buildroot configuration down by removing configuration
+options that are at their default value. The result is stored in a file
+called +defconfig+. If you want to save it in another place, change the
++BR2_DEFCONFIG+ option in the Buildroot configuration itself, or call
+make with +make savedefconfig BR2_DEFCONFIG=<path-to-defconfig>+.
-For storing the buildroot configuration itself, buildroot offers the
-following command: +make savedefconfig+.
-
-This strips the buildroot configuration down by removing configuration
-options that are at their default value. The result is stored in a file
-called +defconfig+. If you want to save it in another place, change
-the +BR2_DEFCONFIG+ option, or call make with +make savedefconfig
-BR2_DEFCONFIG=<path-to-defconfig>+. The usual place is
-+configs/<boardname>_defconfig+. The configuration can then be rebuilt by
+The recommended place to store this defconfig is
++configs/<boardname>_defconfig+. If you follow this recommendation, the
+configuration will be listed in +make help+ and can be set again by
running +make <boardname>_defconfig+.
Alternatively, you can copy the file to any other place and rebuild with
+make defconfig BR2_DEFCONFIG=<path-to-defconfig-file>+.
+[[customize-store-package-config]]
+=== Storing the configuration of other components
-[[customize-store-package-config]]
-==== Other package configuration
+The configuration files for BusyBox, the Linux kernel, Barebox and
+uClibc should be stored as well if changed. For each of these
+components, a Buildroot configuration option exists to point to an input
+configuration file, e.g. +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+. To store
+their configuration, set these configuration options to a path where you
+want to save the configuration files, and then use the helper targets
+described below to actually store the configuration.
-The configuration files for busybox, the linux kernel, barebox and
-uClibc should be stored as well if changed. For each of these, a
-buildroot configuration option exists to point to an input
-configuration file, e.g. +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+. To
-save their configuration, set those configuration options to a path
-outside your output directory,
-e.g. +board/<manufacturer>/<boardname>/linux.config+. Then, copy the
-configuration files to that path.
+As explained in xref:customize-dir-structure[], the recommended path to
+store these configuration files is
++board/<company>/<boardname>/foo.config+.
Make sure that you create a configuration file 'before' changing
the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+ etc. options. Otherwise,
-buildroot will try to access this config file, which doesn't exist
+Buildroot will try to access this config file, which doesn't exist
yet, and will fail. You can create the configuration file by running
+make linux-menuconfig+ etc.
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 05 of 13] manual/user guide/customization: re-order introduction
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (3 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 04 of 13] manual/user guide/customization: rework " Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 06 of 13] manual/user guide/customization: add section on device/permission tables Thomas De Schampheleire
` (9 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
This patch re-orders the enumeration of typical project customization
actions:
- move the 'patching packages' section downwards.
- group the entries on post-build scripts and rootfs-overlays to match the
actual section text.
Since indented enumerations use asterixes, update the top-level entries with
asterixes too for consistency.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize.txt | 29 +++++++++++++++--------------
1 files changed, 15 insertions(+), 14 deletions(-)
diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -6,20 +6,21 @@
Typical actions you may need to perform for a given project are:
-- configuring Buildroot (including build options and toolchain,
+* 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
+* configuring other components, like the Linux kernel and BusyBox
+* customizing the generated target filesystem
+ ** 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 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
+* adding project-specific packages
An important note regarding such 'project-specific' customizations:
please carefully consider which changes are indeed project-specific and
@@ -45,6 +46,6 @@
include::customize-post-image.txt[]
+include::customize-packages.txt[]
+
include::customize-store.txt[]
-
-include::customize-packages.txt[]
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 06 of 13] manual/user guide/customization: add section on device/permission tables
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (4 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 05 of 13] manual/user guide/customization: re-order introduction Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 07 of 13] manual/user guide/customization: add section on users tables Thomas De Schampheleire
` (8 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
This patch adds basic documentation on device and permission tables, a topic
which was currently not yet covered in the manual.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize-device-permission-tables.txt | 30 ++++++++++++++
docs/manual/customize-rootfs.txt | 2 +
docs/manual/customize.txt | 4 +
3 files changed, 36 insertions(+), 0 deletions(-)
diff --git a/docs/manual/customize-device-permission-tables.txt b/docs/manual/customize-device-permission-tables.txt
new file mode 100644
--- /dev/null
+++ b/docs/manual/customize-device-permission-tables.txt
@@ -0,0 +1,30 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[customize-device-permission]]
+==== Setting file permissions and ownership and adding custom devices nodes
+
+Sometimes it is needed to set specific permissions or ownership on files
+or device nodes. For example, certain files may need to be owned by
+root. Since the post-build scripts are not run as root, you cannot do
+such changes from there unless you use an explicit fakeroot from the
+post-build script.
+
+Instead, Buildroot provides support for so-called _permission tables_.
+To use this feature, set config option +BR2_ROOTFS_DEVICE_TABLE+ to a
+space-separated list of permission tables, regular text files following
+the xref:makedev-syntax[makedev syntax].
+
+If you are using a static device table (i.e. not using +devtmpfs+,
++mdev+, or +(e)udev+) then you can add device nodes using the same
+syntax, in so-called _device tables_. To use this feature, set config
+option +BR2_ROOTFS_STATIC_DEVICE_TABLE+ to a space-separated list of
+device tables.
+
+As shown in xref:customize-dir-structure[], the recommended location for
+such files is +board/<company>/<boardname>/+.
+
+It should be noted that if the specific permissions or device nodes are
+related to a specific application, you should set variables
++FOO_PERMISSIONS+ and +FOO_DEVICES+ in the package's +.mk+ file instead
+(see xref:generic-package-reference[]).
diff --git a/docs/manual/customize-rootfs.txt b/docs/manual/customize-rootfs.txt
--- a/docs/manual/customize-rootfs.txt
+++ b/docs/manual/customize-rootfs.txt
@@ -97,3 +97,5 @@
This method is not recommended because it duplicates the entire
skeleton, which prevents taking advantage of the fixes or improvements
brought to the default skeleton in later Buildroot releases.
+
+include::customize-device-permission-tables.txt[]
diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -16,6 +16,10 @@
+BR2_ROOTFS_POST_BUILD_SCRIPT+)
** running arbitrary commands prior to generating the filesystem image
(using +BR2_ROOTFS_POST_BUILD_SCRIPT+)
+ ** setting file permissions and ownership (using
+ +BR2_ROOTFS_DEVICE_TABLE+)
+ ** adding custom devices nodes (using
+ +BR2_ROOTFS_STATIC_DEVICE_TABLE+)
* running arbitrary commands after generating the filesystem image
(using +BR2_ROOTFS_POST_IMAGE_SCRIPT+)
* adding project-specific patches to some packages (using
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 07 of 13] manual/user guide/customization: add section on users tables
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (5 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 06 of 13] manual/user guide/customization: add section on device/permission tables Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 08 of 13] manual/user guide/customization: rename section 'Customizing packages' Thomas De Schampheleire
` (7 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
This patch adds basic documentation on users tables, a topic which was
currently not yet covered in the manual.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize-users-tables.txt | 18 ++++++++++++++++++
docs/manual/customize.txt | 3 +++
docs/manual/makeusers-syntax.txt | 2 +-
3 files changed, 22 insertions(+), 1 deletions(-)
diff --git a/docs/manual/customize-users-tables.txt b/docs/manual/customize-users-tables.txt
new file mode 100644
--- /dev/null
+++ b/docs/manual/customize-users-tables.txt
@@ -0,0 +1,18 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[customize-users]]
+=== Adding custom user accounts
+
+Sometimes it is needed to add specific users in the target system.
+To cover this requirement, Buildroot provides support for so-called
+_users tables_. To use this feature, set config option
++BR2_ROOTFS_USERS_TABLES+ to a space-separated list of users tables,
+regular text files following the xref:makeuser-syntax[makeusers syntax].
+
+As shown in xref:customize-dir-structure[], the recommended location for
+such files is +board/<company>/<boardname>/+.
+
+It should be noted that if the custom users are related to a specific
+application, you should set variable +FOO_USERS+ in the package's +.mk+
+file instead (see xref:generic-package-reference[]).
diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -20,6 +20,7 @@
+BR2_ROOTFS_DEVICE_TABLE+)
** adding custom devices nodes (using
+BR2_ROOTFS_STATIC_DEVICE_TABLE+)
+* adding custom user accounts (using +BR2_ROOTFS_USERS_TABLES+)
* running arbitrary commands after generating the filesystem image
(using +BR2_ROOTFS_POST_IMAGE_SCRIPT+)
* adding project-specific patches to some packages (using
@@ -48,6 +49,8 @@
include::customize-rootfs.txt[]
+include::customize-users-tables.txt[]
+
include::customize-post-image.txt[]
include::customize-packages.txt[]
diff --git a/docs/manual/makeusers-syntax.txt b/docs/manual/makeusers-syntax.txt
--- a/docs/manual/makeusers-syntax.txt
+++ b/docs/manual/makeusers-syntax.txt
@@ -1,7 +1,7 @@
// -*- mode:doc -*- ;
[[makeuser-syntax]]
-== Makeuser syntax documentation
+== Makeusers syntax documentation
The syntax to create users is inspired by the makedev syntax, above, but
is specific to Buildroot.
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 08 of 13] manual/user guide/customization: rename section 'Customizing packages'
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (6 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 07 of 13] manual/user guide/customization: add section on users tables Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 09 of 13] manual/user guide/customization: change recommendation for package paths Thomas De Schampheleire
` (6 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
This small patch renames the section 'Customizing packages' to 'Adding
project-specific patches'. Additionally, a minor change is done to the
introduction of this section.
To better reflect the contents, the source file is renamed.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize-patches.txt | 11 ++++++-----
docs/manual/customize.txt | 2 +-
docs/manual/patch-policy.txt | 2 +-
3 files changed, 8 insertions(+), 7 deletions(-)
diff --git a/docs/manual/customize-packages.txt b/docs/manual/customize-patches.txt
rename from docs/manual/customize-packages.txt
rename to docs/manual/customize-patches.txt
--- a/docs/manual/customize-packages.txt
+++ b/docs/manual/customize-patches.txt
@@ -1,11 +1,12 @@
// -*- mode:doc -*- ;
-[[packages-custom]]
-=== Customizing packages
+[[customize-patches]]
+=== Adding project-specific patches
-It is sometimes useful to apply 'extra' patches to packages - over and
-above those provided in Buildroot. This might be used to support custom
-features in a project, for example, or when working on a new architecture.
+It is sometimes useful to apply 'extra' patches to packages - on top of
+those provided in Buildroot. This might be used to support custom
+features in a project, for example, or when working on a new
+architecture.
The +BR2_GLOBAL_PATCH_DIR+ configuration option can be used to specify
a space separated list of one or more directories containing package
diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -53,6 +53,6 @@
include::customize-post-image.txt[]
-include::customize-packages.txt[]
+include::customize-patches.txt[]
include::customize-store.txt[]
diff --git a/docs/manual/patch-policy.txt b/docs/manual/patch-policy.txt
--- a/docs/manual/patch-policy.txt
+++ b/docs/manual/patch-policy.txt
@@ -46,7 +46,7 @@
The +BR2_GLOBAL_PATCH_DIR+ configuration file option can be
used to specify a space separated list of one or more directories
-containing global package patches. See xref:packages-custom[] for
+containing global package patches. See xref:customize-patches[] for
details.
[[patch-apply-order]]
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 09 of 13] manual/user guide/customization: change recommendation for package paths
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (7 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 08 of 13] manual/user guide/customization: rename section 'Customizing packages' Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 10 of 13] manual/user guide/customization: add section on project-specific packages Thomas De Schampheleire
` (5 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
The Buildroot manual was recommending following paths for project-specific
packages:
package/<company>/<boardname>/foo/
$BR2_EXTERNAL/package/<boardname>/foo/
However, if a company has several boards, it is often the case that some
packages are common for different boards. Therefore, introducing a
<boardname> path component is not ideal.
This patch changes the recommendation to:
package/<company>/foo/
$BR2_EXTERNAL/package/foo/
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize-directory-structure.txt | 13 ++++++-------
docs/manual/customize-outside-br.txt | 12 +++++++-----
2 files changed, 13 insertions(+), 12 deletions(-)
diff --git a/docs/manual/customize-directory-structure.txt b/docs/manual/customize-directory-structure.txt
--- a/docs/manual/customize-directory-structure.txt
+++ b/docs/manual/customize-directory-structure.txt
@@ -40,13 +40,12 @@
| +-- <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
+| +-- package1/
+| | +-- Config.in
+| | +-- package1.mk
+| +-- package2/
+| +-- Config.in
+| +-- package2.mk
|
+-- Config.in (if using BR2_EXTERNAL)
+-- external.mk (if using BR2_EXTERNAL)
diff --git a/docs/manual/customize-outside-br.txt b/docs/manual/customize-outside-br.txt
--- a/docs/manual/customize-outside-br.txt
+++ b/docs/manual/customize-outside-br.txt
@@ -81,19 +81,21 @@
looks like:
+
------
-source "$BR2_EXTERNAL/package/<boardname>/package1/Config.in"
-source "$BR2_EXTERNAL/package/<boardname>/package2/Config.in"
+source "$BR2_EXTERNAL/package/package1/Config.in"
+source "$BR2_EXTERNAL/package/package2/Config.in"
------
+
Then, have a +$(BR2_EXTERNAL)/external.mk+ file that looks like:
+
------
-include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*/*.mk))
+include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
------
+
-And then in +$(BR2_EXTERNAL)/package/<boardname>/package1+ and
- +$(BR2_EXTERNAL)/package/<boardname>/package2+ create normal Buildroot
+And then in +$(BR2_EXTERNAL)/package/package1+ and
+ +$(BR2_EXTERNAL)/package/package2+ create normal Buildroot
package recipes, as explained in xref:adding-packages[].
+ If you prefer, you can also group the packages in subdirectories
+ called <boardname> and adapt the above paths accordingly.
* One can store Buildroot defconfigs in the +configs+ subdirectory of
+$(BR2_EXTERNAL)+. Buildroot will automatically show them in the
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 10 of 13] manual/user guide/customization: add section on project-specific packages
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (8 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 09 of 13] manual/user guide/customization: change recommendation for package paths Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 11 of 13] manual/user guide/customization: refer to dir structure from rootfs section Thomas De Schampheleire
` (4 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
This patch adds a new section to chapter 'Project-specific customization' to
describe how to add project-specific packages from a project-specific
directory. The principle was already described in the presentation 'Using
Buildroot for real projects' but was never documented in official Buildroot
documentation.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize-packages.txt | 71 ++++++++++++++++++++++++++++++
docs/manual/customize.txt | 2 +
2 files changed, 73 insertions(+), 0 deletions(-)
diff --git a/docs/manual/customize-packages.txt b/docs/manual/customize-packages.txt
new file mode 100644
--- /dev/null
+++ b/docs/manual/customize-packages.txt
@@ -0,0 +1,71 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[customize-packages]]
+=== Adding project-specific packages
+
+In general, any new package should be added directly in the +package+
+directory and submitted to the Buildroot upstream project. How to add
+packages to Buildroot in general is explained in full detail in
+xref:adding-packages[] and will not be repeated here. However, your
+project may need some proprietary packages that cannot be upstreamed.
+This section will explain how you can keep such project-specific
+packages in a project-specific directory.
+
+As shown in xref:customize-dir-structure[], the recommended location for
+project-specific packages is +package/<company>/+. If you are using the
++BR2_EXTERNAL+ feature (see xref:outside-br-custom[]) the recommended
+location is +$(BR2_EXTERNAL)/package/+.
+
+However, Buildroot will not be aware of the packages in this location,
+unless we perform some additional steps. As explained in
+xref:adding-packages[], a package in Buildroot basically consists of two
+files: a +.mk+ file (describing how to build the package) and a
++Config.in+ file (describing the configuration options for this
+package).
+
+Buildroot will automatically include the +.mk+ files in first-level
+subdirectories of the +package+ directory (using the pattern
++package/\*/*.mk+). If we want Buildroot to include +.mk+ files from
+deeper subdirectories (like +package/<company>/package1/+) then we
+simply have to add a +.mk+ file in a first-level subdirectory that
+includes these additional +.mk+ files. Therefore, create a file
++package/<company>/<company>.mk+ with following contents (assuming you
+have only one extra directory level below +package/<company>/+):
+
+-----
+include $(sort $(wildcard package/<company>/*/*.mk))
+-----
+
+If you are using +BR2_EXTERNAL+, create a file
++$(BR2_EXTERNAL)/external.mk+ with following contents (again assuming only
+one extra level):
+
+-----
+include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
+-----
+
+For the +Config.in+ files, create a file +package/<company>/Config.in+
+that includes the +Config.in+ files of all your packages. An exhaustive
+list has to be provided since wildcards are not supported in the source command of kconfig.
+For example:
+
+-----
+source "package/<company>/package1/Config.in"
+source "package/<company>/package2/Config.in"
+-----
+
+Include this new file +package/<company>/Config.in+ from
++package/Config.in+, preferably in a company-specific menu to make
+merges with future Buildroot versions easier.
+
+If you are using +BR2_EXTERNAL+, create a file
++$(BR2_EXTERNAL)/Config.in+ with similar contents:
+
+-----
+source "$BR2_EXTERNAL/package/package1/Config.in"
+source "$BR2_EXTERNAL/package/package2/Config.in"
+-----
+
+You do not have to add an include for this +$(BR2_EXTERNAL)/Config.in+
+file as it is included automatically.
diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -55,4 +55,6 @@
include::customize-patches.txt[]
+include::customize-packages.txt[]
+
include::customize-store.txt[]
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 11 of 13] manual/user guide/customization: refer to dir structure from rootfs section
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (9 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 10 of 13] manual/user guide/customization: add section on project-specific packages Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 12 of 13] manual/user guide/customization: rework 'step-by-step instructions' Thomas De Schampheleire
` (3 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
This small patch adds references to the section on 'recommended directory
structure' from sections explaining the post-build script and rootfs
overlay.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize-rootfs.txt | 6 ++++++
1 files changed, 6 insertions(+), 0 deletions(-)
diff --git a/docs/manual/customize-rootfs.txt b/docs/manual/customize-rootfs.txt
--- a/docs/manual/customize-rootfs.txt
+++ b/docs/manual/customize-rootfs.txt
@@ -21,6 +21,9 @@
directories of version control systems, like +.git+, +.svn+, +.hg+,
etc., files called +.empty+ and files ending in +~+ are excluded from
the copy.
++
+As shown in xref:customize-dir-structure[], the recommended path for
+ this overlay is +board/<company>/<boardname>/rootfs-overlay+.
Post-build scripts (+BR2_ROOTFS_POST_BUILD_SCRIPT+)::
+
@@ -37,6 +40,9 @@
files, you should fix that package rather than work around it with some
post-build cleanup scripts.
+
+As shown in xref:customize-dir-structure[], the recommended path for
+ this script is +board/<company>/<boardname>/post_build.sh+.
++
The post-build scripts are run with the main Buildroot tree as current
working directory. The path to the target filesystem is passed as the
first argument to each script. If the config option
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 12 of 13] manual/user guide/customization: rework 'step-by-step instructions'
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (10 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 11 of 13] manual/user guide/customization: refer to dir structure from rootfs section Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 19:39 ` [Buildroot] [PATCH 13 of 13] manual/user guide/customization: add section on layered customization Thomas De Schampheleire
` (2 subsequent siblings)
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
This patch reworks the section 'Step-by-step instructions for storing
configuration' as follows:
- rename into 'Quick guide to storing your project-specific customizations'
and hence make it serve as a summary to the chapter
- change the introduction to make this clear
- update paths to line-up with section 'recommended directory structure'
- recommend BR2_GLOBAL_PATCH_DIR, as is done in the section on adding
patches.
- mention how to add packages in a project-specific directory (to be
expanded in another patch)
- minor rewording
- rename file into customize-quick-guide.txt
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize-quick-guide.txt | 57 ++++++++++++++++----------
docs/manual/customize.txt | 2 +-
2 files changed, 36 insertions(+), 23 deletions(-)
diff --git a/docs/manual/customize-store.txt b/docs/manual/customize-quick-guide.txt
rename from docs/manual/customize-store.txt
rename to docs/manual/customize-quick-guide.txt
--- a/docs/manual/customize-store.txt
+++ b/docs/manual/customize-quick-guide.txt
@@ -1,18 +1,17 @@
// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
-=== Step-by-step instructions for storing configuration
+=== Quick guide to storing your project-specific customizations
-To store the configuration for a specific product, device or
-application, it is advisable to use the same conventions as for the
-board support: put the buildroot defconfig in the +configs+ directory,
-and any other files in a subdirectory of the +boards+ directory. This
-section gives step-by-step instructions about how to do that. Of course,
-you can skip the steps that are not relevant for your use case.
+Earlier in this chapter, the different methods for making
+project-specific customizations have been described. This section will
+now summarize all this by providing step-by-step instructions to storing your
+project-specific customizations. Clearly, the steps that are not relevant to
+your project can be skipped.
1. +make menuconfig+ to configure toolchain, packages and kernel.
1. +make linux-menuconfig+ to update the kernel config, similar for
- other configuration.
+ other configuration like busybox, uclibc, ...
1. +mkdir -p board/<manufacturer>/<boardname>+
1. Set the following options to +board/<manufacturer>/<boardname>/<package>.config+
(as far as they are relevant):
@@ -25,27 +24,41 @@
* +make linux-update-defconfig+
* +make busybox-update-config+
* +make uclibc-update-config+
- * +cp <output>/build/at91bootstrap3-*/.config board/<manufacturer>/<boardname>/at91bootstrap3.config+
+ * +cp <output>/build/at91bootstrap3-*/.config
+ board/<manufacturer>/<boardname>/at91bootstrap3.config+
* +make barebox-update-defconfig+
-1. Create +board/<manufacturer>/<boardname>/fs-overlay/+ and fill it
+1. Create +board/<manufacturer>/<boardname>/rootfs-overlay/+ and fill it
with additional files you need on your rootfs, e.g.
- +board/<manufacturer>/<boardname>/fs-overlay/etc/inittab+.
+ +board/<manufacturer>/<boardname>/rootfs-overlay/etc/inittab+.
Set +BR2_ROOTFS_OVERLAY+
- to +board/<manufacturer>/<boardname>/fs-overlay+.
+ to +board/<manufacturer>/<boardname>/rootfs-overlay+.
1. Create a post-build script
- +board/<manufacturer>/<boardname>/post-build.sh+. Set
+ +board/<manufacturer>/<boardname>/post_build.sh+. Set
+BR2_ROOTFS_POST_BUILD_SCRIPT+ to
- +board/<manufacturer>/<boardname>/post-build.sh+
+ +board/<manufacturer>/<boardname>/post_build.sh+
1. If additional setuid permissions have to be set or device nodes have
to be created, create +board/<manufacturer>/<boardname>/device_table.txt+
and add that path to +BR2_ROOTFS_DEVICE_TABLE+.
+1. If additional user accounts have to be created, create
+ +board/<manufacturer>/<boardname>/users_table.txt+ and add that path
+ to +BR2_ROOTFS_USERS_TABLES+.
+1. To add custom patches to certain packages, set +BR2_GLOBAL_PATCH_DIR+
+ to +board/<manufacturer>/<boardname>/patches/+ and add your patches
+ for each package in a subdirectory named after the package. Each
+ patch should be called +<packagename>-<num>-<description>.patch+.
+1. Specifically for the Linux kernel, there also exists the option
+ +BR2_LINUX_KERNEL_PATCH+ with as main advantage that it can also
+ download patches from a URL. If you do not need this,
+ +BR2_GLOBAL_PATCH_DIR+ is preferred. U-Boot, Barebox, at91bootstrap
+ and at91bootstrap3 also have separate options, but these do not
+ provide any advantage over +BR2_GLOBAL_PATCH_DIR+ and will likely be
+ removed in the future.
+1. If you need to add project-specific packages, create
+ +package/<manufacturer>/+ and place your packages in that
+ directory. Create an overall +<manufacturer>.mk+ file that
+ includes the +.mk+ files of all your packages. Create an overall
+ +Config.in+ file that sources the +Config.in+ files of all your
+ packages. Include this +Config.in+ file from Buildroot's
+ +package/Config.in+ file.
1. +make savedefconfig+ to save the buildroot configuration.
1. +cp defconfig configs/<boardname>_defconfig+
-1. To add patches to the linux build, set +BR2_LINUX_KERNEL_PATCH+ to
- +board/<manufacturer>/<boardname>/patches/linux/+ and add your
- patches in that directory. Each patch should be called
- +linux-<num>-<description>.patch+. Similar for U-Boot, barebox,
- at91bootstrap and at91bootstrap3.
-1. If you need modifications to other packages, or if you need to add
- packages, do that directly in the +packages/+ directory, following the
- instructions in xref:adding-packages[].
diff --git a/docs/manual/customize.txt b/docs/manual/customize.txt
--- a/docs/manual/customize.txt
+++ b/docs/manual/customize.txt
@@ -57,4 +57,4 @@
include::customize-packages.txt[]
-include::customize-store.txt[]
+include::customize-quick-guide.txt[]
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 13 of 13] manual/user guide/customization: add section on layered customization
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (11 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 12 of 13] manual/user guide/customization: rework 'step-by-step instructions' Thomas De Schampheleire
@ 2014-09-18 19:39 ` Thomas De Schampheleire
2014-09-18 20:03 ` [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas Petazzoni
2014-09-21 17:42 ` Thomas Petazzoni
14 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-18 19:39 UTC (permalink / raw)
To: buildroot
Inspired by some text in the 'project-specific patches' section, this patch
adds a separate section on layering customizations by providing multiple
post-build scripts, multiple rootfs overlays, etc.
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
---
docs/manual/customize-directory-structure.txt | 51 +++++++++++++++++++
docs/manual/customize-patches.txt | 40 +--------------
2 files changed, 52 insertions(+), 39 deletions(-)
diff --git a/docs/manual/customize-directory-structure.txt b/docs/manual/customize-directory-structure.txt
--- a/docs/manual/customize-directory-structure.txt
+++ b/docs/manual/customize-directory-structure.txt
@@ -56,3 +56,54 @@
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.
+
+==== Implementing layered customizations
+
+It is quite common for a user to have several related projects that partly
+need the same customizations. Instead of duplicating these
+customizations for each project, it is recommended to use a layered
+customization approach, as explained in this section.
+
+Almost all of the customization methods available in Buildroot, like
+post-build scripts and root filesystem overlays, accept a
+space-separated list of items. The specified items are always treated in
+order, from left to right. By creating more than one such item, one for
+the common customizations and another one for the really
+project-specific customizations, you can avoid unnecessary duplication.
+Each layer is typically embodied by a separate directory inside
++board/<company>/+. Depending on your projects, you could even introduce
+more than two layers.
+
+An example directory structure for where a user has two customization
+layers 'common' and 'fooboard' is:
+
+-----
++-- board/
+ +-- <company>/
+ +-- common/
+ | +-- post_build.sh
+ | +-- rootfs_overlay/
+ | | +-- ...
+ | +-- patches/
+ | +-- ...
+ |
+ +-- fooboard/
+ +-- linux.config
+ +-- busybox.config
+ +-- <other configuration files>
+ +-- post_build.sh
+ +-- rootfs_overlay/
+ | +-- ...
+ +-- patches/
+ +-- ...
+-----
+
+For example, if the user has the +BR2_GLOBAL_PATCH_DIR+ configuration
+option set as:
+
+-----
+BR2_GLOBAL_PATCH_DIR="board/<company>/common/patches board/<company>/fooboard/patches"
+-----
+
+then first the patches from the 'common' layer would be applied,
+followed by the patches from the 'fooboard' layer.
diff --git a/docs/manual/customize-patches.txt b/docs/manual/customize-patches.txt
--- a/docs/manual/customize-patches.txt
+++ b/docs/manual/customize-patches.txt
@@ -10,13 +10,7 @@
The +BR2_GLOBAL_PATCH_DIR+ configuration option can be used to specify
a space separated list of one or more directories containing package
-patches. By specifying multiple global patch directories, a user could
-implement a layered approach to patches. This could be useful when a
-user has multiple boards that share a common processor architecture.
-It is often the case that a subset of patches for a package need to be
-shared between the different boards a user has. However, each board
-may require specific patches for the package that build on top of the
-common subset of patches.
+patches.
For a specific version +<packageversion>+ of a specific package
+<packagename>+, patches are applied from +BR2_GLOBAL_PATCH_DIR+ as
@@ -63,35 +57,3 @@
patches that are applied after patches available in +BR2_GLOBAL_PATCH_DIR+,
as it is done from a post-patch hook of the Linux package.
-An example directory structure for where a user has multiple
-directories specified for +BR2_GLOBAL_PATCH_DIR+ may look like this:
-
------
-board/
-+-- common-fooarch
-| +-- patches
-| +-- linux
-| | +-- linux-patch1.patch
-| | +-- linux-patch2.patch
-| +-- uboot
-| +-- foopkg
-+-- fooarch-board
- +-- patches
- +-- linux
- | +-- linux-patch3.patch
- +-- uboot
- +-- foopkg
------
-
-If the user has the +BR2_GLOBAL_PATCH_DIR+ configuration option set as
-follows:
-
------
-BR2_GLOBAL_PATCH_DIR="board/common-fooarch/patches board/fooarch-board/patches"
------
-
-Then the patches would applied as follows for the Linux kernel:
-
-. board/common-fooarch/patches/linux/linux-patch1.patch
-. board/common-fooarch/patches/linux/linux-patch2.patch
-. board/fooarch-board/patches/linux/linux-patch3.patch
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (12 preceding siblings ...)
2014-09-18 19:39 ` [Buildroot] [PATCH 13 of 13] manual/user guide/customization: add section on layered customization Thomas De Schampheleire
@ 2014-09-18 20:03 ` Thomas Petazzoni
2014-09-19 6:40 ` Thomas De Schampheleire
2014-09-21 17:42 ` Thomas Petazzoni
14 siblings, 1 reply; 17+ messages in thread
From: Thomas Petazzoni @ 2014-09-18 20:03 UTC (permalink / raw)
To: buildroot
Dear Thomas De Schampheleire,
On Thu, 18 Sep 2014 21:39:23 +0200, Thomas De Schampheleire wrote:
> This series makes improvements to the Project-specific customizations
> chapter in the manual.
>
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
For the entire series:
Reviewed-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
I noticed a few possible improvements here and there, but I generally
believe that the patch series brings very nice improvements already,
and since I know reworking such patch series is particularly boring,
I'd prefer to see the patches committed as is, and the other possible
improvements be done as followup patches.
Thanks!
Thomas
--
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
^ permalink raw reply [flat|nested] 17+ messages in thread* [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section
2014-09-18 20:03 ` [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas Petazzoni
@ 2014-09-19 6:40 ` Thomas De Schampheleire
0 siblings, 0 replies; 17+ messages in thread
From: Thomas De Schampheleire @ 2014-09-19 6:40 UTC (permalink / raw)
To: buildroot
Hi Thomas,
On Thu, Sep 18, 2014 at 10:03 PM, Thomas Petazzoni
<thomas.petazzoni@free-electrons.com> wrote:
> Dear Thomas De Schampheleire,
>
> On Thu, 18 Sep 2014 21:39:23 +0200, Thomas De Schampheleire wrote:
>
>> This series makes improvements to the Project-specific customizations
>> chapter in the manual.
>>
>> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>
> For the entire series:
>
> Reviewed-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
>
Thanks a lot for your review.
> I noticed a few possible improvements here and there, but I generally
> believe that the patch series brings very nice improvements already,
> and since I know reworking such patch series is particularly boring,
> I'd prefer to see the patches committed as is, and the other possible
> improvements be done as followup patches.
If you are talking about additions of new information or some rework
of the existing one, then I fully agree with your proposed strategy. I
assume you will provide further feedback about these improvements
later?
However, if it's typos or incorrect information you refer to, then I
think we should fix it in the current series.
Thanks,
Thomas
^ permalink raw reply [flat|nested] 17+ messages in thread
* [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section
2014-09-18 19:39 [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas De Schampheleire
` (13 preceding siblings ...)
2014-09-18 20:03 ` [Buildroot] [PATCH 00 of 13] manual: improvements in 'Project-specific customization' section Thomas Petazzoni
@ 2014-09-21 17:42 ` Thomas Petazzoni
14 siblings, 0 replies; 17+ messages in thread
From: Thomas Petazzoni @ 2014-09-21 17:42 UTC (permalink / raw)
To: buildroot
Dear Thomas De Schampheleire,
On Thu, 18 Sep 2014 21:39:23 +0200, Thomas De Schampheleire wrote:
> Hi,
>
> This series makes improvements to the Project-specific customizations
> chapter in the manual.
>
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>
> ---
> Thomas De Schampheleire (13)
> manual: move 'Creating your own board support' from User to Developer guide
> manual/developer guide: minor rework of 'adding board support' section
> manual/user guide/customization: move section on storing configuration
> manual/user guide/customization: rework section on storing configuration
> manual/user guide/customization: re-order introduction
> manual/user guide/customization: add section on device/permission tables
> manual/user guide/customization: add section on users tables
> manual/user guide/customization: rename section 'Customizing packages'
> manual/user guide/customization: change recommendation for package paths
> manual/user guide/customization: add section on project-specific packages
> manual/user guide/customization: refer to dir structure from rootfs section
> manual/user guide/customization: rework 'step-by-step instructions'
> manual/user guide/customization: add section on layered customization
Series applied, thanks!
Thomas
--
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
^ permalink raw reply [flat|nested] 17+ messages in thread