[project @ 1999-05-11 16:42:29 by keithw]

(this is number 5b of 9 commits to be applied together)

  The major purpose of this commit is to introduce usage information
  and usage analysis into the compiler, per the paper _Once Upon a
  Polymorphic Type_ (Keith Wansbrough and Simon Peyton Jones, POPL'99,
  and Glasgow TR-1998-19).

  An analysis is provided that annotates a Core program with optimal
  usage annotations.  This analysis is performed by -fusagesp
  (=CoreDoUSPInf), and requires -fusagesp-on (=opt_UsageSPOn).  This
  latter performs an analysis in tidyCorePgm, immediately before
  CoreToStg is done.  The driver flag -fusagesp currently provides hsc
  with -fusagesp-on, and if -O is on does a single -fusagesp early on
  in the Core-to-Core sequence.  Please change this as desired.

  *NB*: For now, -fusagesp with -O requires -fno-specialise.  Sorry.

  The flags -ddump-usagesp (=opt_D_dump_usagesp) and -dusagesp-lint
  (=opt_DoUSPLinting) (also -dnousagesp-lint to the driver) have been
  added and are documented in the User Guide.

1 files changed, 28 insertions, 0 deletions

diff --git a/ghc/docs/users_guide/debugging.vsgml b/ghc/docs/users_guide/debugging.vsgml
index cdf951c9cc..78842c7f57 100644
--- a/ghc/docs/users_guide/debugging.vsgml
+++ b/ghc/docs/users_guide/debugging.vsgml
@@ -109,6 +109,7 @@ need a short form...).  Some of the most useful ones are:
 @-ddump-ds@ | desugarer output @@
 @-ddump-simpl@ | simplifer output (Core-to-Core passes) @@
 @-ddump-stranal@ | strictness analyser output @@
+@-ddump-usagesp@ | UsageSP inference pre-inf and output @@
 @-ddump-occur-anal@ | `occurrence analysis' output @@
 @-ddump-spec@ | dump specialisation info @@
 @-ddump-stg@ | output of STG-to-STG passes @@
@@ -124,6 +125,7 @@ need a short form...).  Some of the most useful ones are:
 <nidx>-ddump-deriv option</nidx>%
 <nidx>-ddump-ds option</nidx>%
 <nidx>-ddump-simpl option</nidx>%
+<nidx>-ddump-usagesp option</nidx>%
 <nidx>-ddump-stranal option</nidx>%
 <nidx>-ddump-occur-anal option</nidx>%
 <nidx>-ddump-spec option</nidx>%
@@ -191,6 +193,32 @@ Have the renamer report what imports does not contribute.
 %-ddump-asm-globals-info
 
 %----------------------------------------------------------------------
+<sect2>Checking for consistency
+<label id="checking-consistency">
+<p>
+<nidx>consistency checks</nidx>
+<nidx>lint</nidx>
+
+<descrip>
+<tag>@-dcore-lint@:</tag>
+<nidx>-dcore-lint option</nidx>
+Turn on heavyweight intra-pass sanity-checking within GHC, at Core
+level.  (It checks GHC's sanity, not yours.)
+
+<tag>@-dstg-lint@:</tag>
+<nidx>-dstg-lint option</nidx>
+Ditto for STG level.
+
+<tag>@-dusagesp-lint@:</tag>
+<nidx>-dstg-lint option</nidx>
+Turn on checks around UsageSP inference (@-fusagesp@).  This verifies
+various simple properties of the results of the inference, and also
+warns if any identifier with a used-once annotation before the
+inference has a used-many annotation afterwards; this could indicate a
+non-worksafe transformation is being applied.
+</descrip>
+
+%----------------------------------------------------------------------
 <sect2>How to read Core syntax (from some @-ddump-*@ flags)
 <p>
 <nidx>reading Core syntax</nidx>