kumquat-buildroot/docs/manual/customize-store.txt

158 lines
7.2 KiB
Plaintext
Raw Normal View History

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
[[customize-store]]
manual: use one-line titles instead of two-line titles (trivial) Asciidoc supports two syntaxes for section titles: two-line titles (title plus underline consisting of a particular symbol), and one-line titles (title prefixed with a specific number of = signs). The two-line title underlines are: Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ and the one-line title prefixes: = Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) ===== The buildroot manual is currenly using the two-line titles, but this has multiple disadvantages: - asciidoc also uses some of the underline symbols for other purposes (like preformatted code, example blocks, ...), which makes it difficult to do mass replacements, such as a planned follow-up patch that needs to move all sections one level down. - it is difficult to remember which level a given underline symbol (=-~^+) corresponds to, while counting = signs is easy. This patch changes all two-level titles to one-level titles in the manual. The bulk of the change was done with the following Python script, except for the level 1 titles (-----) as these underlines are also used for literal code blocks. This patch only changes the titles, no other changes. In adding-packages-directory.txt, I did add missing newlines between some titles and their content. ---------------------------------------------------------------------------- #!/usr/bin/env python import sys import mmap import re for input in sys.argv[1:]: f = open(input, 'r+') f.flush() s = mmap.mmap(f.fileno(), 0) # Level 0 (top level): ====================== = # Level 1: ---------------------- == # Level 2: ~~~~~~~~~~~~~~~~~~~~~~ === # Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ==== # Level 4 (bottom level): ++++++++++++++++++++++ ===== def replace_title(s, symbol, replacement): pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE) return pattern.sub(r'%s \1' % replacement, s) new = s new = replace_title(new, '=', '=') new = replace_title(new, '+', '=====') new = replace_title(new, '^', '====') new = replace_title(new, '~', '===') #new = replace_title(new, '-', '==') s.seek(0) s.write(new) s.resize(s.tell()) s.close() f.close() ---------------------------------------------------------------------------- Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
== 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-basics]]
manual: use one-line titles instead of two-line titles (trivial) Asciidoc supports two syntaxes for section titles: two-line titles (title plus underline consisting of a particular symbol), and one-line titles (title prefixed with a specific number of = signs). The two-line title underlines are: Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ and the one-line title prefixes: = Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) ===== The buildroot manual is currenly using the two-line titles, but this has multiple disadvantages: - asciidoc also uses some of the underline symbols for other purposes (like preformatted code, example blocks, ...), which makes it difficult to do mass replacements, such as a planned follow-up patch that needs to move all sections one level down. - it is difficult to remember which level a given underline symbol (=-~^+) corresponds to, while counting = signs is easy. This patch changes all two-level titles to one-level titles in the manual. The bulk of the change was done with the following Python script, except for the level 1 titles (-----) as these underlines are also used for literal code blocks. This patch only changes the titles, no other changes. In adding-packages-directory.txt, I did add missing newlines between some titles and their content. ---------------------------------------------------------------------------- #!/usr/bin/env python import sys import mmap import re for input in sys.argv[1:]: f = open(input, 'r+') f.flush() s = mmap.mmap(f.fileno(), 0) # Level 0 (top level): ====================== = # Level 1: ---------------------- == # Level 2: ~~~~~~~~~~~~~~~~~~~~~~ === # Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ==== # Level 4 (bottom level): ++++++++++++++++++++++ ===== def replace_title(s, symbol, replacement): pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE) return pattern.sub(r'%s \1' % replacement, s) new = s new = replace_title(new, '=', '=') new = replace_title(new, '+', '=====') new = replace_title(new, '^', '====') new = replace_title(new, '~', '===') #new = replace_title(new, '-', '==') s.seek(0) s.write(new) s.resize(s.tell()) s.close() f.close() ---------------------------------------------------------------------------- Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
=== Basics for storing the configuration
[[customize-store-buildroot-config]]
manual: use one-line titles instead of two-line titles (trivial) Asciidoc supports two syntaxes for section titles: two-line titles (title plus underline consisting of a particular symbol), and one-line titles (title prefixed with a specific number of = signs). The two-line title underlines are: Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ and the one-line title prefixes: = Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) ===== The buildroot manual is currenly using the two-line titles, but this has multiple disadvantages: - asciidoc also uses some of the underline symbols for other purposes (like preformatted code, example blocks, ...), which makes it difficult to do mass replacements, such as a planned follow-up patch that needs to move all sections one level down. - it is difficult to remember which level a given underline symbol (=-~^+) corresponds to, while counting = signs is easy. This patch changes all two-level titles to one-level titles in the manual. The bulk of the change was done with the following Python script, except for the level 1 titles (-----) as these underlines are also used for literal code blocks. This patch only changes the titles, no other changes. In adding-packages-directory.txt, I did add missing newlines between some titles and their content. ---------------------------------------------------------------------------- #!/usr/bin/env python import sys import mmap import re for input in sys.argv[1:]: f = open(input, 'r+') f.flush() s = mmap.mmap(f.fileno(), 0) # Level 0 (top level): ====================== = # Level 1: ---------------------- == # Level 2: ~~~~~~~~~~~~~~~~~~~~~~ === # Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ==== # Level 4 (bottom level): ++++++++++++++++++++++ ===== def replace_title(s, symbol, replacement): pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE) return pattern.sub(r'%s \1' % replacement, s) new = s new = replace_title(new, '=', '=') new = replace_title(new, '+', '=====') new = replace_title(new, '^', '====') new = replace_title(new, '~', '===') #new = replace_title(new, '-', '==') s.seek(0) s.write(new) s.resize(s.tell()) s.close() f.close() ---------------------------------------------------------------------------- Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
==== 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]]
manual: use one-line titles instead of two-line titles (trivial) Asciidoc supports two syntaxes for section titles: two-line titles (title plus underline consisting of a particular symbol), and one-line titles (title prefixed with a specific number of = signs). The two-line title underlines are: Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ and the one-line title prefixes: = Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) ===== The buildroot manual is currenly using the two-line titles, but this has multiple disadvantages: - asciidoc also uses some of the underline symbols for other purposes (like preformatted code, example blocks, ...), which makes it difficult to do mass replacements, such as a planned follow-up patch that needs to move all sections one level down. - it is difficult to remember which level a given underline symbol (=-~^+) corresponds to, while counting = signs is easy. This patch changes all two-level titles to one-level titles in the manual. The bulk of the change was done with the following Python script, except for the level 1 titles (-----) as these underlines are also used for literal code blocks. This patch only changes the titles, no other changes. In adding-packages-directory.txt, I did add missing newlines between some titles and their content. ---------------------------------------------------------------------------- #!/usr/bin/env python import sys import mmap import re for input in sys.argv[1:]: f = open(input, 'r+') f.flush() s = mmap.mmap(f.fileno(), 0) # Level 0 (top level): ====================== = # Level 1: ---------------------- == # Level 2: ~~~~~~~~~~~~~~~~~~~~~~ === # Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ==== # Level 4 (bottom level): ++++++++++++++++++++++ ===== def replace_title(s, symbol, replacement): pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE) return pattern.sub(r'%s \1' % replacement, s) new = s new = replace_title(new, '=', '=') new = replace_title(new, '+', '=====') new = replace_title(new, '^', '====') new = replace_title(new, '~', '===') #new = replace_title(new, '-', '==') s.seek(0) s.write(new) s.resize(s.tell()) s.close() f.close() ---------------------------------------------------------------------------- Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
==== 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+.
[[customize-store-board-support]]
manual: use one-line titles instead of two-line titles (trivial) Asciidoc supports two syntaxes for section titles: two-line titles (title plus underline consisting of a particular symbol), and one-line titles (title prefixed with a specific number of = signs). The two-line title underlines are: Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ and the one-line title prefixes: = Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) ===== The buildroot manual is currenly using the two-line titles, but this has multiple disadvantages: - asciidoc also uses some of the underline symbols for other purposes (like preformatted code, example blocks, ...), which makes it difficult to do mass replacements, such as a planned follow-up patch that needs to move all sections one level down. - it is difficult to remember which level a given underline symbol (=-~^+) corresponds to, while counting = signs is easy. This patch changes all two-level titles to one-level titles in the manual. The bulk of the change was done with the following Python script, except for the level 1 titles (-----) as these underlines are also used for literal code blocks. This patch only changes the titles, no other changes. In adding-packages-directory.txt, I did add missing newlines between some titles and their content. ---------------------------------------------------------------------------- #!/usr/bin/env python import sys import mmap import re for input in sys.argv[1:]: f = open(input, 'r+') f.flush() s = mmap.mmap(f.fileno(), 0) # Level 0 (top level): ====================== = # Level 1: ---------------------- == # Level 2: ~~~~~~~~~~~~~~~~~~~~~~ === # Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ==== # Level 4 (bottom level): ++++++++++++++++++++++ ===== def replace_title(s, symbol, replacement): pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE) return pattern.sub(r'%s \1' % replacement, s) new = s new = replace_title(new, '=', '=') new = replace_title(new, '+', '=====') new = replace_title(new, '^', '====') new = replace_title(new, '~', '===') #new = replace_title(new, '-', '==') s.seek(0) s.write(new) s.resize(s.tell()) s.close() f.close() ---------------------------------------------------------------------------- Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
=== 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.
manual: use one-line titles instead of two-line titles (trivial) Asciidoc supports two syntaxes for section titles: two-line titles (title plus underline consisting of a particular symbol), and one-line titles (title prefixed with a specific number of = signs). The two-line title underlines are: Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ and the one-line title prefixes: = Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) ===== The buildroot manual is currenly using the two-line titles, but this has multiple disadvantages: - asciidoc also uses some of the underline symbols for other purposes (like preformatted code, example blocks, ...), which makes it difficult to do mass replacements, such as a planned follow-up patch that needs to move all sections one level down. - it is difficult to remember which level a given underline symbol (=-~^+) corresponds to, while counting = signs is easy. This patch changes all two-level titles to one-level titles in the manual. The bulk of the change was done with the following Python script, except for the level 1 titles (-----) as these underlines are also used for literal code blocks. This patch only changes the titles, no other changes. In adding-packages-directory.txt, I did add missing newlines between some titles and their content. ---------------------------------------------------------------------------- #!/usr/bin/env python import sys import mmap import re for input in sys.argv[1:]: f = open(input, 'r+') f.flush() s = mmap.mmap(f.fileno(), 0) # Level 0 (top level): ====================== = # Level 1: ---------------------- == # Level 2: ~~~~~~~~~~~~~~~~~~~~~~ === # Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ==== # Level 4 (bottom level): ++++++++++++++++++++++ ===== def replace_title(s, symbol, replacement): pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE) return pattern.sub(r'%s \1' % replacement, s) new = s new = replace_title(new, '=', '=') new = replace_title(new, '+', '=====') new = replace_title(new, '^', '====') new = replace_title(new, '~', '===') #new = replace_title(new, '-', '==') s.seek(0) s.write(new) s.resize(s.tell()) s.close() f.close() ---------------------------------------------------------------------------- Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
=== Step-by-step instructions for storing configuration
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.
1. +make menuconfig+ to configure toolchain, packages and kernel.
1. +make linux-menuconfig+ to update the kernel config, similar for
other configuration.
1. +mkdir -p board/<manufacturer>/<boardname>+
1. Set the following options to +board/<manufacturer>/<boardname>/<package>.config+
(as far as they are relevant):
* +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+
* +BR2_PACKAGE_BUSYBOX_CONFIG+
* +BR2_UCLIBC_CONFIG+
* +BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE+
* +BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE+
1. Write the configuration files:
* +make linux-update-defconfig+
* +make busybox-update-config+
* +make uclibc-update-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
with additional files you need on your rootfs, e.g.
+board/<manufacturer>/<boardname>/fs-overlay/etc/inittab+.
Set +BR2_ROOTFS_OVERLAY+
to +board/<manufacturer>/<boardname>/fs-overlay+.
1. Create a post-build script
+board/<manufacturer>/<boardname>/post-build.sh+. Set
+BR2_ROOTFS_POST_BUILD_SCRIPT+ to
+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. +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[].