Skip to contentSkip to conversation

Pull request for branch for-2010.11/doc-updates

GIT PULL New Thomas Petazzoni 3 participants 13 messages Nov 24, 2010

lore
Share & tools
lore
#0 lore raw

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,

Signature · 1 line
Thomas Petazzoni
#1 lore raw

PATCH 1/8 documentation: clarify Buildroot steps

---
 docs/buildroot.html |   11 +++++------
 1 files changed, 5 insertions(+), 6 deletions(-)
docs/buildroot.html +5 -6
index 0a0114a..0b87bff 100644
@@ -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>
Signature · 1 line
1.7.0.4
#2 lore raw

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

In reply to Thomas Petazzoni
---
 docs/buildroot.html |    6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)
docs/buildroot.html +6 -0
index 0b87bff..571414b 100644
@@ -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>
Signature · 1 line
1.7.0.4
#3 lore raw

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

In reply to Thomas Petazzoni

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

---
 docs/buildroot.html |    9 +++------
 1 files changed, 3 insertions(+), 6 deletions(-)
docs/buildroot.html +3 -6
index 571414b..333ea22 100644
@@ -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>
Signature · 1 line
1.7.0.4
#4 lore raw

PATCH 4/8 documentation: Update details about external toolchains

In reply to Thomas Petazzoni
---
 docs/buildroot.html |   18 +++++++++++-------
 1 files changed, 11 insertions(+), 7 deletions(-)
docs/buildroot.html +11 -7
index 333ea22..aed3856 100644
@@ -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>
Signature · 1 line
1.7.0.4
#5 lore raw

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

In reply to Thomas Petazzoni
---
 docs/buildroot.html |   11 ++++++-----
 1 files changed, 6 insertions(+), 5 deletions(-)
docs/buildroot.html +6 -5
index aed3856..9ea0374 100644
@@ -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>
 
Signature · 1 line
1.7.0.4
#6 lore raw

PATCH 6/8 documentation: Reword introduction about external toolchains

In reply to Thomas Petazzoni
---
 docs/buildroot.html |   23 ++++++++++++++++-------
 1 files changed, 16 insertions(+), 7 deletions(-)
docs/buildroot.html +16 -7
index 9ea0374..a7dd8d6 100644
@@ -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>
Signature · 1 line
1.7.0.4
#7 lore raw

PATCH 6/8 documentation: Reword introduction about external toolchains

Thomas, All,

Quoted 11 lines · On Wednesday 24 November 2010 153840 Thomas Petazzoni wrote:
---
 docs/buildroot.html |   23 ++++++++++++++++-------
 1 files changed, 16 insertions(+), 7 deletions(-)
docs/buildroot.html +0 -0
index 9ea0374..a7dd8d6 100644
@@ -715,13 +715,22 @@ endif
 

docs/buildroot.html endif · line 718

Quoted 10 lines
docs/buildroot.html +1 -7
     <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 ^^^ ?

Quoted 7 lines
docs/buildroot.html +7 -0
+    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

docs/buildroot.html endif · line 736

Quoted 10 lines
docs/buildroot.html +7 -0
+	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.

Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  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.  |
'------------------------------'-------'------------------'--------------------'
#8 lore raw

PATCH 6/8 documentation: Reword introduction about external toolchains

Quoted 2 lines · On Wed, 24 Nov 2010 15:48:57 +0100 "Yann E. MORIN"…
Quoted 1 line

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

Signature · 4 lines
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com
#9 lore raw

PATCH 6/8 documentation: Reword introduction about external toolchains

In reply to Thomas Petazzoni
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

"Thomas" == Thomas Petazzoni <[email protected]> writes:

Thomas> Signed-off-by: Thomas Petazzoni <[email protected]> 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 ;) --^
Signature · 1 line
Bye, Peter Korsgaard
#10 lore raw

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

In reply to Thomas Petazzoni
---
 docs/buildroot.html |   46 +++++++++++++++++++++++++++++++++++++---------
 1 files changed, 37 insertions(+), 9 deletions(-)
docs/buildroot.html +37 -9
index a7dd8d6..97f5db7 100644
@@ -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
Signature · 1 line
1.7.0.4
#11 lore raw

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

In reply to Thomas Petazzoni
---
 docs/buildroot.html |   21 ++++++++-------------
 1 files changed, 8 insertions(+), 13 deletions(-)
docs/buildroot.html +8 -13
index 97f5db7..a184e2b 100644
@@ -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
Signature · 1 line
1.7.0.4
#12 lore raw
In reply to Thomas Petazzoni
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

"Thomas" == Thomas Petazzoni <[email protected]> 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!

Signature · 1 line
Bye, Peter Korsgaard