From patchwork Thu Nov 8 08:36:07 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Arnout Vandecappelle X-Patchwork-Id: 197795 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from silver.osuosl.org (silver.osuosl.org [140.211.166.136]) by ozlabs.org (Postfix) with ESMTP id 9DA972C0134 for ; Thu, 8 Nov 2012 19:36:30 +1100 (EST) Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id D2407311B5; Thu, 8 Nov 2012 08:36:28 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from silver.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id bbfR38AEPYvm; Thu, 8 Nov 2012 08:36:25 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by silver.osuosl.org (Postfix) with ESMTP id 4A1DD201E2; Thu, 8 Nov 2012 08:36:25 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from whitealder.osuosl.org (whitealder.osuosl.org [140.211.166.138]) by ash.osuosl.org (Postfix) with ESMTP id 1E7A98F74A for ; Thu, 8 Nov 2012 08:36:27 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id 172268CA76 for ; Thu, 8 Nov 2012 08:36:23 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from whitealder.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id xCnefH6zDmzo for ; Thu, 8 Nov 2012 08:36:21 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from viper.mind.be (132.79-246-81.adsl-static.isp.belgacom.be [81.246.79.132]) by whitealder.osuosl.org (Postfix) with ESMTPS id 3A6CC8CA4B for ; Thu, 8 Nov 2012 08:36:21 +0000 (UTC) Received: from [172.16.2.6] (helo=vandecaa-laptop) by viper.mind.be with esmtp (Exim 4.69) (envelope-from ) id 1TWNaz-0003by-FO; Thu, 08 Nov 2012 09:36:18 +0100 Received: from arnout by vandecaa-laptop with local (Exim 4.80) (envelope-from ) id 1TWNay-0006Am-V7; Thu, 08 Nov 2012 09:36:17 +0100 From: "Arnout Vandecappelle (Essensium/Mind)" To: buildroot@busybox.net Date: Thu, 8 Nov 2012 09:36:07 +0100 Message-Id: <1352363776-23638-1-git-send-email-arnout@mind.be> X-Mailer: git-send-email 1.7.10.4 Subject: [Buildroot] [PATCH v3 01/10] manual: add section about storing the configuration. X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.14 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: buildroot-bounces@busybox.net Sender: buildroot-bounces@busybox.net From: "Arnout Vandecappelle (Essensium/Mind)" Reuse part of board-support.txt, and remove that one because it was unused. Signed-off-by: Arnout Vandecappelle (Essensium/Mind) --- v2: mention LINUX_KERNEL_PATCH also in in-tree documentation (Samuel Martin) v3: - Removed the section about out-of-tree configuration. - Added barebox config. - Comments from Luca. It's probably Acked-by Luca, but since my changes are pretty heavy (removing a whole section, adding barebox) I didn't include the ack. --- docs/manual/adding-packages-directory.txt | 1 + docs/manual/board-support.txt | 35 ------- docs/manual/customize-store.txt | 158 +++++++++++++++++++++++++++++ docs/manual/customize.txt | 2 + 4 files changed, 161 insertions(+), 35 deletions(-) delete mode 100644 docs/manual/board-support.txt create mode 100644 docs/manual/customize-store.txt diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt index 4a96415..ce9c5ce 100644 --- a/docs/manual/adding-packages-directory.txt +++ b/docs/manual/adding-packages-directory.txt @@ -147,6 +147,7 @@ package. 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, diff --git a/docs/manual/board-support.txt b/docs/manual/board-support.txt deleted file mode 100644 index d1d9d63..0000000 --- a/docs/manual/board-support.txt +++ /dev/null @@ -1,35 +0,0 @@ -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 +MYBOARD_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 -platform, 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. diff --git a/docs/manual/customize-store.txt b/docs/manual/customize-store.txt new file mode 100644 index 0000000..a62d3e2 --- /dev/null +++ b/docs/manual/customize-store.txt @@ -0,0 +1,158 @@ +Storing the configuration +------------------------- +[[customize-store]] + +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=+. + + +Other package configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The configuration files for busybox, the linux kernel, barebox, uClibc and +crosstool-NG should be stored as well. 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///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 and 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 +_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 +platform, 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/+ and a subdirectory ++board//+. 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//+ +1. Set the following options to +board///.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 /build/build-toolchain/.config board///ctng.config+ + * +make uclibc-update-config+ + * +cp /build/at91bootstrap3-*/.config board///at91bootstrap3.config+ + * +make barebox-update-defconfig+ +1. Create +board///fs-overlay/+ and fill it + with additional files you need on your rootfs, e.g. + +board///fs-overlay/etc/inittab+. +1. Create a post-build script + +board///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///post-build.sh+ +1. If additional setuid permissions have to be set or device nodes have + to be created, create +board///device_table.txt+ + and add that path to +BR2_ROOTFS_DEVICE_TABLE+. +1. +make savedefconfig+ to save the buildroot configuration. +1. +cp defconfig configs/_defconfig+ +1. To add patches to the linux build, set +BR2_LINUX_KERNEL_PATCH+ to + +board///patches/linux/+ and add your + patches in that directory. Each patch should be called + +linux--.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 index e8235de..6bd5811 100644 --- a/docs/manual/customize.txt +++ b/docs/manual/customize.txt @@ -10,3 +10,5 @@ include::customize-uclibc-config.txt[] include::customize-kernel-config.txt[] include::customize-toolchain.txt[] + +include::customize-store.txt[]