Command-line arguments are either options or file names.
Command-line options begin with \tr{-}. They may {\em not} be
-grouped: \tr{-vO} is different from \tr{-v -O}.
-Options need not precede filenames: e.g., \tr{ghc *.o -o foo}.
-All options are processed
-and then apply to all files; you cannot, for example,
-invoke \tr{ghc -c -O1 Foo.hs -O2 Bar.hs} to apply different
-optimisation levels to the files \tr{Foo.hs} and \tr{Bar.hs}. For
-conflicting options, e.g., \tr{-c -S}, we reserve the right to do
-anything we want. (Usually, the last one applies.)
+grouped: \tr{-vO} is different from \tr{-v -O}. Options need not
+precede filenames: e.g., \tr{ghc *.o -o foo}. All options are
+processed and then applied to all files; you cannot, for example, invoke
+\tr{ghc -c -O1 Foo.hs -O2 Bar.hs} to apply different optimisation
+levels to the files \tr{Foo.hs} and \tr{Bar.hs}. For conflicting
+options, e.g., \tr{-c -S}, we reserve the right to do anything we
+want. (Usually, the last one applies.)
Options related to profiling, Glasgow extensions to Haskell (e.g.,
-unboxed values), Concurrent and Parallel Haskell are
-described in \sectionref{profiling}, \sectionref{glasgow-exts}, and
+unboxed values), Concurrent and Parallel Haskell are described in
+\sectionref{profiling}, \sectionref{glasgow-exts}, and
\sectionref{concurrent-and-parallel}, respectively.
%************************************************************************
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}
literate pre-processor & .lhs & - & - \\
C pre-processor (opt.) & - & - & - \\
-Haskell parser & .hs & - & - \\
-Haskell compiler & - & -C, -S & .hc, .s \\
+Haskell compiler & .hs & -C, -S & .hc, .s \\
C compiler (opt.) & .hc or .c & -S & .s \\
assembler & .s & -c & .o \\
linker & other & - & a.out \\
%files as if they had suffix \pl{<suf>}. [NOT IMPLEMENTED YET]
The option \tr{-cpp}\index{-cpp option} must be given for the C
-pre-processor phase to be run.
+pre-processor phase to be run, that is, the pre-processor will be run
+over your Haskell source file before continuing.
The option \tr{-E}\index{-E option} runs just the C-preprocessor part
of the C-compiling phase, sending the result to stdout [I think]. (For
Once you choose a \tr{-O*} ``package,'' stick with it---don't chop and
change. Modules' interfaces {\em will} change with a shift to a new
-\tr{-O*} option, and you will have to recompile all importing modules
-before your program can again be run safely.
+\tr{-O*} option, and you may have to recompile a large chunk of all
+importing modules before your program can again be run
+safely\sectionref{recomp}.
\begin{description}
\item[No \tr{-O*}-type option specified:]
runtime or space {\em worse} if you're unlucky. They are
normally turned on or off individually.
-As of version~0.26, \tr{-O2} is {\em unlikely} to produce
+At the moment, \tr{-O2} is {\em unlikely} to produce
better code than \tr{-O}.
% \item[\tr{-O0}:]
strictness analyser.
The options you are most likely to want to turn off are:
-\tr{-fno-update-analysis}\index{-fno-update-analysis option} [because
-it is sometimes slow],
\tr{-fno-strictness}\index{-fno-strictness option} (strictness
analyser [because it is sometimes slow]),
\tr{-fno-specialise}\index{-fno-specialise option} (automatic
specialisation of overloaded functions [because it makes your code
bigger]) [US spelling also accepted],
and
-\tr{-fno-foldr-build}\index{-fno-foldr-build option} [because no-one
-knows what Andy Gill made it do].
+\tr{-fno-foldr-build}\index{-fno-foldr-build option}.
Should you wish to turn individual flags {\em on}, you are advised to
use the \tr{-Ofile} option, described above. Because the order in
\begin{description}
%------------------------------------------------------------------
\item[\tr{-funfolding-creation-threshold<n>}:]
-(Default: 30) By raising or lowering this number, you can raise or lower the
-amount of pragmatic junk that gets spewed into interface files.
-(An unfolding has a ``size'' that reflects the cost in terms of ``code
-bloat'' of expanding that unfolding in another module. A bigger
-Core expression would be assigned a bigger cost.)
+(Default: 30) By raising or lowering this number, you can raise or
+lower the amount of pragmatic junk that gets spewed into interface
+files. (An unfolding has a ``size'' that reflects the cost in terms
+of ``code bloat'' of expanding that unfolding in another module. A
+bigger Core expression would be assigned a bigger cost.)
\item[\tr{-funfolding-use-threshold<n>}:]
(Default: 3) By raising or lowering this number, you can make the
still under the ``override threshold.'' You can use this flag to
adjust this threshold (why, I'm not sure).
-\item[\tr{-fliberated-case-threshold<n>}:]
-(Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
-``Case liberation'' lifts evaluation out of recursive functions; it
-does this by duplicating code. Done without constraint, you can get
-serious code bloat; so we only do it if the ``size'' of the duplicated
-code is smaller than some ``threshold.'' This flag can fiddle that
-threshold.
+% \item[\tr{-fliberated-case-threshold<n>}:]
+% (Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
+% ``Case liberation'' lifts evaluation out of recursive functions; it
+% does this by duplicating code. Done without constraint, you can get
+% serious code bloat; so we only do it if the ``size'' of the duplicated
+% code is smaller than some ``threshold.'' This flag can fiddle that
+% threshold.
\item[\tr{-fsemi-tagging}:]
This option (which {\em does not work} with the native-code generator)
program, you lose otherwise. (And you pay in extra code space.)
We have not played with \tr{-fsemi-tagging} enough to recommend it.
-(For all we know, it doesn't even work in 0.26. Sigh.)
+(For all we know, it doesn't even work anymore... Sigh.)
\end{description}
%----------------------------------------------------------------------
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-[432]-regs}:]
+\item[\tr{-monly-[32]-regs}:]
(iX86 machines)\index{-monly-N-regs option (iX86 only)}
-GHC tries to ``steal'' five registers from GCC, for performance
+GHC tries to ``steal'' four registers from GCC, for performance
reasons; it almost always works. However, when GCC is compiling some
-modules with five stolen registers, it will crash, probably saying:
+modules with four stolen registers, it will crash, probably saying:
\begin{verbatim}
Foo.hc:533: fixed or forbidden register was spilled.
This may be due to a compiler bug or to impossible asm
statements or clauses.
\end{verbatim}
-Just give some registers back with \tr{-monly-N-regs}. Try `4' first,
-then `3', then `2'. If `2' doesn't work, please report the bug to us.
+Just give some registers back with \tr{-monly-N-regs}. Try `3' first,
+then `2'. If `2' doesn't work, please report the bug to us.
\end{description}
%----------------------------------------------------------------------
\index{optimisation by GCC}
\index{GCC optimisation}
-The C~compiler, normally GCC, is run with \tr{-O} turned on. (It has
-to be, actually.)
+The C~compiler (GCC) is run with \tr{-O} turned on. (It has
+to be, actually).
If you want to run GCC with \tr{-O2}---which may be worth a few
percent in execution speed---you can give a
%************************************************************************
%* *
-\subsection[options-sanity]{Sanity-checking options}
+\subsection[options-sanity]{Warnings and sanity-checking}
\index{sanity-checking options}
%* *
%************************************************************************
If you would like to disallow ``name shadowing,'' i.e., an inner-scope
value has the same name as an outer-scope value, then use the
-\tr{-fname-shadowing-not-ok}
-option.\index{-fname-shadowing-not-ok option}
+\tr{-fwarn-name-shadowing}
+option.\index{-fwarn-name-shadowing option}
This option catches typographical errors that turn into hard-to-find
bugs, e.g., in the inadvertent cyclic definition \tr{let x = ... x ... in}.
Consequently, this option does {\em not} allow cyclic recursive
definitions.
+By default, the compiler will warn you if a set of patterns are either
+incomplete (i.e., you're only matching on a subset of an algebraic
+data type's constructors), or overlapping, i.e.,
+
+\begin{verbatim}
+f :: String -> Int
+f [] = 0
+f (_:xs) = 1
+f "2" = 2
+\end{verbatim}
+
+where the last pattern match won't ever be reached, as the second
+pattern overlaps it. More often than not, `completeness' of
+patterns is a programmer mistake/error, but if you don't want
+the compiler to ``baby-sit'', use \tr{-fno-warn-incomplete-patterns} option
+to turn them off.\index{-fno-warn-incomplete-patterns option}.
+
If you're feeling really paranoid, the \tr{-dcore-lint}
option\index{-dcore-lint option} is a good choice. It turns on
heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
\tr{bar/Foo.hs}, the interface file would normally be \tr{bar/Foo.hi}.
The interface output may be directed to another file
\tr{bar2/Wurble.iface} with the option
-\tr{-ohi bar2/Wurble.iface}\index{-ohi <file> option}.
+\tr{-ohi bar2/Wurble.iface}\index{-ohi <file> option} (not recommended).
To avoid generating an interface file at all, use a \tr{-nohi}
option.\index{-nohi option}
be informed. The \tr{-hi-diffs}\index{-hi-diffs option} option will
make \tr{ghc} run \tr{diff} on the old and new \tr{.hi} files.
+The \tr{.hi} files from GHC 2.xx contain ``usage'' information which
+changes often and uninterestingly. If you really want to see these
+changes reported, you need to use the
+\tr{-hi-diffs-with-usages}\index{-hi-diffs-with-usages option} option.
+
GHC's non-interface output normally goes into a \tr{.hc}, \tr{.o},
etc., file, depending on the last-run compilation phase. The option
\tr{-o foo}\index{-o option} re-directs the output of that last-run
\tr{ghc -C -o foo.o foo.hs} will put the intermediate C code in the
file \tr{foo.o}, name notwithstanding!
-EXOTICA: But the \tr{-o} option isn't much use if you have {\em
-several} input files... Non-interface output files are normally put
+EXOTICA: But the \tr{-o} option isn't of much use if you have {\em
+several} input files... Non-interface output files are normally put
in the same directory as their corresponding input file came from.
You may specify that they be put in another directory using the
\tr{-odir <dir>}\index{-odir <dir> option} (the ``Oh, dear'' option).
The \tr{-hisuf}/\tr{-osuf} game is useful if you want to compile a
program with both GHC and HBC (say) in the same directory. Let HBC
use the standard \tr{.hi}/\tr{.o} suffixes; add
-\tr{-hisuf _g.hi -osuf _g.o} to your \tr{make} rule for GHC compiling...
+\tr{-hisuf g_hi -osuf g_o} to your \tr{make} rule for GHC compiling...
+
+NB: {\em A change from 0.26 and before:} Before, you might have said
+\tr{-hisuf _g.hi -osuf _g.o}; now, the \tr{.} is assumed and you
+specify what comes {\em after} it. (This is a more portable solution
+for the long term.)
% THIS SHOULD HAPPEN AUTOMAGICALLY:
% If you want to change the suffix looked for on system-supplied
the directory where temporary files should be put. GCC and other
programs will honour the \tr{TMPDIR} variable as well.
-EVEN BETTER IDEA: Configure GHC with \tr{--with-tmpdir=<mumble>} when
-you build it, and never worry about \tr{TMPDIR} again.
+EVEN BETTER IDEA: Set the \tr{TMPDIR} variable when building
+GHC, and never worry about \tr{TMPDIR} again. (see the build
+documentation).
%************************************************************************
%* *
A plain \tr{-i} resets the ``import directories'' list back to nothing.
-GHC normally imports \tr{PreludeCore.hi} and \tr{Prelude.hi} files for
-you. If you'd rather it didn't, then give it a
-\tr{-fno-implicit-prelude} option\index{-fno-implicit-prelude option}.
-(Sadly, it still has to {\em find} a \tr{PreludeNull_.hi} file; it
-just won't feed it into the compiler proper.) You are unlikely to get
+GHC normally imports \tr{Prelude.hi} files for you. If you'd rather
+it didn't, then give it a \tr{-fno-implicit-prelude}
+option\index{-fno-implicit-prelude option}. You are unlikely to get
very far without a Prelude, but, hey, it's a free country.
If you are using a system-supplied non-Prelude library (e.g., the HBC
\item[\tr{-I<dir>}:]
\index{-I<dir> option}
Specify a directory in which to look for \tr{#include} files, in
-the usual UNIX/C way.
+the usual C way.
\end{description}
The \tr{ghc} driver pre-defines several macros:
\index{__HASKELL1__ macro}
If defined to $n$, that means GHC supports the
Haskell language defined in the Haskell report version $1.n$.
-Currently 2.
+Currently 4.
NB: This macro is set both when pre-processing Haskell source and
when pre-processing generated C (\tr{.hc}) files.
-If you give the \tr{-fhaskell-1.3} flag\index{-fhaskell-1.3 option},
-then \tr{__HASKELL1__} is set to 3. Obviously.
+% If you give the \tr{-fhaskell-1.3} flag\index{-fhaskell-1.3 option},
+% then \tr{__HASKELL1__} is set to 3. Obviously.
\item[\tr{__GLASGOW_HASKELL__}:]
\index{__GLASGOW_HASKELL__ macro}
For version $n$ of the GHC system, this will be \tr{#define}d to
-$100 \times n$. So, for version~0.26, it is 26.
+$100 \times n$. So, for version~2.02, it is 202.
This macro is {\em only} set when pre-processing Haskell source.
({\em Not} when pre-processing generated C.)
implementations that support C-style pre-processing.
(For reference: the comparable symbols for other systems are:
-\tr{__YALE_HASKELL__} for Yale Haskell, \tr{__HBC__} for Chalmers
-HBC, and \tr{__GOFER__} for Gofer [I think].)
+\tr{__HUGS__} for Hugs and \tr{__HBC__} for Chalmers.)
\item[\tr{__CONCURRENT_HASKELL__}:]
\index{__CONCURRENT_HASKELL__ macro}
Only defined when \tr{-concurrent} is in use!
-This symbol is
-defined when pre-processing Haskell (input) and pre-processing C (GHC
-output).
+This symbol is defined when pre-processing Haskell (input) and
+pre-processing C (GHC output).
\item[\tr{__PARALLEL_HASKELL__}:]
\index{__PARALLEL_HASKELL__ macro}
\subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
\index{C compiler options}
\index{GCC options}
+\index{include file option}
%* *
%************************************************************************
\index{-dgcc-lint option (GCC paranoia)}
If you are compiling with lots of \tr{ccalls}, etc., you may need to
-tell the C~compiler about some \tr{#include} files. There is no
+tell the C~compiler about some \tr{#include} files. There is no real
pretty way to do this, but you can use this hack from the
command-line:
\begin{verbatim}
% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
\end{verbatim}
-\index{-#include <file> option}
+
%************************************************************************
%* *
-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 an optional GHC-supplied library (e.g., the HBC
+If you are using a Haskell ``system library'' (e.g., the HBC
library), just use the \tr{-syslib hbc} option, and the correct code
should be linked in.
-Please see \sectionref{syslibs} for information about optional
-GHC-supplied libraries.
+%Please see \sectionref{syslibs} for information about
+%``system libraries.''
\item[\tr{-L<dir>}:]
\index{-L<dir> option}
Alternatively, if you'd rather the GC stats went straight to standard
error, you can ``cheat'' by using, instead: \tr{-optCrts-Sstderr}.
-
-\item[\tr{-Rhbc}:]
-\index{-Rhbc option}
-Tell the compiler it has an HBC-style RTS; i.e., it was compiled with
-HBC. Not used in Real Life.
-
-\item[\tr{-Rghc}:]
-\index{-Rghc option}
-Tell the compiler it has a GHC-style RTS; i.e., it was compiled with
-GHC. Not used in Real Life.
+%
+%\item[\tr{-Rhbc}:]
+%\index{-Rhbc option}
+%Tell the compiler it has an HBC-style RTS; i.e., it was compiled with
+%HBC. Not used in Real Life.
+%
+%\item[\tr{-Rghc}:]
+%\index{-Rghc option}
+%Tell the compiler it has a GHC-style RTS; i.e., it was compiled with
+%GHC. Not used in Real Life.
\end{description}
For all \tr{<size>}s: If the last character of \tr{size} is a K,
%************************************************************************
%* *
-\subsection[options-experimental]{For experimental purposes}
-\index{experimental options}
+%\subsection[options-experimental]{For experimental purposes}
+%\index{experimental options}
%* *
%************************************************************************
-From time to time, we provide GHC options for ``experimenting.'' Easy
-come, easy go. In version~0.26, the ``experimental'' options are:
-\begin{description}
-\item[\tr{-firrefutable-tuples} option:]
-\index{-firrefutable-tuples option (experimental)}
-Pretend that every tuple pattern is irrefutable; i.e., has a
-``twiddle'' (\tr{~}) in front of it.
-
-Some parts of the GHC system {\em depend} on strictness properties which
-\tr{-firrefutable-tuples} may undo, notably the low-level state-transformer
-stuff, which includes I/O (!). You're on your own...
-
-\item[\tr{-fall-strict} option:]
-\index{-fall-strict option (experimental)}
-(DOESN'T REALLY WORK, I THINK) Changes the strictness analyser so
-that, when it asks the question ``Is this function argument certain to
-be evaluated?'', the answer is always ``yes''.
-
-Compilation is changed in no other way.
-\end{description}
+%From time to time, we provide GHC options for ``experimenting.'' Easy
+%come, easy go. In version~0.26, the ``experimental'' options are:
+%\begin{description}
+%\item[\tr{-firrefutable-tuples} option:]
+%\index{-firrefutable-tuples option (experimental)}
+%Pretend that every tuple pattern is irrefutable; i.e., has a
+%``twiddle'' (\tr{~}) in front of it.
+%
+%Some parts of the GHC system {\em depend} on strictness properties which
+%\tr{-firrefutable-tuples} may undo, notably the low-level state-transformer
+%stuff, which includes I/O (!). You're on your own...
+%
+%\item[\tr{-fall-strict} option:]
+%\index{-fall-strict option (experimental)}
+% (DOESN'T REALLY WORK, I THINK) Changes the strictness analyser so
+%that, when it asks the question ``Is this function argument certain to
+%be evaluated?'', the answer is always ``yes''.
+%
+%Compilation is changed in no other way.
+%\end{description}
+
% -firrefutable-everything
% -fall-demanded
You may specify that a different program
be used for one of the phases of the compilation system, in place of
whatever the driver \tr{ghc} has wired into it. For example, you
-might want to test a replacement parser. The
+might want to try a different assembler. The
\tr{-pgm<phase-code><program-name>}\index{-pgm<phase><stuff> option} option to
\tr{ghc} will cause it to use \pl{<program-name>} for phase
\pl{<phase-code>}, where the codes to indicate the phases are:
code & phase \\ \hline
L & literate pre-processor \\
P & C pre-processor (if -cpp only) \\
-p & parser \\
C & Haskell compiler \\
-cO & C compiler for `optimised' (normal) compiling \\
-c & C compiler for `unregisterised' compiling \\
+c & C compiler\\
a & assembler \\
l & linker \\
\end{tabular}
-If you use the ambiguous \tr{-pgmcOle}, it will take it to mean
-``use program \tr{le} for optimised C compiling.''
-
%----------------------------------------------------------------------
\subsubsection[forcing-options-through]{Forcing options to a particular phase.}
\index{forcing GHC-phase options}
profiled compiler binary, I use this script:
\begin{verbatim}
#! /bin/sh
-exec /local/grasp_tmp3/partain/ghc-BUILDS/working-alpha/ghc/driver/ghc \
- -pgmC/local/grasp_tmp3/partain/ghc-BUILDS/working-hsc-prof/hsc \
+exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
+ -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
-optCrts-i0.5 \
-optCrts-PT \
"$@"
conjunction with \tr{-noC}, which turns off interface generation;
thus: \tr{-noC -hi}.
-\item[\tr{-ddump-parser}:]
-\index{-ddump-parser option}
-This debugging option shows the exact prefix-form Haskell that is fed
-into the Haskell compiler proper.
+\item[\tr{-dshow-passes}:]
+\index{-dshow-passes option}
+Prints a message to stderr as each pass starts. Gives a warm but
+undoubtedly misleading feeling that GHC is telling you what's
+happening.
\item[\tr{-ddump-<pass>}:]
\index{-ddump-<pass> options}
need a short form...). Some of the most useful ones are:
\begin{tabular}{ll}
-\tr{-ddump-rif2hs} & reader output (earliest stuff in the compiler) \\
-\tr{-ddump-rn4} & renamer output \\
+\tr{-ddump-rdr} & reader output (earliest stuff in the compiler) \\
+\tr{-ddump-rn} & renamer output \\
\tr{-ddump-tc} & typechecker output \\
\tr{-ddump-deriv} & derived instances \\
\tr{-ddump-ds} & desugarer output \\
\tr{-ddump-simpl} & simplifer output (Core-to-Core passes) \\
- & (and don't forget \tr{-O}, too!) \\
\tr{-ddump-stranal} & strictness analyser output \\
- & (only works in conjunction with -ddump-simpl)\\
\tr{-ddump-occur-anal} & `occurrence analysis' output \\
- & (only works in conjunction with -ddump-simpl)\\
\tr{-ddump-spec} & dump specialisation info \\
\tr{-ddump-stg} & output of STG-to-STG passes \\
\tr{-ddump-absC} & {\em un}flattened Abstract~C \\
\tr{-ddump-realC} & same as what goes to the C compiler \\
\tr{-ddump-asm} & assembly language from the native-code generator \\
\end{tabular}
-\index{-ddump-rif2hs option}%
-\index{-ddump-rn4 option}%
+\index{-ddump-rdr option}%
+\index{-ddump-rn option}%
\index{-ddump-tc option}%
\index{-ddump-deriv option}%
\index{-ddump-ds option}%
\item[\tr{-ddump-raw-asm}:]
\index{-ddump-raw-asm option}
Dump out the assembly-language stuff, before the ``mangler'' gets it.
-
-\item[\tr{-dgc-debug}:]
-\index{-dgc-debug option}
-Enables some debugging code related to the garbage-collector.
+%
+%\item[\tr{-dgc-debug}:]
+%\index{-dgc-debug option}
+%Enables some debugging code related to the garbage-collector.
\end{description}
%ToDo: -ddump-asm-insn-counts
trademark of Peyton Jones Enterprises, plc.)
%----------------------------------------------------------------------
-\subsubsection[arity-checking]{Options to insert arity-checking code}
-\index{arity checking}
+\subsubsection[source-file-options]{Command line options in source files}
+\index{source-file options}
+
+Sometimes it is useful to make the connection between a source file
+and the command-line options it requires, quite tight. For instance,
+if a (Glasgow) Haskell source file uses \tr{casm}s, the C back-end
+often needs to be told about header files to use,
+\ref{include file option}. Rather than maintaining the list of
+files the source depends on in a \tr{Makefile}, it is possible to
+do this directly in the source file using the \tr{OPTIONS} pragma
+\index{OPTIONS pragma}:
-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...
+\begin{verbatim}
+{-# OPTIONS -#include "foo.h" #-}
+module X where
-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.
+...
+\end{verbatim}
-%----------------------------------------------------------------------
-\subsubsection[omit-checking]{Options to omit checking code}
-\index{omitting runtime checks}
+\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}.
-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):
+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.
-\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}
+%----------------------------------------------------------------------
+%\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.
-Warning: all very lightly tested, if at all...
+%----------------------------------------------------------------------
+%\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...
%% %************************************************************************
%% %* *
projects / ghc-hetmet.git / blobdiff