Add some bad documentation for kernel debugging

Author: ChrisJefferson

doc/dev/lib.xml

@@ -12,6 +12,61 @@ kernel among the developers.
 
 <Chapter Label="Chap-Lib">
 <Heading>Maintaining the &GAP; kernel and library</Heading>
+
+<Section Label="Sect-debugging">
+<Heading>Debugging the GAP Kernel</Heading>
+
+The GAP kernel supports a variety of options which enabled when running <C>configure</C>,
+to help writing and debugging GAP kernel code.
+<P/>
+
+The first option, <C>--enable-debug</C>, is well supported can can be used
+whenever the GAP kernel, or kernel modules, are being developed (although
+developers should still check their code works without it).
+<P/>
+<C>--enable-debug</C> enables assertions throughout the kernel. These
+assertions are implemented using the <C>GAP_ASSERT</C> macro. These
+assertions are disabled when GAP is compiled without <C>--enable-debug</C>.
+When <C>--enable-debug</C> is enabled, <C>KernelDebug</C> will be shown in
+the Configuration line when GAP is started.
+<P/>
+
+The next two options are more experimental, and are not designed to be constantly
+enabled. They are particularly designed to track down bugs relating to memory
+corruption relating to GASMAN (GAP's memory manager). They cannot both be enabled
+at the same time.
+<P/>
+<C>--enable-memory-checking</C> makes GAP check for C pointers to the content of Bags
+being used after a new Bag has been created or a Bag is resized. GASMAN
+moves Bags during garbage collection, which can happen whenever a new Bag is created
+or a Bag is resized. However, as it is very unlikely that any single allocation
+will cause a garbage collection, these bugs trigger very rarely. Also the problems
+caused by these bugs are, if the C pointer is written to, a random other Bag,
+somewhere in GAP, is changed.
+<P/>
+
+After configuring, the memory checking must still be turned on. This can be done
+either by passing <C>--</C> to GAP's command line, or calling <C>GASMAN_MEM_CHECK(1)</C>.
+Note that enabling these tests makes GAP VERY, VERY slow. It can (depending on the
+machine and operating system) take GAP over a day to start, and load all standard
+packages. The recommending way to use this option is to start GAP, and then load
+small test files to try to isolate the problem. <C>MemCheck</C> will be shown in
+the Configuration line when GAP is started.
+<P/>
+
+Known bugs: GAP will crash if IO_fork is called while memory checking is enabled.
+<P/>
+
+<C>--enable-valgrind</C> makes changes to GASMAN so it is compatible with the
+valgrind memory checking program. Without this, valgrind will report many 
+incorrect warnings relating to GASMAN, and no useful warnings.
+<P/>
+
+At present, this <C>--enable-valgrind</C> only checks for invalid writes to the
+last bag which was created. Also, this option does not do anything unless GAP
+is run through Valgrind (for example by running <C>valgrind ./gap</C>.
+</Section>
+
 <Index>modules</Index>
 
 Modules, PROPOSALs, ...