Reorganize some toolchain pages.

17 files changed, 348 insertions, 255 deletions

diff --git a/binutils.mdwn b/binutils.mdwn
index 3ce28bb1..00926a44 100644
--- a/binutils.mdwn
+++ b/binutils.mdwn
@@ -1,4 +1,5 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008, 2010 Free Software Foundation,
+Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
@@ -8,4 +9,21 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
-The [GNU Binutils](http://www.gnu.org/software/binutils/).
+[[!meta title="GNU Binutils"]]
+
+
+# <http://www.gnu.org/software/binutils/>
+
+
+# Specifics
+
+Actually *non-*specifics: as these tools primarily deal with low-level parts of
+the target architecture and the object file format (ELF ABI), which are
+essentially (at least meant to be) the same, there shouldn't be many
+differences comparing the binutils between the GNU/Hurd and GNU/Linux ports,
+for example.
+
+
+# Open Issues
+
+[[!inline pages=tag/open_issue_binutils raw=yes feeds=no]]
diff --git a/gcc.mdwn b/gcc.mdwn
index 81a2a357..2192ab54 100644
--- a/gcc.mdwn
+++ b/gcc.mdwn
@@ -1,4 +1,4 @@
-[[!meta copyright="Copyright © 2007, 2008, 2009 Free Software Foundation,
+[[!meta copyright="Copyright © 2007, 2008, 2009, 2010 Free Software Foundation,
 Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
@@ -9,6 +9,22 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
-The [GNU Compiler Collection](http://gcc.gnu.org/).
+[[!meta title="GNU Compiler Collection"]]
+
+
+# http://gcc.gnu.org/
 
   * [[Open Issues|tag/open_issue_gcc]]
+
+
+# Specifics
+
+Actually mostly *non-*specifics: apart from the target-specific configuration
+machinery, there shouldn't be any major differences within GCC between the
+GNU/Hurd and GNU/Linux ports, for example.  Especially all the compiler magic
+is all the same.
+
+
+# Open Issues
+
+[[!inline pages=tag/open_issue_gcc raw=yes feeds=no]]
diff --git a/glibc.mdwn b/glibc.mdwn
index c7e5eeb7..cefbb19c 100644
--- a/glibc.mdwn
+++ b/glibc.mdwn
@@ -1,4 +1,5 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008, 2010 Free Software Foundation,
+Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
@@ -8,4 +9,26 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
-The [GNU C Library](http://www.gnu.org/software/libc/).
+[[!meta title="GNU C Library"]]
+
+
+# <http://www.gnu.org/software/libc/>
+
+
+## Sources
+
+For concenience, we maintain our own [[source
+repository|source_repositories/glibc]].
+
+
+# Specifics
+
+Porting glibc to a specific architecture is non-trivial.
+
+
+## [[Hurd-specific Port|hurd/glibc]]
+
+
+# Open Issues
+
+[[!inline pages=tag/open_issue_glibc raw=yes feeds=no]]
diff --git a/hurd.mdwn b/hurd.mdwn
index 24610f97..18748229 100644
--- a/hurd.mdwn
+++ b/hurd.mdwn
@@ -75,15 +75,13 @@ in the *unstable* branch of the Debian archive.
 
 * [[Contributing]]
 
-* [[Building]]
-  * [[building/Cross-Compiling]]
-
 * [[Open Issues|tag/open_issue_hurd]]
 
 # Developer References
 
 * [[Rules]]
 * [[Trackers]]
+* [[Building]]
 * [[Toolchain]]
     * [[glibc]]
 * RPC [[Interface]]s
diff --git a/hurd/binutils.mdwn b/hurd/binutils.mdwn
index 76b0ae60..f9266448 100644
--- a/hurd/binutils.mdwn
+++ b/hurd/binutils.mdwn
@@ -1,14 +1,11 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no Invariant
 Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
-is included in the section entitled
-[[GNU Free Documentation License|/fdl]]."]]"""]]
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
 
-[[General_information|/binutils]] about the binutils.
-
-There shouldn't be any differences within the binutils between, for example,
-the GNU/Hurd and GNU/Linux ports.
+[[!meta redir=/binutils]]
diff --git a/hurd/building.mdwn b/hurd/building.mdwn
index 01586c84..1674b770 100644
--- a/hurd/building.mdwn
+++ b/hurd/building.mdwn
@@ -13,6 +13,12 @@ do what you expect it to do is the highest if you try building from the Debian
 source packages.  This is especially true if you want to use your compilation
 within a Debian system.
 
+Note that for building code to run on GNU/Hurd systems, you need a toolchain
+for the GNU Hurd.  You can either compile on a GNU/Hurd system, or need a
+cross-compiler targeting GNU/Hurd.  Our [[toolchain page|toolchain]] has the
+details.
+
+
 ## Getting the Source Code
 
 You can chose between getting the [sources from the developers's
@@ -93,10 +99,6 @@ to `make`:
 This will automatically build all libraries that are required to build the
 requested server or library.
 
-### Cross Compiling
-
-Read about [[cross-compiling]].
-
 
 ## RPC IDs
 
diff --git a/hurd/building/cross-compiling.mdwn b/hurd/building/cross-compiling.mdwn
index d5beade9..1ecfd0bd 100644
--- a/hurd/building/cross-compiling.mdwn
+++ b/hurd/building/cross-compiling.mdwn
@@ -1,208 +1,11 @@
-[[!meta copyright="Copyright © 2007, 2008, 2010 Free Software Foundation,
-Inc."]]
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no Invariant
 Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
-is included in the section entitled
-[[GNU Free Documentation License|/fdl]]."]]"""]]
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
 
-# `cross-gnu`
-
-[[Thomas_Schwinge|tschwinge]] has written a shell script for building a
-complete cross-build environment for GNU/Hurd systems.
-
-Find it in the [[source repositories/incubator]], *cross-gnu* branch.
-
-
-## Using
-
-Read through it.  Understand it.  Only then use it by following the next steps.
-
-
-## Status
-
-/!\ Please note that these cross toolchains does not yet encompass all of the
-functionality that native toolchains provide.  For example, there is only
-support for C and C++ so far, but not for other languages.  A bunch of fixes /
-enhancements of [[glibc]] are missing.  We're working towards minimizing these
-differences, as well as towards pushing all patches upstream.
-
-
-### Supported Versions of Source Packages
-
-The following ones are known to work.  Others may work as well, but no
-guarantee is given.  Always the preferred version is listed first.
-
-  * `src/binutils`: [[GNU_Binutils|binutils]]
-
-      * CVS `binutils-2_20-branch`
-
-            $ mkdir binutils-2_20-branch
-            $ cd binutils-2_20-branch/
-            $ cvs -d:pserver:anoncvs@sources.redhat.com:/cvs/src ↩
-                co -r binutils-2_20-branch binutils
-
-        The sources are rooted in `binutils-2_20-branch/src/`.  Also use the above
-        commands for updating, instead of the usual `cvs update`.
-
-      * Release of the 2.20 series from <ftp://ftp.gnu.org/gnu/binutils/>
-        should also be fine.
-
-  * `src/gcc`: [[GNU_Compiler_Collection|gcc]]
-
-      * SVN `gcc-4_5-branch`
-
-            $ svn co svn://gcc.gnu.org/svn/gcc/branches/gcc-4_5-branch
-
-        Patches:
-
-          * <http://gcc.gnu.org/ml/gcc-patches/2010-04/msg00602.html>
-
-        Prepare:
-
-            $ ( cd gcc-4_5-branch/ && contrib/gcc_update --touch )
-
-      * SVN `gcc-4_4-branch`
-
-            $ svn co svn://gcc.gnu.org/svn/gcc/branches/gcc-4_4-branch
-
-        Patches:
-
-          * <http://gcc.gnu.org/ml/gcc-patches/2010-04/msg00602.html>
-
-        Prepare:
-
-            $ ( cd gcc-4_4-branch/ && contrib/gcc_update --touch )
-
-      * Releases of the 4.5 and 4.4 series from <ftp://ftp.gnu.org/gnu/gcc/>
-        should also be fine, but need the same set of patches as the
-        `gcc-4_5-branch` needs.
-
-  * `src/gnumach`: [[GNU_Mach|microkernel/mach/gnumach]]
-
-      * Git `master` branch
-
-            $ git clone ↩
-                git://git.sv.gnu.org/hurd/gnumach.git gnumach
-
-        Prepare:
-
-            $ ( cd gnumach/ && autoreconf -vi )
-
-  * `src/mig`: [[microkernel/mach/mig/GNU_MIG]]
-
-      * Git `master` branch
-
-            $ git clone ↩
-                git://git.sv.gnu.org/hurd/mig.git mig
-
-        Prepare:
-
-            $ ( cd mig/ && autoreconf -vi )
-
-  * `src/hurd`: [[GNU_Hurd|hurd]]
-
-      * Git `master` branch
-
-            $ git clone ↩
-                git://git.sv.gnu.org/hurd/hurd.git hurd
-
-  * `src/libpthread`: [[libpthread]]
-
-      * Git `tschwinge/Peter_Herbolzheimer` branch
-
-            $ git clone --no-checkout ↩
-                git://git.sv.gnu.org/hurd/libpthread.git libpthread
-            $ cd libpthread/
-            $ git checkout origin/tschwinge/Peter_Herbolzheimer
-
-  * `src/glibc`: [[GNU_C_Library|glibc]]
-
-      * Git `tschwinge/Roger_Whittaker` branch
-
-            $ git clone --no-checkout ↩
-                git://git.sv.gnu.org/hurd/glibc.git glibc
-            $ cd glibc/
-            $ git checkout origin/tschwinge/Roger_Whittaker
-
-<!--
-
-  * `src/gdb`: [[GNU_Debugger|gdb]]
-
-    This is optional and will only be compiled if present.
-
-      * CVS `gdb_6_6-branch`
-
-            $ cvs -d:pserver:anoncvs@sources.redhat.com:/cvs/src ↩
-              co -r gdb_6_6-branch gdb
-            $ mv src gdb_6_6-branch
-
-        Also needs some patch because of MIG changes, if I remember correctly.
-
-      * Recent tarballs from <ftp://ftp.gnu.org/gnu/gdb/> should also work.
-
--->
-
-
-### Preparation
-
-Unpack the tarballs if you downloaded any.
-
-Create a directory where the cross build shall be rooted in and a `src`
-subdirectory in there.  Then create symbolic links for every of the above
-packages: from `src/PACKAGE` to where you stored or unpacked it.  If you don't
-intend to build several cross compilers or use the source trees otherwise, you
-can also directly store the source trees in `src/`.  The source trees can be
-shared between multiple cross build trees since the packages' build systems are
-supposed not to modify the files in the source trees.  Not all packages adhere
-to that, but they fail to do so only for pre-processed documentation, etc.
-
-Either make sure that `cross-gnu-env` and `cross-gnu` are found in `$PATH`
-(`~/bin/`, for example) or alternatively remember to use their full paths in
-the following.
-
-The system you're running the script on (the *build* system) needs to have a
-basic compiling environment installed, i.e., a C compiler with the basic
-libraries and `make`.  You might also need `flex` and `bison`.  For building
-recent version of GCC (4.3 onwards)
-you'll need to have development packages of GMP and MPFR installed.
-
-
-### Setting Up the Environment
-
-Do this every time you intend to use the cross compiler:
-
-    $ ROOT=to/the/cross/build/root
-    $ . cross-gnu-env
-
-This will set several environment variables, which are later used by (a) the
-`cross-gnu` script and (b) by you, the user of the cross compiler.  `$TARGET`
-will be set by the script, `$PATH` will be adjusted, etc.  See the
-`cross-gnu-env` file for all environment variables that are set, as well as
-their default values.  `$ROOT` will be made an absolute path if it isn't
-already.
-
-Later, you'll be able to do things like `../configure --host="$TARGET"` and the
-cross compiler will be found automatically.
-
-
-### Creating the Cross Build Environment
-
-After setting up the environemt, just run `cross-gnu` and watch the messages
-flow by.  In the end you should see a message: *[...]/cross-gnu: Everything
-should be in place now.*
-
-
-### Staying Up-To-Date
-
-You can re-run `cross-gnu` to rebuild the parts of the sources that have
-changed since the last run.  This will save a lot of time compared to starting
-from scratch again.  Also, it is especially useful if you aren't working with
-unpacked tarballs, but on CVS's / SVN's / Git's branches or want to quickly get
-a new toolchain
-with patches you applied to the source trees.  However: do *not* use this
-technique when doing major changes to the source trees, like switching from GCC
-4.4 to GCC 4.5.
+[[!meta redir=/toolchain/cross-gnu]]
diff --git a/hurd/debugging/glibc.mdwn b/hurd/debugging/glibc.mdwn
index 905dd0da..e9817132 100644
--- a/hurd/debugging/glibc.mdwn
+++ b/hurd/debugging/glibc.mdwn
@@ -1,4 +1,5 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008, 2010 Free Software Foundation,
+Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
@@ -15,7 +16,7 @@ glibc have been done.
 
 First step is having the build of glibc succeed.  This is actually more
 difficult than one might expect as it involves (towards the end of the build
-process -- unless you are [[building/cross-compiling]], of course -- that the
+process -- unless you are cross-compiling, of course -- that the
 newly created libraries and loader actually work: they'll be used to run the
 `rpcgen` program.  If that step doesn't succeed, it'll look similar to this:
 
@@ -25,12 +26,10 @@ newly created libraries and loader actually work: they'll be used to run the
 
 ---
 
-Unless [[building/cross-compiling]], the next thing you'll probably want to do
+Unless cross-compiling, the next thing you'll probably want to do
 is running the test suite, or parts of it.
 
-Here is a list of known failures:
-
-[TODO].
+There is a list of [[known failures|open_issues/glibc_testsuite]].
 
 ---
 
diff --git a/hurd/gcc.mdwn b/hurd/gcc.mdwn
index 53b5e071..129aa8a9 100644
--- a/hurd/gcc.mdwn
+++ b/hurd/gcc.mdwn
@@ -1,15 +1,11 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no Invariant
 Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
-is included in the section entitled
-[[GNU Free Documentation License|/fdl]]."]]"""]]
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
 
-[[General_information|/gcc]] about the GCC.
-
-Apart from the target-specific configuration machinery, there shouldn't be any
-major differences within GCC between, for example, the GNU/Hurd and GNU/Linux
-ports.  Especially all the compiler magic is all the same.
+[[!meta redir=/gcc]]
diff --git a/hurd/toolchain.mdwn b/hurd/toolchain.mdwn
index 8b852089..91d49b2c 100644
--- a/hurd/toolchain.mdwn
+++ b/hurd/toolchain.mdwn
@@ -1,18 +1,11 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no Invariant
 Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
-is included in the section entitled
-[[GNU Free Documentation License|/fdl]]."]]"""]]
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
 
-* [[binutils]]
-* [[GCC]]
-* [[glibc]]
-
-Before beginning to work on the inner parts of the GNU/Hurd toolchain, it's
-always profitable to also know how things are done on other systems.  Compare,
-for example, how things are done differently for GNU/Hurd than they are done
-for GNU/Linux.
+[[!meta redir=/toolchain]]
diff --git a/libpthread.mdwn b/libpthread.mdwn
index f6210706..b31876b3 100644
--- a/libpthread.mdwn
+++ b/libpthread.mdwn
@@ -10,10 +10,21 @@ License|/fdl]]."]]"""]]
 
 [[!meta title="POSIX Threading Library"]]
 
-Used by / ported to the [[Hurd]] on [[GNU Mach|microkernel/mach/gnumach]], some
-[[microkernel/L4]] variants, and [[microkernel/Viengoos]].
+
+# Sources
+
+<http://git.savannah.gnu.org/cgit/hurd/libpthread.git/>
+
+
+# Specifics
+
+Porting libpthread to a specific architecture is non-trivial.
+
+Our libpthread is currently used by / ported to the [[Hurd]] on [[GNU
+Mach|microkernel/mach/gnumach]], some [[microkernel/L4]] variants, and
+[[microkernel/Viengoos]].
 
 
 # Open Issues
 
-  * [[tag/open_issue_libpthread]]
+[[!inline pages=tag/open_issue_libpthread raw=yes feeds=no]]
diff --git a/news/2010-04-30.mdwn b/news/2010-04-30.mdwn
index 131af4ea..254ceb99 100644
--- a/news/2010-04-30.mdwn
+++ b/news/2010-04-30.mdwn
@@ -51,7 +51,8 @@ else="[[!paste id=full_news]]"]]
 > package (and these are meant to eventually be submitted upstream).  After a
 > long break, he as well
 > [updated](http://lists.gnu.org/archive/html/bug-hurd/2010-04/msg00062.html)
-> his [[toolchain_cross-compilation_script|hurd/building/cross-compiling]] to
+> his toolchain cross-compilation script [[`cross-gnu`|toolchain/cross-gnu]]
+> to
 > the current source code packages, and added C++ support.
 
 > On to the Google Summer of Code 2010: we got three students working on the
diff --git a/open_issues/ifunc.mdwn b/open_issues/ifunc.mdwn
index f005a409..a3c30dc2 100644
--- a/open_issues/ifunc.mdwn
+++ b/open_issues/ifunc.mdwn
@@ -10,5 +10,8 @@ License|/fdl]]."]]"""]]
 
 [[!tag open_issue_binutils open_issue_gcc open_issue_glibc]]
 
-Needs porting / support in binutils and glibc, and probably also some [target
-configure magic for GCC support](http://nickclifton.livejournal.com/6612.html).
+Needs porting / support in [[/binutils]] and [[/glibc]], and probably also some
+target configure magic for [[/GCC]].
+
+<http://nickclifton.livejournal.com/6612.html> has a short summary about how to
+use it from GCC.
diff --git a/open_issues/nightly_builds.mdwn b/open_issues/nightly_builds.mdwn
index fb85cee1..506697bb 100644
--- a/open_issues/nightly_builds.mdwn
+++ b/open_issues/nightly_builds.mdwn
@@ -8,12 +8,12 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled [[GNU Free Documentation
 License|/fdl]]."]]"""]]
 
-We'd like to have nightly builds for the whole toolchain, and then do some
+We'd like to have nightly builds for the whole [[toolchain]], and then do some
 automatic [[unit_testing]] on them.
 
 Resources:
 
-  * the [[hurd/building/cross-compiling]] script
+  * [[toolchain/cross-gnu]]
 
   * As reported in the [[news/2010-05-31]] news, there's Hydra doing nightly
     builds / Nix packages.
diff --git a/tag.mdwn b/tag.mdwn
index 590d5d3a..e96e88d5 100644
--- a/tag.mdwn
+++ b/tag.mdwn
@@ -26,7 +26,7 @@ Most of them should be self-explanatory.
   * *open_issue_porting*
 
     A list of open issues in porting software to run on GNU/Hurd systems.  This
-    list also includes [[hurd/toolchain]]-level items, items that are either
+    list also includes [[toolchain]]-level items, items that are either
     already solved in [[Debian GNU/Hurd|hurd/running/debian]] systems (tagged
     *fixed_in_debian*) or being worked around, so if you're out for working on
     application-level porting issues, then perusing through the list of
diff --git a/toolchain.mdwn b/toolchain.mdwn
new file mode 100644
index 00000000..b08dba95
--- /dev/null
+++ b/toolchain.mdwn
@@ -0,0 +1,27 @@
+[[!meta copyright="Copyright © 2007, 2008, 2010 Free Software Foundation,
+Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+  * [[binutils]]
+
+  * [[GCC]]
+
+  * [[glibc]]
+
+  * [[libpthread]]
+
+
+Before beginning to work on the inner parts of the GNU/Hurd toolchain, it's
+always profitable to also know how things are done on other systems.  Compare,
+for example, how things are done differently for GNU/Hurd than they are done
+for GNU/Linux.
+
+
+  * [[cross-gnu]]
diff --git a/toolchain/cross-gnu.mdwn b/toolchain/cross-gnu.mdwn
new file mode 100644
index 00000000..62c55a04
--- /dev/null
+++ b/toolchain/cross-gnu.mdwn
@@ -0,0 +1,206 @@
+[[!meta copyright="Copyright © 2007, 2008, 2010 Free Software Foundation,
+Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+[[Thomas_Schwinge|tschwinge]] has written a shell script for building a
+complete cross-build environment for GNU/Hurd systems.
+
+Find it in the [[source_repositories/incubator]], *cross-gnu* branch.
+
+
+# Using
+
+Read through it.  Understand it.  Only then use it by following the next steps.
+
+
+# Status
+
+/!\ Please note that these cross toolchains does not yet encompass all of the
+functionality that native toolchains provide.  For example, there is only
+support for C and C++ so far, but not for other languages.  A bunch of fixes /
+enhancements of [[glibc]] are missing.  We're working towards minimizing these
+differences, as well as towards pushing all patches upstream.
+
+
+## Supported Versions of Source Packages
+
+The following ones are known to work.  Others may work as well, but no
+guarantee is given.  Always the preferred version is listed first.
+
+  * [[`src/binutils`|binutils]]
+
+      * CVS `binutils-2_20-branch`
+
+            $ mkdir binutils-2_20-branch
+            $ cd binutils-2_20-branch/
+            $ cvs -d:pserver:anoncvs@sources.redhat.com:/cvs/src ↩
+                co -r binutils-2_20-branch binutils
+
+        The sources are rooted in `binutils-2_20-branch/src/`.  Also use the above
+        commands for updating, instead of the usual `cvs update`.
+
+      * Release of the 2.20 series from <ftp://ftp.gnu.org/gnu/binutils/>
+        should also be fine.
+
+  * [[`src/gcc`|gcc]]
+
+      * SVN `gcc-4_5-branch`
+
+            $ svn co svn://gcc.gnu.org/svn/gcc/branches/gcc-4_5-branch
+
+        Patches:
+
+          * <http://gcc.gnu.org/ml/gcc-patches/2010-04/msg00602.html>
+
+        Prepare:
+
+            $ ( cd gcc-4_5-branch/ && contrib/gcc_update --touch )
+
+      * SVN `gcc-4_4-branch`
+
+            $ svn co svn://gcc.gnu.org/svn/gcc/branches/gcc-4_4-branch
+
+        Patches:
+
+          * <http://gcc.gnu.org/ml/gcc-patches/2010-04/msg00602.html>
+
+        Prepare:
+
+            $ ( cd gcc-4_4-branch/ && contrib/gcc_update --touch )
+
+      * Releases of the 4.5 and 4.4 series from <ftp://ftp.gnu.org/gnu/gcc/>
+        should also be fine, but need the same set of patches as the
+        `gcc-4_5-branch` needs.
+
+  * [[`src/gnumach`|microkernel/mach/gnumach]]
+
+      * Git `master` branch
+
+            $ git clone ↩
+                git://git.sv.gnu.org/hurd/gnumach.git gnumach
+
+        Prepare:
+
+            $ ( cd gnumach/ && autoreconf -vi )
+
+  * [[`src/mig`|microkernel/mach/mig/gnu_mig]]
+
+      * Git `master` branch
+
+            $ git clone ↩
+                git://git.sv.gnu.org/hurd/mig.git mig
+
+        Prepare:
+
+            $ ( cd mig/ && autoreconf -vi )
+
+  * [[`src/hurd`|hurd]]
+
+      * Git `master` branch
+
+            $ git clone ↩
+                git://git.sv.gnu.org/hurd/hurd.git hurd
+
+  * [[`src/libpthread`|libpthread]]
+
+      * Git `tschwinge/Peter_Herbolzheimer` branch
+
+            $ git clone --no-checkout ↩
+                git://git.sv.gnu.org/hurd/libpthread.git libpthread
+            $ cd libpthread/
+            $ git checkout origin/tschwinge/Peter_Herbolzheimer
+
+  * [[`src/glibc`|glibc]]
+
+      * Git `tschwinge/Roger_Whittaker` branch
+
+            $ git clone --no-checkout ↩
+                git://git.sv.gnu.org/hurd/glibc.git glibc
+            $ cd glibc/
+            $ git checkout origin/tschwinge/Roger_Whittaker
+
+<!--
+
+  * [[`src/gdb`|gdb]]
+
+    This is optional and will only be compiled if present.
+
+      * CVS `gdb_6_6-branch`
+
+            $ cvs -d:pserver:anoncvs@sources.redhat.com:/cvs/src ↩
+              co -r gdb_6_6-branch gdb
+            $ mv src gdb_6_6-branch
+
+        Also needs some patch because of MIG changes, if I remember correctly.
+
+      * Recent tarballs from <ftp://ftp.gnu.org/gnu/gdb/> should also work.
+
+-->
+
+
+## Preparation
+
+Unpack the tarballs if you downloaded any.
+
+Create a directory where the cross build shall be rooted in and a `src`
+subdirectory in there.  Then create symbolic links for every of the above
+packages: from `src/PACKAGE` to where you stored or unpacked it.  If you don't
+intend to build several cross compilers or use the source trees otherwise, you
+can also directly store the source trees in `src/`.  The source trees can be
+shared between multiple cross build trees since the packages' build systems are
+supposed not to modify the files in the source trees.  Not all packages adhere
+to that, but they fail to do so only for pre-processed documentation, etc.
+
+Either make sure that `cross-gnu-env` and `cross-gnu` are found in `$PATH`
+(`~/bin/`, for example) or alternatively remember to use their full paths in
+the following.
+
+The system you're running the script on (the *build* system) needs to have a
+basic compiling environment installed, i.e., a C compiler with the basic
+libraries and `make`.  You might also need `flex` and `bison`.  For building
+recent version of GCC (4.3 onwards)
+you'll need to have development packages of GMP and MPFR installed.
+
+
+## Setting Up the Environment
+
+Do this every time you intend to use the cross compiler:
+
+    $ ROOT=to/the/cross/build/root
+    $ . cross-gnu-env
+
+This will set several environment variables, which are later used by (a) the
+`cross-gnu` script and (b) by you, the user of the cross compiler.  `$TARGET`
+will be set by the script, `$PATH` will be adjusted, etc.  See the
+`cross-gnu-env` file for all environment variables that are set, as well as
+their default values.  `$ROOT` will be made an absolute path if it isn't
+already.
+
+Later, you'll be able to do things like `../configure --host="$TARGET"` and the
+cross compiler will be found automatically.
+
+
+## Creating the Cross Build Environment
+
+After setting up the environemt, just run `cross-gnu` and watch the messages
+flow by.  In the end you should see a message: *[...]/cross-gnu: Everything
+should be in place now.*
+
+
+## Staying Up-To-Date
+
+You can re-run `cross-gnu` to rebuild the parts of the sources that have
+changed since the last run.  This will save a lot of time compared to starting
+from scratch again.  Also, it is especially useful if you aren't working with
+unpacked tarballs, but on CVS's / SVN's / Git's branches or want to quickly get
+a new toolchain
+with patches you applied to the source trees.  However: do *not* use this
+technique when doing major changes to the source trees, like switching from GCC
+4.4 to GCC 4.5.