+++ /dev/null
-\section[invoking-GHC]{Invoking GHC: Command-line options}
-\index{command-line options}
-\index{options, GHC command-line}
-
-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 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.,
-unboxed values), Concurrent and Parallel Haskell are described in
-\sectionref{profiling}, \sectionref{glasgow-exts}, and
-\sectionref{concurrent-and-parallel}, respectively.
-
-%************************************************************************
-%* *
-\subsection[file-suffixes]{Meaningful file suffixes}
-\index{suffixes, file}
-\index{file suffixes for GHC}
-%* *
-%************************************************************************
-
-File names with ``meaningful'' suffixes (e.g., \tr{.lhs} or \tr{.o})
-cause the ``right thing'' to happen to those files.
-
-\begin{description}
-\item[\tr{.lhs}:]
-\index{lhs suffix@.lhs suffix}
-A ``literate Haskell'' module.
-
-\item[\tr{.hs}:]
-A not-so-literate Haskell module.
-
-\item[\tr{.hi}:]
-A Haskell interface file, probably compiler-generated.
-
-\item[\tr{.hc}:]
-Intermediate C file produced by the Haskell compiler.
-
-\item[\tr{.c}:]
-A C~file not produced by the Haskell compiler.
-
-% \item[\tr{.i}:]
-% C code after it has be preprocessed by the C compiler (using the
-% \tr{-E} flag).
-
-\item[\tr{.s}:]
-An assembly-language source file, usually
-produced by the compiler.
-
-\item[\tr{.o}:]
-An object file, produced by an assembler.
-\end{description}
-
-Files with other suffixes (or without suffixes) are passed straight
-to the linker.
-
-%************************************************************************
-%* *
-\subsection[options-help]{Help and verbosity options}
-\index{help options (GHC)}
-\index{verbose option (GHC)}
-%* *
-%************************************************************************
-
-A good option to start with is the \tr{-help} (or \tr{-?}) option.
-\index{-help option}
-\index{-? option}
-GHC spews a long message to standard output and then exits.
-
-The \tr{-v}\index{-v option} option makes GHC {\em verbose}: it
-reports its version number and shows (on stderr) exactly how it invokes each
-phase of the compilation system. Moreover, it passes
-the \tr{-v} flag to most phases; each reports
-its version number (and possibly some other information).
-
-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.
-
-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}
-\index{order of passes in GHC}
-\index{pass ordering in GHC}
-%* *
-%************************************************************************
-
-The basic task of the \tr{ghc} driver is to run each input file
-through the right phases (parsing, 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:
-
-\begin{tabular}{llll}
-phase of the & suffix saying & flag saying & (suffix of) \\
-compilation system & ``start here''& ``stop after''& output file \\ \hline
-
-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 \\
-\end{tabular}
-\index{-C option}
-\index{-S option}
-\index{-c option}
-
-Thus, a common invocation would be: \tr{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 suffix information may be overridden with a \tr{-lang <suf>}
-%\index{-lang <suf> option} option. This says: process all inputs
-%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, 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 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 \tr{-cpp}, the
-output is the de-litted version of the original source.
-
-The option \tr{-optcpp-E}\index{-optcpp-E option} runs just the
-pre-processing stage of the C-compiling phase, sending the result to
-stdout. (For debugging or obfuscation contests, usually.)
-
-%************************************************************************
-%* *
-\subsection[options-optimise]{Optimisation (code improvement)}
-\index{optimisation (GHC)}
-\index{improvement, code (GHC)}
-%* *
-%************************************************************************
-
-The \tr{-O*} options specify convenient ``packages'' of optimisation
-flags; the \tr{-f*} options described later on specify {\em individual}
-optimisations to be turned on/off; the \tr{-m*} options specify {\em
-machine-specific} optimisations to be turned on/off.
-
-%----------------------------------------------------------------------
-\subsubsection[optimise-pkgs]{\tr{-O*}: convenient ``packages'' of optimisation flags.}
-\index{-O options (GHC)}
-
-There are {\em many} 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 \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 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:]
-\index{-O* not specified}
-This is taken to mean: ``Please compile quickly; I'm not over-bothered
-about compiled-code quality.'' So, for example: \tr{ghc -c Foo.hs}
-
-\item[\tr{-O} or \tr{-O1}:]
-\index{-O option}
-\index{-O1 option}
-\index{optimise normally}
-Means: ``Generate good-quality code without taking too long about it.''
-Thus, for example: \tr{ghc -c -O Main.lhs}
-
-\item[\tr{-O2}:]
-\index{-O2 option}
-\index{optimise aggressively}
-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} if you're unlucky. They are
-normally turned on or off individually.
-
-At the moment, \tr{-O2} is {\em unlikely} to produce
-better code than \tr{-O}.
-
-% \item[\tr{-O0}:]
-% \index{-O0 option}
-% \index{optimise minimally}
-% [``Oh zero''] Means: ``Turn {\em off} as many optimisations (e.g.,
-% simplifications) as possible.'' This is the only optimisation level
-% at which the GCC-register-trickery is turned off. {\em You can't use
-% it unless you have a suitably-built Prelude to match.} Intended for
-% hard-core debugging.
-
-\item[\tr{-fvia-C}:]
-\index{-fvia-C option}
-\index{-fvia-c option}
-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
-\tr{_ccall_}s or \tr{_casm_}s, you probably {\em have to} use
-\tr{-fvia-C}.
-
-The lower-case incantation, \tr{-fvia-c}, is synonymous.
-
-\item[\tr{-O2-for-C}:]
-\index{-O2-for-C option}
-Says to run GCC with \tr{-O2}, which may be worth a few percent in
-execution speed. Don't forget \tr{-fvia-C}, lest you use the
-native-code generator and bypass GCC altogether!
-
-\item[\tr{-Onot}:]
-\index{-Onot option}
-\index{optimising, reset}
-This option will make GHC ``forget'' any -Oish options it has seen
-so far. Sometimes useful; for example: \tr{make all EXTRA_HC_OPTS=-Onot}.
-
-\item[\tr{-Ofile <file>}:]
-\index{-Ofile <file> option}
-\index{optimising, customised}
-For those who need {\em absolute} control over {\em exactly} what
-options are used (e.g., compiler writers, sometimes :-), a list of
-options can be put in a file and then slurped in with \tr{-Ofile}.
-
-In that file, comments are of the \tr{#}-to-end-of-line variety; blank
-lines and most whitespace is ignored.
-
-Please ask if you are baffled and would like an example of \tr{-Ofile}!
-\end{description}
-
-At Glasgow, we don't use a \tr{-O*} flag for day-to-day work. We use
-\tr{-O} to get respectable speed; e.g., when we want to measure
-something. When we want to go for broke, we tend to use
-\tr{-O -fvia-C -O2-for-C} (and we go for lots of coffee breaks).
-
-%Here is a table to summarise whether pragmatic interface information
-%is used or not, whether the native-code generator is used (if
-%available), and whether we use GCC register tricks (for speed!) on the
-%generated C code:
-%
-%\begin{tabular}{lccl}
-%\tr{-O*} & Interface & Native code & `Registerised' C \\
-% & pragmas? & (if avail.) & (if avail.) \\ \hline
-%%
-%\pl{<none>} & no & yes & yes, only if \tr{-fvia-C} \\
-%\tr{-O,-O1} & yes & yes & yes, only if \tr{-fvia-C} \\
-%\tr{-O2} & yes & no & yes \\
-%\tr{-Ofile} & yes & yes & yes, only if \tr{-fvia-C} \\
-%\end{tabular}
-
-The easiest way to see what \tr{-O} (etc) ``really mean'' is to run
-with \tr{-v}, then stand back in amazement.
-Alternatively, just look at the
-\tr{@HsC_minus<blah>} lists in the \tr{ghc} driver script.
-
-%----------------------------------------------------------------------
-\subsubsection{\tr{-f*}: platform-independent flags}
-\index{-f* options (GHC)}
-\index{-fno-* options (GHC)}
-
-Flags can be turned {\em off} individually. (NB: I hope
-you have a good reason for doing this....) To turn off the \tr{-ffoo}
-flag, just use the \tr{-fno-foo} flag.\index{-fno-<opt> anti-option}
-So, for example, you can say
-\tr{-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:
-\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}.
-
-Should you wish to turn individual flags {\em on}, you are advised to
-use the \tr{-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} want to try:
-\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.)
-
-\item[\tr{-funfolding-use-threshold<n>}:]
-(Default: 3) By raising or lowering this number, you can make the
-compiler more or less keen to expand unfoldings.
-
-OK, folks, these magic numbers `30' and `3' are mildly arbitrary; they
-are of the ``seem to be OK'' variety. The `3' is the more critical
-one; it's what determines how eager GHC is about expanding unfoldings.
-
-\item[\tr{-funfolding-override-threshold<n>}:]
-(Default: 8) [Pretty obscure]
-When deciding what unfoldings from a module should be made available
-to the rest of the world (via this module's interface), the compiler
-normally likes ``small'' expressions.
-
-For example, if it sees \tr{foo = bar}, it will decide that the very
-small expression \tr{bar} is a great unfolding for \tr{foo}. But if
-\tr{bar} turns out to be \tr{(True,False,True)}, we would probably
-prefer {\em that} for the unfolding for \tr{foo}.
-
-Should we ``override'' the initial small unfolding from \tr{foo=bar}
-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).
-
-% \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)
-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 \tr{-fsemi-tagging} enough to recommend it.
-(For all we know, it doesn't even work anymore... Sigh.)
-\end{description}
-
-%----------------------------------------------------------------------
-% \subsubsection[optimise-simplifier]{Controlling ``simplification'' in the Haskell compiler.}
-%
-%Almost everyone turns program transformation
-% (a.k.a. ``simplification'') on/off via one of the ``packages'' above,
-%but you can exert absolute control if you want to. Do a \tr{ghc -v -O ...},
-%and you'll see there are plenty of knobs to turn!
-%
-%The Core-to-Core and STG-to-STG passes can be run multiple times, and
-%in varying orders (though you may live to regret it). The on-or-off
-%global flags, however, are simply, well, on or off.
-%
-%The best way to give an exact list of options is the \tr{-Ofile}
-%option, described elsewhere.
-%
-% [Check out \tr{ghc/compiler/simplCore/SimplCore.lhs} and
-%\tr{simplStg/SimplStg.lhs} if you {\em really} want to see every
-%possible Core-to-Core and STG-to-STG pass, respectively. The
-%on-or-off global flags that effect what happens {\em within} one of
-%these passes are defined by the \tr{GlobalSwitch} datatype in
-%\tr{compiler/main/CmdLineOpts.lhs}.]
-
-%----------------------------------------------------------------------
-\subsubsection{\tr{-m*}: platform-specific flags}
-\index{-m* options (GHC)}
-\index{platform-specific options}
-\index{machine-specific options}
-
-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{-monly-[32]-regs}:]
-(iX86 machines)\index{-monly-N-regs option (iX86 only)}
-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:
-\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 `3' first,
-then `2'. If `2' doesn't work, please report the bug to us.
-\end{description}
-
-%----------------------------------------------------------------------
-\subsubsection[optimise-C-compiler]{Code improvement by the C compiler.}
-\index{optimisation by GCC}
-\index{GCC optimisation}
-
-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
-\tr{-O2-for-C}\index{-O2-for-C option} option.
-
-%If you are brave or foolish, you might want to omit some checking code
-% (e.g., for stack-overflow checks), as sketched in
-%\sectionref{omit-checking}.
-
-%************************************************************************
-%* *
-\subsection[options-sanity]{Warnings and sanity-checking}
-\index{sanity-checking options}
-\index{warnings}
-%* *
-%************************************************************************
-
-GHC has a selection 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:
-\tr{-fwarn-overlpapping-patterns} and \tr{-fwarn-missing-methods}.
-The following flags are simple ways to select standard ``packages'' of
-warnings:
-
-\begin{description}
-
-\item[\tr{-Wnot}:]
-\index{-Wnot option}
-
-Turns off all warnings, including the standard ones.
-
-\item[\tr{-w}:]
-\index{-w option}
-
-Synonym for \tr{-Wnot}.
-
-\item[\tr{-W}:]
-\index{-W option}
-
-Provides the standard warnings plus \tr{-fwarn-incomplete-patterns}
-and \tr{-fwarn-unused-names}.
-
-\item[\tr{-Wall}:]
-\index{-Wall option}
-
-Turns on all warning options.
-
-\end{description}
-
-The full set of warning options is described below. To turn off any
-warning, simply give the corresponding \tr{-fno-warn-...} option on
-the command line.
-
-\begin{description}
-
-\item[\tr{-fwarn-name-shadowing}:]
-\index{-fwarn-name-shadowing option}
-\index{shadowing, warning}
-
-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
-\tr{let x = ... x ... in}.
-
-Consequently, this option does {\em not} allow cyclic recursive
-definitions.
-
-\item[\tr{-fwarn-overlapping-patterns}:]
-\index{-fwarn-overlapping-patterns option}
-\index{overlapping patterns, warning}
-\index{patterns, overlapping}
-
-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
-
-g [] = 2
-\end{verbatim}
-
-where the last pattern match in \tr{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.
-
-\item[\tr{-fwarn-incomplete-patterns}:]
-\index{-fwarn-incomplete-patterns option}
-\index{incomplete patterns, warning}
-\index{patterns, incomplete}
-
-Similarly for incomplete patterns, the function \tr{g} will fail when
-applied to non-empty lists, so the compiler will emit a warning about
-this when this option is enabled.
-
-\item[\tr{-fwarn-missing-methods}:]
-\index{-fwarn-missing-methods option}
-\index{methods, missing}
-
-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.
-
-\item[\tr{-fwarn-unused-names}:]
-\index{-fwarn-unused-names}
-Have the renamer report which locally defined names are not
-used/exported. This option is not currently supported.
-
-\item[\tr{-fwarn-duplicate-exports}:]
-\index{-fwarn-duplicate-exports option}
-\index{export lists, duplicates}
-
-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.
-
-\end{description}
-
-If you would like GHC to check that every top-level value has a type
-signature, use the \tr{-fsignatures-required}
-option.\index{-fsignatures-required 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
-sanity, not yours.)
-
-%************************************************************************
-%* *
-\subsection[options-output]{Re-directing the compilation output(s)}
-\index{output-directing options}
-%* *
-%************************************************************************
-
-When compiling a Haskell module, GHC may produce several files of
-output (usually two).
-
-One file is usually an {\em interface file}. The name of the
-interface file follows the Haskell {\em module} name, i.e., if
-compiling \tr{bar/Foo.hs}, and it implements \tr{module Bar ...}, the
-interface file would normally be \tr{bar/Bar.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} (not recommended).
-
-NOTE: Having the name of the interface file follow the module name
-and not the file name, means that working with tools such as
-\tr{make(1)} become harder. \tr{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.
-
-To avoid generating an interface file at all, use a \tr{-nohi}
-option.\index{-nohi option}
-
-The compiler does not overwrite an existing \tr{.hi} interface file if
-the new one is byte-for-byte the same as the old one; this is friendly to
-\tr{make}. When an interface does change, it is often enlightening 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. You can
-also record the difference in the interface file itself, the
-\tr{-keep-hi-diffs}\index{-keep-hi-diffs} option takes care of that.
-
-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
-phase to file \tr{foo}.
-
-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!
-
-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).
-For example:
-
-\begin{verbatim}
-% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
-\end{verbatim}
-
-The output files, \tr{Foo.o}, \tr{Bar.o}, and \tr{Bumble.o} would be
-put into a subdirectory named after the architecture of the executing
-machine (\tr{sun4}, \tr{mips}, etc). The directory must already
-exist; it won't be created.
-
-Note that the \tr{-odir} option does {\em not} affect where the
-interface files are put. In the above example, they would still be
-put in \tr{parse/Foo.hi}, \tr{parse/Bar.hi}, and
-\tr{gurgle/Bumble.hi}.
-
-MORE EXOTICA: The \tr{-osuf <suffix>}\index{-osuf <suffix> option}
-will change the \tr{.o} file suffix for object files to whatever
-you specify. (We use this in compiling the prelude.)
-
-Similarly, the \tr{-hisuf <suffix>}\index{-hisuf <suffix> option} will
-change the \tr{.hi} file suffix for non-system interface files. This
-can be useful when you are trying to compile a program several ways,
-all in the same directory. The suffix given is used for {\em all}
-interfaces files written, {\em and} for all non-system interface files
-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
-\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
-% interface files (notably the \tr{Prelude.hi} file), use the
-% \tr{-hisuf-prelude <suffix>}\index{-hisuf-prelude <suffix> option}
-% option. (This may be useful if you've built GHC in various funny
-% ways, and you are running tests in even more funny ways. It happens.)
-
-FURTHER EXOTICA: If you are doing a normal \tr{.hs}-to-\tr{.o} compilation
-but would like to hang onto the intermediate \tr{.hc} C file, just
-throw in a \tr{-keep-hc-file-too} option\index{-keep-hc-file-too option}.
-If you would like to look at the assembler output, toss in a
-\tr{-keep-s-file-too},\index{-keep-hc-file-too option} too.
-
-SAVING GHC STDERR OUTPUT: Sometimes, you may cause GHC to be rather
-chatty on standard error; with \tr{-fshow-import-specs}, for example.
-You can instruct GHC to {\em append} this output to a particular log
-file with a \tr{-odump <blah>}\index{-odump <blah> option} option.
-
-TEMPORARY FILES: If you have trouble because of running out of space
-in \tr{/tmp/} (or wherever your installation thinks temporary files
-should go), you may use the \tr{-tmpdir <dir>}\index{-tmpdir <dir> option}
-option to specify an alternate directory. For example, \tr{-tmpdir .}
-says to put temporary files in the current working directory.
-
-BETTER IDEA FOR TEMPORARY FILES: Use your \tr{TMPDIR} environment
-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.
-
-EVEN BETTER IDEA: Set the \tr{TMPDIR} variable when building
-GHC, and never worry about \tr{TMPDIR} again. (see the build
-documentation).
-
-%************************************************************************
-%* *
-\subsection[options-finding-imports-etc]{For finding interface files, etc.}
-\index{interface files, finding them}
-\index{finding interface files}
-%* *
-%************************************************************************
-
-In your program, you import a module \tr{Foo} by saying
-\tr{import Foo}. GHC goes looking for an interface file, \tr{Foo.hi}.
-It has a builtin list of directories (notably including \tr{.}) where
-it looks.
-
-The \tr{-i<dirs>} option\index{-i<dirs> option} prepends a
-colon-separated list of \tr{dirs} to the ``import directories'' list.
-
-A plain \tr{-i} resets the ``import directories'' list back to nothing.
-
-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
-library), just use a \tr{-syslib hbc}\index{-syslib <lib> option}
-option (for example). The right interface files should then be
-available.
-
-Once a Haskell module has been compiled to C (\tr{.hc} file), you may
-wish to specify where GHC tells the C compiler to look for \tr{.h}
-files. (Or, if you are using the \tr{-cpp} option\index{-cpp option},
-where it tells the C pre-processor to look...) For this purpose, use
-a \tr{-I<dir>}\index{-I<dir> option} in the usual C-ish way.
-
-Pragmas: Interface files are normally jammed full of
-compiler-produced {\em pragmas}, 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 \tr{-fignore-interface-pragmas}\index{-fignore-interface-pragmas option}
-option.
-
-When compiling without optimisations on, the compiler is extra-careful
-about not slurping in data constructors and instance declarations that
-it will not need. If you believe it is getting it wrong and not
-importing stuff which you think it should, this optimisation can be
-turned off with \tr{-fno-prune-tydecls} and \tr{-fno-prune-instdecls}.
-\index{-fno-prune-tydecls option}\index{-fno-prune-instdecls}
-
-See also \sectionref{options-linker}, which describes how the linker
-finds standard Haskell libraries.
-
-%************************************************************************
-%* *
-%\subsection[options-names]{Fiddling with namespaces}
-%* *
-%************************************************************************
-
-%-split-objs and -fglobalise-toplev-names. You don't need them and you
-%don't want to know; used for the prelude (ToDo).
-
-%************************************************************************
-%* *
-\subsection[options-CPP]{Related to the C pre-processor}
-\index{C pre-processor options}
-\index{pre-processor (cpp) options}
-%* *
-%************************************************************************
-
-The C pre-processor \tr{cpp} is run over your Haskell code only if the
-\tr{-cpp} option \index{-cpp option} is given. Unless you are
-building a large system with significant doses of conditional
-compilation, you really shouldn't need it.
-\begin{description}
-\item[\tr{-D<foo>}:]
-\index{-D<name> option}
-Define macro \tr{<foo>} in the usual way. NB: does {\em not} affect
-\tr{-D} macros passed to the C~compiler when compiling via C! For
-those, use the \tr{-optc-Dfoo} hack...
-
-\item[\tr{-U<foo>}:]
-\index{-U<name> option}
-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
-the usual C way.
-\end{description}
-
-The \tr{ghc} driver pre-defines several macros:
-\begin{description}
-\item[\tr{__HASKELL1__}:]
-\index{__HASKELL1__ macro}
-If defined to $n$, that means GHC supports the
-Haskell language defined in the Haskell report version $1.n$.
-Currently 4.
-
-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.
-
-\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~2.02, it is 202.
-
-This macro is {\em only} set when pre-processing Haskell source.
-({\em Not} when pre-processing generated C.)
-
-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:
-\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!
-This symbol is defined when pre-processing Haskell (input) and
-pre-processing C (GHC output).
-
-\item[\tr{__PARALLEL_HASKELL__}:]
-\index{__PARALLEL_HASKELL__ macro}
-Only defined when \tr{-parallel} is in use! This symbol is defined when
-pre-processing Haskell (input) and pre-processing C (GHC output).
-\end{description}
-
-Options other than the above can be forced through to the C
-pre-processor with the \tr{-opt} flags (see
-\sectionref{forcing-options-through}).
-
-A small word of warning: \tr{-cpp} is not friendly to ``string
-gaps''.\index{-cpp vs string gaps}\index{string gaps vs -cpp}. In
-other words, strings such as the following:
-
-\begin{verbatim}
- strmod = "\
- \ p \
- \ "
-\end{verbatim}
-
-don't work with \tr{-cpp}; \tr{/usr/bin/cpp} elides the
-backslash-newline pairs.
-
-However, it appears that if you add a space at the end of the line,
-then \tr{cpp} (at least GNU \tr{cpp} and possibly other \tr{cpp}s)
-leaves the backslash-space pairs alone and the string gap works as
-expected.
-
-%************************************************************************
-%* *
-\subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
-\index{include-file-option}
-\index{C compiler options}
-\index{GCC options}
-%* *
-%************************************************************************
-
-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:
-
-\begin{tabular}{ll}
-\tr{-Wall} & get all warnings from GCC \\
-\tr{-ansi} & do ANSI C (not K\&R) \\
-\tr{-pedantic} & be so\\
-\tr{-dgcc-lint} & (hack) short for ``make GCC very paranoid''\\
-\end{tabular}
-\index{-Wall option (for GCC)}
-\index{-ansi option (for GCC)}
-\index{-pedantic option (for GCC)}
-\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 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}
-
-
-%************************************************************************
-%* *
-%\subsection[options-native-code]{Options affecting the native-code generator(s)}
-%* *
-%************************************************************************
-
-%The only option is to select the target architecture. Right now,
-%you have only at most one choice: \tr{-fasm-sparc}.\index{-fasm-<target> option}
-%
-%EXPECT this native-code stuff to change in the future.
-
-%************************************************************************
-%* *
-\subsection[options-linker]{Linking and consistency-checking}
-\index{linker options}
-\index{ld options}
-%* *
-%************************************************************************
-
-GHC has to link your code with various libraries, possibly including:
-user-supplied, GHC-supplied, and system-supplied (\tr{-lm} math
-library, for example).
-
-\begin{description}
-\item[\tr{-l<FOO>}:]
-\index{-l<lib> option}
-Link in a library named \tr{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: \tr{ghc -lbar *.o} is almost certainly
-wrong, because it will search \tr{libbar.a} {\em before} it has
-collected unresolved symbols from the \tr{*.o} files.
-\tr{ghc *.o -lbar} is probably better.
-
-The linker will of course be informed about some GHC-supplied
-libraries automatically; these are:
-
-\begin{tabular}{ll}
--l equivalent & description \\ \hline
-
--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}
-\index{-lHS_cbits library}
-\index{-lHSrts library}
-\index{-lgmp library}
-
-\item[\tr{-syslib <name>}:]
-\index{-syslib <name> option}
-
-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.
-
-%Please see \sectionref{syslibs} for information about
-%``system libraries.''
-
-\item[\tr{-L<dir>}:]
-\index{-L<dir> option}
-Where to find user-supplied libraries... Prepend the directory
-\tr{<dir>} to the library directories path.
-
-\item[\tr{-static}:]
-\index{-static option}
-Tell the linker to avoid shared libraries.
-
-\item[\tr{-no-link-chk} and \tr{-link-chk}:]
-\index{-no-link-chk option}
-\index{-link-chk option}
-\index{consistency checking of executables}
-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 \tr{.o} file was compiled
-for a parallel machine and the others weren't.) You may turn off this
-check with \tr{-no-link-chk}. You can turn it (back) on with
-\tr{-link-chk} (the default).
-\end{description}
-
-%************************************************************************
-%* *
-\subsection[options-compiler-RTS]{For the compiler's RTS: heap, stack sizes, etc.}
-\index{heap-size options (for GHC)}
-\index{stack-size options (for GHC)}
-%* *
-%************************************************************************
-
-The compiler is itself a Haskell program, so it has a tweakable
-runtime-system (RTS), just like any other Haskell program.
-
-\begin{description}
-\item[\tr{-H<size>} or \tr{-Rmax-heapsize <size>}:]
-\index{-H<size> option}
-\index{-Rmax-heapsize <size> option}
-Don't use more than \tr{<size>} {\em bytes} for heap space. If more
-than one of these arguments is given, the largest will be taken.
-
-A size of zero can be used to reset the heap size downwards. For
-example, to run GHC with a heap of 250KB (the default is 6MB), do
-\tr{-H0 -H250k}.
-
-\item[\tr{-K<size>} or \tr{-Rmax-stksize <size>}:]
-\index{-K<size> option}
-\index{-Rmax-stksize <size> option}
-Set the stack space to \tr{<size>} bytes. If you have to set it very
-high [a megabyte or two, say], the compiler is probably looping, which
-is a BUG (please report).
-
-A size of zero can be used to rest the stack size downwards, as above.
-
-\item[\tr{-Rscale-sizes<factor>}:]
-\index{-Rscale-sizes<factor> option}
-Multiply the given (or default) heap and stack sizes by \tr{<factor>}.
-For example, on a DEC Alpha (a 64-bit machine), you might want to
-double those space sizes; just use \tr{-Rscale-sizes2}.
-
-A non-integral factor is OK, too: \tr{-Rscale-sizes1.2}.
-
-\item[\tr{-Rghc-timing}:]
-\index{-Rghc-timing option}
-Reports a one-line useful collection of time- and space- statistics
-for a module's compilation.
-
-\item[\tr{-Rgc-stats}:]
-\index{-Rgc-stats option}
-Report garbage-collection statistics. It will create a
-\tr{<foo>.stat} file, in some obvious place (I hope).
-
-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.
-\end{description}
-
-For all \tr{<size>}s: If the last character of \tr{size} is a K,
-multiply by 1000; if an M, by 1,000,000; if a G, by 1,000,000,000.
-Sizes are always in {\em bytes}, not words. Good luck on the G's (I
-think the counter is still only 32-bits [WDP])!
-
-%************************************************************************
-%* *
-%\subsection[options-cross-compiling]{For cross-compiling to another architecture}
-%* *
-%************************************************************************
-%
-% (We do this for GRIP at Glasgow; it's hacked in---not proper
-%cross-compiling support. But you could do the same, if required...)
-%
-%The \tr{-target <arch>} option\index{-target <arch> option} says to
-%generate code for the \tr{<arch>} architecture.
-
-%************************************************************************
-%* *
-\subsection[options-parallel]{For Concurrent and Parallel Haskell}
-%* *
-%************************************************************************
-
-For the full story on using GHC for concurrent \& parallel Haskell
-programming, please see \Sectionref{concurrent-and-parallel}.
-
-%The \tr{-fparallel} option\index{-fparallel option} tells the compiler
-%to generate code for parallel execution. The \tr{-mgrip}
-%option\index{-mgrip option} says that the code should be explicitly
-%suitable for the GRIP multiprocessor (the one in our Glasgow basement).
-
-%************************************************************************
-%* *
-%\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}
-
-% -firrefutable-everything
-% -fall-demanded
-
-%************************************************************************
-%* *
-\subsection[options-debugging]{For debugging the compiler}
-\index{debugging options (for GHC)}
-%* *
-%************************************************************************
-
-HACKER TERRITORY. HACKER TERRITORY.
-(You were warned.)
-
-%----------------------------------------------------------------------
-\subsubsection[replacing-phases]{Replacing the program for one or more phases.}
-\index{GHC phases, changing}
-\index{phases, changing GHC}
-
-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 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:
-
-\begin{tabular}{ll}
-code & phase \\ \hline
-L & literate pre-processor \\
-P & C pre-processor (if -cpp only) \\
-C & Haskell compiler \\
-c & C compiler\\
-a & assembler \\
-l & linker \\
-\end{tabular}
-
-%----------------------------------------------------------------------
-\subsubsection[forcing-options-through]{Forcing options to a particular phase.}
-\index{forcing GHC-phase options}
-
-The preceding sections describe driver options that are mostly
-applicable to one particular phase. You may also {\em force} a
-specific option \tr{<option>} to be passed to a particular phase
-\tr{<phase-code>} by feeding the driver the option
-\tr{-opt<phase-code><option>}.\index{-opt<phase><stuff> option} The
-codes to indicate the phases are the same as in the previous section.
-
-So, for example, to force an \tr{-Ewurble} option to the assembler, you
-would tell the driver \tr{-opta-Ewurble} (the dash before the E is
-required).
-
-Besides getting options to the Haskell compiler with \tr{-optC<blah>},
-you can get options through to its runtime system with
-\tr{-optCrts<blah>}\index{-optCrts<blah> option}.
-
-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
-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 \
- "$@"
-\end{verbatim}
-
-%----------------------------------------------------------------------
-\subsubsection[dumping-output]{Dumping out compiler intermediate structures}
-\index{dumping GHC intermediates}
-\index{intermediate passes, output}
-
-\begin{description}
-\item[\tr{-noC}:]
-\index{-noC option}
-Don't bother generating C output {\em or} an interface file. Usually
-used in conjunction with one or more of the \tr{-ddump-*} options; for
-example: \tr{ghc -noC -ddump-simpl Foo.hs}
-
-\item[\tr{-hi}:]
-\index{-hi option}
-{\em Do} generate an interface file. This would normally be used in
-conjunction with \tr{-noC}, which turns off interface generation;
-thus: \tr{-noC -hi}.
-
-\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}
-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}
-\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-stranal} & strictness analyser output \\
-\tr{-ddump-occur-anal} & `occurrence analysis' output \\
-\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-flatC} & {\em flattened} Abstract~C \\
-\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-rdr option}%
-\index{-ddump-rn option}%
-\index{-ddump-tc option}%
-\index{-ddump-deriv option}%
-\index{-ddump-ds option}%
-\index{-ddump-simpl option}%
-\index{-ddump-stranal option}%
-\index{-ddump-occur-anal option}%
-\index{-ddump-spec option}%
-\index{-ddump-stg option}%
-\index{-ddump-absC option}%
-\index{-ddump-flatC option}%
-\index{-ddump-realC option}%
-\index{-ddump-asm option}
-
-%For any other \tr{-ddump-*} options: consult the source, notably
-%\tr{ghc/compiler/main/CmdLineOpts.lhs}.
-
-\item[\tr{-dverbose-simpl} and \tr{-dverbose-stg}:]
-\index{-dverbose-simpl option}
-\index{-dverbose-stg option}
-Show the output of the intermediate Core-to-Core and STG-to-STG
-passes, respectively. ({\em Lots} of output!) So: when we're
-really desperate:
-\begin{verbatim}
-% ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
-\end{verbatim}
-
-\item[\tr{-dppr-{user,debug,all}}:]
-\index{-dppr-user option}
-\index{-dppr-debug option}
-\index{-dppr-all option}
-Debugging output is in one of several ``styles.'' Take the printing
-of types, for example. In the ``user'' style, the compiler's internal
-ideas about types are presented in Haskell source-level syntax,
-insofar as possible. In the ``debug'' style (which is the default for
-debugging output), the types are printed in the most-often-desired
-form, with explicit foralls, etc. In the ``show all'' style, very
-verbose information about the types (e.g., the Uniques on the
-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-rn-trace}:]
-\index{-ddump-rn-trace}
-Make the renamer be *real* chatty about what it is upto.
-
-\item[\tr{-dshow-rn-stats}:]
-\index{-dshow-rn-stats}
-Print out summary of what kind of information the renamer had to bring
-in.
-\item[\tr{-dshow-unused-imports}:]
-\index{-dshow-unused-imports}
-Have the renamer report what imports does not contribute.
-
-%
-%\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
-
-%----------------------------------------------------------------------
-\subsubsection{How to read Core syntax (from some \tr{-ddump-*} flags)}
-\index{reading Core syntax}
-\index{Core syntax, how to read}
-
-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).
-
-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[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 which header files to include. Rather than
-maintaining the list of files the source depends on in a
-\tr{Makefile} (using the \tr{-#include} command-line option), it is
-possible to do this directly in the source file using the \tr{OPTIONS}
-pragma \index{OPTIONS pragma}:
-
-\begin{verbatim}
-{-# OPTIONS -#include "foo.h" #-}
-module X where
-
-...
-\end{verbatim}
-
-\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}.
-
-NOTE: 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 \tr{OPTIONS} pragma
-is the Right Thing. (If you use \tr{-keep-hc-file-too} and have OPTION
-flags in your module, the OPTIONS will get put into the generated .hc
-file).
-
-%----------------------------------------------------------------------
-\subsubsection{How to compile mutually recursive modules}
-\index{module system, recursion}
-
-Currently, the compiler does not have proper support for dealing with
-mutually recursive modules:
-
-\begin{verbatim}
-module A where
-
-import B
-
-newtype A = A Int
-
-f :: B -> A
-f (B x) = A x
---------
-module B where
-
-import A
-
-data B = B !Int
-
-g :: A -> B
-g (A x) = B x
-\end{verbatim}
-
-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. For the example at hand, the
-boot interface file for A would like the following:
-
-\begin{verbatim}
-_interface_ A 1
-_exports_
-A A(A) f;
-_declarations_
-1 newtype A = A PrelBase.Int ;
-1 f _:_ B.B -> A.A ;;
-\end{verbatim}
-
-To make sure you get the syntax right, tailoring an existing interface
-file is a Good Idea.
-
-{\bf Note:} This is all a temporary solution, a version of the compiler
-that handles mutually recursive properly without the manual
-construction of interface file, is in the works.
-
-%----------------------------------------------------------------------
-%\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...
-
-%% %************************************************************************
-%% %* *
-%% \subsection[options-GC]{Choosing a garbage collector}
-%% %* *
-%% %************************************************************************
-%%
-%% (Note: you need a Good Reason before launching into this territory.)
-%%
-%% There are up to four garbage collectors to choose from (it depends how
-%% your local system was built); the Appel-style generational collector
-%% is the default.
-%%
-%% If you choose a non-default collector, you must specify it both when
-%% compiling the modules and when linking them together into an
-%% executable. Also, the native-code generator only works with the
-%% default collector (a small point to bear in mind).
-%%
-%% \begin{description}
-%% \item[\tr{-gc-ap} option:]
-%% \index{-gc-ap option}
-%% Appel-like generational collector (the default).
-%%
-%% \item[\tr{-gc-2s} option:]
-%% \index{-gc-2s option}
-%% Two-space copying collector.
-%%
-%% \item[\tr{-gc-1s} option:]
-%% \index{-gc-1s option}
-%% One-space compacting collector.
-%%
-%% \item[\tr{-gc-du} option:]
-%% \index{-gc-du option}
-%% Dual-mode collector (swaps between copying and compacting).
-%% \end{description}
projects / ghc-hetmet.git / blobdiff