diff options
| author | Ulf Samuelsson <ulf.samuelsson@atmel.com> | 2007-08-16 21:54:48 +0000 |
|---|---|---|
| committer | Ulf Samuelsson <ulf.samuelsson@atmel.com> | 2007-08-16 21:54:48 +0000 |
| commit | f7b89d1dfcb2a71f4f052cff96efd902e1a48027 (patch) | |
| tree | 0b5d08d81bf6bc5a4b30cc8bb2b309fbb5383e66 | |
| parent | 5d2be049791872cd2a66a4ef80bd22e199d9c876 (diff) | |
Add further documentation for BSP patch
| -rw-r--r-- | docs/buildroot.html | 279 |
1 files changed, 274 insertions, 5 deletions
diff --git a/docs/buildroot.html b/docs/buildroot.html index 6f9a670e3..c496b8db4 100644 --- a/docs/buildroot.html +++ b/docs/buildroot.html @@ -345,14 +345,13 @@ $ make me<TAB> uClibc). </p> <p>There is basically one Makefile per software, and they are named with - the <code>.mk</code> extension. Makefiles are split into three + the <code>.mk</code> extension. Makefiles are split into four sections:</p> <ul> - <li><b>package</b> (in the <code>package/</code> directory) contains the - Makefiles and associated files for all user-space tools that Buildroot - can compile and add to the target root filesystem. There is one - sub-directory per tool. </li> + <li><b>project</b> (in the <code>project/</code> directory) contains + the Makefiles and associated files for all software related to the + building several root file systems in the same buildroot tree. </li> <li><b>toolchain</b> (in the <code>toolchain/</code> directory) contains the Makefiles and associated files for all software related to the @@ -360,6 +359,11 @@ $ make me<TAB> <code>gcc</code>, <code>gdb</code>, <code>kernel-headers</code> and <code>uClibc</code>. </li> + <li><b>package</b> (in the <code>package/</code> directory) contains the + Makefiles and associated files for all user-space tools that Buildroot + can compile and add to the target root filesystem. There is one + sub-directory per tool. </li> + <li><b>target</b> (in the <code>target</code> directory) contains the Makefiles and associated files for software related to the generation of the target root filesystem image. Four types of filesystems are supported @@ -442,6 +446,271 @@ $ make me<TAB> TARGETS global variable. </li> </ol> + <h2><a name="multi_project" id="multi_project"></a>Building several + projects in the same buildroot source tree</h2> + + <p><b>BACKGROUND</b></p> + + <p>Buildroot has always supported building several projects in the same + tree if each project was for a different architecture. </p> + + <p>The root file system has been created in the + <code>"build_<ARCH>/root"</code> + directory which is unique for each architecture. + Toolchains have been built in + <code>"toolchain_build_<ARCH>"</code>. </p> + + <p> It the user wanted to build several root file systems for the same + architecture, a prefix or suffix could be added in the configuration file + so the root file system would be built in + <code>"<PREFIX>_build_<ARCH>_<SUFFIX>/root"</code> + By supplying <u>unique</u> combinations of + <code>"<PREFIX>"</code> and + <code>"<SUFFIX>"</code> + each project would get a <u>unique</u> root file system tree. </p> + + <p>The disadvantage of this approach is that a new toolchain was + built for each project, adding considerable time to the build + process, even if it was two projects for the same chip. </p> + + <p>This drawback has been somewhat lessened with + <code>gcc-4.x.y</code> which allows buildroot to use an external + toolchain. Certain packages requires special + features in the toolchain, and if an external toolchain is selected, + this may lack the neccessary features to complete the build of the root + file system.</p> + + <p>A bigger problem was that the + <code>"build_<ARCH>"</code> tree + was also duplicated, so each </code>package</code> would also + be rebuilt once per project, resulting in even longer build times.</p> + + + <p><b>PROJECT TO SHARE TOOLCHAIN AND PACKAGE BUILDS</b></p> + + <p>Work has started on a project which will allow the user to build + multiple root file systems for the same architecture in the same tree. + The toolchain and the package build directory will be shared, but each + project will have a dedicated directory tree for project specific + builds. </p> + + <p>With this approach, most, if not all packages will be compiled + when the first project is built. + The process is almost identical to the original process. + Packages are downloaded and extracted to the shared + <code>"build_<ARCH>/<package>"</code> + directory. They are configured and compiled. </p> + + <p>Package libraries and headers are installed in the shared $(STAGING_DIR), + and then the project specific root file system "$(TARGET_DIR)" + is populated. </p> + + <p>At the end of the build, the root file system will be used + to generate the resulting root file system binaries. </p> + + <p>Once the first project has been built, building other projects will + typically involve populating the new project's root file system directory + from the existing binaries generated in the shared + <code>"build_<ARCH>/<>"</code> directory. </p> + + <p>Only packages, not used by the first project, will have to go + through the normal extract-configure-compile flow. </p> + + <p><b>IMPLEMENTATION</b></p> + + <p>The core of the solution is the introduction + of two new directories: </p> + + <ul> + <li><code>project_build_<ARCH></code></li> + + <li><code>binaries;</code></li> + </ul> + + <p>Each of the directories contain one subdirectory per project. + The name of the subdirectory is configured by the user in the + normal buildroot configuration, using the value of: </p> + + <p><code>Project Options ---> Project name</code></p> + + <p>The configuration defines the $(PROJECT) variable.</p> + + <p>The default project name is <code>"uclibc"</code>.</p> + + <p><code>"package/Makefile.in"</code> defines: + <pre> + <code>PROJECT_BUILD_DIR:=project_build_$(ARCH)/$(PROJECT)</code> + <code>BINARIES_DIR:=binaries/$(PROJECT)</code> + </pre> + </p> + + <p>It also defines the location for the target root file system: + <pre> + <code>TARGET_DIR:=$(PROJECT_BUILD_DIR)/$(PROJECT)/root</code> + </pre> + </p> + + <p>I.E: If the user has choosen + <code>"myproject"</code> + as the $(PROJECT) name: + + <ul> + <li><code>"project_build_<ARCH>/myproject"</code></li> + <li><code>"binaries/myproject"</code></li> + </ul> + + <p>will be created. </p> + + <p>Currently, the <u>root file system</u>, <u>busybox</u> and an Atmel + customized version of + <u><code>U-Boot</code></u>, as well as some Atmel specific + bootloaders like <u>at91-bootstrap</u> and <u>dataflashboot.bin</u> + are built in + <code>"$(PROJECT_BUILD_DIR)"</code> + + <p>The resulting binaries for all architectures are stored in the + <code>"$(BINARIES_DIR)"</code> directory. <p> + + <p><b>SUMMARY</b></p> + + <p>The project will share directories which can be share without + conflicts, but will use unique build directories, where the user + can configure the build. </p> + + <p><b>THINGS TO DO</b></p> + + <ol> + + <li>Linux</li> + + <p>The current Linux implementation is flawed. It only works + if the user chooses to use one of the few kernels selected + as base for the kernel-headers. While the Makefile seems to have + hooks, allowing the developer to specify whatever version he/she + wants in the target/device/*/* Makefiles, the build will fail + if another kernel version is choosen.</p> + + <p>The reason for this is that the kernel patches are not + applied by the <code>"target/linux/linux.mk"</code> + build script fragment. They are only applied by the + <code>"toolchain/kernel-headers/*.makefile"</code> + build script fragments</p> + + <p>If the kernel-header version and the linux version differs, + there will be two <code>"linux-2.6.X.Y"</code> + directories in + <code>"build_<ARCH>/<>"</code>, + each with its own set of patches. </p> + + <p>The solution in the works, is to move the build of Linux to + <code>"project_build_<ARCH>/<project name>/linux-2.6.X.Y"</code> combined with method to configure + which patches can be applied. Possibly, the linux source tree + used to generate the kernel headers will be moved to the + <code>"toolchain_build_<ARCH>"</code> + directory + </p> + + <p>The user will be able to select from three different + Linux strategies: + + <ul> + <li>Conservative Strategy: Only use version ssupported by the kernel headers</li> + <li>Stable Linux Strategy: Allow any 2.6.X.Y combination. + (Minimum 2.6.19)</li> + <li>Power-User Strategy: Allow + <code>"-git"</code>, or + <code>"-mm"</code>, or user downloadable kernels</li> + </ul> + + <p>The current kernel patches can be configured to be applied to the + linux source tree even if the version differs from the + kernel header version. </p> + + <p>Since the user can select any kernel-patch + he/she will be able to select a non-working combination. + If the patch fails, the user will have to generate a new + proprietary kernel-patch or decide to not apply the kernel + patches</p> + + <p>Other optional patches will be <u>board specific</u> or + <u>architecture specific</u> patches. </p> + + <p>There will also be a way for the user to supply absolute + or relative paths to patches, possibly outside the main tree. + This can be used to apply custom kernel-header-patches, if + the versions available in buildroot cannot be applied to the + specific linux version used</p> + + <p>Maybe, there will also be a possibility to supply an + <code>"URL"</code> to a patch available on Internet. </p> + + <li>Configurable packages</li> + + <p>Many packages can, on top of the simple + "enable/disable build", + be further configured using Kconfig. + Currently these packages will be compiled using the + configuration specified in the + <code>".config"</code> file of the <u>first</u> + project demanding the build of the package.</p> + + <p>If <u>another</u> project uses the same packages, but with + a different configuration,these packages will <u>not</u> be rebuilt, + and the root file system for the new project will be populated + with files from the build of the <u>first</u> project</p> + + <p>If multiple project are built, and a specific package + needs two different configuration, then the user must + delete the package from the + <code>"build_<ARCH>"</code> directory + before rebuilding the new project.<p> + + <p>A long term solution is to edit the package makefile and move + the build of the configurable packages from + <code>"build_<ARCH>"</code> to + <code>"project_build_<ARCH>/<project name>"</code> + and send a patch to the buildroot mailing list. + + <li>Naming conventions</li> + + <p>Names of resulting binaries should reflect the + "project name" + + <li>Generating File System binaries</li> + <p> + Packages which needs to be installed with the "root" + as owner, will generate a + <code>".fakeroot.<package>"</code> file + which will be used for the final build of the root file system binary. </p> + + <p>This was previously located in the + <code>"$(STAGING_DIR)"</code> directory, but was + recently moved to the + <code>"$(PROJECT_BUILD_DIR)"</code> directory. </p> + + <p>Currently only three packages: + <code>"at"</code>, + <code>"ltp-testsuite"</code> and + <code>"nfs-utils"</code> + requests fakeroot. <p> + + <p>The makefile fragments for each file system type like + <code>"ext2"</code>, + <code>"jffs2"</code> or + <code>"squashfs"</code> + will, when the file system binary is generated, + collect all present + <code>".fakeroot.<package>"</code> files + to a single <code>"_fakeroot.<file system>"</code> + file and call fakeroot.</p> + <code>".fakeroot.<package>"</code> + files are deleted as the last action of the Buildroot Makefile. </p> + + <p>It needs to be evaluated if any further action for the + file system binary build is needed. </p> + + </ol> + <h2><a name="using_toolchain" id="using_toolchain"></a>Using the uClibc toolchain</h2> |