1 files changed, 92 insertions, 0 deletions
diff --git a/hurd/debugging/glibc.mdwn b/hurd/debugging/glibc.mdwn
new file mode 100644
index 00000000..905dd0da
--- /dev/null
+++ b/hurd/debugging/glibc.mdwn
@@ -0,0 +1,92 @@
+[[!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 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 [...]
+    Segmentation fault
+
+---
+
+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:
+
+[TODO].
+
+---
+
+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.
+
+[TODO].
+
+Then debug its startup as a normal program on your working hurd.
+
+    $ [...]/ext2fs.static --help
+    [...]
+
+Then try its full server startup.
+
+    $ settrans -ca node [...]/ext2fs.static BACKING_STORE
+    $ ls -l node/
+    [...]
+
+Make sure dynamic linking for servers is working.  If you haven't broken the
+ABI, you can just use an existing `/hurd/foobar` binary, started the way
+glibc's `testrun.sh` does it.
+
+[TODO]: Is this the correct way to do that?
+
+    $ settrans -ca node [glibc]/build/testrun.sh /hurd/ext2fs BACKING_STORE
+    $ cd node/
+    [...]
+
+---
+
+Test it in a [[subhurd]].
+
+---
+
+Test it on a real system.