Documentation: add debugging doc

Layout the base for tips on debugging util-linux programs/wrappers.

[kerolasa@iki.fi:
	- rename file README.debug -> howto-debug.txt
	- wrap over 80 chars wide lines
	- change example commands to be relative to util-linux root
	- indent command examples
]

Signed-off-by: Davidlohr Bueso <dave@gnu.org>
Signed-off-by: Sami Kerola <kerolasa@iki.fi>

diff --git a/Documentation/howto-debug.txt b/Documentation/howto-debug.txt
new file mode 100644 (file)
index 0000000..bacc615
--- /dev/null
+++ b/Documentation/howto-debug.txt
@@ -0,0 +1,38 @@
+Debugging util-linux programs
+=============================
+
+How to deal libtool
+-------------------
+
+There are considerations to be made when profiling or debugging some programs
+found in the util-linux package. Because wrapper scripts are used for the
+binaries to make sure all library dependencies are met, you cannot use tools
+such as gdb or valgrind directly with them.
+
+Let's take for example the mount command:
+
+       $> cd /path/to/util-linux
+       $> file mount/mount
+       mount/mount: Bourne-Again shell script text executable
+
+The binary itself is located in the mount/.libs/ directory:
+
+       $> file mount/.libs/mount
+       mount/.libs/mount: ELF 64-bit LSB executable, x86-64, version 1 \
+       (SYSV), dynamically linked (uses shared libs) [...]
+
+When this command is run, there's a library dependency error:
+
+       $> mount/.libs/mount
+       mount/.libs/mount: /lib/libblkid.so.1: version `BLKID_2.20' not found \
+       (required by mount/.libs/mount)
+
+To overcome this we need set the LD_LIBRARY_PATH variable to read the path of
+the shared lib found in the sources, and not system-wide:
+
+       $> export LD_LIBRARY_PATH=$PWD/libblkid/src/.libs/:$LD_LIBRARY_PATH
+
+Now external debugging tools can be run on the binary.
+
+Happy hacking!
+Davidlohr Bueso, August 2011