[project @ 1999-11-29 12:02:42 by keithw]

This commit adds the new RTS option `-xc', which prints the current
cost-centre stack to stderr whenever an exception is raised.  This is
intended to be a debugging tool, to help trace those "Prelude.head:
empty list" errors that are so frustrating to find.

`-xc' is only available for programs compiled with -prof, and you
probably want -auto as well to get useful information.

This is currently experimental; it would be better if it only
displayed the info for *uncaught* exceptions, but this is harder to
implement.

This commit also makes an OFTEL-inspired extension to the RTS option
space.  Since we've almost run out of options, `-x' is now reserved
for `extended' options.  `-xc' is the first of these, but that leaves
'-x[0-9A-Zabd-wyz]' still to be used!  The prefix `-xx' is reserved
for future extension.

1 files changed, 9 insertions, 0 deletions

diff --git a/ghc/docs/users_guide/runtime_control.vsgml b/ghc/docs/users_guide/runtime_control.vsgml
index 464483aa24..04caf42424 100644
--- a/ghc/docs/users_guide/runtime_control.vsgml
+++ b/ghc/docs/users_guide/runtime_control.vsgml
@@ -255,6 +255,15 @@ on how to set things up for easy ``ticky-ticky'' profiling.  For more
 information, see Section <ref name="Using ``ticky-ticky'' profiling
 (for implementors)" id="ticky-ticky">.
 
+<tag>@-xc@:</tag>
+<nidx>-xc RTS option</nidx>
+<nidx>cost centre display on exception</nidx>
+Display the current cost centre stack whenever an exception is
+raised.  The program must have been compiled with profiling turned on:
+see Section <ref name="Profiling" id="profiling">.  This feature is
+experimental; one day it will display the information only on
+<em>uncaught</em> exceptions.
+
 <tag>@-D<num>@:</tag>
 <nidx>-D RTS option</nidx>
 An RTS debugging flag; varying quantities of output depending on which