[project @ 1997-03-24 04:42:42 by sof]

[ghc-hetmet.git] / ghc / docs / users_guide / how_to_run.lit

diff --git a/ghc/docs/users_guide/how_to_run.lit b/ghc/docs/users_guide/how_to_run.lit
index 79c7ab9..34fdd32 100644 (file)
--- a/ghc/docs/users_guide/how_to_run.lit
+++ b/ghc/docs/users_guide/how_to_run.lit
@@ -5,18 +5,17 @@
 Command-line arguments are either options or file names.
 
 Command-line options begin with \tr{-}.  They may {\em not} be
 Command-line arguments are either options or file names.
 
 Command-line options begin with \tr{-}.  They may {\em not} be

-grouped: \tr{-vO} is different from \tr{-v -O}.
-Options need not precede filenames: e.g., \tr{ghc *.o -o foo}.
-All options are processed
-and then apply to all files; you cannot, for example,
-invoke \tr{ghc -c -O1 Foo.hs -O2 Bar.hs} to apply different
-optimisation levels to the files \tr{Foo.hs} and \tr{Bar.hs}.  For
-conflicting options, e.g., \tr{-c -S}, we reserve the right to do
-anything we want.  (Usually, the last one applies.)
+grouped: \tr{-vO} is different from \tr{-v -O}.  Options need not
+precede filenames: e.g., \tr{ghc *.o -o foo}.  All options are
+processed and then applied to all files; you cannot, for example, invoke
+\tr{ghc -c -O1 Foo.hs -O2 Bar.hs} to apply different optimisation
+levels to the files \tr{Foo.hs} and \tr{Bar.hs}.  For conflicting
+options, e.g., \tr{-c -S}, we reserve the right to do anything we
+want.  (Usually, the last one applies.)

 
 Options related to profiling, Glasgow extensions to Haskell (e.g.,
 
 Options related to profiling, Glasgow extensions to Haskell (e.g.,

-unboxed values), Concurrent and Parallel Haskell are
-described in \sectionref{profiling}, \sectionref{glasgow-exts}, and
+unboxed values), Concurrent and Parallel Haskell are described in
+\sectionref{profiling}, \sectionref{glasgow-exts}, and

 \sectionref{concurrent-and-parallel}, respectively.
 
 %************************************************************************
 \sectionref{concurrent-and-parallel}, respectively.
 
 %************************************************************************

@@ -85,6 +84,10 @@ Please, oh please, use the \tr{-v} option when reporting bugs!
 Knowing that you ran the right bits in the right order is always the
 first thing we want to verify.
 
 Knowing that you ran the right bits in the right order is always the
 first thing we want to verify.
 

+If you're just interested in the compiler version number, the
+\tr{--version}\index{--version option} option prints out a
+one-line string containing the requested info.
+

 %************************************************************************
 %*                                                                      *
 \subsection[options-order]{Running the right phases in the right order}
 %************************************************************************
 %*                                                                      *
 \subsection[options-order]{Running the right phases in the right order}

@@ -106,8 +109,7 @@ compilation system & ``start here''& ``stop after''& output file \\ \hline
 
 literate pre-processor & .lhs      & -      & - \\
 C pre-processor (opt.) & -         & -      & - \\
 
 literate pre-processor & .lhs      & -      & - \\
 C pre-processor (opt.) & -         & -      & - \\

-Haskell parser      & .hs       & -      & -  \\
-Haskell compiler    & -    & -C, -S     & .hc, .s \\
+Haskell compiler    & .hs    & -C, -S     & .hc, .s \\

 C compiler (opt.)       & .hc or .c & -S            & .s  \\
 assembler              & .s        & -c     & .o  \\
 linker                 & other     & -      & a.out \\
 C compiler (opt.)       & .hc or .c & -S            & .s  \\
 assembler              & .s        & -c     & .o  \\
 linker                 & other     & -      & a.out \\

@@ -127,7 +129,8 @@ native-code generator is used (producing assembly language) or not
 %files as if they had suffix \pl{<suf>}. [NOT IMPLEMENTED YET]
 
 The option \tr{-cpp}\index{-cpp option} must be given for the C
 %files as if they had suffix \pl{<suf>}. [NOT IMPLEMENTED YET]
 
 The option \tr{-cpp}\index{-cpp option} must be given for the C

-pre-processor phase to be run.
+pre-processor phase to be run, that is, the pre-processor will be run
+over your Haskell source file before continuing.

 
 The option \tr{-E}\index{-E option} runs just the C-preprocessor part
 of the C-compiling phase, sending the result to stdout [I think].  (For
 
 The option \tr{-E}\index{-E option} runs just the C-preprocessor part
 of the C-compiling phase, sending the result to stdout [I think].  (For

@@ -157,8 +160,9 @@ following ``packages'' of optimisations (or lack thereof) should suffice.
 
 Once you choose a \tr{-O*} ``package,'' stick with it---don't chop and
 change.  Modules' interfaces {\em will} change with a shift to a new
 
 Once you choose a \tr{-O*} ``package,'' stick with it---don't chop and
 change.  Modules' interfaces {\em will} change with a shift to a new

-\tr{-O*} option, and you will have to recompile all importing modules
-before your program can again be run safely.
+\tr{-O*} option, and you may have to recompile a large chunk of all
+importing modules before your program can again be run
+safely\sectionref{recomp}.

 
 \begin{description}
 \item[No \tr{-O*}-type option specified:]
 
 \begin{description}
 \item[No \tr{-O*}-type option specified:]

@@ -183,7 +187,7 @@ The avoided ``dangerous'' optimisations are those that can make
 runtime or space {\em worse} if you're unlucky.  They are
 normally turned on or off individually.
 
 runtime or space {\em worse} if you're unlucky.  They are
 normally turned on or off individually.
 

-As of version~0.26, \tr{-O2} is {\em unlikely} to produce
+At the moment, \tr{-O2} is {\em unlikely} to produce

 better code than \tr{-O}.
 
 % \item[\tr{-O0}:]
 better code than \tr{-O}.
 
 % \item[\tr{-O0}:]

@@ -266,16 +270,13 @@ So, for example, you can say
 strictness analyser.
 
 The options you are most likely to want to turn off are:
 strictness analyser.
 
 The options you are most likely to want to turn off are:

-\tr{-fno-update-analysis}\index{-fno-update-analysis option} [because
-it is sometimes slow],

 \tr{-fno-strictness}\index{-fno-strictness option} (strictness
 analyser [because it is sometimes slow]),
 \tr{-fno-specialise}\index{-fno-specialise option} (automatic
 specialisation of overloaded functions [because it makes your code
 bigger]) [US spelling also accepted],
 and
 \tr{-fno-strictness}\index{-fno-strictness option} (strictness
 analyser [because it is sometimes slow]),
 \tr{-fno-specialise}\index{-fno-specialise option} (automatic
 specialisation of overloaded functions [because it makes your code
 bigger]) [US spelling also accepted],
 and

-\tr{-fno-foldr-build}\index{-fno-foldr-build option} [because no-one
-knows what Andy Gill made it do].
+\tr{-fno-foldr-build}\index{-fno-foldr-build option}.

 
 Should you wish to turn individual flags {\em on}, you are advised to
 use the \tr{-Ofile} option, described above.  Because the order in
 
 Should you wish to turn individual flags {\em on}, you are advised to
 use the \tr{-Ofile} option, described above.  Because the order in

@@ -286,11 +287,11 @@ Here are some ``dangerous'' optimisations you {\em might} want to try:
 \begin{description}
 %------------------------------------------------------------------
 \item[\tr{-funfolding-creation-threshold<n>}:]
 \begin{description}
 %------------------------------------------------------------------
 \item[\tr{-funfolding-creation-threshold<n>}:]

-(Default: 30) By raising or lowering this number, you can raise or lower the
-amount of pragmatic junk that gets spewed into interface files.
-(An unfolding has a ``size'' that reflects the cost in terms of ``code
-bloat'' of expanding that unfolding in another module.  A bigger
-Core expression would be assigned a bigger cost.)
+(Default: 30) By raising or lowering this number, you can raise or
+lower the amount of pragmatic junk that gets spewed into interface
+files.  (An unfolding has a ``size'' that reflects the cost in terms
+of ``code bloat'' of expanding that unfolding in another module.  A
+bigger Core expression would be assigned a bigger cost.)

 
 \item[\tr{-funfolding-use-threshold<n>}:]
 (Default: 3) By raising or lowering this number, you can make the
 
 \item[\tr{-funfolding-use-threshold<n>}:]
 (Default: 3) By raising or lowering this number, you can make the

@@ -316,13 +317,13 @@ with the bigger-but-better one?  Yes, if the bigger one's ``size'' is
 still under the ``override threshold.''  You can use this flag to
 adjust this threshold (why, I'm not sure).
 
 still under the ``override threshold.''  You can use this flag to
 adjust this threshold (why, I'm not sure).
 

-\item[\tr{-fliberated-case-threshold<n>}:]
-(Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
-``Case liberation'' lifts evaluation out of recursive functions; it
-does this by duplicating code.  Done without constraint, you can get
-serious code bloat; so we only do it if the ``size'' of the duplicated
-code is smaller than some ``threshold.''  This flag can fiddle that
-threshold.
+% \item[\tr{-fliberated-case-threshold<n>}:]
+% (Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
+% ``Case liberation'' lifts evaluation out of recursive functions; it
+% does this by duplicating code.  Done without constraint, you can get
+% serious code bloat; so we only do it if the ``size'' of the duplicated
+% code is smaller than some ``threshold.''  This flag can fiddle that
+% threshold.

 
 \item[\tr{-fsemi-tagging}:]
 This option (which {\em does not work} with the native-code generator)
 
 \item[\tr{-fsemi-tagging}:]
 This option (which {\em does not work} with the native-code generator)

@@ -331,7 +332,7 @@ values.  You win if you have lots of such values during a run of your
 program, you lose otherwise.  (And you pay in extra code space.)
 
 We have not played with \tr{-fsemi-tagging} enough to recommend it.
 program, you lose otherwise.  (And you pay in extra code space.)
 
 We have not played with \tr{-fsemi-tagging} enough to recommend it.

-(For all we know, it doesn't even work in 0.26.  Sigh.)
+(For all we know, it doesn't even work anymore...  Sigh.)

 \end{description}
 
 %----------------------------------------------------------------------
 \end{description}
 
 %----------------------------------------------------------------------

@@ -365,23 +366,29 @@ We have not played with \tr{-fsemi-tagging} enough to recommend it.
 Some flags only make sense for particular target platforms.
 
 \begin{description}
 Some flags only make sense for particular target platforms.
 
 \begin{description}

+\item[\tr{-mv8}:]
+(SPARC machines)\index{-mv8 option (SPARC only)}
+Means to pass the like-named option to GCC; it says to use the
+Version 8 SPARC instructions, notably integer multiply and divide.
+The similiar \tr{-m*} GCC options for SPARC also work, actually.
+

 \item[\tr{-mlong-calls}:]
 (HPPA machines)\index{-mlong-calls option (HPPA only)}
 Means to pass the like-named option to GCC.  Required for Very Big
 modules, maybe.  (Probably means you're in trouble...)
 
 \item[\tr{-mlong-calls}:]
 (HPPA machines)\index{-mlong-calls option (HPPA only)}
 Means to pass the like-named option to GCC.  Required for Very Big
 modules, maybe.  (Probably means you're in trouble...)
 

-\item[\tr{-monly-[432]-regs}:]
+\item[\tr{-monly-[32]-regs}:]

 (iX86 machines)\index{-monly-N-regs option (iX86 only)}
 (iX86 machines)\index{-monly-N-regs option (iX86 only)}

-GHC tries to ``steal'' five registers from GCC, for performance
+GHC tries to ``steal'' four registers from GCC, for performance

 reasons; it almost always works.  However, when GCC is compiling some
 reasons; it almost always works.  However, when GCC is compiling some

-modules with five stolen registers, it will crash, probably saying:
+modules with four stolen registers, it will crash, probably saying:

 \begin{verbatim}
 Foo.hc:533: fixed or forbidden register was spilled.
 This may be due to a compiler bug or to impossible asm
 statements or clauses.
 \end{verbatim}
 \begin{verbatim}
 Foo.hc:533: fixed or forbidden register was spilled.
 This may be due to a compiler bug or to impossible asm
 statements or clauses.
 \end{verbatim}

-Just give some registers back with \tr{-monly-N-regs}.  Try `4' first,
-then `3', then `2'.  If `2' doesn't work, please report the bug to us.
+Just give some registers back with \tr{-monly-N-regs}.  Try `3' first,
+then `2'.  If `2' doesn't work, please report the bug to us.

 \end{description}
 
 %----------------------------------------------------------------------
 \end{description}
 
 %----------------------------------------------------------------------

@@ -389,8 +396,8 @@ then `3', then `2'.  If `2' doesn't work, please report the bug to us.
 \index{optimisation by GCC}
 \index{GCC optimisation}
 
 \index{optimisation by GCC}
 \index{GCC optimisation}
 

-The C~compiler, normally GCC, is run with \tr{-O} turned on.  (It has
-to be, actually.)
+The C~compiler (GCC) is run with \tr{-O} turned on.  (It has
+to be, actually).

 
 If you want to run GCC with \tr{-O2}---which may be worth a few
 percent in execution speed---you can give a
 
 If you want to run GCC with \tr{-O2}---which may be worth a few
 percent in execution speed---you can give a

@@ -402,7 +409,7 @@ percent in execution speed---you can give a
 
 %************************************************************************
 %*                                                                      *
 
 %************************************************************************
 %*                                                                      *

-\subsection[options-sanity]{Sanity-checking options}
+\subsection[options-sanity]{Warnings and sanity-checking}

 \index{sanity-checking options}
 %*                                                                      *
 %************************************************************************
 \index{sanity-checking options}
 %*                                                                      *
 %************************************************************************

@@ -413,14 +420,31 @@ option.\index{-fsignatures-required option}
 
 If you would like to disallow ``name shadowing,'' i.e., an inner-scope
 value has the same name as an outer-scope value, then use the
 
 If you would like to disallow ``name shadowing,'' i.e., an inner-scope
 value has the same name as an outer-scope value, then use the

-\tr{-fname-shadowing-not-ok}
-option.\index{-fname-shadowing-not-ok option}
+\tr{-fwarn-name-shadowing}
+option.\index{-fwarn-name-shadowing option}

 This option catches typographical errors that turn into hard-to-find
 bugs, e.g., in the inadvertent cyclic definition \tr{let x = ... x ... in}.
 
 Consequently, this option does {\em not} allow cyclic recursive
 definitions.
 
 This option catches typographical errors that turn into hard-to-find
 bugs, e.g., in the inadvertent cyclic definition \tr{let x = ... x ... in}.
 
 Consequently, this option does {\em not} allow cyclic recursive
 definitions.
 

+By default, the compiler will warn you if a set of patterns are either
+incomplete (i.e., you're only matching on a subset of an algebraic
+data type's constructors), or overlapping, i.e.,
+
+\begin{verbatim}
+f :: String -> Int
+f []     = 0
+f (_:xs) = 1
+f "2"    = 2
+\end{verbatim}
+
+where the last pattern match won't ever be reached, as the second
+pattern overlaps it. More often than not, `completeness' of
+patterns is a programmer mistake/error, but if you don't want
+the compiler to ``baby-sit'', use \tr{-fno-warn-incomplete-patterns} option
+to turn them off.\index{-fno-warn-incomplete-patterns option}.
+

 If you're feeling really paranoid, the \tr{-dcore-lint}
 option\index{-dcore-lint option} is a good choice.  It turns on
 heavyweight intra-pass sanity-checking within GHC.  (It checks GHC's
 If you're feeling really paranoid, the \tr{-dcore-lint}
 option\index{-dcore-lint option} is a good choice.  It turns on
 heavyweight intra-pass sanity-checking within GHC.  (It checks GHC's

@@ -440,7 +464,7 @@ One file is usually an {\em interface file}.  If compiling
 \tr{bar/Foo.hs}, the interface file would normally be \tr{bar/Foo.hi}.
 The interface output may be directed to another file
 \tr{bar2/Wurble.iface} with the option
 \tr{bar/Foo.hs}, the interface file would normally be \tr{bar/Foo.hi}.
 The interface output may be directed to another file
 \tr{bar2/Wurble.iface} with the option

-\tr{-ohi bar2/Wurble.iface}\index{-ohi <file> option}.
+\tr{-ohi bar2/Wurble.iface}\index{-ohi <file> option} (not recommended).

 
 To avoid generating an interface file at all, use a \tr{-nohi}
 option.\index{-nohi option}
 
 To avoid generating an interface file at all, use a \tr{-nohi}
 option.\index{-nohi option}

@@ -451,6 +475,11 @@ the new one is byte-for-byte the same as the old one; this is friendly to
 be informed.  The \tr{-hi-diffs}\index{-hi-diffs option} option will
 make \tr{ghc} run \tr{diff} on the old and new \tr{.hi} files.
 
 be informed.  The \tr{-hi-diffs}\index{-hi-diffs option} option will
 make \tr{ghc} run \tr{diff} on the old and new \tr{.hi} files.
 

+The \tr{.hi} files from GHC 2.xx contain ``usage'' information which
+changes often and uninterestingly.  If you really want to see these
+changes reported, you need to use the
+\tr{-hi-diffs-with-usages}\index{-hi-diffs-with-usages option} option.
+

 GHC's non-interface output normally goes into a \tr{.hc}, \tr{.o},
 etc., file, depending on the last-run compilation phase.  The option
 \tr{-o foo}\index{-o option} re-directs the output of that last-run
 GHC's non-interface output normally goes into a \tr{.hc}, \tr{.o},
 etc., file, depending on the last-run compilation phase.  The option
 \tr{-o foo}\index{-o option} re-directs the output of that last-run

@@ -460,8 +489,8 @@ Note: this ``feature'' can be counterintuitive:
 \tr{ghc -C -o foo.o foo.hs} will put the intermediate C code in the
 file \tr{foo.o}, name notwithstanding!
 
 \tr{ghc -C -o foo.o foo.hs} will put the intermediate C code in the
 file \tr{foo.o}, name notwithstanding!
 

-EXOTICA: But the \tr{-o} option isn't much use if you have {\em
-several} input files...  Non-interface output files are normally put
+EXOTICA: But the \tr{-o} option isn't of much use if you have {\em
+several} input files... Non-interface output files are normally put

 in the same directory as their corresponding input file came from.
 You may specify that they be put in another directory using the
 \tr{-odir <dir>}\index{-odir <dir> option} (the ``Oh, dear'' option).
 in the same directory as their corresponding input file came from.
 You may specify that they be put in another directory using the
 \tr{-odir <dir>}\index{-odir <dir> option} (the ``Oh, dear'' option).

@@ -495,7 +524,12 @@ that your read.
 The \tr{-hisuf}/\tr{-osuf} game is useful if you want to compile a
 program with both GHC and HBC (say) in the same directory.  Let HBC
 use the standard \tr{.hi}/\tr{.o} suffixes; add
 The \tr{-hisuf}/\tr{-osuf} game is useful if you want to compile a
 program with both GHC and HBC (say) in the same directory.  Let HBC
 use the standard \tr{.hi}/\tr{.o} suffixes; add

-\tr{-hisuf _g.hi -osuf _g.o} to your \tr{make} rule for GHC compiling...
+\tr{-hisuf g_hi -osuf g_o} to your \tr{make} rule for GHC compiling...
+
+NB: {\em A change from 0.26 and before:} Before, you might have said
+\tr{-hisuf _g.hi -osuf _g.o}; now, the \tr{.} is assumed and you
+specify what comes {\em after} it.  (This is a more portable solution
+for the long term.)

 
 % THIS SHOULD HAPPEN AUTOMAGICALLY:
 % If you want to change the suffix looked for on system-supplied
 
 % THIS SHOULD HAPPEN AUTOMAGICALLY:
 % If you want to change the suffix looked for on system-supplied

@@ -526,8 +560,9 @@ variable.\index{TMPDIR environment variable}  Set it to the name of
 the directory where temporary files should be put.  GCC and other
 programs will honour the \tr{TMPDIR} variable as well.
 
 the directory where temporary files should be put.  GCC and other
 programs will honour the \tr{TMPDIR} variable as well.
 

-EVEN BETTER IDEA: Configure GHC with \tr{--with-tmpdir=<mumble>} when
-you build it, and never worry about \tr{TMPDIR} again.
+EVEN BETTER IDEA: Set the \tr{TMPDIR} variable when building
+GHC, and never worry about \tr{TMPDIR} again. (see the build
+documentation).

 
 %************************************************************************
 %*                                                                      *
 
 %************************************************************************
 %*                                                                      *

@@ -547,11 +582,9 @@ colon-separated list of \tr{dirs} to the ``import directories'' list.
 
 A plain \tr{-i} resets the ``import directories'' list back to nothing.
 
 
 A plain \tr{-i} resets the ``import directories'' list back to nothing.
 

-GHC normally imports \tr{PreludeCore.hi} and \tr{Prelude.hi} files for
-you.  If you'd rather it didn't, then give it a
-\tr{-fno-implicit-prelude} option\index{-fno-implicit-prelude option}.
-(Sadly, it still has to {\em find} a \tr{PreludeNull_.hi} file; it
-just won't feed it into the compiler proper.)  You are unlikely to get
+GHC normally imports \tr{Prelude.hi} files for you.  If you'd rather
+it didn't, then give it a \tr{-fno-implicit-prelude}
+option\index{-fno-implicit-prelude option}.  You are unlikely to get

 very far without a Prelude, but, hey, it's a free country.
 
 If you are using a system-supplied non-Prelude library (e.g., the HBC
 very far without a Prelude, but, hey, it's a free country.
 
 If you are using a system-supplied non-Prelude library (e.g., the HBC

@@ -610,7 +643,7 @@ Undefine macro \tr{<foo>} in the usual way.
 \item[\tr{-I<dir>}:]
 \index{-I<dir> option}
 Specify a directory in which to look for \tr{#include} files, in
 \item[\tr{-I<dir>}:]
 \index{-I<dir> option}
 Specify a directory in which to look for \tr{#include} files, in

-the usual UNIX/C way.
+the usual C way.

 \end{description}
 
 The \tr{ghc} driver pre-defines several macros:
 \end{description}
 
 The \tr{ghc} driver pre-defines several macros:

@@ -619,18 +652,18 @@ The \tr{ghc} driver pre-defines several macros:
 \index{__HASKELL1__ macro}
 If defined to $n$, that means GHC supports the
 Haskell language defined in the Haskell report version $1.n$.
 \index{__HASKELL1__ macro}
 If defined to $n$, that means GHC supports the
 Haskell language defined in the Haskell report version $1.n$.

-Currently 2.
+Currently 4.

 
 NB: This macro is set both when pre-processing Haskell source and
 when pre-processing generated C (\tr{.hc}) files.
 
 
 NB: This macro is set both when pre-processing Haskell source and
 when pre-processing generated C (\tr{.hc}) files.
 

-If you give the \tr{-fhaskell-1.3} flag\index{-fhaskell-1.3 option},
-then \tr{__HASKELL1__} is set to 3.  Obviously.
+% If you give the \tr{-fhaskell-1.3} flag\index{-fhaskell-1.3 option},
+% then \tr{__HASKELL1__} is set to 3.  Obviously.

 
 \item[\tr{__GLASGOW_HASKELL__}:]
 \index{__GLASGOW_HASKELL__ macro}
 For version $n$ of the GHC system, this will be \tr{#define}d to
 
 \item[\tr{__GLASGOW_HASKELL__}:]
 \index{__GLASGOW_HASKELL__ macro}
 For version $n$ of the GHC system, this will be \tr{#define}d to

-$100 \times n$.  So, for version~0.26, it is 26.
+$100 \times n$.  So, for version~2.02, it is 202.

 
 This macro is {\em only} set when pre-processing Haskell source.
 ({\em Not} when pre-processing generated C.)
 
 This macro is {\em only} set when pre-processing Haskell source.
 ({\em Not} when pre-processing generated C.)

@@ -639,15 +672,13 @@ With any luck, \tr{__GLASGOW_HASKELL__} will be undefined in all other
 implementations that support C-style pre-processing.
 
 (For reference: the comparable symbols for other systems are:
 implementations that support C-style pre-processing.
 
 (For reference: the comparable symbols for other systems are:

-\tr{__YALE_HASKELL__} for Yale Haskell, \tr{__HBC__} for Chalmers
-HBC, and \tr{__GOFER__} for Gofer [I think].)
+\tr{__HUGS__} for Hugs and \tr{__HBC__} for Chalmers.)

 
 \item[\tr{__CONCURRENT_HASKELL__}:]
 \index{__CONCURRENT_HASKELL__ macro}
 Only defined when \tr{-concurrent} is in use!
 
 \item[\tr{__CONCURRENT_HASKELL__}:]
 \index{__CONCURRENT_HASKELL__ macro}
 Only defined when \tr{-concurrent} is in use!

-This symbol is
-defined when pre-processing Haskell (input) and pre-processing C (GHC
-output).
+This symbol is defined when pre-processing Haskell (input) and
+pre-processing C (GHC output).

 
 \item[\tr{__PARALLEL_HASKELL__}:]
 \index{__PARALLEL_HASKELL__ macro}
 
 \item[\tr{__PARALLEL_HASKELL__}:]
 \index{__PARALLEL_HASKELL__ macro}

@@ -668,6 +699,7 @@ A small word of warning: \tr{-cpp} is not friendly to
 \subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
 \index{C compiler options}
 \index{GCC options}
 \subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
 \index{C compiler options}
 \index{GCC options}

+\index{include file option}

 %*                                                                      *
 %************************************************************************
 
 %*                                                                      *
 %************************************************************************
 

@@ -687,13 +719,13 @@ THIS MAY CHANGE.  Meanwhile, options so sent are:
 \index{-dgcc-lint option (GCC paranoia)}
 
 If you are compiling with lots of \tr{ccalls}, etc., you may need to
 \index{-dgcc-lint option (GCC paranoia)}
 
 If you are compiling with lots of \tr{ccalls}, etc., you may need to

-tell the C~compiler about some \tr{#include} files.  There is no
+tell the C~compiler about some \tr{#include} files.  There is no real

 pretty way to do this, but you can use this hack from the
 command-line:
 \begin{verbatim}
 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
 \end{verbatim}
 pretty way to do this, but you can use this hack from the
 command-line:
 \begin{verbatim}
 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
 \end{verbatim}

-\index{-#include <file> option}
+

 
 %************************************************************************
 %*                                                                      *
 
 %************************************************************************
 %*                                                                      *

@@ -738,21 +770,23 @@ libraries automatically; these are:
 
 -lHSrts,-lHSclib & basic runtime libraries \\
 -lHS         & standard Prelude library \\
 
 -lHSrts,-lHSclib & basic runtime libraries \\
 -lHS         & standard Prelude library \\

+-lHS\_cbits  & C support code for standard Prelude library \\

 -lgmp        & GNU multi-precision library (for Integers)\\
 \end{tabular}
 \index{-lHS library}
 -lgmp        & GNU multi-precision library (for Integers)\\
 \end{tabular}
 \index{-lHS library}

+\index{-lHS_cbits library}

 \index{-lHSrts library}
 \index{-lgmp library}
 
 \item[\tr{-syslib <name>}:]
 \index{-syslib <name> option}
 
 \index{-lHSrts library}
 \index{-lgmp library}
 
 \item[\tr{-syslib <name>}:]
 \index{-syslib <name> option}
 

-If you are using an optional GHC-supplied library (e.g., the HBC
+If you are using a Haskell ``system library'' (e.g., the HBC

 library), just use the \tr{-syslib hbc} option, and the correct code
 should be linked in.
 
 library), just use the \tr{-syslib hbc} option, and the correct code
 should be linked in.
 

-Please see \sectionref{syslibs} for information about optional
-GHC-supplied libraries.
+%Please see \sectionref{syslibs} for information about
+%``system libraries.''

 
 \item[\tr{-L<dir>}:]
 \index{-L<dir> option}
 
 \item[\tr{-L<dir>}:]
 \index{-L<dir> option}

@@ -828,16 +862,16 @@ Report garbage-collection statistics.  It will create a
 
 Alternatively, if you'd rather the GC stats went straight to standard
 error, you can ``cheat'' by using, instead: \tr{-optCrts-Sstderr}.
 
 Alternatively, if you'd rather the GC stats went straight to standard
 error, you can ``cheat'' by using, instead: \tr{-optCrts-Sstderr}.

-
-\item[\tr{-Rhbc}:]
-\index{-Rhbc option}
-Tell the compiler it has an HBC-style RTS; i.e., it was compiled with
-HBC.  Not used in Real Life.
-
-\item[\tr{-Rghc}:]
-\index{-Rghc option}
-Tell the compiler it has a GHC-style RTS; i.e., it was compiled with
-GHC.  Not used in Real Life.
+%
+%\item[\tr{-Rhbc}:]
+%\index{-Rhbc option}
+%Tell the compiler it has an HBC-style RTS; i.e., it was compiled with
+%HBC.  Not used in Real Life.
+%
+%\item[\tr{-Rghc}:]
+%\index{-Rghc option}
+%Tell the compiler it has a GHC-style RTS; i.e., it was compiled with
+%GHC.  Not used in Real Life.

 \end{description}
 
 For all \tr{<size>}s: If the last character of \tr{size} is a K,
 \end{description}
 
 For all \tr{<size>}s: If the last character of \tr{size} is a K,

@@ -873,31 +907,32 @@ programming, please see \Sectionref{concurrent-and-parallel}.
 
 %************************************************************************
 %*                                                                      *
 
 %************************************************************************
 %*                                                                      *

-\subsection[options-experimental]{For experimental purposes}
-\index{experimental options}
+%\subsection[options-experimental]{For experimental purposes}
+%\index{experimental options}

 %*                                                                      *
 %************************************************************************
 
 %*                                                                      *
 %************************************************************************
 

-From time to time, we provide GHC options for ``experimenting.''  Easy
-come, easy go.  In version~0.26, the ``experimental'' options are:
-\begin{description}
-\item[\tr{-firrefutable-tuples} option:]
-\index{-firrefutable-tuples option (experimental)}
-Pretend that every tuple pattern is irrefutable; i.e., has a
-``twiddle'' (\tr{~}) in front of it.
-
-Some parts of the GHC system {\em depend} on strictness properties which
-\tr{-firrefutable-tuples} may undo, notably the low-level state-transformer
-stuff, which includes I/O (!).  You're on your own...
-
-\item[\tr{-fall-strict} option:]
-\index{-fall-strict option (experimental)}
-(DOESN'T REALLY WORK, I THINK) Changes the strictness analyser so
-that, when it asks the question ``Is this function argument certain to
-be evaluated?'', the answer is always ``yes''.
-
-Compilation is changed in no other way.
-\end{description}
+%From time to time, we provide GHC options for ``experimenting.''  Easy
+%come, easy go.  In version~0.26, the ``experimental'' options are:
+%\begin{description}
+%\item[\tr{-firrefutable-tuples} option:]
+%\index{-firrefutable-tuples option (experimental)}
+%Pretend that every tuple pattern is irrefutable; i.e., has a
+%``twiddle'' (\tr{~}) in front of it.
+%
+%Some parts of the GHC system {\em depend} on strictness properties which
+%\tr{-firrefutable-tuples} may undo, notably the low-level state-transformer
+%stuff, which includes I/O (!).  You're on your own...
+%
+%\item[\tr{-fall-strict} option:]
+%\index{-fall-strict option (experimental)}
+% (DOESN'T REALLY WORK, I THINK) Changes the strictness analyser so
+%that, when it asks the question ``Is this function argument certain to
+%be evaluated?'', the answer is always ``yes''.
+%
+%Compilation is changed in no other way.
+%\end{description}
+

 % -firrefutable-everything
 % -fall-demanded
 
 % -firrefutable-everything
 % -fall-demanded
 

@@ -919,7 +954,7 @@ HACKER TERRITORY. HACKER TERRITORY.
 You may specify that a different program
 be used for one of the phases of the compilation system, in place of
 whatever the driver \tr{ghc} has wired into it.  For example, you
 You may specify that a different program
 be used for one of the phases of the compilation system, in place of
 whatever the driver \tr{ghc} has wired into it.  For example, you

-might want to test a replacement parser.  The
+might want to try a different assembler.  The

 \tr{-pgm<phase-code><program-name>}\index{-pgm<phase><stuff> option} option to
 \tr{ghc} will cause it to use \pl{<program-name>} for phase
 \pl{<phase-code>}, where the codes to indicate the phases are:
 \tr{-pgm<phase-code><program-name>}\index{-pgm<phase><stuff> option} option to
 \tr{ghc} will cause it to use \pl{<program-name>} for phase
 \pl{<phase-code>}, where the codes to indicate the phases are:

@@ -928,17 +963,12 @@ might want to test a replacement parser.  The
 code & phase \\ \hline
 L    & literate pre-processor \\
 P    & C pre-processor (if -cpp only) \\
 code & phase \\ \hline
 L    & literate pre-processor \\
 P    & C pre-processor (if -cpp only) \\

-p    & parser \\

 C    & Haskell compiler \\
 C    & Haskell compiler \\

-cO   & C compiler for `optimised' (normal) compiling \\
-c    & C compiler for `unregisterised' compiling \\
+c    & C compiler\\

 a    & assembler \\
 l    & linker \\
 \end{tabular}
 
 a    & assembler \\
 l    & linker \\
 \end{tabular}
 

-If you use the ambiguous \tr{-pgmcOle}, it will take it to mean
-``use program \tr{le} for optimised C compiling.''
-

 %----------------------------------------------------------------------
 \subsubsection[forcing-options-through]{Forcing options to a particular phase.}
 \index{forcing GHC-phase options}
 %----------------------------------------------------------------------
 \subsubsection[forcing-options-through]{Forcing options to a particular phase.}
 \index{forcing GHC-phase options}

@@ -962,8 +992,8 @@ So, for example: when I want to use my normal driver but with my
 profiled compiler binary, I use this script:
 \begin{verbatim}
 #! /bin/sh
 profiled compiler binary, I use this script:
 \begin{verbatim}
 #! /bin/sh

-exec /local/grasp_tmp3/partain/ghc-BUILDS/working-alpha/ghc/driver/ghc \
-     -pgmC/local/grasp_tmp3/partain/ghc-BUILDS/working-hsc-prof/hsc \
+exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
+     -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \

      -optCrts-i0.5 \
      -optCrts-PT \
      "$@"
      -optCrts-i0.5 \
      -optCrts-PT \
      "$@"

@@ -987,10 +1017,11 @@ example: \tr{ghc -noC -ddump-simpl Foo.hs}
 conjunction with \tr{-noC}, which turns off interface generation;
 thus: \tr{-noC -hi}.
 
 conjunction with \tr{-noC}, which turns off interface generation;
 thus: \tr{-noC -hi}.
 

-\item[\tr{-ddump-parser}:]
-\index{-ddump-parser option}
-This debugging option shows the exact prefix-form Haskell that is fed
-into the Haskell compiler proper.
+\item[\tr{-dshow-passes}:]
+\index{-dshow-passes option}
+Prints a message to stderr as each pass starts.  Gives a warm but
+undoubtedly misleading feeling that GHC is telling you what's
+happening.

 
 \item[\tr{-ddump-<pass>}:]
 \index{-ddump-<pass> options}
 
 \item[\tr{-ddump-<pass>}:]
 \index{-ddump-<pass> options}

@@ -998,17 +1029,14 @@ Make a debugging dump after pass \tr{<pass>} (may be common enough to
 need a short form...).  Some of the most useful ones are:
 
 \begin{tabular}{ll}
 need a short form...).  Some of the most useful ones are:
 
 \begin{tabular}{ll}

-\tr{-ddump-rif2hs} & reader output (earliest stuff in the compiler) \\
-\tr{-ddump-rn4} & renamer output \\
+\tr{-ddump-rdr} & reader output (earliest stuff in the compiler) \\
+\tr{-ddump-rn} & renamer output \\

 \tr{-ddump-tc} & typechecker output \\
 \tr{-ddump-deriv} & derived instances \\
 \tr{-ddump-ds} & desugarer output \\
 \tr{-ddump-simpl} & simplifer output (Core-to-Core passes) \\
 \tr{-ddump-tc} & typechecker output \\
 \tr{-ddump-deriv} & derived instances \\
 \tr{-ddump-ds} & desugarer output \\
 \tr{-ddump-simpl} & simplifer output (Core-to-Core passes) \\

-        & (and don't forget \tr{-O}, too!) \\

 \tr{-ddump-stranal} & strictness analyser output \\
 \tr{-ddump-stranal} & strictness analyser output \\

-        & (only works in conjunction with -ddump-simpl)\\

 \tr{-ddump-occur-anal} & `occurrence analysis' output \\
 \tr{-ddump-occur-anal} & `occurrence analysis' output \\

-        & (only works in conjunction with -ddump-simpl)\\

 \tr{-ddump-spec} & dump specialisation info \\
 \tr{-ddump-stg} & output of STG-to-STG passes \\
 \tr{-ddump-absC} & {\em un}flattened Abstract~C \\
 \tr{-ddump-spec} & dump specialisation info \\
 \tr{-ddump-stg} & output of STG-to-STG passes \\
 \tr{-ddump-absC} & {\em un}flattened Abstract~C \\

@@ -1016,8 +1044,8 @@ need a short form...).  Some of the most useful ones are:
 \tr{-ddump-realC} & same as what goes to the C compiler \\
 \tr{-ddump-asm} & assembly language from the native-code generator \\
 \end{tabular}
 \tr{-ddump-realC} & same as what goes to the C compiler \\
 \tr{-ddump-asm} & assembly language from the native-code generator \\
 \end{tabular}

-\index{-ddump-rif2hs option}%
-\index{-ddump-rn4 option}%
+\index{-ddump-rdr option}%
+\index{-ddump-rn option}%

 \index{-ddump-tc option}%
 \index{-ddump-deriv option}%
 \index{-ddump-ds option}%
 \index{-ddump-tc option}%
 \index{-ddump-deriv option}%
 \index{-ddump-ds option}%

@@ -1060,48 +1088,178 @@ individual type variables) is displayed.
 \item[\tr{-ddump-raw-asm}:]
 \index{-ddump-raw-asm option}
 Dump out the assembly-language stuff, before the ``mangler'' gets it.
 \item[\tr{-ddump-raw-asm}:]
 \index{-ddump-raw-asm option}
 Dump out the assembly-language stuff, before the ``mangler'' gets it.

-
-\item[\tr{-dgc-debug}:]
-\index{-dgc-debug option}
-Enables some debugging code related to the garbage-collector.
+%
+%\item[\tr{-dgc-debug}:]
+%\index{-dgc-debug option}
+%Enables some debugging code related to the garbage-collector.

 \end{description}
 
 %ToDo: -ddump-asm-insn-counts
 %-ddump-asm-globals-info
 
 %----------------------------------------------------------------------
 \end{description}
 
 %ToDo: -ddump-asm-insn-counts
 %-ddump-asm-globals-info
 
 %----------------------------------------------------------------------

-\subsubsection[arity-checking]{Options to insert arity-checking code}
-\index{arity checking}
+\subsubsection{How to read Core syntax (from some \tr{-ddump-*} flags)}
+\index{reading Core syntax}
+\index{Core syntax, how to read}

 
 

-The \tr{-darity-checks}\index{-darity-checks option} option inserts
-code to check for arity violations.  Unfortunately, it's not that
-simple: you have to link with a prelude that was also built with arity
-checks.  If you have one, then great; otherwise...
+Let's do this by commenting an example.  It's from doing
+\tr{-ddump-ds} on this code:
+\begin{verbatim}
+skip2 m = m : skip2 (m+2)
+\end{verbatim}
+
+Before we jump in, a word about names of things.  Within GHC,
+variables, type constructors, etc., are identified by their
+``Uniques.''  These are of the form `letter' plus `number' (both
+loosely interpreted).  The `letter' gives some idea of where the
+Unique came from; e.g., \tr{_} means ``built-in type variable'';
+\tr{t} means ``from the typechecker''; \tr{s} means ``from the
+simplifier''; and so on.  The `number' is printed fairly compactly in
+a `base-62' format, which everyone hates except me (WDP).

 
 

-The \tr{-darity-checks-C-only}\index{-darity-checks-C-only option}
-option inserts the self-same arity checking code into \tr{.hc} files,
-but doesn't compile it into the \tr{.o} files.  We use this flag with
-the \tr{-keep-hc-file-too}\index{-keep-hc-file-too option}, where we
-are keeping \tr{.hc} files around for debugging purposes.
+Remember, everything has a ``Unique'' and it is usually printed out
+when debugging, in some form or another.  So here we go...
+
+\begin{verbatim}
+Desugared:
+Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4]
+
+--# `r1L6' is the Unique for Main.skip2;
+--# `_4' is the Unique for the type-variable (template) `a'
+--# `{{Num a$_4}}' is a dictionary argument
+
+_NI_
+
+--# `_NI_' means "no (pragmatic) information" yet; it will later
+--# evolve into the GHC_PRAGMA info that goes into interface files.
+
+Main.skip2{-r1L6-} =
+    /\ _4 -> \ d.Num.t4Gt ->
+       let {
+         {- CoRec -}
+         +.t4Hg :: _4 -> _4 -> _4
+         _NI_
+         +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
+
+         fromInt.t4GS :: Int{-2i-} -> _4
+         _NI_
+         fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
+
+--# The `+' class method (Unique: r3JH) selects the addition code
+--# from a `Num' dictionary (now an explicit lamba'd argument).
+--# Because Core is 2nd-order lambda-calculus, type applications
+--# and lambdas (/\) are explicit.  So `+' is first applied to a
+--# type (`_4'), then to a dictionary, yielding the actual addition
+--# function that we will use subsequently...
+
+--# We play the exact same game with the (non-standard) class method
+--# `fromInt'.  Unsurprisingly, the type `Int' is wired into the
+--# compiler.
+
+         lit.t4Hb :: _4
+         _NI_
+         lit.t4Hb =
+             let {
+               ds.d4Qz :: Int{-2i-}
+               _NI_
+               ds.d4Qz = I#! 2#
+             } in  fromInt.t4GS ds.d4Qz
+
+--# `I# 2#' is just the literal Int `2'; it reflects the fact that
+--# GHC defines `data Int = I# Int#', where Int# is the primitive
+--# unboxed type.  (see relevant info about unboxed types elsewhere...)
+
+--# The `!' after `I#' indicates that this is a *saturated*
+--# application of the `I#' data constructor (i.e., not partially
+--# applied).
+
+         skip2.t3Ja :: _4 -> [_4]
+         _NI_
+         skip2.t3Ja =
+             \ m.r1H4 ->
+                 let { ds.d4QQ :: [_4]
+                       _NI_
+                       ds.d4QQ =
+                   let {
+                     ds.d4QY :: _4
+                     _NI_
+                     ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
+                   } in  skip2.t3Ja ds.d4QY
+                 } in
+                 :! _4 m.r1H4 ds.d4QQ
+
+         {- end CoRec -}
+       } in  skip2.t3Ja
+\end{verbatim}
+
+(``It's just a simple functional language'' is an unregisterised
+trademark of Peyton Jones Enterprises, plc.)

 
 %----------------------------------------------------------------------
 
 %----------------------------------------------------------------------

-\subsubsection[omit-checking]{Options to omit checking code}
-\index{omitting runtime checks}
+\subsubsection[source-file-options]{Command line options in source files}
+\index{source-file options}
+
+Sometimes it is useful to make the connection between a source file
+and the command-line options it requires, quite tight. For instance,
+if a (Glasgow) Haskell source file uses \tr{casm}s, the C back-end
+often needs to be told about header files to use,
+\ref{include file option}. Rather than maintaining the list of
+files the source depends on in a \tr{Makefile}, it is possible to
+do this directly in the source file using the \tr{OPTIONS} pragma
+\index{OPTIONS pragma}:

 
 

-By default, the GHC system emits all possible not-too-expensive
-runtime checking code.  If you are brave or experimenting, you might
-want to turn off some of this (not recommended):
+\begin{verbatim}
+{-# OPTIONS -#include "foo.h" #-}
+module X where

 
 

-\begin{tabular}{ll}
--dno-black-holing & won't buy you much (even if it works) \\
--dno-updates & you're crazy if you do this \\
--dno-stk-stubbing & omit stack stubbing (NOT DONE YET) \\
-\end{tabular}
-\index{-dno-black-holing option}%
-\index{-dno-updates option}%
-\index{-dno-stk-stubbing option}
+...
+\end{verbatim}

 
 

-Warning: all very lightly tested, if at all...
+\tr{OPTIONS} pragmas are only looked for at the top of your source
+files, upto the first (non-literate,non-empty) line not containing
+\tr{OPTIONS}. Multiple \tr{OPTIONS} pragmas are recognised. Note
+that your command shell does not get to the source file options, they
+are just included literally in the array of command-line arguments
+the compiler driver maintains internally, so you'll be desperately
+disappointed if you try to glob etc. inside \tr{OPTIONS}.
+
+It is not recommended to move all the contents of your Makefiles into
+your source files, but in some circumstances, the \tr{OPTIONS} pragma
+is the Right Thing.
+
+%----------------------------------------------------------------------
+%\subsubsection[arity-checking]{Options to insert arity-checking code}
+%\index{arity checking}
+%
+%The \tr{-darity-checks}\index{-darity-checks option} option inserts
+%code to check for arity violations.  Unfortunately, it's not that
+%simple: you have to link with a prelude that was also built with arity
+%checks.  If you have one, then great; otherwise...
+%
+%The \tr{-darity-checks-C-only}\index{-darity-checks-C-only option}
+%option inserts the self-same arity checking code into \tr{.hc} files,
+%but doesn't compile it into the \tr{.o} files.  We use this flag with
+%the \tr{-keep-hc-file-too}\index{-keep-hc-file-too option}, where we
+%are keeping \tr{.hc} files around for debugging purposes.
+
+%----------------------------------------------------------------------
+%\subsubsection[omit-checking]{Options to omit checking code}
+%\index{omitting runtime checks}
+%
+%By default, the GHC system emits all possible not-too-expensive
+%runtime checking code.  If you are brave or experimenting, you might
+%want to turn off some of this (not recommended):
+%
+%\begin{tabular}{ll}
+%-dno-black-holing & won't buy you much (even if it works) \\
+%-dno-updates & you're crazy if you do this \\
+%-dno-stk-stubbing & omit stack stubbing (NOT DONE YET) \\
+%\end{tabular}
+%\index{-dno-black-holing option}%
+%\index{-dno-updates option}%
+%\index{-dno-stk-stubbing option}
+%
+%Warning: all very lightly tested, if at all...

 
 %% %************************************************************************
 %% %*                                                                   *
 
 %% %************************************************************************
 %% %*                                                                   *