Merge branch 'for-2010.11/doc-updates' of git://git.busybox.net/~tpetazzoni/git/buildroot

 $ 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>

      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

    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 &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>

    <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>

    <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>

      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>

    <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

      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