[Buildroot] [pull request] Pull request for branch for-2010.11/doc-updates

[Buildroot] [pull request] Pull request for branch for-2010.11/doc-updates

[Thomas Petazzoni]

The following changes since commit d8de970bae3744fe830e96a1ae0c4aff6ce47ba1:
  Peter Korsgaard (1):
        uClibc: sys/ptrace.h fix for 0.9.31 / powerpc so ltrace builds

are available in the git repository at:

  git://git.busybox.net/~tpetazzoni/git/buildroot for-2010.11/doc-updates

Thomas Petazzoni (8):
      documentation: clarify Buildroot steps
      documentation: Tell not to use make -jN
      documentation: Remove mention of gcc 3.x
      documentation: Update details about external toolchains
      documentation: Mention which external toolchains we tested
      documentation: Reword introduction about external toolchains
      documentation: Document the GIT/SVN download capabilities
      documentation: Mention the fact that the skeleton location can be configured

 docs/buildroot.html |  145 ++++++++++++++++++++++++++++++++-------------------
 1 files changed, 92 insertions(+), 53 deletions(-)

Thanks,
-- 
Thomas Petazzoni

[Buildroot] [PATCH 1/8] documentation: clarify Buildroot steps

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/buildroot.html |   11 +++++------
 1 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index 0a0114a..0b87bff 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -185,15 +185,14 @@
     <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>
-- 
1.7.0.4

[Buildroot] [PATCH 2/8] documentation: Tell not to use make -jN

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/buildroot.html |    6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index 0b87bff..571414b 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -182,6 +182,12 @@
  $ 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>
-- 
1.7.0.4

[Buildroot] [PATCH 3/8] documentation: Remove mention of gcc 3.x

[Thomas Petazzoni]

We don't support gcc 3.x anymore, so get rid of 3.x-specific details

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/buildroot.html |    9 +++------
 1 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index 571414b..333ea22 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -676,12 +676,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>
-- 
1.7.0.4

[Buildroot] [PATCH 4/8] documentation: Update details about external toolchains

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/buildroot.html |   18 +++++++++++-------
 1 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index 333ea22..aed3856 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -729,6 +729,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>
@@ -737,13 +748,6 @@ 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>
-- 
1.7.0.4

[Buildroot] [PATCH 5/8] documentation: Mention which external toolchains we tested

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/buildroot.html |   11 ++++++-----
 1 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index aed3856..9ea0374 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -748,11 +748,12 @@ endif
       correspond to your cross-compiling tools</li>
     </ul>
 
-    <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>
 
-- 
1.7.0.4

[Buildroot] [PATCH 6/8] documentation: Reword introduction about external toolchains

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/buildroot.html |   23 ++++++++++++++++-------
 1 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index 9ea0374..a7dd8d6 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -715,13 +715,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>It might be useful not to use an already existing toolchain,
+    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>
-- 
1.7.0.4

[Buildroot] [PATCH 7/8] documentation: Document the GIT/SVN download capabilities

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/buildroot.html |   46 +++++++++++++++++++++++++++++++++++++---------
 1 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index a7dd8d6..97f5db7 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -997,9 +997,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
@@ -1018,13 +1021,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
-- 
1.7.0.4

[Buildroot] [PATCH 8/8] documentation: Mention the fact that the skeleton location can be configured

[Thomas Petazzoni]

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
---
 docs/buildroot.html |   21 ++++++++-------------
 1 files changed, 8 insertions(+), 13 deletions(-)

diff --git a/docs/buildroot.html b/docs/buildroot.html
index 97f5db7..a184e2b 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -335,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
-- 
1.7.0.4

[Buildroot] [PATCH 6/8] documentation: Reword introduction about external toolchains

[Yann E. MORIN]

Thomas, All,

On Wednesday 24 November 2010 153840 Thomas Petazzoni wrote:
> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
> ---
>  docs/buildroot.html |   23 ++++++++++++++++-------
>  1 files changed, 16 insertions(+), 7 deletions(-)
> 
> diff --git a/docs/buildroot.html b/docs/buildroot.html
> index 9ea0374..a7dd8d6 100644
> --- a/docs/buildroot.html
> +++ b/docs/buildroot.html
> @@ -715,13 +715,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>It might be useful not to use an already existing toolchain,
Are you sure you meant this  ^^^ ?

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

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +0/33 662376056 | Software  Designer | \ / CAMPAIGN     |   ^                |
| --==< O_o >==-- '------------.-------:  X  AGAINST      |  /e\  There is no  |
| http://ymorin.is-a-geek.org/ | (*_*) | / \ HTML MAIL    |  """  conspiracy.  |
'------------------------------'-------'------------------'--------------------'

[Buildroot] [PATCH 6/8] documentation: Reword introduction about external toolchains

[Peter Korsgaard]

>>>>> "Thomas" == Thomas Petazzoni <thomas.petazzoni@free-electrons.com> writes:

 Thomas> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
 Thomas> ---
 Thomas>  docs/buildroot.html |   23 ++++++++++++++++-------
 Thomas>  1 files changed, 16 insertions(+), 7 deletions(-)

 Thomas> diff --git a/docs/buildroot.html b/docs/buildroot.html
 Thomas> index 9ea0374..a7dd8d6 100644
 Thomas> --- a/docs/buildroot.html
 Thomas> +++ b/docs/buildroot.html
 Thomas> @@ -715,13 +715,22 @@ endif
 
 Thomas>      <h2 id="external_toolchain">Using an external toolchain</h2>
 
 Thomas> -    <p>It might be useful not to use the toolchain generated by
 Thomas> -    Buildroot, for example if you already have a toolchain that is known
 Thomas> -    to work for your specific CPU, or if the toolchain generation feature
 Thomas> -    of Buildroot is not sufficiently flexible for you (for example if you
 Thomas> -    need to generate a system with <i>glibc</i> instead of
 Thomas> -    <i>uClibc</i>). Buildroot supports using an <i>external
 Thomas> -    toolchain</i>.</p>
 Thomas> +    <p>It might be useful not to use an already existing toolchain,
                         Funny ;) --^

-- 
Bye, Peter Korsgaard

[Buildroot] [PATCH 6/8] documentation: Reword introduction about external toolchains

[Thomas Petazzoni]

On Wed, 24 Nov 2010 15:48:57 +0100
"Yann E. MORIN" <yann.morin.1998@anciens.enib.fr> wrote:

> > +    <p>It might be useful not to use an already existing toolchain,
> Are you sure you meant this  ^^^ ?

No :-)

I've pushed a fixed version. Thanks for the review.

Thomas
-- 
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com

[Buildroot] [pull request] Pull request for branch for-2010.11/doc-updates

[Peter Korsgaard]

>>>>> "Thomas" == Thomas Petazzoni <thomas.petazzoni@free-electrons.com> writes:

 Thomas> The following changes since commit d8de970bae3744fe830e96a1ae0c4aff6ce47ba1:
 Thomas>   Peter Korsgaard (1):
 Thomas>         uClibc: sys/ptrace.h fix for 0.9.31 / powerpc so ltrace builds

 Thomas> are available in the git repository at:

 Thomas>   git://git.busybox.net/~tpetazzoni/git/buildroot for-2010.11/doc-updates

Pulled and pushed, thanks!

-- 
Bye, Peter Korsgaard