diff options
| -rw-r--r-- | docs/buildroot.html | 145 |
1 files changed, 92 insertions, 53 deletions
diff --git a/docs/buildroot.html b/docs/buildroot.html index 0a0114a3b..144461298 100644 --- a/docs/buildroot.html +++ b/docs/buildroot.html @@ -182,18 +182,23 @@ $ make </pre> + <p>You <b>should never</b> use <code>make -jN</code> with + Buildroot: it does not support <i>top-level parallel + make</i>. Instead, use the <code>BR2_JLEVEL</code> option to tell + Buildroot to run each package compilation with <pre>make + -jN</pre>.</p> + <p>This command will generally perform the following steps:</p> <ul> <li>Download source files (as required)</li> - <li>Configure cross-compile toolchain</li> - <li>Build/install cross-compile toolchain</li> + <li>Configure, build and install the cross-compiling toolchain + if an internal toolchain is used, or import a toolchain if an + external toolchain is used</li> <li>Build/install selected target packages</li> - <li>Build a kernel image</li> + <li>Build a kernel image, if selected</li> + <li>Build a bootloader image, if selected</li> <li>Create a root filesystem in selected formats</li> </ul> - <p>Some of the above steps might not be performed if they are not - selected in the Buildroot configuration. - </p> <p>Buildroot output is stored in a single directory, <code>output/</code>. This directory contains several subdirectories:</p> @@ -330,19 +335,14 @@ completely rebuild your toolchain and tools, these changes will be lost.</li> - <li>Customize the target filesystem skeleton available under <code> - fs/skeleton/</code>. You can customize configuration files or other - stuff here. However, the full file hierarchy is not yet present - because it's created during the compilation process. Therefore, you - can't do everything on this target filesystem skeleton, but changes to - it do remain even if you completely rebuild the cross-compilation - toolchain and the tools. <br /> You can also customize the <code> - target/generic/device_table.txt</code> file, which is used by the - tools that generate the target filesystem image to properly set - permissions and create device nodes.<br /> These customizations are - deployed into <code>output/target/</code> just before the actual image - is made. Simply rebuilding the image by running make should propagate - any new changes to the image.</li> + <li>Create your own <i>target skeleton</i>. You can start with + the default skeleton available under <code>fs/skeleton</code> + and then customize it to suit your + needs. The <code>BR2_ROOTFS_SKELETON_CUSTOM</code> + and <code>BR2_ROOTFS_SKELETON_CUSTOM_PATH</code> will allow you + to specify the location of your custom skeleton. At build time, + the contents of the skeleton are copied to output/target before + any package installation.</li> <li>Add support for your own target in Buildroot, so that you have your own target skeleton (see <a href="#board_support">this @@ -671,12 +671,9 @@ endif then to use <code>ARCH-linux-gcc</code>, <code>ARCH-linux-objdump</code>, <code>ARCH-linux-ld</code>, etc.</p> - <p><b>Important</b>: do not try to move a gcc-3.x toolchain to another - directory — it won't work because there are some hardcoded paths - in the gcc-3.x configuration. If you are using a current gcc-4.x, it is - possible to relocate the toolchain — but then <code>--sysroot</code> - must be passed every time the compiler is called to tell where the - libraries and header files are.</p> + <p>It is possible to relocate the toolchain — but + then <code>--sysroot</code> must be passed every time the compiler + is called to tell where the libraries and header files are.</p> <p>It is also possible to generate the Buildroot toolchain in a directory other than <code>output/staging</code> by using the <code> @@ -713,13 +710,22 @@ endif <h2 id="external_toolchain">Using an external toolchain</h2> - <p>It might be useful not to use the toolchain generated by - Buildroot, for example if you already have a toolchain that is known - to work for your specific CPU, or if the toolchain generation feature - of Buildroot is not sufficiently flexible for you (for example if you - need to generate a system with <i>glibc</i> instead of - <i>uClibc</i>). Buildroot supports using an <i>external - toolchain</i>.</p> + <p>Using an already existing toolchain is useful for different + reasons:</p> + + <ul> + <li>you already have a toolchain that is known to work for your + specific CPU</li> + <li>you want to speed up the Buildroot build process by skipping + the long toolchain build part</li> + <li>the toolchain generation feature of Buildroot is not + sufficiently flexible for you (for example if you need to + generate a system with <i>glibc</i> instead of + <i>uClibc</i>)</li> + </ul> + + <p>Buildroot supports using existing toolchains through a + mechanism called <i>external toolchain</i>.</p> <p>To enable the use of an external toolchain, go to the <code>Toolchain</code> menu, and :</p> @@ -727,6 +733,17 @@ endif <ul> <li>Select the <code>External binary toolchain</code> toolchain type</li> + <li>Select the appropriate <code>External toolchain C + library</code></li> + <li>Select the appropriate values for <code>Enable large + file</code>, <code>Enable IPv6</code>, <code>Enable + RPC</code>, <code>Enable toolchain + locale/i18n</code>, <code>Enable WCHAR</code>, <code>Enable + program invocation</code>, <code>Build/install c++ compiler and + libstdc++</code>, according to the configuration of your + external toolchain. Buildroot will check those values at the + beginning of the compilation process and will tell you if you + used incorrect values.</li> <li>Adjust the <code>External toolchain path</code> appropriately. It should be set to a path where a bin/ directory contains your cross-compiling tools</li> @@ -735,18 +752,12 @@ endif correspond to your cross-compiling tools</li> </ul> - <p>If you are using an external toolchain based on <i>uClibc</i>, the - <code>Core C library from the external toolchain</code> and - <code>Libraries to copy from the external toolchain</code> options - should already have correct values. However, if your external - toolchain is based on <i>glibc</i>, you'll have to change these values - according to your cross-compiling toolchain.</p> - - <p>To generate external toolchains, we recommend using - <a href="http://ymorin.is-a-geek.org/dokuwiki/projects/crosstool">Crosstool-NG</a>. - It allows generating toolchains based on <i>uClibc</i>, <i>glibc</i> - and <i>eglibc</i> for a wide range of architectures and has good - community support.</p> + <p>Our external toolchain support has been tested with toolchains + from CodeSourcery, toolchains generated + by <a href="http://ymorin.is-a-geek.org/dokuwiki/projects/crosstool">Crosstool-NG</a>, + and toolchains generated by Buildroot itself. In general, all + toolchains that support the <i>sysroot</i> feature should + work. If not, do not hesitate to contact the developers.</p> <h2 id="add_packages">Adding new packages to Buildroot</h2> @@ -981,9 +992,12 @@ $(eval $(call GENTARGETS,package,libfoo,host)) <code>libfoo</code>) :</p> <ul> - <li><code>LIBFOO_VERSION</code>, mandatory, must contain the version - of the package. Note that if <code>HOST_LIBFOO_VERSION</code> doesn't - exist, it is assumed to be the same as <code>LIBFOO_VERSION</code>.<br/> + <li><code>LIBFOO_VERSION</code>, mandatory, must contain the + version of the package. Note that + if <code>HOST_LIBFOO_VERSION</code> doesn't exist, it is assumed + to be the same as <code>LIBFOO_VERSION</code>. It can also be a + Subversion or Git branch or tag, for packages that are fetched + directly from their revision control system.<br/> Example: <code>LIBFOO_VERSION = 0.1.2</code></li> <li><code>LIBFOO_SOURCE</code> may contain the name of the tarball of @@ -1002,13 +1016,38 @@ $(eval $(call GENTARGETS,package,libfoo,host)) in the package directory inside Buildroot will be applied to the package after extraction.</li> - <li><code>LIBFOO_SITE</code> may contain the Internet location of the - tarball of the package. If <code>HOST_LIBFOO_SITE</code> is not - specified, it defaults to <code>LIBFOO_SITE</code>. If none are - specified, then the location is assumed to be + <li><code>LIBFOO_SITE</code> may contain the Internet location + of the package. It can either be the HTTP or FTP location of a + tarball, or the URL of a Git or Subversion repository + (see <code>LIBFOO_SITE_METHOD</code> + below). If <code>HOST_LIBFOO_SITE</code> is not specified, it + defaults to <code>LIBFOO_SITE</code>. If none are specified, + then the location is assumed to be <code>http://$$(BR2_SOURCEFORGE_MIRROR).dl.sourceforge.net/sourceforge/packagename</code>. - <br/>Example: - <code>LIBFOO_SITE=http://www.libfoosoftware.org/libfoo</code>.</li> + <br/>Examples:<br/> + <code>LIBFOO_SITE=http://www.libfoosoftware.org/libfoo</code><br/> + <code>LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor/</code></li> + + <li><code>LIBFOO_SITE_METHOD</code> may contain the method to + fetch the package source code. It can either + be <code>WGET</code> (for normal FTP/HTTP downloads of + tarballs), <code>SVN</code> or <code>GIT</code>. When not + specified, it is guessed from the URL given + in <code>LIBFOO_SITE</code>: <code>git://</code> + and <code>svn://</code> URLs will use the <code>GIT</code> + and <code>SVN</code> methods respectively. All other URL-types + will use the <code>WGET</code> method. So for example, in the + case of a package whose source code is available through + Subversion repository on HTTP, one <i>must</i> + specifiy <code>LIBFOO_SITE_METHOD=SVN</code>. For <code>SVN</code> + and <code>GIT</code> methods, what Buildroot does is a + checkout/clone of the repository which is then tarballed and + stored into the download cache. Next builds will not + checkout/clone again, but will use the tarball + directly. When <code>HOST_LIBFOO_SITE_METHOD</code> is not + specified, it defaults to the value + of <code>LIBFOO_SITE_METHOD</code>. See <code>package/multimedia/tremor/</code> + for an example.</li> <li><code>LIBFOO_DEPENDENCIES</code> lists the dependencies (in terms of package name) that are required for the current target package to |