X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fusing.vsgml;fp=ghc%2Fdocs%2Fusers_guide%2Fusing.vsgml;h=0000000000000000000000000000000000000000;hb=a13f31cc8f8da4e71ee252dfcf838993a16e032f;hp=88d404ad2822d4c5a05e7f337d5beda25fd483b9;hpb=c7f8f1e62b555462f98c3f813440559116033a99;p=ghc-hetmet.git

diff --git a/ghc/docs/users_guide/using.vsgml b/ghc/docs/users_guide/using.vsgml
deleted file mode 100644
index 88d404a..0000000
--- a/ghc/docs/users_guide/using.vsgml
+++ /dev/null
@@ -1,1664 +0,0 @@
-<sect> Using GHC
-<label id="using-GHC">
-<p>
-<nidx>GHC, using</nidx>
-<nidx>using GHC</nidx>
-
-GHC is a command-line compiler: in order to compile a Haskell program,
-GHC must be invoked on the source file(s) by typing a command to the
-shell.  The steps involved in compiling a program can be automated
-using the @make@ tool (this is especially useful if the program
-consists of multiple source files which depend on each other).  This
-section describes how to use GHC from the command-line.
-
-%************************************************************************
-%*                                                                      *
-<sect1> Overall command-line structure
-<label id="command-line-structure">
-<p>
-<nidx>structure, command-line</nidx>
-<nidx>command-line structure</nidx>
-%*                                                                      *
-%************************************************************************
-
-An invocation of GHC takes the following form:
-
-<tscreen> <verb>
-ghc [argument...]
-</verb> </tscreen>
-
-Command-line arguments are either options or file names.
-
-Command-line options begin with @-@.  They may <em>not</em> be
-grouped: @-vO@ is different from @-v -O@.  Options need not
-precede filenames: e.g., @ghc *.o -o foo@.  All options are
-processed and then applied to all files; you cannot, for example, invoke
-@ghc -c -O1 Foo.hs -O2 Bar.hs@ to apply different optimisation
-levels to the files @Foo.hs@ and @Bar.hs@.  For conflicting
-options, e.g., @-c -S@, we reserve the right to do anything we
-want.  (Usually, the last one applies.)
-
-%************************************************************************
-%*                                                                      *
-<sect1>Meaningful file suffixes
-<label id="file-suffixes">
-<p>
-<nidx>suffixes, file</nidx>
-<nidx>file suffixes for GHC</nidx>
-%*                                                                      *
-%************************************************************************
-
-File names with ``meaningful'' suffixes (e.g., @.lhs@ or @.o@)
-cause the ``right thing'' to happen to those files.
-
-<descrip>
-<tag>@.lhs@:</tag>
-<nidx>lhs suffix</nidx>
-A ``literate Haskell'' module.
-
-<tag>@.hs@:</tag> 
-A not-so-literate Haskell module.
-
-<tag>@.hi@:</tag>
-A Haskell interface file, probably compiler-generated.
-
-<tag>@.hc@:</tag>
-Intermediate C file produced by the Haskell compiler.
-
-<tag>@.c@:</tag>
-A C~file not produced by the Haskell compiler.
-
-% <tag>@.i@:</tag>
-% C code after it has be preprocessed by the C compiler (using the
-% @-E@ flag).
-
-<tag>@.s@:</tag>
-An assembly-language source file, usually
-produced by the compiler.
-
-<tag>@.o@:</tag>
-An object file, produced by an assembler.
-</descrip>
-
-Files with other suffixes (or without suffixes) are passed straight
-to the linker.
-
-%************************************************************************
-%*                                                                      *
-<sect1>Help and verbosity options
-<label id="options-help">
-<p>
-<nidx>help options (GHC)</nidx>
-<nidx>verbose option (GHC)</nidx>
-%*                                                                      *
-%************************************************************************
-
-A good option to start with is the @-help@ (or @-?@) option.
-<nidx>-help option</nidx>
-<nidx>-? option</nidx>
-GHC spews a long message to standard output and then exits.
-
-The @-v@<nidx>-v option</nidx> option makes GHC <em>verbose</em>: it
-reports its version number and shows (on stderr) exactly how it invokes each 
-phase of the compilation system.  Moreover, it passes
-the @-v@ flag to most phases; each reports
-its version number (and possibly some other information).
-
-Please, oh please, use the @-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.
-
-If you're just interested in the compiler version number, the
-@--version@<nidx>--version option</nidx> option prints out a
-one-line string containing the requested info.
-
-%************************************************************************
-%*                                                                      *
-<sect1>Running the right phases in the right order
-<label id="options-order">
-<p>
-<nidx>order of passes in GHC</nidx>
-<nidx>pass ordering in GHC</nidx>
-%*                                                                      *
-%************************************************************************
-
-The basic task of the @ghc@ driver is to run each input file
-through the right phases (compiling, linking, etc.).
-
-The first phase to run is determined by the input-file suffix, and the
-last phase is determined by a flag.  If no relevant flag is present,
-then go all the way through linking.  This table summarises:
-
-<tabular ca="llll">
-Phase of the           | Suffix saying | Flag saying   | (suffix of) @@
-compilation system     | ``start here''| ``stop after''| output file @@
-@@
-literate pre-processor | .lhs          | -             | - @@
-C pre-processor (opt.) | -             | -             | - @@
-Haskell compiler       | .hs           | -C, -S        | .hc, .s @@
-C compiler (opt.)      | .hc or .c     | -S            | .s  @@
-assembler              | .s            | -c            | .o  @@
-linker                 | other         | -             | a.out @@
-</tabular>
-<nidx>-C option</nidx>
-<nidx>-S option</nidx>
-<nidx>-c option</nidx>
-
-Thus, a common invocation would be: @ghc -c Foo.hs@
-
-Note: What the Haskell compiler proper produces depends on whether a
-native-code generator is used (producing assembly language) or not
-(producing C).
-
-The option @-cpp@<nidx>-cpp option</nidx> must be given for the C
-pre-processor phase to be run, that is, the pre-processor will be run
-over your Haskell source file before continuing.
-
-The option @-E@<nidx>-E option</nidx> runs just the pre-processing
-passes of the compiler, outputting the result on stdout before
-stopping. If used in conjunction with -cpp, the output is the
-code blocks of the original (literal) source after having put it
-through the grinder that is the C pre-processor. Sans @-cpp@, the
-output is the de-litted version of the original source.
-
-The option @-optcpp-E@<nidx>-optcpp-E option</nidx> runs just the
-pre-processing stage of the C-compiling phase, sending the result to
-stdout.  (For debugging or obfuscation contests, usually.)
-
-%************************************************************************
-%*                                                                      *
-<sect1>Re-directing the compilation output(s)
-<label id="options-output">
-<p>
-<nidx>output-directing options</nidx>
-%*                                                                      *
-%************************************************************************
-
-GHC's compiled output normally goes into a @.hc@, @.o@, etc., file,
-depending on the last-run compilation phase.  The option @-o
-foo@<nidx>-o option</nidx> re-directs the output of that last-run
-phase to file @foo@.
-
-Note: this ``feature'' can be counterintuitive:
-@ghc -C -o foo.o foo.hs@ will put the intermediate C code in the
-file @foo.o@, name notwithstanding!
-
-EXOTICA: But the @-o@ option isn't of much use if you have
-<em>several</em> 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 @-odir <dir>@<nidx>-odir &lt;dir&gt; option</nidx> (the
-``Oh, dear'' option).  For example:
-
-<tscreen><verb>
-% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
-</verb></tscreen>
-
-The output files, @Foo.o@, @Bar.o@, and @Bumble.o@ would be
-put into a subdirectory named after the architecture of the executing
-machine (@sun4@, @mips@, etc).  The directory must already
-exist; it won't be created.
-
-Note that the @-odir@ option does <em>not</em> affect where the
-interface files are put.  In the above example, they would still be
-put in @parse/Foo.hi@, @parse/Bar.hi@, and @gurgle/Bumble.hi@.
-
-MORE EXOTICA: The @-osuf <suffix>@<nidx>-osuf &lt;suffix&gt;
-option</nidx> will change the @.o@ file suffix for object files to
-whatever you specify.  (We use this in compiling the prelude.).
-Similarly, the @-hisuf <suffix>@<nidx>-hisuf &lt;suffix&gt;
-option</nidx> will change the @.hi@ file suffix for non-system
-interface files (see Section <ref name="Other options related to
-interface files" id="hi-options">).
-
-The @-hisuf@/@-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 @.hi@/@.o@ suffixes; add @-hisuf g_hi -osuf g_o@ to your
-@make@ rule for GHC compiling...
-
-FURTHER EXOTICA: If you are doing a normal @.hs@-to-@.o@ compilation
-but would like to hang onto the intermediate @.hc@ C file, just
-throw in a @-keep-hc-file-too@ option<nidx>-keep-hc-file-too option</nidx>.
-If you would like to look at the assembler output, toss in a
-@-keep-s-file-too@,<nidx>-keep-s-file-too option</nidx> too.
-
-<sect2> Saving GHC's standard error output
-<label id="saving-ghc-stderr">
-<p>
-<nidx>standard error, saving</nidx>
-
-Sometimes, you may cause GHC to be rather chatty on standard error;
-with @-v@, for example.  You can instruct GHC to <em>append</em> this
-output to a particular log file with a @-odump <blah>@<nidx>-odump
-&lt;blah&gt; option</nidx> option.
-
-<sect2> Redirecting temporary files
-<label id="temp-files">
-<p>
-<nidx>temporary files, redirecting</nidx>
-
-If you have trouble because of running out of space in @/tmp@ (or
-wherever your installation thinks temporary files should go), you may
-use the @-tmpdir <dir>@<nidx>-tmpdir &lt;dir&gt; option</nidx> option
-to specify an alternate directory.  For example, @-tmpdir .@ says to
-put temporary files in the current working directory.
-
-Alternatively, use your @TMPDIR@ environment variable.<nidx>TMPDIR
-environment variable</nidx> Set it to the name of the directory where
-temporary files should be put.  GCC and other programs will honour the
-@TMPDIR@ variable as well.
-
-Even better idea: Set the @TMPDIR@ variable when building GHC, and
-never worry about @TMPDIR@ again. (see the build documentation).
-
-%************************************************************************
-%*                                                                      *
-<sect1>Warnings and sanity-checking
-<label id="options-sanity">
-<p>
-<nidx>sanity-checking options</nidx>
-<nidx>warnings</nidx>
-%*                                                                      *
-%************************************************************************
-
-GHC has a number of options that select which types of non-fatal error
-messages, otherwise known as warnings, can be generated during
-compilation.  By default, you get a standard set of warnings which are
-generally likely to indicate bugs in your program.  These are:
-@-fwarn-overlpapping-patterns@, @-fwarn-duplicate-exports@, and
-@-fwarn-missing-methods@.  The following flags are simple ways to
-select standard ``packages'' of warnings:
-
-<descrip>
-
-<tag>@-Wnot@:</tag>
-<nidx>-Wnot option</nidx>
-
-Turns off all warnings, including the standard ones.
-
-<tag>@-w@:</tag>
-<nidx>-w option</nidx>
-
-Synonym for @-Wnot@.
-
-<tag>@-W@:</tag>
-<nidx>-W option</nidx>
-
-Provides the standard warnings plus @-fwarn-incomplete-patterns@,
-@-fwarn-unused-imports@ and @-fwarn-unused-binds@.
-
-<tag>@-Wall@:</tag>
-<nidx>-Wall option</nidx>
-
-Turns on all warning options.
-
-</descrip>
-
-The full set of warning options is described below.  To turn off any
-warning, simply give the corresponding @-fno-warn-...@ option on
-the command line.
-
-<descrip>
-
-<tag>@-fwarn-name-shadowing@:</tag> 
-<nidx>-fwarn-name-shadowing option</nidx>
-<nidx>shadowing, warning</nidx>
-
-This option causes a warning to be emitted whenever an inner-scope
-value has the same name as an outer-scope value, i.e. the inner value
-shadows the outer one.  This can catch typographical errors that turn
-into hard-to-find bugs, e.g., in the inadvertent cyclic definition
-@let x = ... x ... in@.
-
-Consequently, this option does <em>not</em> allow cyclic recursive
-definitions.
-
-<tag>@-fwarn-overlapping-patterns@:</tag>
-<nidx>-fwarn-overlapping-patterns option</nidx>
-<nidx>overlapping patterns, warning</nidx>
-<nidx>patterns, overlapping</nidx>
-
-By default, the compiler will warn you if a set of patterns are
-overlapping, i.e.,
-
-<tscreen><verb>
-f :: String -> Int
-f []     = 0
-f (_:xs) = 1
-f "2"    = 2
-</verb></tscreen>
-
-where the last pattern match in @f@ won't ever be reached, as the
-second pattern overlaps it. More often than not, redundant patterns
-is a programmer mistake/error, so this option is enabled by default.
-
-<tag>@-fwarn-incomplete-patterns@:</tag>
-<nidx>-fwarn-incomplete-patterns option</nidx>
-<nidx>incomplete patterns, warning</nidx>
-<nidx>patterns, incomplete</nidx>
-
-Similarly for incomplete patterns, the function @g@ below will fail
-when applied to non-empty lists, so the compiler will emit a warning
-about this when @-fwarn-incomplete-patterns@ is enabled.
-
-<tscreen><verb>
-g [] = 2
-</verb></tscreen>
-
-This option isn't enabled be default because it can be a bit noisy,
-and it doesn't always indicate a bug in the program.  However, it's
-generally considered good practice to cover all the cases in your
-functions.
-
-<tag>@-fwarn-missing-methods@:</tag>
-<nidx>-fwarn-missing-methods option</nidx>
-<nidx>missing methods, warning</nidx>
-<nidx>methods, missing</nidx>
-
-This option is on by default, and warns you whenever an instance
-declaration is missing one or more methods, and the corresponding
-class declaration has no default declaration for them.
-
-<tag>@-fwarn-missing-fields@:</tag>
-<nidx>-fwarn-missing-fields option</nidx>
-<nidx>missing fields, warning</nidx>
-<nidx>fields, missing</nidx>
-
-This option is on by default, and warns you whenever the construction
-of a labelled field constructor isn't complete, missing initializers
-for one or more fields. While not an error (the missing fields are
-initialised with bottoms), it is often an indication of a programmer
-error.
-
-<tag>@-fwarn-unused-imports@:</tag>
-<nidx>-fwarn-unused-imports option</nidx>
-<nidx>unused imports, warning</nidx>
-<nidx>imports, unused</nidx>
-
-Report any objects that are explicitly imported but never used.
-
-<tag>@-fwarn-unused-binds@:</tag>
-<nidx>-fwarn-unused-binds option</nidx>
-<nidx>unused binds, warning</nidx>
-<nidx>binds, unused</nidx>
-
-Report any function definitions (and local bindings) which are unused.
-For top-level functions, the warning is only given if the binding is
-not exported.
-
-<tag>@-fwarn-unused-matches@:</tag>
-<nidx>-fwarn-unused-matches option</nidx>
-<nidx>unused matches, warning</nidx>
-<nidx>matches, unused</nidx>
-
-Report all unused variables which arise from pattern matches,
-including patterns consisting of a single variable.  For instance @f x
-y = []@ would report @x@ and @y@ as unused.  To eliminate the warning,
-all unused variables can be replaced with wildcards.
-
-<tag>@-fwarn-duplicate-exports@:</tag>
-<nidx>-fwarn-duplicate-exports option</nidx>
-<nidx>duplicate exports, warning</nidx>
-<nidx>export lists, duplicates</nidx>
-
-Have the compiler warn about duplicate entries in export lists. This
-is useful information if you maintain large export lists, and want to
-avoid the continued export of a definition after you've deleted (one)
-mention of it in the export list.
-
-This option is on by default.
-
-<tag><tt>-fwarn-type-defaults</tt>:</tag>
-<nidx>-fwarn-type-defaults option</nidx>
-<nidx>defaulting mechanism, warning</nidx>
-
-Have the compiler warn/inform you where in your source the Haskell
-defaulting mechanism for numeric types kicks in. This is useful
-information when converting code from a context that assumed one
-default into one with another, e.g., the 'default default' for Haskell
-1.4 caused the otherwise unconstrained value <tt>1</tt> to be given
-the type <tt>Int</tt>, whereas Haskell 98 defaults it to
-<tt>Integer</tt>.  This may lead to differences in performance and
-behaviour, hence the usefulness of being non-silent about this.
-
-This warning is off by default.
-
-<tag>@-fwarn-missing-signatures@:</tag>
-<nidx>-fwarn-missing-signatures option</nidx>
-<nidx>type signatures, missing</nidx>
-
-If you would like GHC to check that every top-level function/value has
-a type signature, use the @-fwarn-missing-signatures@ option.  This
-option is off by default.
-
-</descrip>
-
-If you're feeling really paranoid, the @-dcore-lint@
-option<nidx>-dcore-lint option</nidx> is a good choice.  It turns on
-heavyweight intra-pass sanity-checking within GHC.  (It checks GHC's
-sanity, not yours.)
-
-%************************************************************************
-%*                                                                      *
-<sect1>Separate compilation
-<label id="separate-compilation">
-<p>
-<nidx>separate compilation</nidx>
-<nidx>recompilation checker</nidx>
-<nidx>make and recompilation</nidx>
-%*                                                                      *
-%************************************************************************
-
-This section describes how GHC supports separate compilation.
-
-<sect2>Interface files
-<label id="hi-files">
-<p>
-<nidx>interface files</nidx>
-<nidx>.hi files</nidx>
-
-When GHC compiles a source file @F@ which contains a module @A@, say,
-it generates an object @F.o@, <em>and</em> a companion <em>interface
-file</em> @A.hi@.  The interface file is not intended for human
-consumption, as you'll see if you take a look at one.  It's merely
-there to help the compiler compile other modules in the same program.
-
-NOTE: <em>The name of the interface file is derived from the name
-of the module, not from the name of the file containing the module</em>.
-This means that GHC knows what to look for when it sees <tt>import A</tt>
-in another module.  However, having the name of the interface file follow the module name and
-not the file name, means that working with tools such as @make(1)@
-become harder. @make@ implicitly assumes that any output files
-produced by processing a translation unit will have file names that
-can be derived from the file name of the translation unit.  For
-instance, pattern rules becomes unusable.  For this reason, we
-recommend you stick to using the same file name as the module name.
-
-The interface file for @A@ contains information needed by the compiler
-when it compiles any module @B@ that imports @A@, whether directly or
-indirectly.  When compiling @B@, GHC will read @A.hi@ to find the
-details that it needs to know about things defined in @A@.
-
-Furthermore, when compiling module @C@ which imports @B@, GHC may
-decide that it needs to know something about @A@ --- for example, @B@
-might export a function that involves a type defined in @A@.  In this
-case, GHC will go and read @A.hi@ even though @C@ does not explicitly
-import @A@ at all.
-
-The interface file may contain all sorts of things that aren't
-explicitly exported from @A@ by the programmer.  For example, even
-though a data type is exported abstractly, @A.hi@ will contain the
-full data type definition.  For small function definitions, @A.hi@
-will contain the complete definition of the function.  For bigger
-functions, @A.hi@ will contain strictness information about the
-function.  And so on.  GHC puts much more information into @.hi@ files
-when optimisation is turned on with the @-O@ flag.  Without @-O@ it
-puts in just the minimum; with @-O@ it lobs in a whole pile of stuff.
-<nidx>optimsation, effect on .hi files</nidx>
-
-@A.hi@ should really be thought of as a compiler-readable version of
-@A.o@.  If you use a @.hi@ file that wasn't generated by the same
-compilation run that generates the @.o@ file the compiler may assume
-all sorts of incorrect things about @A@, resulting in core dumps and
-other unpleasant happenings.
-
-%************************************************************************
-%*                                                                      *
-<sect2>File names and module names
-<label id="files-and-modules">
-<p>
-%*                                                                      *
-%************************************************************************
-
-Typically, a module @Foo@ will be contained in a file called @Foo.hs@
-or @Foo.lhs@.  But GHC does not require that to be the case.  You can put a module
-named @Foo@ in a file named @SomethingElse@.  In this case, <em>GHC will still
-write an interface file @Foo.hi@</em>, but it will write an object fild
-@SomethingElse.o@.  Any module that imports @Foo@ will
-of course look for @Foo.hi@, and it will find it.
-
-A useful consequence is that you can have many files, @A.hs@, @B.hs@, etc, containing
-the module @Main@.  This is useful if you want to build distinct programs
-in the same directory.
-
-
-%************************************************************************
-%*                                                                      *
-<sect2>Finding interface files
-<label id="options-finding-imports">
-<p>
-<nidx>interface files, finding them</nidx>
-<nidx>finding interface files</nidx>
-%*                                                                      *
-%************************************************************************
-
-In your program, you import a module @Foo@ by saying
-@import Foo@.  GHC goes looking for an interface file, @Foo.hi@.
-It has a builtin list of directories (notably including @.@) where
-it looks.
-
-<descrip>
-
-<tag>@-i<dirs>@</tag><nidx>-i&lt;dirs&gt; option</nidx> This flag
-prepends a colon-separated list of @dirs@ to the ``import
-directories'' list.
-See also Section <ref id="recomp"> for the significance of using
-relative and absolute pathnames in the @-i@ list.
-
-<tag>@-i@</tag> resets the ``import directories'' list back to nothing.
-
-<tag>@-fno-implicit-prelude@</tag>
-<nidx>-fno-implicit-prelude option</nidx>
-GHC normally imports @Prelude.hi@ files for you.  If you'd rather it
-didn't, then give it a @-fno-implicit-prelude@ option.  You are
-unlikely to get very far without a Prelude, but, hey, it's a free
-country.
-
-<tag>@-syslib <lib>@</tag>
-<nidx>-syslib &lt;lib&gt; option</nidx>
-
-If you are using a system-supplied non-Prelude library (e.g., the
-POSIX library), just use a @-syslib posix@ option (for example).  The
-right interface files should then be available.  Section <ref
-name="The GHC Prelude and Libraries" id="ghc-prelude"> lists the
-libraries available by this mechanism.
-
-<tag>@-I<dir>@</tag>
-<nidx>-I&lt;dir&gt; option</nidx>
-
-Once a Haskell module has been compiled to C (@.hc@ file), you may
-wish to specify where GHC tells the C compiler to look for @.h@ files.
-(Or, if you are using the @-cpp@ option<nidx>-cpp option</nidx>, where
-it tells the C pre-processor to look...)  For this purpose, use a @-I@
-option in the usual C-ish way.
-
-</descrip>
-
-%************************************************************************
-%*                                                                      *
-<sect2>Other options related to interface files
-<label id="hi-options">
-<p>
-<nidx>interface files, options</nidx>
-%*                                                                      *
-%************************************************************************
-
-GHC supports some other more exotic command-line options related to interface files.
-Most programmers should never need to use any of them.
-
-<descrip>
-
-<tag>@-ohi@ <filename></tag> 
-<nidx>-ohi &lt;file&gt; option</nidx> 
-
-The interface output may be directed to another file
-@bar2/Wurble.iface@ with the option @-ohi bar2/Wurble.iface@
-(not recommended).
-
-<tag>@-nohi@</tag>
-<nidx>-nohi option</nidx>
-
-Don't generate an interface file at all.
-
-<tag>@-hi-diffs@, @-hi-diffs-with-usages@, @-keep-hi-diffs@</tag>
-<nidx>-hi-diffs option</nidx> 
-<nidx>-hi-diffs-with-usages option</nidx> 
-<nidx>-keep-hi-diffs option</nidx> 
-The compiler does not overwrite an existing @.hi@ interface file if
-the new one is byte-for-byte the same as the old one; this is friendly
-to @make@.  When an interface does change, it is often enlightening to
-be informed.  The @-hi-diffs@ option will
-make @ghc@ run @diff@ on the old and new @.hi@ files. You can also
-record the difference in the interface file itself, the
-@-keep-hi-diffs@<nidx>-keep-hi-diffs</nidx> option takes care of that.
-
-The @.hi@ files from GHC contain ``usage'' information which changes
-often and uninterestingly.  If you really want to see these changes
-reported, you need to use the
-@-hi-diffs-with-usages@<nidx>-hi-diffs-with-usages option</nidx>
-option.
-
-<tag>@-fignore-interface-pragmas@</tag>
-<nidx>-fignore-interface-pragmas option</nidx>
-
-Interface files are normally jammed full of compiler-produced
-<em>pragmas</em>, which record arities, strictness info, etc.  If you
-think these pragmas are messing you up (or you are doing some kind of
-weird experiment), you can tell GHC to ignore them with the
-@-fignore-interface-pragmas@ option.
-
-<tag>@-fno-prune-tydecls@</tag>
-<nidx>-fno-prune-tydecls option</nidx>
-When compiling without optimisations on, the compiler is extra-careful
-about not slurping in data constructors that it will not need. 
-The @-fno-prune-tydecls@ flag lets you turn this cleverness off; the reason
-is to allow us to measure the effect of the cleverness.   (In earlier versions
-of GHC there was a bug that meant you <em>had</em> to turn it off sometimes,
-but that is no longer true.)
-</descrip>
-
-See also Section <ref name="Linking and consistency-checking"
-id="options-linker">, which describes how the linker finds standard
-Haskell libraries.
-
-%************************************************************************
-%*                                                                      *
-<sect2>The recompilation checker
-<label id="recomp">
-<p>
-<nidx>recompilation checker</nidx>
-%*                                                                      *
-%************************************************************************
-
-In the olden days, GHC compared the newly-generated @.hi@ file with
-the previous version; if they were identical, it left the old one
-alone and didn't change its modification date.  In consequence,
-importers of a module with an unchanged output @.hi@ file were not
-recompiled.
-
-This doesn't work any more.  In our earlier example, module @C@ does
-not import module @A@ directly, yet changes to @A.hi@ should force a
-recompilation of @C@.  And some changes to @A@ (changing the
-definition of a function that appears in an inlining of a function
-exported by @B@, say) may conceivably not change @B.hi@ one jot.  So
-now...
-
-GHC keeps a version number on each interface file, and on each type
-signature within the interface file.  It also keeps in every interface
-file a list of the version numbers of everything it used when it last
-compiled the file.  If the source file's modification date is earlier
-than the @.o@ file's date (i.e. the source hasn't changed since the
-file was last compiled), GHC will be clever.  It compares the version
-numbers on the things it needs this time with the version numbers on
-the things it needed last time (gleaned from the interface file of the
-module being compiled); if they are all the same it stops compiling
-rather early in the process saying ``Compilation IS NOT required''.
-What a beautiful sight!
-
-GHC <em>only</em> keeps detailed dependency information for ``user'' modules,
-not for ``library'' modules.  It distinguishes the two by a hack: a module
-whose @.hi@ file has an absolute path name is considered a library module,
-while a relative path name indicates a user module.  So if you have a 
-multi-directory application, use <em>relative</em> path names in your
-@-i@ path, to force GHC to record detailed dependency information.
-Use absolute path names only for directories containing slowly-changing
-library modules.
-
-A path is considered ``absolute'' if it starts with ``@/@'', or
-``@A:/@'', or ``@A:\@'' (or ``@B:/@'', ``@B:\@'' etc).
-
-Patrick Sansom had a workshop paper about how all this is done (though
-the details have changed quite a bit).  Ask
-him (email: <htmlurl name="sansom@@dcs.gla.ac.uk"
-url="mailto:sansom@@dcs.gla.ac.uk">) if you want a copy.
-
-%************************************************************************
-%*                                                                      *
-<sect2>Using @make@
-<label id="using-make">
-<p>
-<ncdx>make</ncdx>
-%*                                                                      *
-%************************************************************************
-
-It is reasonably straightforward to set up a @Makefile@ to use with
-GHC, assuming you name your source files the same as your modules.
-Thus:
-
-<tscreen><verb>
-HC      = ghc
-HC_OPTS = -cpp $(EXTRA_HC_OPTS)
-
-SRCS = Main.lhs Foo.lhs Bar.lhs
-OBJS = Main.o   Foo.o   Bar.o
-
-.SUFFIXES : .o .hi .lhs .hc .s
-
-cool_pgm : $(OBJS)
-        rm $@
-        $(HC) -o $@ $(HC_OPTS) $(OBJS)
-
-# Standard suffix rules
-.o.hi:
-	@:
-
-.lhs.o:
-        $(HC) -c $< $(HC_OPTS)
-
-.hs.o:
-        $(HC) -c $< $(HC_OPTS)
-
-# Inter-module dependencies
-Foo.o Foo.hc Foo.s    : Baz.hi		# Foo imports Baz
-Main.o Main.hc Main.s : Foo.hi Baz.hi	# Main imports Foo and Baz
-</verb></tscreen>
-
-(Sophisticated @make@ variants may achieve some of the above more
-elegantly.  Notably, @gmake@'s pattern rules let you write the more
-comprehensible:
-
-<tscreen><verb>
-%.o : %.lhs
-        $(HC) -c $< $(HC_OPTS)
-</verb></tscreen>
-
-What we've shown should work with any @make@.)
-
-Note the cheesy @.o.hi@ rule: It records the dependency of the
-interface (@.hi@) file on the source.  The rule says a @.hi@ file can
-be made from a @.o@ file by doing... nothing.  Which is true.
-
-Note the inter-module dependencies at the end of the Makefile, which
-take the form
-
-<tscreen><verb>
-Foo.o Foo.hc Foo.s    : Baz.hi		# Foo imports Baz
-</verb></tscreen>
-
-They tell @make@ that if any of @Foo.o@, @Foo.hc@ or @Foo.s@ have an
-earlier modification date than @Baz.hi@, then the out-of-date file
-must be brought up to date.  To bring it up to date, @make@ looks for
-a rule to do so; one of the preceding suffix rules does the job
-nicely.
-
-Putting inter-dependencies of the form @Foo.o : Bar.hi@ into your
-@Makefile@ by hand is rather error-prone.  Don't worry---never fear,
-@mkdependHS@ is here! (and is distributed as part of GHC) Add the
-following to your @Makefile@:
-
-<tscreen><verb>
-depend :
-        mkdependHS -- $(HC_OPTS) -- $(SRCS)
-</verb></tscreen>
-
-Now, before you start compiling, and any time you change the @imports@
-in your program, do @make depend@ before you do @make cool_pgm@.
-@mkdependHS@ will append the needed dependencies to your @Makefile@.
-@mkdependHS@ is fully describe in Section <ref name="Makefile
-dependencies in Haskell: using mkdependHS" id="mkdependHS">.
-
-A few caveats about this simple scheme:
-
-<itemize>
-
-<item> You may need to compile some modules explicitly to create their
-interfaces in the first place (e.g., @make Bar.o@ to create @Bar.hi@).
-
-<item> You may have to type @make@ more than once for the dependencies
-to have full effect.  However, a @make@ run that does nothing
-<em>does</em> mean ``everything's up-to-date.''
-
-<item> This scheme will work with mutually-recursive modules but,
-again, it may take multiple iterations to ``settle.''
-
-</itemize>
-
-%************************************************************************
-%*                                                                      *
-<sect2>How to compile mutually recursive modules
-<label id="mutual-recursion">
-<p>
-<nidx>module system, recursion</nidx>
-<nidx>recursion, between modules</nidx>
-%*                                                                      *
-%************************************************************************
-
-Currently, the compiler does not have proper support for dealing with
-mutually recursive modules:
-
-<tscreen><verb>
-module A where
-
-import B
-
-newtype TA = MkTA Int
-
-f :: TB -> TA
-f (MkTB x) = MkTA x
---------
-module B where
-
-import A
-
-data TB = MkTB !Int
-
-g :: TA -> TB
-g (MkTA x) = MkTB x
-</verb></tscreen>
-
-When compiling either module A and B, the compiler will try (in vain)
-to look for the interface file of the other. So, to get mutually
-recursive modules off the ground, you need to hand write an interface
-file for A or B, so as to break the loop.  These hand-written
-interface files are called @hi-boot@ files, and are placed in a file
-called @<module>.hi-boot@.  To import from an @hi-boot@ file instead
-of the standard @.hi@ file, use the following syntax in the importing module:
-<nidx>hi-boot files</nidx>
-<nidx>importing, hi-boot files</nidx>
-
-<tscreen> <verb>
-import {-# SOURCE #-} A
-</verb> </tscreen>
-
-The hand-written interface need only contain the bare minimum of
-information needed to get the bootstrapping process started.  For
-example, it doesn't need to contain declarations for <em/everything/
-that module @A@ exports, only the things required by the module that
-imports @A@ recursively.
-
-For the example at hand, the boot interface file for A would look like
-the following:
-
-<tscreen><verb>
-__interface A 1 404 where
-__export A TA{MkTA} ;
-1 newtype TA = MkTA PrelBase.Int ;
-</verb></tscreen>
-
-The syntax is essentially the same as a normal @.hi@ file
-(unfortunately), but you can usually tailor an existing @.hi@ file to
-make a @.hi-boot@ file.
-
-Notice that we only put the declaration for the newtype @TA@ in the
-@hi-boot@ file, not the signature for @f@, since @f@ isn't used by
-@B@.
-
-The number ``1'' after ``__interface A'' gives the version number of module A;
-it is incremented whenever anything in A's interface file changes.  The ``404'' is
-the version number of the interface file <em>syntax</em>; we change it when
-we change the syntax of interface files so that you get a better error message when
-you try to read an old-format file with a new-format compiler.
-
-The number ``1'' at the beginning of a declaration is the <em>version
-number</em> of that declaration: for the purposes of @.hi-boot@ files
-these can all be set to 1.  All names must be fully qualified with the
-<em/original/ module that an object comes from: for example, the
-reference to @Int@ in the interface for @A@ comes from @PrelBase@,
-which is a module internal to GHC's prelude.  It's a pain, but that's
-the way it is.
-
-If you want an hi-boot file to export a data type, but you don't want to give its constructors
-(because the constructors aren't used by the SOURCE-importing module), you can write simply:
-
-<tscreen><verb>
-__interface A 1 404 where
-__export A TA;
-1 data TA
-</verb></tscreen>
-
-(You must write all the type parameters, but leave out the '=' and everything that follows it.)
-
-<bf>Note:</bf> This is all a temporary solution, a version of the
-compiler that handles mutually recursive properly without the manual
-construction of interface files, is (allegedly) in the works.
-
-%************************************************************************
-%*                                                                      *
-<sect1>Command line options in source files
-<label id="source-file-options">
-<p>
-<nidx>source-file options</nidx>
-%*                                                                      *
-%************************************************************************
-
-GHC expects its flags on the command line, but it is also possible
-to embed them in the Haskell module itself, using the  @OPTIONS@
-pragma <nidx>OPTIONS pragma</nidx>: 
-<tscreen><verb>
-  {-# OPTIONS -fglasgow-exts -fno-cpr-analyse #-}
-  module X where
-  
-  ...
-</verb></tscreen>
-@OPTIONS@ pragmas are only looked for at the top of your source
-files, upto the first (non-literate,non-empty) line not containing
-@OPTIONS@. Multiple @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 @OPTIONS@.
-
-The contents of @OPTIONS@ are prepended to the command-line
-options, so you *do* have the ability to override @OPTIONS@ settings
-via the command line.
-
-It is not recommended to move all the contents of your Makefiles into
-your source files, but in some circumstances, the @OPTIONS@ pragma
-is the Right Thing. (If you use @-keep-hc-file-too@ and have @OPTIONS@
-flags in your module, the @OPTIONS@ will get put into the generated .hc
-file).
-
-
-%************************************************************************
-%*                                                                      *
-<sect1>Optimisation (code improvement)
-<label id="options-optimise">
-<p>
-<nidx>optimisation (GHC)</nidx>
-<nidx>improvement, code (GHC)</nidx>
-%*                                                                      *
-%************************************************************************
-
-The @-O*@ options specify convenient ``packages'' of optimisation
-flags; the @-f*@ options described later on specify
-<em>individual</em> optimisations to be turned on/off; the @-m*@
-options specify <em>machine-specific</em> optimisations to be turned
-on/off.
-
-%----------------------------------------------------------------------
-<sect2>@-O*@: convenient ``packages'' of optimisation flags.
-<label id="optimise-pkgs">
-<p>
-<nidx>-O options</nidx>
-
-There are <em>many</em> options that affect the quality of code
-produced by GHC.  Most people only have a general goal, something like
-``Compile quickly'' or ``Make my program run like greased lightning.''
-The following ``packages'' of optimisations (or lack thereof) should
-suffice.
-
-Once you choose a @-O*@ ``package,'' stick with it---don't chop and
-change.  Modules' interfaces <em>will</em> change with a shift to a new
-@-O*@ option, and you may have to recompile a large chunk of all
-importing modules before your program can again be run
-safely (see Section <ref name="The recompilation checker" id="recomp">).
-
-<descrip>
-<tag>No @-O*@-type option specified:</tag>
-<nidx>-O* not specified</nidx>
-This is taken to mean: ``Please compile quickly; I'm not over-bothered
-about compiled-code quality.''  So, for example: @ghc -c Foo.hs@
-
-<tag>@-O@ or @-O1@:</tag>
-<nidx>-O option</nidx>
-<nidx>-O1 option</nidx>
-<nidx>optimise normally</nidx>
-Means: ``Generate good-quality code without taking too long about it.''
-Thus, for example: @ghc -c -O Main.lhs@
-
-<tag>@-O2@:</tag>
-<nidx>-O2 option</nidx>
-<nidx>optimise aggressively</nidx>
-Means: ``Apply every non-dangerous optimisation, even if it means
-significantly longer compile times.''
-
-The avoided ``dangerous'' optimisations are those that can make
-runtime or space <em>worse</em> if you're unlucky.  They are
-normally turned on or off individually.
-
-At the moment, @-O2@ is <em>unlikely</em> to produce
-better code than @-O@.
-
-<tag>@-O2-for-C@:</tag>
-<nidx>-O2-for-C option</nidx>
-<nidx>gcc, invoking with -O2</nidx>
-
-Says to run GCC with @-O2@, which may be worth a few percent in
-execution speed.  Don't forget @-fvia-C@, lest you use the native-code
-generator and bypass GCC altogether!
-
-<tag>@-Onot@:</tag>
-<nidx>-Onot option</nidx>
-<nidx>optimising, reset</nidx>
-
-This option will make GHC ``forget'' any @-O@ish options it has seen so
-far.  Sometimes useful; for example: @make all EXTRA_HC_OPTS=-Onot@.
-
-<tag>@-Ofile <file>@:</tag>
-<nidx>-Ofile &lt;file&gt; option</nidx>
-<nidx>optimising, customised</nidx>
-
-For those who need <em>absolute</em> control over <em>exactly</em>
-what options are used (e.g., compiler writers, sometimes :-), a list
-of options can be put in a file and then slurped in with @-Ofile@.
-
-In that file, comments are of the @#@-to-end-of-line variety; blank
-lines and most whitespace is ignored.
-
-Please ask if you are baffled and would like an example of @-Ofile@!
-</descrip>
-
-At Glasgow, we don't use a @-O*@ flag for day-to-day work.  We use
-@-O@ to get respectable speed; e.g., when we want to measure
-something.  When we want to go for broke, we tend to use @-O -fvia-C
--O2-for-C@ (and we go for lots of coffee breaks).
-
-The easiest way to see what @-O@ (etc.) ``really mean'' is to run with
-@-v@, then stand back in amazement.  Alternatively, just look at the
-@HsC_minus<blah>@ lists in the @ghc@ driver script.
-
-%----------------------------------------------------------------------
-<sect2>@-f*@: platform-independent flags
-<p>
-<nidx>-f* options (GHC)</nidx>
-<nidx>-fno-* options (GHC)</nidx>
-
-Flags can be turned <em>off</em> individually.  (NB: I hope you have a
-good reason for doing this....) To turn off the @-ffoo@ flag, just use
-the @-fno-foo@ flag.<nidx>-fno-&lt;opt&gt; anti-option</nidx> So, for
-example, you can say @-O2 -fno-strictness@, which will then drop out
-any running of the strictness analyser.
-
-The options you are most likely to want to turn off are:
-<itemize>
-<item>
-@-fno-strictness@<nidx>-fno-strictness option</nidx> (strictness
-analyser, because it is sometimes slow),
-<item>
-@-fno-specialise@<nidx>-fno-specialise option</nidx> (automatic
-specialisation of overloaded functions, because it can make your code
-bigger) (US spelling also accepted), and
-<item>
-@-fno-cpr-analyse@<nidx>-fno-cpr-analyse option</nidx> switches off the CPR (constructed product
-result) analyser.
-</itemize>
-
-Should you wish to turn individual flags <em>on</em>, you are advised
-to use the @-Ofile@ option, described above.  Because the order in
-which optimisation passes are run is sometimes crucial, it's quite
-hard to do with command-line options.
-
-Here are some ``dangerous'' optimisations you <em>might</em> want to try:
-<descrip>
-%------------------------------------------------------------------
-<tag>@-fvia-C@:</tag>
-<nidx>-fvia-C option</nidx>
-<nidx>native code generator, turning off</nidx>
-
-Compile via C, and don't use the native-code generator.  (There are
-many cases when GHC does this on its own.)  You might pick up a little
-bit of speed by compiling via C.  If you use @_ccall_gc_@s or
-@_casm_@s, you probably <em>have to</em> use @-fvia-C@.
-
-The lower-case incantation, @-fvia-c@, is synonymous.
-
-Compiling via C will probably be slower (in compilation time) than
-using GHC's native code generator.
-
-<tag>@-funfolding-interface-threshold<n>@:</tag>
-<nidx>-funfolding-interface-threshold option</nidx>
-<nidx>inlining, controlling</nidx>
-<nidx>unfolding, controlling</nidx>
-(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 function would be assigned a bigger cost.)
-
-<tag>@-funfolding-creation-threshold<n>@:</tag>
-<nidx>-funfolding-creation-threshold option</nidx>
-<nidx>inlining, controlling</nidx>
-<nidx>unfolding, controlling</nidx>
-(Default: 30) This option is similar to
-@-funfolding-interface-threshold@, except that it governs unfoldings
-within a single module.  Increasing this figure is more likely to
-result in longer compile times than faster code.  The next option is
-more useful:
-
-<tag>@-funfolding-use-threshold<n>@:</tag>
-<nidx>-funfolding-use-threshold option</nidx>
-<nidx>inlining, controlling</nidx>
-<nidx>unfolding, controlling</nidx>
-(Default: 8) This is the magic cut-off figure for unfolding: below
-this size, a function definition will be unfolded at the call-site,
-any bigger and it won't.  The size computed for a function depends on
-two things: the actual size of the expression minus any discounts that
-apply (see @-funfolding-con-discount@).
-
-<tag>@-funfolding-con-discount<n>@:</tag>
-<nidx>-funfolding-con-discount option</nidx>
-<nidx>inlining, controlling</nidx>
-<nidx>unfolding, controlling</nidx>
-(Default: 2) If the compiler decides that it can eliminate some
-computation by performing an unfolding, then this is a discount factor
-that it applies to the funciton size before deciding whether to unfold
-it or not.
-
-OK, folks, these magic numbers `30', `8', and '2' are mildly
-arbitrary; they are of the ``seem to be OK'' variety.  The `8' is the
-more critical one; it's what determines how eager GHC is about
-expanding unfoldings.
-
-<tag>@-funbox-strict-fields@:</tag>
-<nidx>-funbox-strict-fields option</nidx>
-<nidx>strict constructor fields</nidx>
-<nidx>constructor fields, strict</nidx>
-
-This option causes all constructor fields which are marked strict
-(i.e. ``!'') to be unboxed or unpacked if possible.  For example:
-
-<tscreen><verb>
-data T = T !Float !Float
-</verb></tscreen>
-
-will create a constructor @T@ containing two unboxed floats if the
-@-funbox-strict-fields@ flag is given.  This may not always be an
-optimisation: if the @T@ constructor is scrutinised and the floats
-passed to a non-strict function for example, they will have to be
-reboxed (this is done automatically by the compiler).
-
-This option should only be used in conjunction with @-O@, in order to
-expose unfoldings to the compiler so the reboxing can be removed as
-often as possible.  For example:
-
-<tscreen><verb>
-f :: T -> Float
-f (T f1 f2) = f1 + f2
-</verb></tscreen>
-
-The compiler will avoid reboxing @f1@ and @f2@ by inlining @+@ on
-floats, but only when @-O@ is on.
-
-Any single-constructor data is eligible for unpacking; for example
-
-<tscreen><verb>
-data T = T !(Int,Int)
-</verb></tscreen>
-
-will store the two @Int@s directly in the @T@ constructor, by flattening
-the pair.  Multi-level unpacking is also supported:
-
-<tscreen><verb>
-data T = T !S
-data S = S !Int !Int
-</verb></tscreen>
-
-will store two unboxed @Int#@s directly in the @T@ constructor.
-
-<tag>@-fsemi-tagging@:</tag>
-This option (which <em>does not work</em> with the native-code generator)
-tells the compiler to add extra code to test for already-evaluated
-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 @-fsemi-tagging@ enough to recommend it.
-(For all we know, it doesn't even work anymore...  Sigh.)
-</descrip>
-
-%----------------------------------------------------------------------
-<sect2>@-m*@: platform-specific flags
-<p>
-<nidx>-m* options (GHC)</nidx>
-<nidx>platform-specific options</nidx>
-<nidx>machine-specific options</nidx>
-
-Some flags only make sense for particular target platforms.
-
-<descrip>
-<tag>@-mv8@:</tag>
-(SPARC machines)<nidx>-mv8 option (SPARC only)</nidx>
-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 @-m*@ GCC options for SPARC also work, actually.
-
-<tag>@-mlong-calls@:</tag>
-(HPPA machines)<nidx>-mlong-calls option (HPPA only)</nidx>
-Means to pass the like-named option to GCC.  Required for Very Big
-modules, maybe.  (Probably means you're in trouble...)
-
-<tag>@-monly-[32]-regs@:</tag>
-(iX86 machines)<nidx>-monly-N-regs option (iX86 only)</nidx>
-GHC tries to ``steal'' four registers from GCC, for performance
-reasons; it almost always works.  However, when GCC is compiling some
-modules with four stolen registers, it will crash, probably saying:
-<tscreen><verb>
-Foo.hc:533: fixed or forbidden register was spilled.
-This may be due to a compiler bug or to impossible asm
-statements or clauses.
-</verb></tscreen>
-Just give some registers back with @-monly-N-regs@.  Try `3' first,
-then `2'.  If `2' doesn't work, please report the bug to us.
-</descrip>
-
-%----------------------------------------------------------------------
-<sect2>Code improvement by the C compiler.
-<label id="optimise-C-compiler">
-<p>
-<nidx>optimisation by GCC</nidx>
-<nidx>GCC optimisation</nidx>
-
-The C~compiler (GCC) is run with @-O@ turned on.  (It has
-to be, actually).
-
-If you want to run GCC with @-O2@---which may be worth a few
-percent in execution speed---you can give a
-@-O2-for-C@<nidx>-O2-for-C option</nidx> option.
-
-%************************************************************************
-%*                                                                      *
-<sect1>Options related to a particular phase
-<label id="options-phases">
-<p>
-%*                                                                      *
-%************************************************************************
-
-<sect2> The C pre-processor
-<label id="c-pre-processor">
-<p>
-<nidx>pre-processing: cpp</nidx>
-<nidx>C pre-processor options</nidx>
-<nidx>cpp, pre-processing with</nidx>
-
-The C pre-processor @cpp@ is run over your Haskell code only if the
-@-cpp@ option <nidx>-cpp option</nidx> is given.  Unless you are
-building a large system with significant doses of conditional
-compilation, you really shouldn't need it.
-<descrip>
-<tag>@-D<foo>@:</tag>
-<nidx>-D&lt;name&gt; option</nidx>
-Define macro @<foo>@ in the usual way.  NB: does <em>not</em> affect
-@-D@ macros passed to the C~compiler when compiling via C!  For those,
-use the @-optc-Dfoo@ hack... (see Section <ref name="Forcing options
-to a particular phase." id="forcing-options-through">).
-
-<tag>@-U<foo>@:</tag>
-<nidx>-U&lt;name&gt; option</nidx>
-Undefine macro @<foo>@ in the usual way.
-
-<tag>@-I<dir>@:</tag>
-<nidx>-I&lt;dir&gt; option</nidx>
-Specify a directory in which to look for @#include@ files, in
-the usual C way.
-</descrip>
-
-The @ghc@ driver pre-defines several macros when processing Haskell
-source code (@.hs@ or @.lhs@ files):
-
-<descrip>
-<tag>@__HASKELL98__@:</tag>
-<nidx>__HASKELL98__</nidx>
-If defined, this means that GHC supports the language defined by the
-Haskell 98 report.
-
-<tag>@__HASKELL__=98@:</tag>
-<nidx>__HASKELL__</nidx>
-In GHC 4.04 and later, the @__HASKELL__@ macro is defined as having
-the value @98@.
-
-<tag>@__HASKELL1__@:</tag>
-<nidx>__HASKELL1__ macro</nidx>
-If defined to <em/n/, that means GHC supports the Haskell language
-defined in the Haskell report version <em/1.n/.  Currently 5.  This
-macro is deprecated, and will probably disappear in future versions.
-
-<tag>@__GLASGOW_HASKELL__@:</tag>
-<nidx>__GLASGOW_HASKELL__ macro</nidx>
-For version <em/n/ of the GHC system, this will be @#define@d to
-<em/100n/.  So, for version 4.00, it is 400.
-
-With any luck, @__GLASGOW_HASKELL__@ will be undefined in all other
-implementations that support C-style pre-processing.
-
-(For reference: the comparable symbols for other systems are:
-@__HUGS__@ for Hugs and @__HBC__@ for Chalmers.)
-
-NB. This macro is set when pre-processing both Haskell source and C
-source, including the C source generated from a Haskell module
-(ie. @.hs@, @.lhs@, @.c@ and @.hc@ files).
-
-<tag>@__CONCURRENT_HASKELL__@:</tag>
-<nidx>__CONCURRENT_HASKELL__ macro</nidx>
-This symbol is defined when pre-processing Haskell (input) and
-pre-processing C (GHC output).  Since GHC from verion 4.00 now
-supports concurrent haskell by default, this symbol is always defined.
-
-<tag>@__PARALLEL_HASKELL__@:</tag>
-<nidx>__PARALLEL_HASKELL__ macro</nidx>
-Only defined when @-parallel@ is in use!  This symbol is defined when
-pre-processing Haskell (input) and pre-processing C (GHC output).
-</descrip>
-
-Options other than the above can be forced through to the C
-pre-processor with the @-opt@ flags (see
-Section <ref name="Forcing options to a particular phase." id="forcing-options-through">).
-
-A small word of warning: @-cpp@ is not friendly to ``string
-gaps''.<nidx>-cpp vs string gaps</nidx><nidx>string gaps vs
--cpp</nidx>.  In other words, strings such as the following:
-
-<tscreen><verb>
-	strmod = "\
-	\ p \
-	\ "
-</verb></tscreen>
-
-don't work with @-cpp@; @/usr/bin/cpp@ elides the
-backslash-newline pairs.
-
-However, it appears that if you add a space at the end of the line,
-then @cpp@ (at least GNU @cpp@ and possibly other @cpp@s)
-leaves the backslash-space pairs alone and the string gap works as
-expected.
-
-%************************************************************************
-%*                                                                      *
-<sect2>Options affecting the C compiler (if applicable)
-<label id="options-C-compiler">
-<p>
-<nidx>include-file options</nidx>
-<nidx>C compiler options</nidx>
-<nidx>GCC options</nidx>
-%*                                                                      *
-%************************************************************************
-
-At the moment, quite a few common C-compiler options are passed on
-quietly to the C compilation of Haskell-compiler-generated C files.
-THIS MAY CHANGE.  Meanwhile, options so sent are:
-
-<tabular ca="ll">
-@-ansi@      | do ANSI C (not K&amp;R) @@
-@-pedantic@  | be so@@
-@-dgcc-lint@ | (hack) short for ``make GCC very paranoid''@@
-</tabular>
-<nidx>-ansi option (for GCC)</nidx>
-<nidx>-pedantic option (for GCC)</nidx>
-<nidx>-dgcc-lint option (GCC paranoia)</nidx>
-
-If you are compiling with lots of @ccalls@, etc., you may need to
-tell the C~compiler about some @#include@ files.  There is no real
-pretty way to do this, but you can use this hack from the
-command-line:
-
-<tscreen><verb>
-% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
-</verb></tscreen>
-
-
-%************************************************************************
-%*                                                                      *
-<sect2>Linking and consistency-checking
-<label id="options-linker">
-<p>
-<nidx>linker options</nidx>
-<nidx>ld options</nidx>
-%*                                                                      *
-%************************************************************************
-
-GHC has to link your code with various libraries, possibly including:
-user-supplied, GHC-supplied, and system-supplied (@-lm@ math
-library, for example).
-
-<descrip>
-<tag>@-l<FOO>@:</tag>
-<nidx>-l&lt;lib&gt; option</nidx>
-Link in a library named @lib<FOO>.a@ which resides somewhere on the
-library directories path.
-
-Because of the sad state of most UNIX linkers, the order of such
-options does matter.  Thus: @ghc -lbar *.o@ is almost certainly
-wrong, because it will search @libbar.a@ <em>before</em> it has
-collected unresolved symbols from the @*.o@ files.
-@ghc *.o -lbar@ is probably better.
-
-The linker will of course be informed about some GHC-supplied
-libraries automatically; these are:
-
-<tabular ca="ll">
-<bf>-l equivalent</bf> | <bf>description</bf> @@
-@@
-@-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)@@
-</tabular>
-
-<nidx>-lHS library</nidx>
-<nidx>-lHS_cbits library</nidx>
-<nidx>-lHSrts library</nidx>
-<nidx>-lgmp library</nidx>
-
-<tag>@-syslib <name>@:</tag>
-<nidx>-syslib &lt;name&gt; option</nidx>
-
-If you are using a Haskell ``system library'' (e.g., the POSIX
-library), just use the @-syslib posix@ option, and the correct code
-should be linked in.
-
-<tag>@-L<dir>@:</tag>
-<nidx>-L&lt;dir&gt; option</nidx>
-Where to find user-supplied libraries...  Prepend the directory
-@<dir>@ to the library directories path.
-
-<tag>@-static@:</tag>
-<nidx>-static option</nidx>
-Tell the linker to avoid shared libraries.
-
-<tag>@-no-link-chk@ and @-link-chk@:</tag>
-<nidx>-no-link-chk option</nidx>
-<nidx>-link-chk option</nidx>
-<nidx>consistency checking of executables</nidx>
-By default, immediately after linking an executable, GHC verifies that
-the pieces that went into it were compiled with compatible flags; a
-``consistency check''.
-(This is to avoid mysterious failures caused by non-meshing of
-incompatibly-compiled programs; e.g., if one @.o@ file was compiled
-for a parallel machine and the others weren't.)  You may turn off this
-check with @-no-link-chk@.  You can turn it (back) on with
-@-link-chk@ (the default).
-
-<tag><tt>-no-hs-main</tt>:</tag>
-<nidx>-no-hs-main option</nidx>
-<nidx>linking Haskell libraries with foreign code</nidx>
-
-In the event you want to include ghc-compiled code as part of another
-(non-Haskell) program, the RTS will not be supplying its definition of
-<tt/main()/ at link-time, you will have to. To signal that to the
-driver script when linking, use <tt/-no-hs-main/.
-
-Notice that since the command-line passed to the linker is rather
-involved, you probably want to use the ghc driver script to do the
-final link of your `mixed-language' application. This is not a
-requirement though, just try linking once with <tt/-v/ on to see what
-options the driver passes through to the linker.
-
-</descrip>
-
-%************************************************************************
-%*                                                                      *
-<sect1>Using Concurrent Haskell
-<p>
-<nidx>Concurrent Haskell---use</nidx>
-%*                                                                      *
-%************************************************************************
-
-GHC (as of version 4.00) supports Concurrent Haskell by default,
-without requiring a special option or libraries compiled in a certain
-way.  To get access to the support libraries for Concurrent Haskell
-(ie. @Concurrent@ and friends), use the @-syslib concurrent@ option.
-
-Three RTS options are provided for modifying the behaviour of the
-threaded runtime system.  See the descriptions of @-C[<us>]@, @-q@,
-and @-t<num>@ in Section <ref name="RTS options for
-Concurrent/Parallel Haskell" id="parallel-rts-opts">.
-
-Concurrent Haskell is described in more detail in Section <ref
-name="Concurrent and Parallel Haskell" id="concurrent-and-parallel">.
-
-%************************************************************************
-%*                                                                      *
-<sect1>Using Parallel Haskell
-<p>
-<nidx>Parallel Haskell---use</nidx>
-%*                                                                      *
-%************************************************************************
-
-[You won't be able to execute parallel Haskell programs unless PVM3
-(Parallel Virtual Machine, version 3) is installed at your site.]
-
-To compile a Haskell program for parallel execution under PVM, use the
-@-parallel@ option,<nidx>-parallel option</nidx> both when compiling
-<em>and linking</em>.  You will probably want to @import Parallel@
-into your Haskell modules.
-
-To run your parallel program, once PVM is going, just invoke it ``as
-normal''.  The main extra RTS option is @-N<n>@, to say how many
-PVM ``processors'' your program to run on.  (For more details of
-all relevant RTS options, please see Section <ref name="RTS options for Concurrent/Parallel Haskell" id="parallel-rts-opts">.)
-
-In truth, running Parallel Haskell programs and getting information
-out of them (e.g., parallelism profiles) is a battle with the vagaries of
-PVM, detailed in the following sections.
-
-%************************************************************************
-%*                                                                      *
-<sect2>Dummy's guide to using PVM
-<p>
-<nidx>PVM, how to use</nidx>
-<nidx>Parallel Haskell---PVM use</nidx>
-%*                                                                      *
-%************************************************************************
-
-Before you can run a parallel program under PVM, you must set the
-required environment variables (PVM's idea, not ours); something like,
-probably in your @.cshrc@ or equivalent:
-<tscreen><verb>
-setenv PVM_ROOT /wherever/you/put/it
-setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
-setenv PVM_DPATH $PVM_ROOT/lib/pvmd
-</verb></tscreen>
-
-Creating and/or controlling your ``parallel machine'' is a purely-PVM
-business; nothing specific to Parallel Haskell.
-
-You use the @pvm@<nidx>pvm command</nidx> command to start PVM on your
-machine.  You can then do various things to control/monitor your
-``parallel machine;'' the most useful being:
-
-\begin{tabular}{ll}
-@Control-D@ & exit @pvm@, leaving it running \\
-@halt@ & kill off this ``parallel machine'' \& exit \\
-@add <host>@ & add @<host>@ as a processor \\
-@delete <host>@ & delete @<host>@ \\
-@reset@	& kill what's going, but leave PVM up \\
-@conf@       & list the current configuration \\
-@ps@         & report processes' status \\
-@pstat <pid>@ & status of a particular process \\
-\end{tabular}
-
-The PVM documentation can tell you much, much more about @pvm@!
-
-%************************************************************************
-%*                                                                      *
-<sect2>Parallelism profiles
-<p>
-<nidx>parallelism profiles</nidx>
-<nidx>profiles, parallelism</nidx>
-<nidx>visualisation tools</nidx>
-%*                                                                      *
-%************************************************************************
-
-With Parallel Haskell programs, we usually don't care about the
-results---only with ``how parallel'' it was!  We want pretty pictures.
-
-Parallelism profiles (\`a la @hbcpp@) can be generated with the
-@-q@<nidx>-q RTS option (concurrent, parallel)</nidx> RTS option.  The
-per-processor profiling info is dumped into files named
-@<full-path><program>.gr@.  These are then munged into a PostScript picture,
-which you can then display.  For example, to run your program
-@a.out@ on 8 processors, then view the parallelism profile, do:
-
-<tscreen><verb>
-% ./a.out +RTS -N8 -q
-% grs2gr *.???.gr > temp.gr	# combine the 8 .gr files into one
-% gr2ps -O temp.gr		# cvt to .ps; output in temp.ps
-% ghostview -seascape temp.ps	# look at it!
-</verb></tscreen>
-
-The scripts for processing the parallelism profiles are distributed
-in @ghc/utils/parallel/@.
-
-%************************************************************************
-%*                                                                      *
-<sect2>Other useful info about running parallel programs
-<p>
-%*                                                                      *
-%************************************************************************
-
-The ``garbage-collection statistics'' RTS options can be useful for
-seeing what parallel programs are doing.  If you do either
-@+RTS -Sstderr@<nidx>-Sstderr RTS option</nidx> or @+RTS -sstderr@, then
-you'll get mutator, garbage-collection, etc., times on standard
-error. The standard error of all PE's other than the `main thread'
-appears in @/tmp/pvml.nnn@, courtesy of PVM.
-
-Whether doing @+RTS -Sstderr@ or not, a handy way to watch
-what's happening overall is: @tail -f /tmp/pvml.nnn@.
-
-%************************************************************************
-%*                                                                      *
-<sect2>RTS options for Concurrent/Parallel Haskell
-<label id="parallel-rts-opts">
-<p>
-<nidx>RTS options, concurrent</nidx>
-<nidx>RTS options, parallel</nidx>
-<nidx>Concurrent Haskell---RTS options</nidx>
-<nidx>Parallel Haskell---RTS options</nidx>
-%*                                                                      *
-%************************************************************************
-
-Besides the usual runtime system (RTS) options
-(Section <ref name="Running a compiled program" id="runtime-control">), there are a few options particularly
-for concurrent/parallel execution.
-
-<descrip>
-<tag>@-N<N>@:</tag>
-<nidx>-N&lt;N&gt; RTS option (parallel)</nidx>
-(PARALLEL ONLY) Use @<N>@ PVM processors to run this program;
-the default is 2.
-
-<tag>@-C[<us>]@:</tag>
-<nidx>-C&lt;us&gt; RTS option</nidx>
-Sets the context switch interval to @<us>@ microseconds.  A context
-switch will occur at the next heap allocation after the timer expires.
-With @-C0@ or @-C@, context switches will occur as often as
-possible (at every heap allocation).  By default, context switches
-occur every 10 milliseconds.  Note that many interval timers are only
-capable of 10 millisecond granularity, so the default setting may be
-the finest granularity possible, short of a context switch at every
-heap allocation.
-
-[NOTE: this option currently has no effect (version 4.00).  Context
-switches happen when the current heap block is full, i.e. every 4k of
-allocation].
-
-<tag>@-q[v]@:</tag>
-<nidx>-q RTS option</nidx>
-(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
-in the file @<program>.qp@.  In the style of @hbcpp@, this profile
-records the movement of threads between the green (runnable) and red
-(blocked) queues.  If you specify the verbose suboption (@-qv@), the
-green queue is split into green (for the currently running thread
-only) and amber (for other runnable threads).  We do not recommend
-that you use the verbose suboption if you are planning to use the
-@hbcpp@ profiling tools or if you are context switching at every heap
-check (with @-C@).
-
-<tag>@-t<num>@:</tag>
-<nidx>-t&lt;num&gt; RTS option</nidx>
-(PARALLEL ONLY) Limit the number of concurrent threads per processor
-to @<num>@.  The default is 32.  Each thread requires slightly over 1K
-<em>words</em> in the heap for thread state and stack objects.  (For
-32-bit machines, this translates to 4K bytes, and for 64-bit machines,
-8K bytes.)
-
-<tag>@-d@:</tag>
-<nidx>-d RTS option (parallel)</nidx>
-(PARALLEL ONLY) Turn on debugging.  It pops up one xterm (or GDB, or
-something...) per PVM processor.  We use the standard @debugger@
-script that comes with PVM3, but we sometimes meddle with the
-@debugger2@ script.  We include ours in the GHC distribution,
-in @ghc/utils/pvm/@.
-
-<tag>@-e<num>@:</tag>
-<nidx>-e&lt;num&gt; RTS option (parallel)</nidx>
-(PARALLEL ONLY) Limit the number of pending sparks per processor to
-@<num>@. The default is 100. A larger number may be appropriate if
-your program generates large amounts of parallelism initially.
-
-<tag>@-Q<num>@:</tag>
-<nidx>-Q&lt;num&gt; RTS option (parallel)</nidx>
-(PARALLEL ONLY) Set the size of packets transmitted between processors
-to @<num>@. The default is 1024 words. A larger number may be
-appropriate if your machine has a high communication cost relative to
-computation speed.
-</descrip>