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

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