Merge branch 'for-2010.11/doc-updates' of git://git.busybox.net/~tpetazzoni/git/buildroot
This commit is contained in:
Peter Korsgaard
commit
8463801fa9
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user