manual: add section about storing the configuration.
Reuse part of board-support.txt, and remove that one because it was unused. [Peter: minor tweaks to text] Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be> Signed-off-by: Peter Korsgaard <jacmet@sunsite.dk>
This commit is contained in:
Arnout Vandecappelle (Essensium/Mind)
Peter Korsgaard
parent
2cd9121c77
commit
a0ad75a125
@ -168,6 +168,7 @@ coding style].
|
||||
|
||||
The +.mk+ file
|
||||
~~~~~~~~~~~~~~
|
||||
[[adding-packages-mk]]
|
||||
|
||||
Finally, here's the hardest part. Create a file named +libfoo.mk+. It
|
||||
describes how the package should be downloaded, configured, built,
|
||||
|
||||
@ -1,38 +0,0 @@
|
||||
// -*- mode:doc -*- ;
|
||||
|
||||
[[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 upstream versions of the Linux kernel and
|
||||
bootloaders where possible, and also to use default kernel and bootloader
|
||||
configurations if possible. If the defaults 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+ (after replacing, of course,
|
||||
MANUFACTURER and BOARDNAME with the appropriate values, in lower case
|
||||
letters). You can then store your patches and configurations in these
|
||||
directories, and reference them from the main Buildroot configuration.
|
||||
160
docs/manual/customize-store.txt
Normal file
160
docs/manual/customize-store.txt
Normal file
@ -0,0 +1,160 @@
|
||||
// -*- mode:doc -*-
|
||||
|
||||
[[customize-store]]
|
||||
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.
|
||||
|
||||
Basics for storing the configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
[[customize-store-basics]]
|
||||
|
||||
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+. Copy this file to +foo_defconfig+ in the +configs+
|
||||
directory. The configuration can then be rebuilt by running
|
||||
+make foo_defconfig+
|
||||
|
||||
Alternatively, you can copy the file to any other place and rebuild with
|
||||
+make defconfig BR2_DEFCONFIG=<path-to-defconfig-file>+.
|
||||
|
||||
|
||||
Other package configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The configuration files for busybox, the linux kernel, barebox, uClibc and
|
||||
crosstool-NG 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 crosstool-NG and at91bootstrap3, no helper exists so you
|
||||
have to copy the config file manually to +BR2_TOOLCHAIN_CTNG_CONFIG+,
|
||||
resp. +BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE+.
|
||||
|
||||
|
||||
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
|
||||
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_TOOLCHAIN_CTNG_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+
|
||||
* +cp <output>/build/build-toolchain/.config board/<manufacturer>/<boardname>/ctng.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+.
|
||||
1. Create a post-build script
|
||||
+board/<manufacturer>/<boardname>/post-build.sh+. It should contain
|
||||
the following command:
|
||||
+
|
||||
------------
|
||||
rsync -a --exclude .empty --exclude '*~' ${0%/*}/fs-overlay $1
|
||||
------------
|
||||
+
|
||||
1. 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[].
|
||||
@ -12,3 +12,5 @@ include::customize-uclibc-config.txt[]
|
||||
include::customize-kernel-config.txt[]
|
||||
|
||||
include::customize-toolchain.txt[]
|
||||
|
||||
include::customize-store.txt[]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user