1 \section[invoking-GHC]{Invoking GHC: Command-line options}
2 \index{command-line options}
3 \index{options, GHC command-line}
5 Command-line arguments are either options or file names.
7 Command-line options begin with \tr{-}. They may {\em not} be
8 grouped: \tr{-vO} is different from \tr{-v -O}.
9 Options need not precede filenames: e.g., \tr{ghc *.o -o foo}.
10 All options are processed
11 and then apply to all files; you cannot, for example,
12 invoke \tr{ghc -c -O1 Foo.hs -O2 Bar.hs} to apply different
13 optimisation levels to the files \tr{Foo.hs} and \tr{Bar.hs}. For
14 conflicting options, e.g., \tr{-c -S}, we reserve the right to do
15 anything we want. (Usually, the last one applies.)
17 Options related to profiling, Glasgow extensions to Haskell (e.g.,
18 unboxed values), Concurrent and Parallel Haskell are
19 described in \sectionref{profiling}, \sectionref{glasgow-exts}, and
20 \sectionref{concurrent-and-parallel}, respectively.
22 %************************************************************************
24 \subsection[file-suffixes]{Meaningful file suffixes}
25 \index{suffixes, file}
26 \index{file suffixes for GHC}
28 %************************************************************************
30 File names with ``meaningful'' suffixes (e.g., \tr{.lhs} or \tr{.o})
31 cause the ``right thing'' to happen to those files.
35 \index{lhs suffix@.lhs suffix}
36 A ``literate Haskell'' module.
39 A not-so-literate Haskell module.
42 A Haskell interface file, probably compiler-generated.
45 Intermediate C file produced by the Haskell compiler.
48 A C~file not produced by the Haskell compiler.
51 % C code after it has be preprocessed by the C compiler (using the
55 An assembly-language source file, usually
56 produced by the compiler.
59 An object file, produced by an assembler.
62 Files with other suffixes (or without suffixes) are passed straight
65 %************************************************************************
67 \subsection[options-help]{Help and verbosity options}
68 \index{help options (GHC)}
69 \index{verbose option (GHC)}
71 %************************************************************************
73 A good option to start with is the \tr{-help} (or \tr{-?}) option.
76 GHC spews a long message to standard output and then exits.
78 The \tr{-v}\index{-v option} option makes GHC {\em verbose}: it
79 reports its version number and shows (on stderr) exactly how it invokes each
80 phase of the compilation system. Moreover, it passes
81 the \tr{-v} flag to most phases; each reports
82 its version number (and possibly some other information).
84 Please, oh please, use the \tr{-v} option when reporting bugs!
85 Knowing that you ran the right bits in the right order is always the
86 first thing we want to verify.
88 %************************************************************************
90 \subsection[options-order]{Running the right phases in the right order}
91 \index{order of passes in GHC}
92 \index{pass ordering in GHC}
94 %************************************************************************
96 The basic task of the \tr{ghc} driver is to run each input file
97 through the right phases (parsing, linking, etc.).
99 The first phase to run is determined by the input-file suffix, and the
100 last phase is determined by a flag. If no relevant flag is present,
101 then go all the way through linking. This table summarises:
103 \begin{tabular}{llll}
104 phase of the & suffix saying & flag saying & (suffix of) \\
105 compilation system & ``start here''& ``stop after''& output file \\ \hline
107 literate pre-processor & .lhs & - & - \\
108 C pre-processor (opt.) & - & - & - \\
109 Haskell parser & .hs & - & - \\
110 Haskell compiler & - & -C, -S & .hc, .s \\
111 C compiler (opt.) & .hc or .c & -S & .s \\
112 assembler & .s & -c & .o \\
113 linker & other & - & a.out \\
119 Thus, a common invocation would be: \tr{ghc -c Foo.hs}
121 Note: What the Haskell compiler proper produces depends on whether a
122 native-code generator is used (producing assembly language) or not
125 %The suffix information may be overridden with a \tr{-lang <suf>}
126 %\index{-lang <suf> option} option. This says: process all inputs
127 %files as if they had suffix \pl{<suf>}. [NOT IMPLEMENTED YET]
129 The option \tr{-cpp}\index{-cpp option} must be given for the C
130 pre-processor phase to be run.
132 The option \tr{-E}\index{-E option} runs just the C-preprocessor part
133 of the C-compiling phase, sending the result to stdout [I think]. (For
136 %************************************************************************
138 \subsection[options-optimise]{Optimisation (code improvement)}
139 \index{optimisation (GHC)}
140 \index{improvement, code (GHC)}
142 %************************************************************************
144 The \tr{-O*} options specify convenient ``packages'' of optimisation
145 flags; the \tr{-f*} options described later on specify {\em individual}
146 optimisations to be turned on/off; the \tr{-m*} options specify {\em
147 machine-specific} optimisations to be turned on/off.
149 %----------------------------------------------------------------------
150 \subsubsection[optimise-pkgs]{\tr{-O*}: convenient ``packages'' of optimisation flags.}
151 \index{-O options (GHC)}
153 There are {\em many} options that affect the quality of code produced by
154 GHC. Most people only have a general goal, something like ``Compile
155 quickly'' or ``Make my program run like greased lightning.'' The
156 following ``packages'' of optimisations (or lack thereof) should suffice.
158 Once you choose a \tr{-O*} ``package,'' stick with it---don't chop and
159 change. Modules' interfaces {\em will} change with a shift to a new
160 \tr{-O*} option, and you will have to recompile all importing modules
161 before your program can again be run safely.
164 \item[No \tr{-O*}-type option specified:]
165 \index{-O* not specified}
166 This is taken to mean: ``Please compile quickly; I'm not over-bothered
167 about compiled-code quality.'' So, for example: \tr{ghc -c Foo.hs}
169 \item[\tr{-O} or \tr{-O1}:]
172 \index{optimise normally}
173 Means: ``Generate good-quality code without taking too long about it.''
174 Thus, for example: \tr{ghc -c -O Main.lhs}
178 \index{optimise aggressively}
179 Means: ``Apply every non-dangerous optimisation, even if it means
180 significantly longer compile times.''
182 The avoided ``dangerous'' optimisations are those that can make
183 runtime or space {\em worse} if you're unlucky. They are
184 normally turned on or off individually.
186 As of version~0.26, \tr{-O2} is {\em unlikely} to produce
187 better code than \tr{-O}.
191 % \index{optimise minimally}
192 % [``Oh zero''] Means: ``Turn {\em off} as many optimisations (e.g.,
193 % simplifications) as possible.'' This is the only optimisation level
194 % at which the GCC-register-trickery is turned off. {\em You can't use
195 % it unless you have a suitably-built Prelude to match.} Intended for
196 % hard-core debugging.
199 \index{-fvia-C option}
200 Compile via C, and don't use the native-code generator.
201 (There are many cases when GHC does this on its own.) You might
202 pick up a little bit of speed by compiling via C. If you use
203 \tr{_ccall_}s or \tr{_casm_}s, you probably {\em have to} use
206 \item[\tr{-O2-for-C}:]
207 \index{-O2-for-C option}
208 Says to run GCC with \tr{-O2}, which may be worth a few percent in
209 execution speed. Don't forget \tr{-fvia-C}, lest you use the
210 native-code generator and bypass GCC altogether!
214 \index{optimising, reset}
215 This option will make GHC ``forget'' any -Oish options it has seen
216 so far. Sometimes useful; for example: \tr{make all EXTRA_HC_OPTS=-Onot}.
218 \item[\tr{-Ofile <file>}:]
219 \index{-Ofile <file> option}
220 \index{optimising, customised}
221 For those who need {\em absolute} control over {\em exactly} what
222 options are used (e.g., compiler writers, sometimes :-), a list of
223 options can be put in a file and then slurped in with \tr{-Ofile}.
225 In that file, comments are of the \tr{#}-to-end-of-line variety; blank
226 lines and most whitespace is ignored.
228 Please ask if you are baffled and would like an example of \tr{-Ofile}!
231 At Glasgow, we don't use a \tr{-O*} flag for day-to-day work. We use
232 \tr{-O} to get respectable speed; e.g., when we want to measure
233 something. When we want to go for broke, we tend to use
234 \tr{-O -fvia-C -O2-for-C} (and we go for lots of coffee breaks).
236 %Here is a table to summarise whether pragmatic interface information
237 %is used or not, whether the native-code generator is used (if
238 %available), and whether we use GCC register tricks (for speed!) on the
241 %\begin{tabular}{lccl}
242 %\tr{-O*} & Interface & Native code & `Registerised' C \\
243 % & pragmas? & (if avail.) & (if avail.) \\ \hline
245 %\pl{<none>} & no & yes & yes, only if \tr{-fvia-C} \\
246 %\tr{-O,-O1} & yes & yes & yes, only if \tr{-fvia-C} \\
247 %\tr{-O2} & yes & no & yes \\
248 %\tr{-Ofile} & yes & yes & yes, only if \tr{-fvia-C} \\
251 The easiest way to see what \tr{-O} (etc) ``really mean'' is to run
252 with \tr{-v}, then stand back in amazement.
253 Alternatively, just look at the
254 \tr{@HsC_minus<blah>} lists in the \tr{ghc} driver script.
256 %----------------------------------------------------------------------
257 \subsubsection{\tr{-f*}: platform-independent flags}
258 \index{-f* options (GHC)}
259 \index{-fno-* options (GHC)}
261 Flags can be turned {\em off} individually. (NB: I hope
262 you have a good reason for doing this....) To turn off the \tr{-ffoo}
263 flag, just use the \tr{-fno-foo} flag.\index{-fno-<opt> anti-option}
264 So, for example, you can say
265 \tr{-O2 -fno-strictness}, which will then drop out any running of the
268 The options you are most likely to want to turn off are:
269 \tr{-fno-update-analysis}\index{-fno-update-analysis option} [because
270 it is sometimes slow],
271 \tr{-fno-strictness}\index{-fno-strictness option} (strictness
272 analyser [because it is sometimes slow]),
273 \tr{-fno-specialise}\index{-fno-specialise option} (automatic
274 specialisation of overloaded functions [because it makes your code
275 bigger]) [US spelling also accepted],
277 \tr{-fno-foldr-build}\index{-fno-foldr-build option} [because no-one
278 knows what Andy Gill made it do].
280 Should you wish to turn individual flags {\em on}, you are advised to
281 use the \tr{-Ofile} option, described above. Because the order in
282 which optimisation passes are run is sometimes crucial, it's quite
283 hard to do with command-line options.
285 Here are some ``dangerous'' optimisations you {\em might} want to try:
287 %------------------------------------------------------------------
288 \item[\tr{-funfolding-creation-threshold<n>}:]
289 (Default: 30) By raising or lowering this number, you can raise or lower the
290 amount of pragmatic junk that gets spewed into interface files.
291 (An unfolding has a ``size'' that reflects the cost in terms of ``code
292 bloat'' of expanding that unfolding in another module. A bigger
293 Core expression would be assigned a bigger cost.)
295 \item[\tr{-funfolding-use-threshold<n>}:]
296 (Default: 3) By raising or lowering this number, you can make the
297 compiler more or less keen to expand unfoldings.
299 OK, folks, these magic numbers `30' and `3' are mildly arbitrary; they
300 are of the ``seem to be OK'' variety. The `3' is the more critical
301 one; it's what determines how eager GHC is about expanding unfoldings.
303 \item[\tr{-funfolding-override-threshold<n>}:]
304 (Default: 8) [Pretty obscure]
305 When deciding what unfoldings from a module should be made available
306 to the rest of the world (via this module's interface), the compiler
307 normally likes ``small'' expressions.
309 For example, if it sees \tr{foo = bar}, it will decide that the very
310 small expression \tr{bar} is a great unfolding for \tr{foo}. But if
311 \tr{bar} turns out to be \tr{(True,False,True)}, we would probably
312 prefer {\em that} for the unfolding for \tr{foo}.
314 Should we ``override'' the initial small unfolding from \tr{foo=bar}
315 with the bigger-but-better one? Yes, if the bigger one's ``size'' is
316 still under the ``override threshold.'' You can use this flag to
317 adjust this threshold (why, I'm not sure).
319 \item[\tr{-fliberated-case-threshold<n>}:]
320 (Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
321 ``Case liberation'' lifts evaluation out of recursive functions; it
322 does this by duplicating code. Done without constraint, you can get
323 serious code bloat; so we only do it if the ``size'' of the duplicated
324 code is smaller than some ``threshold.'' This flag can fiddle that
327 \item[\tr{-fsemi-tagging}:]
328 This option (which {\em does not work} with the native-code generator)
329 tells the compiler to add extra code to test for already-evaluated
330 values. You win if you have lots of such values during a run of your
331 program, you lose otherwise. (And you pay in extra code space.)
333 We have not played with \tr{-fsemi-tagging} enough to recommend it.
334 (For all we know, it doesn't even work in 0.26. Sigh.)
337 %----------------------------------------------------------------------
338 % \subsubsection[optimise-simplifier]{Controlling ``simplification'' in the Haskell compiler.}
340 %Almost everyone turns program transformation
341 % (a.k.a. ``simplification'') on/off via one of the ``packages'' above,
342 %but you can exert absolute control if you want to. Do a \tr{ghc -v -O ...},
343 %and you'll see there are plenty of knobs to turn!
345 %The Core-to-Core and STG-to-STG passes can be run multiple times, and
346 %in varying orders (though you may live to regret it). The on-or-off
347 %global flags, however, are simply, well, on or off.
349 %The best way to give an exact list of options is the \tr{-Ofile}
350 %option, described elsewhere.
352 % [Check out \tr{ghc/compiler/simplCore/SimplCore.lhs} and
353 %\tr{simplStg/SimplStg.lhs} if you {\em really} want to see every
354 %possible Core-to-Core and STG-to-STG pass, respectively. The
355 %on-or-off global flags that effect what happens {\em within} one of
356 %these passes are defined by the \tr{GlobalSwitch} datatype in
357 %\tr{compiler/main/CmdLineOpts.lhs}.]
359 %----------------------------------------------------------------------
360 \subsubsection{\tr{-m*}: platform-specific flags}
361 \index{-m* options (GHC)}
362 \index{platform-specific options}
363 \index{machine-specific options}
365 Some flags only make sense for particular target platforms.
368 \item[\tr{-mlong-calls}:]
369 (HPPA machines)\index{-mlong-calls option (HPPA only)}
370 Means to pass the like-named option to GCC. Required for Very Big
371 modules, maybe. (Probably means you're in trouble...)
373 \item[\tr{-monly-[432]-regs}:]
374 (iX86 machines)\index{-monly-N-regs option (iX86 only)}
375 GHC tries to ``steal'' five registers from GCC, for performance
376 reasons; it almost always works. However, when GCC is compiling some
377 modules with five stolen registers, it will crash, probably saying:
379 Foo.hc:533: fixed or forbidden register was spilled.
380 This may be due to a compiler bug or to impossible asm
381 statements or clauses.
383 Just give some registers back with \tr{-monly-N-regs}. Try `4' first,
384 then `3', then `2'. If `2' doesn't work, please report the bug to us.
387 %----------------------------------------------------------------------
388 \subsubsection[optimise-C-compiler]{Code improvement by the C compiler.}
389 \index{optimisation by GCC}
390 \index{GCC optimisation}
392 The C~compiler, normally GCC, is run with \tr{-O} turned on. (It has
395 If you want to run GCC with \tr{-O2}---which may be worth a few
396 percent in execution speed---you can give a
397 \tr{-O2-for-C}\index{-O2-for-C option} option.
399 %If you are brave or foolish, you might want to omit some checking code
400 % (e.g., for stack-overflow checks), as sketched in
401 %\sectionref{omit-checking}.
403 %************************************************************************
405 \subsection[options-sanity]{Sanity-checking options}
406 \index{sanity-checking options}
408 %************************************************************************
410 If you would like GHC to check that every top-level value has a type
411 signature, use the \tr{-fsignatures-required}
412 option.\index{-fsignatures-required option}
414 If you would like to disallow ``name shadowing,'' i.e., an inner-scope
415 value has the same name as an outer-scope value, then use the
416 \tr{-fname-shadowing-not-ok}
417 option.\index{-fname-shadowing-not-ok option}
418 This option catches typographical errors that turn into hard-to-find
419 bugs, e.g., in the inadvertent cyclic definition \tr{let x = ... x ... in}.
421 Consequently, this option does {\em not} allow cyclic recursive
424 If you're feeling really paranoid, the \tr{-dcore-lint}
425 option\index{-dcore-lint option} is a good choice. It turns on
426 heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
429 %************************************************************************
431 \subsection[options-output]{Re-directing the compilation output(s)}
432 \index{output-directing options}
434 %************************************************************************
436 When compiling a Haskell module, GHC may produce several files of
437 output (usually two).
439 One file is usually an {\em interface file}. If compiling
440 \tr{bar/Foo.hs}, the interface file would normally be \tr{bar/Foo.hi}.
441 The interface output may be directed to another file
442 \tr{bar2/Wurble.iface} with the option
443 \tr{-ohi bar2/Wurble.iface}\index{-ohi <file> option}.
445 To avoid generating an interface file at all, use a \tr{-nohi}
446 option.\index{-nohi option}
448 The compiler does not overwrite an existing \tr{.hi} interface file if
449 the new one is byte-for-byte the same as the old one; this is friendly to
450 \tr{make}. When an interface does change, it is often enlightening to
451 be informed. The \tr{-hi-diffs}\index{-hi-diffs option} option will
452 make \tr{ghc} run \tr{diff} on the old and new \tr{.hi} files.
454 GHC's non-interface output normally goes into a \tr{.hc}, \tr{.o},
455 etc., file, depending on the last-run compilation phase. The option
456 \tr{-o foo}\index{-o option} re-directs the output of that last-run
457 phase to file \tr{foo}.
459 Note: this ``feature'' can be counterintuitive:
460 \tr{ghc -C -o foo.o foo.hs} will put the intermediate C code in the
461 file \tr{foo.o}, name notwithstanding!
463 EXOTICA: But the \tr{-o} option isn't much use if you have {\em
464 several} input files... Non-interface output files are normally put
465 in the same directory as their corresponding input file came from.
466 You may specify that they be put in another directory using the
467 \tr{-odir <dir>}\index{-odir <dir> option} (the ``Oh, dear'' option).
471 % ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
474 The output files, \tr{Foo.o}, \tr{Bar.o}, and \tr{Bumble.o} would be
475 put into a subdirectory named after the architecture of the executing
476 machine (\tr{sun4}, \tr{mips}, etc). The directory must already
477 exist; it won't be created.
479 Note that the \tr{-odir} option does {\em not} affect where the
480 interface files are put. In the above example, they would still be
481 put in \tr{parse/Foo.hi}, \tr{parse/Bar.hi}, and
482 \tr{gurgle/Bumble.hi}.
484 MORE EXOTICA: The \tr{-osuf <suffix>}\index{-osuf <suffix> option}
485 will change the \tr{.o} file suffix for object files to whatever
486 you specify. (We use this in compiling the prelude.)
488 Similarly, the \tr{-hisuf <suffix>}\index{-hisuf <suffix> option} will
489 change the \tr{.hi} file suffix for non-system interface files. This
490 can be useful when you are trying to compile a program several ways,
491 all in the same directory. The suffix given is used for {\em all}
492 interfaces files written, {\em and} for all non-system interface files
495 The \tr{-hisuf}/\tr{-osuf} game is useful if you want to compile a
496 program with both GHC and HBC (say) in the same directory. Let HBC
497 use the standard \tr{.hi}/\tr{.o} suffixes; add
498 \tr{-hisuf _g.hi -osuf _g.o} to your \tr{make} rule for GHC compiling...
500 % THIS SHOULD HAPPEN AUTOMAGICALLY:
501 % If you want to change the suffix looked for on system-supplied
502 % interface files (notably the \tr{Prelude.hi} file), use the
503 % \tr{-hisuf-prelude <suffix>}\index{-hisuf-prelude <suffix> option}
504 % option. (This may be useful if you've built GHC in various funny
505 % ways, and you are running tests in even more funny ways. It happens.)
507 FURTHER EXOTICA: If you are doing a normal \tr{.hs}-to-\tr{.o} compilation
508 but would like to hang onto the intermediate \tr{.hc} C file, just
509 throw in a \tr{-keep-hc-file-too} option\index{-keep-hc-file-too option}.
510 If you would like to look at the assembler output, toss in a
511 \tr{-keep-s-file-too},\index{-keep-hc-file-too option} too.
513 SAVING GHC STDERR OUTPUT: Sometimes, you may cause GHC to be rather
514 chatty on standard error; with \tr{-fshow-import-specs}, for example.
515 You can instruct GHC to {\em append} this output to a particular log
516 file with a \tr{-odump <blah>}\index{-odump <blah> option} option.
518 TEMPORARY FILES: If you have trouble because of running out of space
519 in \tr{/tmp/} (or wherever your installation thinks temporary files
520 should go), you may use the \tr{-tmpdir <dir>}\index{-tmpdir <dir> option}
521 option to specify an alternate directory. For example, \tr{-tmpdir .}
522 says to put temporary files in the current working directory.
524 BETTER IDEA FOR TEMPORARY FILES: Use your \tr{TMPDIR} environment
525 variable.\index{TMPDIR environment variable} Set it to the name of
526 the directory where temporary files should be put. GCC and other
527 programs will honour the \tr{TMPDIR} variable as well.
529 EVEN BETTER IDEA: Configure GHC with \tr{--with-tmpdir=<mumble>} when
530 you build it, and never worry about \tr{TMPDIR} again.
532 %************************************************************************
534 \subsection[options-finding-imports-etc]{For finding interface files, etc.}
535 \index{interface files, finding them}
536 \index{finding interface files}
538 %************************************************************************
540 In your program, you import a module \tr{Foo} by saying
541 \tr{import Foo}. GHC goes looking for an interface file, \tr{Foo.hi}.
542 It has a builtin list of directories (notably including \tr{.}) where
545 The \tr{-i<dirs>} option\index{-i<dirs> option} prepends a
546 colon-separated list of \tr{dirs} to the ``import directories'' list.
548 A plain \tr{-i} resets the ``import directories'' list back to nothing.
550 GHC normally imports \tr{PreludeCore.hi} and \tr{Prelude.hi} files for
551 you. If you'd rather it didn't, then give it a
552 \tr{-fno-implicit-prelude} option\index{-fno-implicit-prelude option}.
553 (Sadly, it still has to {\em find} a \tr{PreludeNull_.hi} file; it
554 just won't feed it into the compiler proper.) You are unlikely to get
555 very far without a Prelude, but, hey, it's a free country.
557 If you are using a system-supplied non-Prelude library (e.g., the HBC
558 library), just use a \tr{-syslib hbc}\index{-syslib <lib> option}
559 option (for example). The right interface files should then be
562 Once a Haskell module has been compiled to C (\tr{.hc} file), you may
563 wish to specify where GHC tells the C compiler to look for \tr{.h}
564 files. (Or, if you are using the \tr{-cpp} option\index{-cpp option},
565 where it tells the C pre-processor to look...) For this purpose, use
566 a \tr{-I<dir>}\index{-I<dir> option} in the usual C-ish way.
568 Pragmas: Interface files are normally jammed full of
569 compiler-produced {\em pragmas}, which record arities, strictness
570 info, etc. If you think these pragmas are messing you up (or you are
571 doing some kind of weird experiment), you can tell GHC to ignore them
572 with the \tr{-fignore-interface-pragmas}\index{-fignore-interface-pragmas option}
575 See also \sectionref{options-linker}, which describes how the linker
576 finds standard Haskell libraries.
578 %************************************************************************
580 %\subsection[options-names]{Fiddling with namespaces}
582 %************************************************************************
584 %-split-objs and -fglobalise-toplev-names. You don't need them and you
585 %don't want to know; used for the prelude (ToDo).
587 %************************************************************************
589 \subsection[options-CPP]{Related to the C pre-processor}
590 \index{C pre-processor options}
591 \index{pre-processor (cpp) options}
593 %************************************************************************
595 The C pre-processor \tr{cpp} is run over your Haskell code only if the
596 \tr{-cpp} option \index{-cpp option} is given. Unless you are
597 building a large system with significant doses of conditional
598 compilation, you really shouldn't need it.
601 \index{-D<name> option}
602 Define macro \tr{<foo>} in the usual way. NB: does {\em not} affect
603 \tr{-D} macros passed to the C~compiler when compiling via C! For
604 those, use the \tr{-optc-Dfoo} hack...
607 \index{-U<name> option}
608 Undefine macro \tr{<foo>} in the usual way.
611 \index{-I<dir> option}
612 Specify a directory in which to look for \tr{#include} files, in
613 the usual UNIX/C way.
616 The \tr{ghc} driver pre-defines several macros:
618 \item[\tr{__HASKELL1__}:]
619 \index{__HASKELL1__ macro}
620 If defined to $n$, that means GHC supports the
621 Haskell language defined in the Haskell report version $1.n$.
624 NB: This macro is set both when pre-processing Haskell source and
625 when pre-processing generated C (\tr{.hc}) files.
627 If you give the \tr{-fhaskell-1.3} flag\index{-fhaskell-1.3 option},
628 then \tr{__HASKELL1__} is set to 3. Obviously.
630 \item[\tr{__GLASGOW_HASKELL__}:]
631 \index{__GLASGOW_HASKELL__ macro}
632 For version $n$ of the GHC system, this will be \tr{#define}d to
633 $100 \times n$. So, for version~0.26, it is 26.
635 This macro is {\em only} set when pre-processing Haskell source.
636 ({\em Not} when pre-processing generated C.)
638 With any luck, \tr{__GLASGOW_HASKELL__} will be undefined in all other
639 implementations that support C-style pre-processing.
641 (For reference: the comparable symbols for other systems are:
642 \tr{__YALE_HASKELL__} for Yale Haskell, \tr{__HBC__} for Chalmers
643 HBC, and \tr{__GOFER__} for Gofer [I think].)
645 \item[\tr{__CONCURRENT_HASKELL__}:]
646 \index{__CONCURRENT_HASKELL__ macro}
647 Only defined when \tr{-concurrent} is in use!
649 defined when pre-processing Haskell (input) and pre-processing C (GHC
652 \item[\tr{__PARALLEL_HASKELL__}:]
653 \index{__PARALLEL_HASKELL__ macro}
654 Only defined when \tr{-parallel} is in use! This symbol is defined when
655 pre-processing Haskell (input) and pre-processing C (GHC output).
658 Options other than the above can be forced through to the C
659 pre-processor with the \tr{-opt} flags (see
660 \sectionref{forcing-options-through}).
662 A small word of warning: \tr{-cpp} is not friendly to
663 ``string gaps''.\index{-cpp vs string gaps}\index{string gaps vs -cpp}
666 %************************************************************************
668 \subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
669 \index{C compiler options}
672 %************************************************************************
674 At the moment, quite a few common C-compiler options are passed on
675 quietly to the C compilation of Haskell-compiler-generated C files.
676 THIS MAY CHANGE. Meanwhile, options so sent are:
679 \tr{-Wall} & get all warnings from GCC \\
680 \tr{-ansi} & do ANSI C (not K\&R) \\
681 \tr{-pedantic} & be so\\
682 \tr{-dgcc-lint} & (hack) short for ``make GCC very paranoid''\\
684 \index{-Wall option (for GCC)}
685 \index{-ansi option (for GCC)}
686 \index{-pedantic option (for GCC)}
687 \index{-dgcc-lint option (GCC paranoia)}
689 If you are compiling with lots of \tr{ccalls}, etc., you may need to
690 tell the C~compiler about some \tr{#include} files. There is no
691 pretty way to do this, but you can use this hack from the
694 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
696 \index{-#include <file> option}
698 %************************************************************************
700 %\subsection[options-native-code]{Options affecting the native-code generator(s)}
702 %************************************************************************
704 %The only option is to select the target architecture. Right now,
705 %you have only at most one choice: \tr{-fasm-sparc}.\index{-fasm-<target> option}
707 %EXPECT this native-code stuff to change in the future.
709 %************************************************************************
711 \subsection[options-linker]{Linking and consistency-checking}
712 \index{linker options}
715 %************************************************************************
717 GHC has to link your code with various libraries, possibly including:
718 user-supplied, GHC-supplied, and system-supplied (\tr{-lm} math
719 library, for example).
723 \index{-l<lib> option}
724 Link in a library named \tr{lib<FOO>.a} which resides somewhere on the
725 library directories path.
727 Because of the sad state of most UNIX linkers, the order of such
728 options does matter. Thus: \tr{ghc -lbar *.o} is almost certainly
729 wrong, because it will search \tr{libbar.a} {\em before} it has
730 collected unresolved symbols from the \tr{*.o} files.
731 \tr{ghc *.o -lbar} is probably better.
733 The linker will of course be informed about some GHC-supplied
734 libraries automatically; these are:
737 -l equivalent & description \\ \hline
739 -lHSrts,-lHSclib & basic runtime libraries \\
740 -lHS & standard Prelude library \\
741 -lgmp & GNU multi-precision library (for Integers)\\
744 \index{-lHSrts library}
745 \index{-lgmp library}
747 \item[\tr{-syslib <name>}:]
748 \index{-syslib <name> option}
750 If you are using an optional GHC-supplied library (e.g., the HBC
751 library), just use the \tr{-syslib hbc} option, and the correct code
754 Please see \sectionref{syslibs} for information about optional
755 GHC-supplied libraries.
758 \index{-L<dir> option}
759 Where to find user-supplied libraries... Prepend the directory
760 \tr{<dir>} to the library directories path.
763 \index{-static option}
764 Tell the linker to avoid shared libraries.
766 \item[\tr{-no-link-chk} and \tr{-link-chk}:]
767 \index{-no-link-chk option}
768 \index{-link-chk option}
769 \index{consistency checking of executables}
770 By default, immediately after linking an executable, GHC verifies that
771 the pieces that went into it were compiled with compatible flags; a
772 ``consistency check''.
773 (This is to avoid mysterious failures caused by non-meshing of
774 incompatibly-compiled programs; e.g., if one \tr{.o} file was compiled
775 for a parallel machine and the others weren't.) You may turn off this
776 check with \tr{-no-link-chk}. You can turn it (back) on with
777 \tr{-link-chk} (the default).
780 %************************************************************************
782 \subsection[options-compiler-RTS]{For the compiler's RTS: heap, stack sizes, etc.}
783 \index{heap-size options (for GHC)}
784 \index{stack-size options (for GHC)}
786 %************************************************************************
788 The compiler is itself a Haskell program, so it has a tweakable
789 runtime-system (RTS), just like any other Haskell program.
792 \item[\tr{-H<size>} or \tr{-Rmax-heapsize <size>}:]
793 \index{-H<size> option}
794 \index{-Rmax-heapsize <size> option}
795 Don't use more than \tr{<size>} {\em bytes} for heap space. If more
796 than one of these arguments is given, the largest will be taken.
798 A size of zero can be used to reset the heap size downwards. For
799 example, to run GHC with a heap of 250KB (the default is 6MB), do
802 \item[\tr{-K<size>} or \tr{-Rmax-stksize <size>}:]
803 \index{-K<size> option}
804 \index{-Rmax-stksize <size> option}
805 Set the stack space to \tr{<size>} bytes. If you have to set it very
806 high [a megabyte or two, say], the compiler is probably looping, which
807 is a BUG (please report).
809 A size of zero can be used to rest the stack size downwards, as above.
811 \item[\tr{-Rscale-sizes<factor>}:]
812 \index{-Rscale-sizes<factor> option}
813 Multiply the given (or default) heap and stack sizes by \tr{<factor>}.
814 For example, on a DEC Alpha (a 64-bit machine), you might want to
815 double those space sizes; just use \tr{-Rscale-sizes2}.
817 A non-integral factor is OK, too: \tr{-Rscale-sizes1.2}.
819 \item[\tr{-Rghc-timing}:]
820 \index{-Rghc-timing option}
821 Reports a one-line useful collection of time- and space- statistics
822 for a module's compilation.
824 \item[\tr{-Rgc-stats}:]
825 \index{-Rgc-stats option}
826 Report garbage-collection statistics. It will create a
827 \tr{<foo>.stat} file, in some obvious place (I hope).
829 Alternatively, if you'd rather the GC stats went straight to standard
830 error, you can ``cheat'' by using, instead: \tr{-optCrts-Sstderr}.
834 Tell the compiler it has an HBC-style RTS; i.e., it was compiled with
835 HBC. Not used in Real Life.
839 Tell the compiler it has a GHC-style RTS; i.e., it was compiled with
840 GHC. Not used in Real Life.
843 For all \tr{<size>}s: If the last character of \tr{size} is a K,
844 multiply by 1000; if an M, by 1,000,000; if a G, by 1,000,000,000.
845 Sizes are always in {\em bytes}, not words. Good luck on the G's (I
846 think the counter is still only 32-bits [WDP])!
848 %************************************************************************
850 %\subsection[options-cross-compiling]{For cross-compiling to another architecture}
852 %************************************************************************
854 % (We do this for GRIP at Glasgow; it's hacked in---not proper
855 %cross-compiling support. But you could do the same, if required...)
857 %The \tr{-target <arch>} option\index{-target <arch> option} says to
858 %generate code for the \tr{<arch>} architecture.
860 %************************************************************************
862 \subsection[options-parallel]{For Concurrent and Parallel Haskell}
864 %************************************************************************
866 For the full story on using GHC for concurrent \& parallel Haskell
867 programming, please see \Sectionref{concurrent-and-parallel}.
869 %The \tr{-fparallel} option\index{-fparallel option} tells the compiler
870 %to generate code for parallel execution. The \tr{-mgrip}
871 %option\index{-mgrip option} says that the code should be explicitly
872 %suitable for the GRIP multiprocessor (the one in our Glasgow basement).
874 %************************************************************************
876 \subsection[options-experimental]{For experimental purposes}
877 \index{experimental options}
879 %************************************************************************
881 From time to time, we provide GHC options for ``experimenting.'' Easy
882 come, easy go. In version~0.26, the ``experimental'' options are:
884 \item[\tr{-firrefutable-tuples} option:]
885 \index{-firrefutable-tuples option (experimental)}
886 Pretend that every tuple pattern is irrefutable; i.e., has a
887 ``twiddle'' (\tr{~}) in front of it.
889 Some parts of the GHC system {\em depend} on strictness properties which
890 \tr{-firrefutable-tuples} may undo, notably the low-level state-transformer
891 stuff, which includes I/O (!). You're on your own...
893 \item[\tr{-fall-strict} option:]
894 \index{-fall-strict option (experimental)}
895 (DOESN'T REALLY WORK, I THINK) Changes the strictness analyser so
896 that, when it asks the question ``Is this function argument certain to
897 be evaluated?'', the answer is always ``yes''.
899 Compilation is changed in no other way.
901 % -firrefutable-everything
904 %************************************************************************
906 \subsection[options-debugging]{For debugging the compiler}
907 \index{debugging options (for GHC)}
909 %************************************************************************
911 HACKER TERRITORY. HACKER TERRITORY.
914 %----------------------------------------------------------------------
915 \subsubsection[replacing-phases]{Replacing the program for one or more phases.}
916 \index{GHC phases, changing}
917 \index{phases, changing GHC}
919 You may specify that a different program
920 be used for one of the phases of the compilation system, in place of
921 whatever the driver \tr{ghc} has wired into it. For example, you
922 might want to test a replacement parser. The
923 \tr{-pgm<phase-code><program-name>}\index{-pgm<phase><stuff> option} option to
924 \tr{ghc} will cause it to use \pl{<program-name>} for phase
925 \pl{<phase-code>}, where the codes to indicate the phases are:
928 code & phase \\ \hline
929 L & literate pre-processor \\
930 P & C pre-processor (if -cpp only) \\
932 C & Haskell compiler \\
933 cO & C compiler for `optimised' (normal) compiling \\
934 c & C compiler for `unregisterised' compiling \\
939 If you use the ambiguous \tr{-pgmcOle}, it will take it to mean
940 ``use program \tr{le} for optimised C compiling.''
942 %----------------------------------------------------------------------
943 \subsubsection[forcing-options-through]{Forcing options to a particular phase.}
944 \index{forcing GHC-phase options}
946 The preceding sections describe driver options that are mostly
947 applicable to one particular phase. You may also {\em force} a
948 specific option \tr{<option>} to be passed to a particular phase
949 \tr{<phase-code>} by feeding the driver the option
950 \tr{-opt<phase-code><option>}.\index{-opt<phase><stuff> option} The
951 codes to indicate the phases are the same as in the previous section.
953 So, for example, to force an \tr{-Ewurble} option to the assembler, you
954 would tell the driver \tr{-opta-Ewurble} (the dash before the E is
957 Besides getting options to the Haskell compiler with \tr{-optC<blah>},
958 you can get options through to its runtime system with
959 \tr{-optCrts<blah>}\index{-optCrts<blah> option}.
961 So, for example: when I want to use my normal driver but with my
962 profiled compiler binary, I use this script:
965 exec /local/grasp_tmp3/partain/ghc-BUILDS/working-alpha/ghc/driver/ghc \
966 -pgmC/local/grasp_tmp3/partain/ghc-BUILDS/working-hsc-prof/hsc \
972 %----------------------------------------------------------------------
973 \subsubsection[dumping-output]{Dumping out compiler intermediate structures}
974 \index{dumping GHC intermediates}
975 \index{intermediate passes, output}
980 Don't bother generating C output {\em or} an interface file. Usually
981 used in conjunction with one or more of the \tr{-ddump-*} options; for
982 example: \tr{ghc -noC -ddump-simpl Foo.hs}
986 {\em Do} generate an interface file. This would normally be used in
987 conjunction with \tr{-noC}, which turns off interface generation;
990 \item[\tr{-ddump-parser}:]
991 \index{-ddump-parser option}
992 This debugging option shows the exact prefix-form Haskell that is fed
993 into the Haskell compiler proper.
995 \item[\tr{-ddump-<pass>}:]
996 \index{-ddump-<pass> options}
997 Make a debugging dump after pass \tr{<pass>} (may be common enough to
998 need a short form...). Some of the most useful ones are:
1001 \tr{-ddump-rif2hs} & reader output (earliest stuff in the compiler) \\
1002 \tr{-ddump-rn4} & renamer output \\
1003 \tr{-ddump-tc} & typechecker output \\
1004 \tr{-ddump-deriv} & derived instances \\
1005 \tr{-ddump-ds} & desugarer output \\
1006 \tr{-ddump-simpl} & simplifer output (Core-to-Core passes) \\
1007 & (and don't forget \tr{-O}, too!) \\
1008 \tr{-ddump-stranal} & strictness analyser output \\
1009 & (only works in conjunction with -ddump-simpl)\\
1010 \tr{-ddump-occur-anal} & `occurrence analysis' output \\
1011 & (only works in conjunction with -ddump-simpl)\\
1012 \tr{-ddump-spec} & dump specialisation info \\
1013 \tr{-ddump-stg} & output of STG-to-STG passes \\
1014 \tr{-ddump-absC} & {\em un}flattened Abstract~C \\
1015 \tr{-ddump-flatC} & {\em flattened} Abstract~C \\
1016 \tr{-ddump-realC} & same as what goes to the C compiler \\
1017 \tr{-ddump-asm} & assembly language from the native-code generator \\
1019 \index{-ddump-rif2hs option}%
1020 \index{-ddump-rn4 option}%
1021 \index{-ddump-tc option}%
1022 \index{-ddump-deriv option}%
1023 \index{-ddump-ds option}%
1024 \index{-ddump-simpl option}%
1025 \index{-ddump-stranal option}%
1026 \index{-ddump-occur-anal option}%
1027 \index{-ddump-spec option}%
1028 \index{-ddump-stg option}%
1029 \index{-ddump-absC option}%
1030 \index{-ddump-flatC option}%
1031 \index{-ddump-realC option}%
1032 \index{-ddump-asm option}
1034 %For any other \tr{-ddump-*} options: consult the source, notably
1035 %\tr{ghc/compiler/main/CmdLineOpts.lhs}.
1037 \item[\tr{-dverbose-simpl} and \tr{-dverbose-stg}:]
1038 \index{-dverbose-simpl option}
1039 \index{-dverbose-stg option}
1040 Show the output of the intermediate Core-to-Core and STG-to-STG
1041 passes, respectively. ({\em Lots} of output!) So: when we're
1044 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
1047 \item[\tr{-dppr-{user,debug,all}}:]
1048 \index{-dppr-user option}
1049 \index{-dppr-debug option}
1050 \index{-dppr-all option}
1051 Debugging output is in one of several ``styles.'' Take the printing
1052 of types, for example. In the ``user'' style, the compiler's internal
1053 ideas about types are presented in Haskell source-level syntax,
1054 insofar as possible. In the ``debug'' style (which is the default for
1055 debugging output), the types are printed in the most-often-desired
1056 form, with explicit foralls, etc. In the ``show all'' style, very
1057 verbose information about the types (e.g., the Uniques on the
1058 individual type variables) is displayed.
1060 \item[\tr{-ddump-raw-asm}:]
1061 \index{-ddump-raw-asm option}
1062 Dump out the assembly-language stuff, before the ``mangler'' gets it.
1064 \item[\tr{-dgc-debug}:]
1065 \index{-dgc-debug option}
1066 Enables some debugging code related to the garbage-collector.
1069 %ToDo: -ddump-asm-insn-counts
1070 %-ddump-asm-globals-info
1072 %----------------------------------------------------------------------
1073 \subsubsection[arity-checking]{Options to insert arity-checking code}
1074 \index{arity checking}
1076 The \tr{-darity-checks}\index{-darity-checks option} option inserts
1077 code to check for arity violations. Unfortunately, it's not that
1078 simple: you have to link with a prelude that was also built with arity
1079 checks. If you have one, then great; otherwise...
1081 The \tr{-darity-checks-C-only}\index{-darity-checks-C-only option}
1082 option inserts the self-same arity checking code into \tr{.hc} files,
1083 but doesn't compile it into the \tr{.o} files. We use this flag with
1084 the \tr{-keep-hc-file-too}\index{-keep-hc-file-too option}, where we
1085 are keeping \tr{.hc} files around for debugging purposes.
1087 %----------------------------------------------------------------------
1088 \subsubsection[omit-checking]{Options to omit checking code}
1089 \index{omitting runtime checks}
1091 By default, the GHC system emits all possible not-too-expensive
1092 runtime checking code. If you are brave or experimenting, you might
1093 want to turn off some of this (not recommended):
1096 -dno-black-holing & won't buy you much (even if it works) \\
1097 -dno-updates & you're crazy if you do this \\
1098 -dno-stk-stubbing & omit stack stubbing (NOT DONE YET) \\
1100 \index{-dno-black-holing option}%
1101 \index{-dno-updates option}%
1102 \index{-dno-stk-stubbing option}
1104 Warning: all very lightly tested, if at all...
1106 %% %************************************************************************
1108 %% \subsection[options-GC]{Choosing a garbage collector}
1110 %% %************************************************************************
1112 %% (Note: you need a Good Reason before launching into this territory.)
1114 %% There are up to four garbage collectors to choose from (it depends how
1115 %% your local system was built); the Appel-style generational collector
1118 %% If you choose a non-default collector, you must specify it both when
1119 %% compiling the modules and when linking them together into an
1120 %% executable. Also, the native-code generator only works with the
1121 %% default collector (a small point to bear in mind).
1123 %% \begin{description}
1124 %% \item[\tr{-gc-ap} option:]
1125 %% \index{-gc-ap option}
1126 %% Appel-like generational collector (the default).
1128 %% \item[\tr{-gc-2s} option:]
1129 %% \index{-gc-2s option}
1130 %% Two-space copying collector.
1132 %% \item[\tr{-gc-1s} option:]
1133 %% \index{-gc-1s option}
1134 %% One-space compacting collector.
1136 %% \item[\tr{-gc-du} option:]
1137 %% \index{-gc-du option}
1138 %% Dual-mode collector (swaps between copying and compacting).
1139 %% \end{description}