Merge branch 'master' of flubber:~hurd-web/hurd-web

2 files changed, 50 insertions, 67 deletions

diff --git a/microkernel/mach/gnumach/building.mdwn b/microkernel/mach/gnumach/building.mdwn
index 8284639b..24a73608 100644
--- a/microkernel/mach/gnumach/building.mdwn
+++ b/microkernel/mach/gnumach/building.mdwn
@@ -8,11 +8,11 @@ enabled) is around 50 MiB.
 
 ## Getting the Source Code
 
-You can either use the git repository (see <http://savannah.gnu.org/git/?group=hurd>),
+You can either use the git repository (see <http://git.savannah.gnu.org/cgit/hurd/>),
 
     $ git clone git.savannah.gnu.org:/srv/git/hurd/gnumach.git
 
-... or Debian sources, if you're using Debian. (See
+... or get the Debian sources, if you're using Debian. (See
 [here](http://packages.debian.net/source/unstable/gnumach).)
 
     $ apt-get source gnumach
@@ -23,16 +23,15 @@ Please see the Debian [[running/debian/FAQ]] before using `apt-get source`.
 
 ### Preparing for the Build
 
-Building GNU Mach requires the *build-essential* and *fakeroot* packages, their
-dependencies and additional packages that are specified by the source gnumach
-package:
+Building GNU Mach requires the *build-essential* and *fakeroot* packages,
+and some additional dependencies specified by the gnumach source package:
 
     # apt-get install build-essential fakeroot
     # apt-get build-dep gnumach
 
 ### Building and Installing ... Debian `.deb` files
 
-Change into the directory with the downloaded / unpacked GNU Mach sources, e.g.
+Change into the directory with the downloaded / unpacked GNU Mach sources,
 
     $ cd gnumach-XXXXXXXX
 
@@ -42,7 +41,7 @@ Start the build process with
 
 [[GNU_Mach|gnumach]] is now building.  To use the new kernel, you must install the
 resulting `.deb` package which is located one directory above the build
-directory and has a similar name as the build directory, e.g.
+directory and has a similar name as the build directory:
 
     # dpkg -i ../gnumach_XXXXXXXX-X_hurd-i386.deb
 
@@ -52,64 +51,43 @@ You can now reboot your computer and enjoy the new kernel.
 
 ### Preparing for the Build
 
-Building GNU Mach requires a C compiler, a _static_ 32 bit standard C library and
+Building GNU Mach requires a C compiler, a _static_ 32 bit standard C library,
 your favourite flavor of awk (gawk) and GNU make.
 
-### Installing the Header Files First
-
-In order to build GNU Mach, you must build and install MIG, which requires that
-you install the GNU Mach header files:
-
 First, create the configuartion files:
 
     $ cd gnumach
     $ autoreconf --install
 
-GNU Mach and its headers should be built in a subdirectory:
+GNU Mach (and the associated headers) need be built in a separate build directory:
 
-    $ mkdir gnumach-build
-    $ cd gnumach-build
+    $ mkdir build
+    $ cd build
 
-Find the path to your GNU Mach sources (`..`) and configure it:
+Run configure:
 
     $ ../configure --prefix=
 
-Use the --host flag on 64 bit systems:
-
-    $ ../configure --prefix= --host=i686-unknown-linux-gnu
-
-Install the header files into e.g. `~/gnu/include/`:
-
-    $ make DESTDIR=~/gnu install-data
-
-### Building and Installing
-
-After you've already installed the header files (above), as well as the the
-Mach Interface Generator, you may finish building GNU Mach.  (See
-[[building_MIG|mig/gnu_mig/building]], then come back here.)
-
-GNU Mach should be built in a subdirectory create it if you have not already. 
-
-    $ mkdir gnumach-build
-    $ cd gnumach-build
+If building on a 64 bit host system,
+you need a number of additional settings to force a 32 bit build:
 
-If you previously ran ../configure for installing the header files, you may run
-into a bug when you configure and run make below. If that is the case, empty
-the _build_ directory, and reconfigure.
+    $ CPP='gcc -m32 -E -x c -undef -ansi' CC='gcc -m32' LD='ld -melf_i386' ../configure --prefix= --host=i686-unknown-linux-gnu
 
-    $ cd gnumach-build
-    $ rm -rf *
+### Installing the Header Files First
 
-Find the path to your GNU Mach sources (`..`) and configure it:
+In order to build GNU Mach, you will need a working MIG.
+Building MIG in turn requires the GNU Mach header files to be already present.
+So for bootstrapping MIG, you have to install the Mach headers first,
+for example into `~/gnu/include/`:
 
-    $ ../configure
+    $ make DESTDIR=~/gnu install-data
 
-If you are building on a 64 bit system, do the following instead:
+Now you can [[build_MIG|mig/gnu_mig/building]].
+Once you are done with that, come back here to finish the Mach build.
 
-    $ CPP='gcc -m32 -E -x c -undef -ansi' CC='gcc -m32' LD='ld -melf_i386'
-    $ ../configure --host=i686-unknown-linux-gnu
+### Building and Installing
 
-Build the kernel image:
+With MIG present, now build the kernel image:
 
     $ make gnumach.gz
 
@@ -117,8 +95,14 @@ Optionally run the (tiny) test suite:
 
     $ make check
 
-You can now install and use `gnumach.gz`.
+It's a good idea to make a backup of the previously installed kernel, in case
+you can't boot using the new one. That way, you can restore it after booting
+from a rescue media (or mounting the disk image used by your vm).
+
+    # cp /boot/gnumach.gz /boot/gnumach.gz.bak
 
-[TODO]
+GNU Mach can now be moved into place, typically `/boot/gnumach.gz`, so that you
+can boot your system with the new kernel.
 
+    # cp gnumach.gz /boot
 
diff --git a/microkernel/mach/mig/gnu_mig/building.mdwn b/microkernel/mach/mig/gnu_mig/building.mdwn
index 6d17e7ef..759c1a84 100644
--- a/microkernel/mach/mig/gnu_mig/building.mdwn
+++ b/microkernel/mach/mig/gnu_mig/building.mdwn
@@ -6,11 +6,11 @@ using a pre-built package, follow these instructions.
 ## <a name="Getting_the_Source_Code"> Getting the Source Code </a>
 
 You can chose between getting the [sources from the developers'
-RCS](http://savannah.gnu.org/git/?group=hurd):
+RCS](http://git.savannah.gnu.org/cgit/hurd/):
 
     $ git clone git://git.savannah.gnu.org:/srv/git/hurd/mig.git
 
-... or (if you are working on a Debian system) the ones that are used for the
+... or (if you are working on a Debian system) get the sources that are used for the
 [current Debian mig package](http://packages.debian.net/source/unstable/mig):
 
     $ apt-get source mig
@@ -23,32 +23,31 @@ The unpacked source tree is around 1 MiB, and the build tree also is around 1 Mi
 
 ### <a name="Preparing_for_the_Build"> Preparing for the Build </a>
 
-Building the Mach Interface Generator requires the _build-essential_ and
-_fakeroot_ packages, their dependencies and additional packages that are
-specified by the source mig package:
+Building MIG requires the *build-essential* and *fakeroot* packages,
+and some additional dependencies specified by the mig source package:
 
     # apt-get install build-essential fakeroot
     # apt-get build-dep mig
 
 ### <a name="Building_and_Installing"> Building and Installing </a> <a name="_a_deb_file"> ... a _.deb_ file </a>
 
-Change into the directory with the downloaded / unpacked MIG sources (_mig-1.3.1.99_):
+Change into the directory with the downloaded / unpacked MIG sources:
 
-    $ cd mig-1.3.1.99
+    $ cd mig-X.X.X.XX
 
 Start the build process:
 
     $ dpkg-buildpackage -us -uc -b -rfakeroot
 
-You can then install / distribute the _.deb_ file which will drop out one
-directory above the current one.
+This will create a _.deb_ package in the parent directory,
+which you can then install on your system.
 
 ## <a name="_on_non_Debian_systems"> On non-Debian Systems: </a>
 
 ### <a name="Preparing_for_the_Build"> Preparing for the Build </a>
 
 Building the Mach Interface Generator requires a C compiler, a standard 32 bit
-C library (with corresponding header files) and your favourite flavor of awk
+C library (with corresponding header files), your favourite flavor of awk
 (gawk), yacc (bison), lex (flex) and make.
 
 Additionally, you need to have GNU Mach's header files installed.  See
@@ -61,24 +60,24 @@ First, generate the configuration files:
     $ cd mig
     $ autoreconf --install
 
-The Mach Interface Generator should be built in a subdirectory:
+The Mach Interface Generator has to be built in a separate build directory:
 
-    $ mkdir mig-build
-    $ cd mig-build
+    $ mkdir build
+    $ cd build
 
-Find the root directory where you installed GNU Mach's header files and where
-you now intend to install the Mach Interface Generator (_~/gnu_) and the path
-to your Mach Interface Generator sources (../mig) and configure it:
+Find the base directory where you installed GNU Mach's header files and where
+you now intend to install the Mach Interface Generator (e.g. _~/gnu_), and run
+configure:
 
     $ GNU=~/gnu
-    $ TARGET_CPPFLAGS=-I"$GNU"/include ../configure 
+    $ TARGET_CPPFLAGS=-I"$GNU"/include ../configure --prefix="$GNU"
 
-The --host flag is necessary if you are building on a 64 bit machine:
+If you are building on a 64 bit machine, you need to add a --host option:
 
     $ GNU=~/gnu
     $ TARGET_CPPFLAGS=-I"$GNU"/include ../configure --prefix="$GNU" --host=i686-unknown-linux-gnu 
 
-Build and install the Mach Interface Generator into _$GNU_, i.e. _~/gnu/_ in our example:
+Build and install the Mach Interface Generator into _$GNU_ (i.e. _~/gnu/_ in our example):
 
     $ make all install