summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPeter Korsgaard <jacmet@sunsite.dk>2010-11-24 16:40:28 +0100
committerPeter Korsgaard <jacmet@sunsite.dk>2010-11-24 16:40:28 +0100
commit8463801fa9f5fb4adb96709dd921ae2634168e8e (patch)
tree8061b0faa73e5d3879cfbf247b607ca03013a991
parentab2f5567c1ca67c7f761486495d3d42f2b7c8eff (diff)
parent49b3ac65607d855889671b27cd6b9f6c1e4f6417 (diff)
downloadbuildroot-novena-8463801fa9f5fb4adb96709dd921ae2634168e8e.tar.gz
buildroot-novena-8463801fa9f5fb4adb96709dd921ae2634168e8e.zip
Merge branch 'for-2010.11/doc-updates' of git://git.busybox.net/~tpetazzoni/git/buildroot
-rw-r--r--docs/buildroot.html145
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 &mdash; 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 &mdash; 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 &mdash; 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