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

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

[Thomas Petazzoni]

The following changes since commit 0fa46e59db087478b4844b2358a496eacdef7569:
  Peter Korsgaard (1):
        lzo: build shared library for host and target

are available in the git repository at:

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

Thomas Petazzoni (6):
      Explain why we don't support ELDK toolchains.
      Update documentation about external toolchain
      Remove more or less inexact option concerning custom target skeleton
      Use <code> instead of <pre> to improve formatting
      Do not mention toolchain/uClibc/uClibc.config-locale
      documentation: mention we can't use the distro toolchain as external

 docs/buildroot.html |  113 +++++++++++++++++++++++++++++++++++---------------
 1 files changed, 79 insertions(+), 34 deletions(-)

Thanks,
-- 
Thomas Petazzoni

[Buildroot] [PATCH 1/6] Explain why we don't support ELDK toolchains.

[Thomas Petazzoni]

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

diff --git a/docs/buildroot.html b/docs/buildroot.html
index 9d6e835..d58c19a 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -740,6 +740,31 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
     toolchains that support the <i>sysroot</i> feature should
     work. If not, do not hesitate to contact the developers.</p>
 
+    <p>We do not support toolchains from
+    the <a href="http://www.denx.de/wiki/DULG/ELDK">ELDK of Denx</a>,
+    for two reasons:</p>
+
+    <ul>
+
+      <li>The ELDK does not contain a pure toolchain (i.e just the
+      compiler, binutils, the C and C++ libraries), but a toolchain
+      that comes with a very large set of pre-compiled libraries and
+      programs. Therefore, Buildroot cannot import the <i>sysroot</i>
+      of the toolchain, as it would contain hundreds of megabytes of
+      pre-compiled libraries that are normally built by
+      Buildroot.</li>
+
+      <li>The ELDK toolchains have a completely non-standard custom
+      mechanism to handle multiple library variants. Instead of using
+      the standard GCC <i>multilib</i> mechanism, the ARM ELDK uses
+      different symbolic links to the compiler to differentiate
+      between library variants (for ARM soft-float and ARM VFP), and
+      the PowerPC ELDK compiler uses a <code>CROSS_COMPILE</code>
+      environment variable. This non-standard behaviour makes it
+      difficult to support ELDK in Buildroot.</li>
+
+    </ul>
+
     <h2 id="add_packages">Adding new packages to Buildroot</h2>
 
     <p>This section covers how new packages (userspace libraries or
-- 
1.7.0.4

[Buildroot] [PATCH 2/6] Update documentation about external toolchain

[Thomas Petazzoni]

Reword the documentation on external toolchain to take into account
the new features added since 2010.11 concerning external toolchain
profiles.

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

diff --git a/docs/buildroot.html b/docs/buildroot.html
index d58c19a..c4508f2 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -706,31 +706,48 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
     </ul>
 
     <p>Buildroot supports using existing toolchains through a
-    mechanism called <i>external toolchain</i>.</p>
+    mechanism called <i>external toolchain</i>. The external toolchain
+    mechanism is enabled in the <code>Toolchain</code> menu, by
+    selecting <code>External toolchain</code> in <code>Toolchain
+    type</code>.</p>
 
-    <p>To enable the use of an external toolchain, go to the
-    <code>Toolchain</code> menu, and :</p>
+    <p>Then, you have three solutions to use an external
+    toolchain:</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>
-      <li>Adjust the <code>External toolchain prefix</code> so that the
-      prefix, suffixed with <code>-gcc</code> or <code>-ld</code> will
-      correspond to your cross-compiling tools</li>
+
+      <li>Use a predefined external toolchain profile, and let
+      Buildroot download, extract and install the toolchain. Buildroot
+      already knows about a few CodeSourcery toolchains for ARM,
+      PowerPC, MIPS and SuperH. Just select the toolchain profile
+      in <code>Toolchain</code> through the available ones. This is
+      definitely the easiest solution.</li>
+
+      <li>Use a predefined external toolchain profile, but instead of
+      having Buildroot download and extract the toolchain, you can
+      tell Buildroot where your toolchain is already installed on your
+      system. Just select the toolchain profile
+      in <code>Toolchain</code> through the available ones,
+      unselect <code>Download toolchain automatically</code>, and fill
+      the <code>Toolchain path</code> text entry with the path to your
+      cross-compiling toolchain.</li>
+
+      <li>Use a completely custom external toolchain. This is
+      particularly useful for toolchains generated using
+      Crosstool-NG. To do this, select the <code>Custom
+      toolchain</code> solution in the <code>Toolchain</code>
+      list. You need to fill the <code>Toolchain
+      path</code>, <code>Toolchain prefix</code> and <code>External
+      toolchain C library</code> options. Then, you have to tell
+      Buildroot what your external toolchain supports. If your
+      external toolchain uses the <i>glibc</i> library, you only have
+      to tell whether your toolchain supports C++ or not. If your
+      external toolchain uses the <i>uclibc</i> library, then you have
+      to tell Buildroot if it supports largefile, IPv6, RPC,
+      wide-char, locale, program invocation, threads and C++. At the
+      beginning of the execution, Buildroot will tell you if the
+      selected options do not match the toolchain configuration.</li>
+
     </ul>
 
     <p>Our external toolchain support has been tested with toolchains
-- 
1.7.0.4

[Buildroot] [PATCH 3/6] Remove more or less inexact option concerning custom target skeleton

[Thomas Petazzoni]

We discourage the addition of custom target skeleton into the official
Buildroot tree, so let's not encourage users to do this in the
documentation.

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

diff --git a/docs/buildroot.html b/docs/buildroot.html
index c4508f2..1b8da2a 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -346,10 +346,6 @@
       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
-      section</a> for details).</li>
-
       <li>In the Buildroot configuration, you can specify the path to a
       post-build script, that gets called <i>after</i> Buildroot builds all
       the selected software, but <i>before</i> the rootfs packages are
-- 
1.7.0.4

[Buildroot] [PATCH 4/6] Use <code> instead of <pre> to improve formatting

[Thomas Petazzoni]

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

diff --git a/docs/buildroot.html b/docs/buildroot.html
index 1b8da2a..e815ee9 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -187,8 +187,8 @@
     <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>
+    Buildroot to run each package compilation with <code>make
+    -jN</code>.</p>
 
     <p>This command will generally perform the following steps:</p>
     <ul>
-- 
1.7.0.4

[Buildroot] [PATCH 5/6] Do not mention toolchain/uClibc/uClibc.config-locale

[Thomas Petazzoni]

The uClibc configuration file toolchain/uClibc/uClibc.config-locale
does not exist anymore.

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

diff --git a/docs/buildroot.html b/docs/buildroot.html
index e815ee9..04cbe67 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -409,9 +409,8 @@
       your configuration changes as appropriate.</li>
 
       <li>Copy the <code>.config</code> file to
-      <code>toolchain/uClibc/uClibc.config</code> or
-      <code>toolchain/uClibc/uClibc.config-locale</code>. The former
-      is used if you haven't selected locale support in Buildroot
+      <code>toolchain/uClibc/uClibc.config</code>. The former is used
+      if you haven't selected locale support in Buildroot
       configuration, and the latter is used if you have selected
       locale support.</li>
 
@@ -419,9 +418,8 @@
     </ol>
 
     <p>Otherwise, you can simply change
-    <code>toolchain/uClibc/uClibc.config</code> or
-    <code>toolchain/uClibc/uClibc.config-locale</code>, without running
-    the configuration assistant.</p>
+    <code>toolchain/uClibc/uClibc.config</code>, without running the
+    configuration assistant.</p>
 
     <p>If you want to use an existing config file for uclibc, then see
     section <a href="#environment_variables">environment variables</a>.</p>
-- 
1.7.0.4

[Buildroot] [PATCH 6/6] documentation: mention we can't use the distro toolchain as external

[Thomas Petazzoni]

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

diff --git a/docs/buildroot.html b/docs/buildroot.html
index 04cbe67..6abffb6 100644
--- a/docs/buildroot.html
+++ b/docs/buildroot.html
@@ -776,6 +776,15 @@ $(ZLIB_DIR)/libz.a: $(ZLIB_DIR)/.configured
 
     </ul>
 
+    <p>We also do not support using the distribution toolchain (i.e
+    the gcc/binutils/C library installed by your distribution) as the
+    toolchain to build software for the target. This is because your
+    distribution toolchain is not a "pure" toolchain (i.e only with
+    the C/C++ library), so we cannot import it properly into the
+    Buildroot build environment. So even if you are building a system
+    for a x86 or x86_64 target, you have to generate a
+    cross-compilation toolchain with Buildroot or Crosstool-NG.</p>
+
     <h2 id="add_packages">Adding new packages to Buildroot</h2>
 
     <p>This section covers how new packages (userspace libraries or
-- 
1.7.0.4

[Buildroot] [PATCH 5/6] Do not mention toolchain/uClibc/uClibc.config-locale

[Peter Korsgaard]

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

 Thomas> The uClibc configuration file toolchain/uClibc/uClibc.config-locale
 Thomas> does not exist anymore.

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

 Thomas> diff --git a/docs/buildroot.html b/docs/buildroot.html
 Thomas> index e815ee9..04cbe67 100644
 Thomas> --- a/docs/buildroot.html
 Thomas> +++ b/docs/buildroot.html
 Thomas> @@ -409,9 +409,8 @@
 Thomas>        your configuration changes as appropriate.</li>
 
 Thomas>        <li>Copy the <code>.config</code> file to
 Thomas> -      <code>toolchain/uClibc/uClibc.config</code> or
 Thomas> -      <code>toolchain/uClibc/uClibc.config-locale</code>. The former
 Thomas> -      is used if you haven't selected locale support in Buildroot
 Thomas> +      <code>toolchain/uClibc/uClibc.config</code>. The former is used
 Thomas> +      if you haven't selected locale support in Buildroot
 Thomas>        configuration, and the latter is used if you have selected
 Thomas>        locale support.</li>

Hmm, this sounds wrong. Now you only have one file, so talking about
former and latter doesn't make sense.

-- 
Bye, Peter Korsgaard

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

[Peter Korsgaard]

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

 Thomas> The following changes since commit 0fa46e59db087478b4844b2358a496eacdef7569:
 Thomas>   Peter Korsgaard (1):
 Thomas>         lzo: build shared library for host and target

 Thomas> are available in the git repository at:

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

Thanks, committed everything except for this one:

 Thomas>       Do not mention toolchain/uClibc/uClibc.config-locale

-- 
Bye, Peter Korsgaard