4 files changed, 90 insertions, 28 deletions
diff --git a/hurd/debugging/glibc.mdwn b/hurd/debugging/glibc.mdwn
index a0890fe8..912f656c 100644
--- a/hurd/debugging/glibc.mdwn
+++ b/hurd/debugging/glibc.mdwn
@@ -1,13 +1,23 @@
+[[meta copyright="Copyright © 2007, 2008 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]]."]]"""]]
+
 Here are some hints about how to approach testing after nontrivial changes to
 glibc have been done.
 
 ---
 
-First step is having the build a glibc complete.  This is actually more
-difficult than one might expect, as it involves (towards the end of the build
-process; unless you are cross-building, of course), that the newly created
-libraries and loader actually work: they're used to run the `rpcgen`
-program.  If that step doesn't succeed, it'll look similar to this:
+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
+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:
 
     [...]
     CPP='gcc -E -x c-header' [...]/build/elf/ld.so.1 --library-path [...] [...]/build/sunrpc/rpcgen [...]
@@ -15,8 +25,8 @@ program.  If that step doesn't succeed, it'll look similar to this:
 
 ---
 
-If building glibc succeeds, the next thing to try is running the test suite, or
-parts of it.
+Unless [[building/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:
 
@@ -24,10 +34,28 @@ Here is a list of known failures:
 
 ---
 
-Make sure static linking is working OK at all.  The `elf/sln` program (a
-stripped-down `ln` that is statically linked) in the glibc build ought to test
-that.  Also, static linking under various conditions will already have been
-tested when running the test suite, especially in `elf/` and `dlfcn/`.
+If you've been doing simple changes to glibc functions that end up in
+`libc.so`, you may test them like this (like for a `strerror_l` implementation
+in this case):
+
+    $ LD_PRELOAD=./libc.so ./ld.so ./a.out 10 1073741928 de_DE.utf8
+    1073741928 (0x40000068): Computer bought the farm
+    1073741928 (0x40000068): Der Computer hat den Bauernhof erworben
+
+You usually will only have luck using the new `libc.so` (from
+`[glibc-build]/libc.so`) in combination together with the new `ld.so` (from
+`[glibc-build]/elf/ld.so`):
+
+    $ LD_PRELOAD=./libc.so ./a.out 10 1073741928 de_DE.utf8
+    Killed
+    $ LD_PRELOAD=./libc.so /lib/ld.so ./a.out 10 1073741928 de_DE.utf8
+    Killed
+
+Make sure static linking is working OK at all.  Running the
+`[glibc-build]/elf/sln` program (a stripped-down `ln` that is statically
+linked) ought to test that.  Also, static linking under various conditions will
+already have been tested when running the test suite, especially in `elf/` and
+`dlfcn/`.
 
 Make sure static linking with cthreads is working.  If you can get an
 `ext2fs.static` compiled and linked against the new glibc, that is good.
@@ -41,8 +69,8 @@ Then debug its startup as a normal program on your working hurd.
 
 Then try its full server startup.
 
-    $ settrans -ca node [...]/ext2fs.static <BACKEND>
-    $ cd node/
+    $ settrans -ca node [...]/ext2fs.static BACKING_STORE
+    $ ls -l node/
     [...]
 
 Make sure dynamic linking for servers is working.  If you haven't broken the
@@ -51,7 +79,7 @@ glibc's `testrun.sh` does it.
 
 [TODO]: Is this the correct way to do that?
 
-    $ settrans -ca node [glibc]/build/testrun.sh /hurd/ext2fs <BACKEND>
+    $ settrans -ca node [glibc]/build/testrun.sh /hurd/ext2fs BACKING_STORE
     $ cd node/
     [...]
 
@@ -62,10 +90,3 @@ Test it in a [[subhurd]].
 ---
 
 Test it on a real system.
-
----
-
-Sources:
-
-* <http://lists.gnu.org/archive/html/bug-hurd/2007-02/msg00038.html>
-* [[Thomas_Schwinge|tschwinge]]'s mind
diff --git a/hurd/debugging/translator.mdwn b/hurd/debugging/translator.mdwn
new file mode 100644
index 00000000..8e8dd6fb
--- /dev/null
+++ b/hurd/debugging/translator.mdwn
@@ -0,0 +1,15 @@
+[[meta copyright="Copyright © 2008 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]]."]]"""]]
+
+[[inline
+pages="hurd/debugging/translator/* and !*/discussion"
+show=0
+feeds=no
+actions=yes]]
diff --git a/hurd/debugging/translator/capturing_stdout_and_stderr.mdwn b/hurd/debugging/translator/capturing_stdout_and_stderr.mdwn
new file mode 100644
index 00000000..8430287a
--- /dev/null
+++ b/hurd/debugging/translator/capturing_stdout_and_stderr.mdwn
@@ -0,0 +1,26 @@
+[[meta copyright="Copyright © 2008 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]]."]]"""]]
+
+Sometimes it may already be helpful to capture a translator's `stdout` and
+`stderr`, for example like this:
+
+    $ sudo settrans -fgap ↩
+      /servers/socket/2 ↩
+      /bin/sh -c '/hurd/pfinet -i eth0 -a [...] > /tmp/stdout 2> /tmp/stderr'
+    $ [...]
+    $ cat /tmp/stdout
+    NET4: Linux TCP/IP 1.0 for NET4.0
+    IP Protocols: ICMP, UDP, TCP
+    TCP: Hash tables configured (ehash 65536 bhash 65536)
+    $ cat /tmp/stderr
+    pfinet: ../../hurd.work/pfinet/ethernet.c:196: ethernet_xmit: Unexpected error: (os/device) invalid IO size.
+
+(Trying to run [[GDB]] in this case was of no help -- due to a bug in GDB
+(supposedly) it wouldn't catch the fault.)
diff --git a/hurd/debugging/hurd.mdwn b/hurd/debugging/translator/gdb.mdwn
index 043da3e0..bee41010 100644
--- a/hurd/debugging/hurd.mdwn
+++ b/hurd/debugging/translator/gdb.mdwn
@@ -8,25 +8,25 @@ 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]]."]]"""]]
 
-Say you want to try running file system server (*[[translator/ext2fs]]*<!--`[[translator/ext2fs]]`-->,
-*[[translator/jfs]]*<!--`[[translator/jfs]]`-->, ...)  against a modified version of *[[libpager]]*<!--`[[libpager]]`--> and
-debug the latter one using [[GDB]].
+Say you want to try running file system server ([[`ext2fs`|translator/ext2fs]],
+[[`jfs`|translator/jfs]], ...) against a modified version of
+[[`libpager`|libpager]] and debug the latter one using [[debugging/GDB]].
 
-Set the [[translator]] like this:
+Set the [[hurd/translator]] like this:
 
     $ settrans -fgap ↩
       jfs.img.i ↩
       /usr/bin/env ↩
         LD_LIBRARY_PATH=~tschwinge/tmp/hurd/hurd.ogi/build/libpager ↩
-      "`pwd`"/jfs.obj/jfs ↩
-      "`pwd`"/jfs.img
+      "$PWD"/jfs.obj/jfs ↩
+        "$PWD"/jfs.img
 
 Then, when starting GDB, start it like this (or use an equivalent method, of
 course):
 
     $ LD_LIBRARY_PATH=~tschwinge/tmp/hurd/hurd.ogi/build/libpager ↩
       gdb ↩
-      ~tschwinge/tmp/jfs/jfs.obj/jfs 15436
+        ~tschwinge/tmp/jfs/jfs.obj/jfs 15436
     GNU gdb 6.5-debian
     [...]
     Reading symbols from /lib/libdiskfs.so.0.3...Reading symbols from /lib/debug/lib/libdiskfs.so.0.3...done.