Update FAQ, remove references to 'toolchain' and instead emphasize

'buildroot', which can do everything 'toolchain' could do and then
some.  And is actively maintained.
 -Erik

1 files changed, 62 insertions, 44 deletions

diff --git a/docs/uclibc.org/FAQ.html b/docs/uclibc.org/FAQ.html
index a28f2569a..c8d136f52 100644
--- a/docs/uclibc.org/FAQ.html
+++ b/docs/uclibc.org/FAQ.html
@@ -228,27 +228,29 @@ How could it be smaller and not suck?</a></h2>
     of <a href="http://sources.redhat.com/binutils/">GNU binutils</a>,
     <a href="http://gcc.gnu.org/">the gcc compiler</a>, and uClibc, all
     built to produce binaries linked with uClibc for your target system.
-    You can build your own native uClibc toolchain using the uClibc
-    toolchain builder from
-    <a href="/cgi-bin/cvsweb/toolchain/">uClibc toolchain builder</a>,
-    or the uClibc buildroot system from
+    You can build your own native uClibc toolchain using the
     <a href="/cgi-bin/cvsweb/buildroot/">uClibc buildroot system</a>.
+
     <p>
     To build your own uClibc toolchain, follow the following simple
     steps:
     <ul>
-	<li> Point your web browser <a href="/cgi-bin/cvsweb/toolchain/">
-	    here is you want to build just a toolchain</a>,
-	    or <a href="/cgi-bin/cvsweb/buildroot/">here if you want to build a toolchain
-	    plus an initial uClibc based root filesystem</a>.
+	<li> Point your web browser <a href="/cgi-bin/cvsweb/buildroot/">here</a>,
 	<li> Click on "Download tarball"
 	<li> Unpack the tarball on your Linux system somewhere
 	<li> Edit the Makefile as needed if you wish to change anything.
-	<li> run 'unset CC'.   Some Linux systems (i.e. Gentoo) set 'CC'
-	    in the system environment which messes up cross compiles.
+	<li> run 'unset CC'.   Then run 'unset CXX'.  Some Linux systems
+	    (i.e. Gentoo) set variables such as 'CC' in the system environment
+	    which really messes things up when cross compiling.
+	<li> run 'make menuconfig'
+	<li> Select the things you want to build.  If you <em>only</em> want a
+	    toolchain, leave everything except the toolchain disabled.
+	<li> save your buildroot configuration.
 	<li> run 'make'
-	<li> go have lunch, drink a pop, call a friend, play a video game, etc till it finishes
-		downloading software and compiling things.
+	<li> go eat a nice loose meat sandwich, drink a pop, call a friend,
+	    play a video game, and generally find something to do.  While you
+	    are waiting, buildroot will download all the needed source code and
+	    then compile things up for you.
 	<li> You should now have a shiny new toolchain.
     </ul>
 
@@ -260,13 +262,17 @@ How could it be smaller and not suck?</a></h2>
     Yes, you really do need to build a toolchain to produce uClibc binaries.
     We used to provide a toolchain wrapper, but that has been removed due to
     numerous problems.  The uClibc developers have gone to a lot of trouble
-    to produce a
-    <a href="/cgi-bin/cvsweb/toolchain/">uClibc toolchain builder</a>,
-    and the
+    to produce the
     <a href="/cgi-bin/cvsweb/buildroot/">uClibc buildroot system</a>,
-    which make it easy to build your own uClibc toolchain.  Feel free to take
-    the gcc and binutils patches we provide and use them in your own toolchain
-    build system.
+    which makes it easy to build your own uClibc toolchain and/or an initial
+    uClibc based system.
+
+    <p>
+    Feel free to take the gcc and binutils patches we provide and use them in
+    your own toolchain build system.  If you choose to use your own toolchain
+    build system, you will need to use these patches since the upstream GNU
+    binutils and gcc releases do not currently have full support for building a
+    uClibc toolchain.
 
 
 <hr />
@@ -277,12 +283,18 @@ How could it be smaller and not suck?</a></h2>
     It is possible in some limited cases to re-use an existing glibc toolchain
     and subvert it into building uClibc binaries by using gcc commands such as
     "-nostdlib" and "-nostdinc".   In fact, this used to be the recommended
-    method for compiling programs with uClibc using a uClibc toolchain wrapper.
+    method for compiling programs with uClibc, and we made this easy to do by
+    providing a uClibc toolchain wrapper, which attempted to automagically subvert
+    an existing glibc toolchain.
+
+    <p>
+
     This toolchain wrapper was removed from uClibc 0.9.22, and it will not be
-    coming back.  This is because it is impossible to fully subvert an existing
-    toolchain in many cases.  As uClibc has become more capable the many problems
-    with re-using an existing glibc toolchain led us to conclude that the only
-    safe and sane way to build uClibc binaries is to use a uClibc toolchain.
+    coming back.  This is because it proved impossible to completely subvert an
+    existing toolchain in many cases, and therefore proved to be a real
+    maintainence burder.  As uClibc became more capable, the many problems with
+    re-using an existing glibc toolchain led us to conclude that the only safe
+    and sane way to build uClibc binaries was to use a uClibc toolchain.
 
     <p>
 
@@ -296,41 +308,47 @@ How could it be smaller and not suck?</a></h2>
 <h2><a name="dev_systems">Is a pre-compiled uClibc development system available?</a></h2>
 <p>
 
-    If you want to be <em>really</em> lazy and start using uClibc right
-    away without needing to compile your own toolchain or anything, you can
-    grab a copy of the uClibc development systems, currently available for
+    If you want to be <em>really</em> lazy and start using uClibc right away
+    without needing to compile your own toolchain or anything, you can grab a
+    pre-compiled uClibc development system.  These are currently available for
+
     <a href="http://www.kernel.org/pub/linux/libs/uclibc/root_fs_i386.bz2">i386</a>,
     <a href="http://www.kernel.org/pub/linux/libs/uclibc/root_fs_powerpc.bz2">powerpc</a>,
     <a href="http://www.kernel.org/pub/linux/libs/uclibc/root_fs_arm.bz2">arm</a>,
     <a href="http://www.kernel.org/pub/linux/libs/uclibc/root_fs_mips.bz2">mips</a>,
     <a href="http://www.kernel.org/pub/linux/libs/uclibc/root_fs_mipsel.bz2">mipsel</a>, and
     <a href="http://www.kernel.org/pub/linux/libs/uclibc/root_fs_sh4.bz2">sh4</a>.
-    The powerpc dev system mostly works, but there is still some sortof
-    problem with the shared library loader that has not yet been resolved.
 
     <p>
-    These are pre-built uClibc only development systems (created using
-    <a href="/cgi-bin/cvsweb/buildroot/">buildroot</a>), and provide a
-    really really easy way to get started.  These are about bzip2 compressed
-    ext2 filesystems containing all the development software you need to build
-    your own uClibc applications.  With bash, awk, make, gcc, g++, autoconf,
-    automake, ncurses, zlib, openssl, openssh, gdb, strace, busybox, GNU
-    coreutils, GNU tar, GNU grep, etc, these should have pretty much everything
-    you need to get started building your own applications linked against
-    uClibc.  You can boot into them, loop mount them, dd them to a spare drive
-    and use resize2fs to make them fill a partition...  Whatever works best for
+
+    Each of these uClibc development systems was created using
+    <a href="/cgi-bin/cvsweb/buildroot/">buildroot</a>).
+
+    <p>
+
+    These are bzip2 compressed ext2 filesystems containing all the development
+    software you need to build your own uClibc applications, including: bash, awk,
+    make, gcc, g++, autoconf, automake, ncurses, zlib, openssl, openssh, gdb,
+    strace, busybox, GNU coreutils, GNU tar, GNU grep, etc.
+
+    <p>
+
+    This should be pretty much everything you need to get started building your
+    own applications with uClibc.  Once you download one of these systems, you
+    can then boot into it, loop mount it, dd it to a spare drive and use a tool
+    such as resize2fs to make it fill a partition...  Whatever works best for
     you.
 
     <p>
     The quickest way to get started using a root_fs image (using the i386
     platform as an example) is:
     <ul>
-    <li>Download root_fs_i386.bz2 from kernel.org</li>
-    <li>bunzip2 root_fs_i386.bz2</li>
-    <li>mkdir root_fs</li>
-    <li>su root</li>
-    <li>mount -o loop root_fs_i386 root_fs</li>
-    <li>chroot root_fs /bin/sh</li>
+	<li>Download root_fs_i386.bz2 from kernel.org</li>
+	<li>bunzip2 root_fs_i386.bz2</li>
+	<li>mkdir root_fs</li>
+	<li>su root</li>
+	<li>mount -o loop root_fs_i386 root_fs</li>
+	<li>chroot root_fs /bin/su -</li>
     </ul>
     Type "exit" to end the chroot session and return to the host system.
     <p>