hurd/building: Some suggestions on testing binaries/shared libraries.

1 files changed, 170 insertions, 11 deletions

diff --git a/hurd/building.mdwn b/hurd/building.mdwn
index 199e77bf..c0d5648c 100644
--- a/hurd/building.mdwn
+++ b/hurd/building.mdwn
@@ -1,8 +1,5 @@
 /!\ The following information may very well be incomplete and out-dated.
 
-
-# Building the Hurd from Source
-
 If you want to build the Hurd libraries and servers (translators) yourself
 instead of just using pre-built binaries, follow these instructions.
 
@@ -16,8 +13,10 @@ 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.
 
+[[!toc]]
+
 
-## Getting the Source Code
+# Getting the Source Code
 
 You can chose between getting the [sources from the developers's
 git](http://savannah.gnu.org/git/?group=hurd):
@@ -34,9 +33,9 @@ Please see the Debian [[running/debian/FAQ]] before using `apt-get source`.
 The unpacked source tree is around 20 MiB, and the build tree (configured with
 `--disable-profile`) is around 100 MiB.
 
-## Preparing for the Build
+# Preparing for the Build
 
-### ... on Debian systems
+## ... on Debian systems
 
 Building the Hurd requires the *build-essential* and *fakeroot* packages, their
 dependencies and additional packages that are specified by the source hurd
@@ -45,13 +44,13 @@ package:
     # apt-get install build-essential fakeroot
     # apt-get build-dep hurd
 
-### ... on non-Debian systems
+## ... on non-Debian systems
 
 [TODO]
 
-## Building
+# Building
 
-### Debian `.deb` Files
+## Debian `.deb` Files
 
 Change into the directory with the downloaded / unpacked Hurd sources, e.g.
 
@@ -69,7 +68,7 @@ process with
 
 The `.deb` packages will then drop out at the `../` directory.
 
-### Building, but not the Debian Way
+## Building, but not the Debian Way
 
 The Hurd has to be built in a separate directory:
 
@@ -98,7 +97,7 @@ This will automatically build all libraries that are required to build the
 requested server or library.
 
 
-## RPC IDs
+# RPC IDs
 
 [TODO: update / integrate somewhere.]
 
@@ -114,3 +113,163 @@ mapping between the number of the RPC call and its name:
 Now you can use this file in the following way:
 
     $ rpctrace -i ~/hurd.msgids ls
+
+
+# Testing
+
+Any statically linked binaries (`make proc && (cd proc/ && make proc.static)`)
+can be used directly, as they are self-contained regarding the Hurd libraries
+they're using.
+
+Dynamically linked binaries will use the system's shared Hurd libraries, which
+may be or may not be what you want.
+
+Check:
+
+    $ ldd utils/ps
+            libhurdbugaddr.so.0.3 => /lib/libhurdbugaddr.so.0.3 (0x01036000)
+            libps.so.0.3 => /lib/libps.so.0.3 (0x01038000)
+            libihash.so.0.3 => /lib/libihash.so.0.3 (0x0104a000)
+            libshouldbeinlibc.so.0.3 => /lib/libshouldbeinlibc.so.0.3 (0x0104e000)
+            libc.so.0.3 => /lib/i386-gnu/libc.so.0.3 (0x0105a000)
+            libhurduser.so.0.3 => /lib/i386-gnu/libhurduser.so.0.3 (0x011eb000)
+            libmachuser.so.1 => /lib/i386-gnu/libmachuser.so.1 (0x01211000)
+            /lib/ld.so => /lib/ld.so.1 (0x00001000)
+
+Run:
+
+    $ utils/ps
+    [...]
+
+For example, if you have done changes to [[libps]] and now want to test them
+with `ps` (which dynamically links to libps), this is not good.  To overcome
+this, `LD_LIBRARY_PATH` can be used:
+
+Check:
+
+    $ LD_LIBRARY_PATH="$PWD"/libps ldd utils/ps
+            libhurdbugaddr.so.0.3 => /lib/libhurdbugaddr.so.0.3 (0x01036000)
+            libps.so.0.3 => /home/thomas/tmp/hurd/git.build/libps/libps.so.0.3 (0x01038000)
+            libihash.so.0.3 => /lib/libihash.so.0.3 (0x0104b000)
+            libshouldbeinlibc.so.0.3 => /lib/libshouldbeinlibc.so.0.3 (0x0104e000)
+            libc.so.0.3 => /lib/i386-gnu/libc.so.0.3 (0x0105a000)
+            libhurduser.so.0.3 => /lib/i386-gnu/libhurduser.so.0.3 (0x011eb000)
+            libmachuser.so.1 => /lib/i386-gnu/libmachuser.so.1 (0x01211000)
+            /lib/ld.so => /lib/ld.so.1 (0x00001000)
+
+Run:
+
+    $ LD_LIBRARY_PATH="$PWD"/libps utils/ps
+    [...]
+
+Additionally, a `hurd-build/lib` directory is populated with links to *all*
+shared Hurd libraries.
+
+Check:
+
+    $ LD_LIBRARY_PATH="$PWD"/lib ldd utils/ps
+            libhurdbugaddr.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libhurdbugaddr.so.0.3 (0x0102b000)
+            libps.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libps.so.0.3 (0x0102d000)
+            libihash.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libihash.so.0.3 (0x01040000)
+            libshouldbeinlibc.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libshouldbeinlibc.so.0.3 (0x01043000)
+            libc.so.0.3 => /lib/i386-gnu/libc.so.0.3 (0x0105a000)
+            libhurduser.so.0.3 => /lib/i386-gnu/libhurduser.so.0.3 (0x011eb000)
+            libmachuser.so.1 => /lib/i386-gnu/libmachuser.so.1 (0x01211000)
+            /lib/ld.so => /lib/ld.so.1 (0x00001000)
+
+Run:
+
+    $ LD_LIBRARY_PATH="$PWD"/lib utils/ps
+    [...]
+
+Likewise, if there is a reason to, it is possible to use the system's `/bin/ps`
+with a freshly built libps:
+
+    $ LD_LIBRARY_PATH="$PWD"/libps /bin/ps
+    [...]
+
+Etc.
+
+And, the same is possible with [[translator]]s, too.
+
+Check, system's shared Hurd libraries:
+
+    $ ldd tmpfs/tmpfs
+            libhurdbugaddr.so.0.3 => /lib/libhurdbugaddr.so.0.3 (0x01036000)
+            libdiskfs.so.0.3 => /lib/libdiskfs.so.0.3 (0x01038000)
+            libpager.so.0.3 => /lib/libpager.so.0.3 (0x01060000)
+            libiohelp.so.0.3 => /lib/libiohelp.so.0.3 (0x01069000)
+            libfshelp.so.0.3 => /lib/libfshelp.so.0.3 (0x0106c000)
+            libstore.so.0.3 => /lib/libstore.so.0.3 (0x01072000)
+            libthreads.so.0.3 => /lib/libthreads.so.0.3 (0x010ba000)
+            libports.so.0.3 => /lib/libports.so.0.3 (0x010c1000)
+            libihash.so.0.3 => /lib/libihash.so.0.3 (0x010ca000)
+            libshouldbeinlibc.so.0.3 => /lib/libshouldbeinlibc.so.0.3 (0x010ce000)
+            libc.so.0.3 => /lib/i386-gnu/libc.so.0.3 (0x010da000)
+            libmachuser.so.1 => /lib/i386-gnu/libmachuser.so.1 (0x0126b000)
+            libhurduser.so.0.3 => /lib/i386-gnu/libhurduser.so.0.3 (0x01282000)
+            libparted.so.0 => /lib/libparted.so.0 (0x012a8000)
+            libuuid.so.1 => /lib/libuuid.so.1 (0x01315000)
+            libdl.so.2 => /lib/i386-gnu/libdl.so.2 (0x01319000)
+            /lib/ld.so => /lib/ld.so.1 (0x00001000)
+
+Check, local libdiskfs, and otherwise system's shared Hurd libraries:
+
+    $ LD_LIBRARY_PATH="$PWD"/libdiskfs ldd tmpfs/tmpfs
+            libhurdbugaddr.so.0.3 => /lib/libhurdbugaddr.so.0.3 (0x01036000)
+            libdiskfs.so.0.3 => /home/thomas/tmp/hurd/git.build/libdiskfs/libdiskfs.so.0.3 (0x01038000)
+            libpager.so.0.3 => /lib/libpager.so.0.3 (0x01061000)
+            libiohelp.so.0.3 => /lib/libiohelp.so.0.3 (0x01069000)
+            libfshelp.so.0.3 => /lib/libfshelp.so.0.3 (0x0106c000)
+            libstore.so.0.3 => /lib/libstore.so.0.3 (0x01072000)
+            libthreads.so.0.3 => /lib/libthreads.so.0.3 (0x010ba000)
+            libports.so.0.3 => /lib/libports.so.0.3 (0x010c1000)
+            libihash.so.0.3 => /lib/libihash.so.0.3 (0x010cb000)
+            libshouldbeinlibc.so.0.3 => /lib/libshouldbeinlibc.so.0.3 (0x010ce000)
+            libc.so.0.3 => /lib/i386-gnu/libc.so.0.3 (0x010da000)
+            libmachuser.so.1 => /lib/i386-gnu/libmachuser.so.1 (0x0126b000)
+            libhurduser.so.0.3 => /lib/i386-gnu/libhurduser.so.0.3 (0x01282000)
+            libparted.so.0 => /lib/libparted.so.0 (0x012a9000)
+            libuuid.so.1 => /lib/libuuid.so.1 (0x01315000)
+            libdl.so.2 => /lib/i386-gnu/libdl.so.2 (0x01319000)
+            /lib/ld.so => /lib/ld.so.1 (0x00001000)
+
+Check, all local shared Hurd libraries:
+
+    $ LD_LIBRARY_PATH="$PWD"/lib ldd tmpfs/tmpfs
+            libhurdbugaddr.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libhurdbugaddr.so.0.3 (0x0102b000)
+            libdiskfs.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libdiskfs.so.0.3 (0x0102d000)
+            libpager.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libpager.so.0.3 (0x01056000)
+            libiohelp.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libiohelp.so.0.3 (0x0105e000)
+            libfshelp.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libfshelp.so.0.3 (0x01061000)
+            libstore.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libstore.so.0.3 (0x01066000)
+            libthreads.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libthreads.so.0.3 (0x010ae000)
+            libports.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libports.so.0.3 (0x010b6000)
+            libihash.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libihash.so.0.3 (0x010be000)
+            libshouldbeinlibc.so.0.3 => /home/thomas/tmp/hurd/git.build/lib/libshouldbeinlibc.so.0.3 (0x010c1000)
+            libc.so.0.3 => /lib/i386-gnu/libc.so.0.3 (0x010d8000)
+            libmachuser.so.1 => /lib/i386-gnu/libmachuser.so.1 (0x01269000)
+            libhurduser.so.0.3 => /lib/i386-gnu/libhurduser.so.0.3 (0x01281000)
+            libparted.so.0 => /lib/libparted.so.0 (0x012a7000)
+            libuuid.so.1 => /lib/libuuid.so.1 (0x01313000)
+            libdl.so.2 => /lib/i386-gnu/libdl.so.2 (0x01317000)
+            /lib/ld.so => /lib/ld.so.1 (0x00001000)
+
+Run, system's shared Hurd libraries:
+
+    $ settrans -ca tmp-0 /usr/bin/env "$PWD"/tmpfs 32M
+
+Run, local libdiskfs, and otherwise system's shared Hurd libraries:
+
+    $ settrans -ca tmp-0 /usr/bin/env LD_LIBRARAY_PATH="$PWD"/libdiskfs "$PWD"/tmpfs 32M
+
+Run, all local shared Hurd libraries:
+
+    $ settrans -ca tmp-0 /usr/bin/env LD_LIBRARAY_PATH="$PWD"/lib "$PWD"/tmpfs 32M
+
+Likewise, if there is a reason to, it is possible to use the system's
+`/hurd/tmpfs` with a freshly built libdiskfs:
+
+    $ settrans -ca tmp-0 /usr/bin/env LD_LIBRARAY_PATH="$PWD"/libdiskfs /hurd/tmpfs 32M
+
+Etc.