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}. Options need not
9 precede filenames: e.g., \tr{ghc *.o -o foo}. All options are
10 processed and then applied to all files; you cannot, for example, invoke
11 \tr{ghc -c -O1 Foo.hs -O2 Bar.hs} to apply different optimisation
12 levels to the files \tr{Foo.hs} and \tr{Bar.hs}. For conflicting
13 options, e.g., \tr{-c -S}, we reserve the right to do anything we
14 want. (Usually, the last one applies.)
16 Options related to profiling, Glasgow extensions to Haskell (e.g.,
17 unboxed values), Concurrent and Parallel Haskell are described in
18 \sectionref{profiling}, \sectionref{glasgow-exts}, and
19 \sectionref{concurrent-and-parallel}, respectively.
21 %************************************************************************
23 \subsection[file-suffixes]{Meaningful file suffixes}
24 \index{suffixes, file}
25 \index{file suffixes for GHC}
27 %************************************************************************
29 File names with ``meaningful'' suffixes (e.g., \tr{.lhs} or \tr{.o})
30 cause the ``right thing'' to happen to those files.
34 \index{lhs suffix@.lhs suffix}
35 A ``literate Haskell'' module.
38 A not-so-literate Haskell module.
41 A Haskell interface file, probably compiler-generated.
44 Intermediate C file produced by the Haskell compiler.
47 A C~file not produced by the Haskell compiler.
50 % C code after it has be preprocessed by the C compiler (using the
54 An assembly-language source file, usually
55 produced by the compiler.
58 An object file, produced by an assembler.
61 Files with other suffixes (or without suffixes) are passed straight
64 %************************************************************************
66 \subsection[options-help]{Help and verbosity options}
67 \index{help options (GHC)}
68 \index{verbose option (GHC)}
70 %************************************************************************
72 A good option to start with is the \tr{-help} (or \tr{-?}) option.
75 GHC spews a long message to standard output and then exits.
77 The \tr{-v}\index{-v option} option makes GHC {\em verbose}: it
78 reports its version number and shows (on stderr) exactly how it invokes each
79 phase of the compilation system. Moreover, it passes
80 the \tr{-v} flag to most phases; each reports
81 its version number (and possibly some other information).
83 Please, oh please, use the \tr{-v} option when reporting bugs!
84 Knowing that you ran the right bits in the right order is always the
85 first thing we want to verify.
87 If you're just interested in the compiler version number, the
88 \tr{--version}\index{--version option} option prints out a
89 one-line string containing the requested info.
91 %************************************************************************
93 \subsection[options-order]{Running the right phases in the right order}
94 \index{order of passes in GHC}
95 \index{pass ordering in GHC}
97 %************************************************************************
99 The basic task of the \tr{ghc} driver is to run each input file
100 through the right phases (parsing, linking, etc.).
102 The first phase to run is determined by the input-file suffix, and the
103 last phase is determined by a flag. If no relevant flag is present,
104 then go all the way through linking. This table summarises:
106 \begin{tabular}{llll}
107 phase of the & suffix saying & flag saying & (suffix of) \\
108 compilation system & ``start here''& ``stop after''& output file \\ \hline
110 literate pre-processor & .lhs & - & - \\
111 C pre-processor (opt.) & - & - & - \\
112 Haskell compiler & .hs & -C, -S & .hc, .s \\
113 C compiler (opt.) & .hc or .c & -S & .s \\
114 assembler & .s & -c & .o \\
115 linker & other & - & a.out \\
121 Thus, a common invocation would be: \tr{ghc -c Foo.hs}
123 Note: What the Haskell compiler proper produces depends on whether a
124 native-code generator is used (producing assembly language) or not
127 %The suffix information may be overridden with a \tr{-lang <suf>}
128 %\index{-lang <suf> option} option. This says: process all inputs
129 %files as if they had suffix \pl{<suf>}. [NOT IMPLEMENTED YET]
131 The option \tr{-cpp}\index{-cpp option} must be given for the C
132 pre-processor phase to be run, that is, the pre-processor will be run
133 over your Haskell source file before continuing.
135 The option \tr{-E}\index{-E option} runs just the pre-processing
136 passes of the compiler, outputting the result on stdout before
137 stopping. If used in conjunction with -cpp, the output is the
138 code blocks of the original (literal) source after having put it
139 through the grinder that is the C pre-processor. Sans \tr{-cpp}, the
140 output is the de-litted version of the original source.
142 The option \tr{-optcpp-E}\index{-optcpp-E option} runs just the
143 pre-processing stage of the C-compiling phase, sending the result to
144 stdout. (For debugging or obfuscation contests, usually.)
146 %************************************************************************
148 \subsection[options-optimise]{Optimisation (code improvement)}
149 \index{optimisation (GHC)}
150 \index{improvement, code (GHC)}
152 %************************************************************************
154 The \tr{-O*} options specify convenient ``packages'' of optimisation
155 flags; the \tr{-f*} options described later on specify {\em individual}
156 optimisations to be turned on/off; the \tr{-m*} options specify {\em
157 machine-specific} optimisations to be turned on/off.
159 %----------------------------------------------------------------------
160 \subsubsection[optimise-pkgs]{\tr{-O*}: convenient ``packages'' of optimisation flags.}
161 \index{-O options (GHC)}
163 There are {\em many} options that affect the quality of code produced by
164 GHC. Most people only have a general goal, something like ``Compile
165 quickly'' or ``Make my program run like greased lightning.'' The
166 following ``packages'' of optimisations (or lack thereof) should suffice.
168 Once you choose a \tr{-O*} ``package,'' stick with it---don't chop and
169 change. Modules' interfaces {\em will} change with a shift to a new
170 \tr{-O*} option, and you may have to recompile a large chunk of all
171 importing modules before your program can again be run
172 safely\sectionref{recomp}.
175 \item[No \tr{-O*}-type option specified:]
176 \index{-O* not specified}
177 This is taken to mean: ``Please compile quickly; I'm not over-bothered
178 about compiled-code quality.'' So, for example: \tr{ghc -c Foo.hs}
180 \item[\tr{-O} or \tr{-O1}:]
183 \index{optimise normally}
184 Means: ``Generate good-quality code without taking too long about it.''
185 Thus, for example: \tr{ghc -c -O Main.lhs}
189 \index{optimise aggressively}
190 Means: ``Apply every non-dangerous optimisation, even if it means
191 significantly longer compile times.''
193 The avoided ``dangerous'' optimisations are those that can make
194 runtime or space {\em worse} if you're unlucky. They are
195 normally turned on or off individually.
197 At the moment, \tr{-O2} is {\em unlikely} to produce
198 better code than \tr{-O}.
202 % \index{optimise minimally}
203 % [``Oh zero''] Means: ``Turn {\em off} as many optimisations (e.g.,
204 % simplifications) as possible.'' This is the only optimisation level
205 % at which the GCC-register-trickery is turned off. {\em You can't use
206 % it unless you have a suitably-built Prelude to match.} Intended for
207 % hard-core debugging.
210 \index{-fvia-C option}
211 \index{-fvia-c option}
212 Compile via C, and don't use the native-code generator.
213 (There are many cases when GHC does this on its own.) You might
214 pick up a little bit of speed by compiling via C. If you use
215 \tr{_ccall_}s or \tr{_casm_}s, you probably {\em have to} use
218 The lower-case incantation, \tr{-fvia-c}, is synonymous.
220 \item[\tr{-O2-for-C}:]
221 \index{-O2-for-C option}
222 Says to run GCC with \tr{-O2}, which may be worth a few percent in
223 execution speed. Don't forget \tr{-fvia-C}, lest you use the
224 native-code generator and bypass GCC altogether!
228 \index{optimising, reset}
229 This option will make GHC ``forget'' any -Oish options it has seen
230 so far. Sometimes useful; for example: \tr{make all EXTRA_HC_OPTS=-Onot}.
232 \item[\tr{-Ofile <file>}:]
233 \index{-Ofile <file> option}
234 \index{optimising, customised}
235 For those who need {\em absolute} control over {\em exactly} what
236 options are used (e.g., compiler writers, sometimes :-), a list of
237 options can be put in a file and then slurped in with \tr{-Ofile}.
239 In that file, comments are of the \tr{#}-to-end-of-line variety; blank
240 lines and most whitespace is ignored.
242 Please ask if you are baffled and would like an example of \tr{-Ofile}!
245 At Glasgow, we don't use a \tr{-O*} flag for day-to-day work. We use
246 \tr{-O} to get respectable speed; e.g., when we want to measure
247 something. When we want to go for broke, we tend to use
248 \tr{-O -fvia-C -O2-for-C} (and we go for lots of coffee breaks).
250 %Here is a table to summarise whether pragmatic interface information
251 %is used or not, whether the native-code generator is used (if
252 %available), and whether we use GCC register tricks (for speed!) on the
255 %\begin{tabular}{lccl}
256 %\tr{-O*} & Interface & Native code & `Registerised' C \\
257 % & pragmas? & (if avail.) & (if avail.) \\ \hline
259 %\pl{<none>} & no & yes & yes, only if \tr{-fvia-C} \\
260 %\tr{-O,-O1} & yes & yes & yes, only if \tr{-fvia-C} \\
261 %\tr{-O2} & yes & no & yes \\
262 %\tr{-Ofile} & yes & yes & yes, only if \tr{-fvia-C} \\
265 The easiest way to see what \tr{-O} (etc) ``really mean'' is to run
266 with \tr{-v}, then stand back in amazement.
267 Alternatively, just look at the
268 \tr{@HsC_minus<blah>} lists in the \tr{ghc} driver script.
270 %----------------------------------------------------------------------
271 \subsubsection{\tr{-f*}: platform-independent flags}
272 \index{-f* options (GHC)}
273 \index{-fno-* options (GHC)}
275 Flags can be turned {\em off} individually. (NB: I hope
276 you have a good reason for doing this....) To turn off the \tr{-ffoo}
277 flag, just use the \tr{-fno-foo} flag.\index{-fno-<opt> anti-option}
278 So, for example, you can say
279 \tr{-O2 -fno-strictness}, which will then drop out any running of the
282 The options you are most likely to want to turn off are:
283 \tr{-fno-strictness}\index{-fno-strictness option} (strictness
284 analyser [because it is sometimes slow]),
285 \tr{-fno-specialise}\index{-fno-specialise option} (automatic
286 specialisation of overloaded functions [because it makes your code
287 bigger]) [US spelling also accepted],
289 \tr{-fno-foldr-build}\index{-fno-foldr-build option}.
291 Should you wish to turn individual flags {\em on}, you are advised to
292 use the \tr{-Ofile} option, described above. Because the order in
293 which optimisation passes are run is sometimes crucial, it's quite
294 hard to do with command-line options.
296 Here are some ``dangerous'' optimisations you {\em might} want to try:
298 %------------------------------------------------------------------
299 \item[\tr{-funfolding-creation-threshold<n>}:]
300 (Default: 30) By raising or lowering this number, you can raise or
301 lower the amount of pragmatic junk that gets spewed into interface
302 files. (An unfolding has a ``size'' that reflects the cost in terms
303 of ``code bloat'' of expanding that unfolding in another module. A
304 bigger Core expression would be assigned a bigger cost.)
306 \item[\tr{-funfolding-use-threshold<n>}:]
307 (Default: 3) By raising or lowering this number, you can make the
308 compiler more or less keen to expand unfoldings.
310 OK, folks, these magic numbers `30' and `3' are mildly arbitrary; they
311 are of the ``seem to be OK'' variety. The `3' is the more critical
312 one; it's what determines how eager GHC is about expanding unfoldings.
314 \item[\tr{-funfolding-override-threshold<n>}:]
315 (Default: 8) [Pretty obscure]
316 When deciding what unfoldings from a module should be made available
317 to the rest of the world (via this module's interface), the compiler
318 normally likes ``small'' expressions.
320 For example, if it sees \tr{foo = bar}, it will decide that the very
321 small expression \tr{bar} is a great unfolding for \tr{foo}. But if
322 \tr{bar} turns out to be \tr{(True,False,True)}, we would probably
323 prefer {\em that} for the unfolding for \tr{foo}.
325 Should we ``override'' the initial small unfolding from \tr{foo=bar}
326 with the bigger-but-better one? Yes, if the bigger one's ``size'' is
327 still under the ``override threshold.'' You can use this flag to
328 adjust this threshold (why, I'm not sure).
330 % \item[\tr{-fliberated-case-threshold<n>}:]
331 % (Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
332 % ``Case liberation'' lifts evaluation out of recursive functions; it
333 % does this by duplicating code. Done without constraint, you can get
334 % serious code bloat; so we only do it if the ``size'' of the duplicated
335 % code is smaller than some ``threshold.'' This flag can fiddle that
338 \item[\tr{-fsemi-tagging}:]
339 This option (which {\em does not work} with the native-code generator)
340 tells the compiler to add extra code to test for already-evaluated
341 values. You win if you have lots of such values during a run of your
342 program, you lose otherwise. (And you pay in extra code space.)
344 We have not played with \tr{-fsemi-tagging} enough to recommend it.
345 (For all we know, it doesn't even work anymore... Sigh.)
348 %----------------------------------------------------------------------
349 % \subsubsection[optimise-simplifier]{Controlling ``simplification'' in the Haskell compiler.}
351 %Almost everyone turns program transformation
352 % (a.k.a. ``simplification'') on/off via one of the ``packages'' above,
353 %but you can exert absolute control if you want to. Do a \tr{ghc -v -O ...},
354 %and you'll see there are plenty of knobs to turn!
356 %The Core-to-Core and STG-to-STG passes can be run multiple times, and
357 %in varying orders (though you may live to regret it). The on-or-off
358 %global flags, however, are simply, well, on or off.
360 %The best way to give an exact list of options is the \tr{-Ofile}
361 %option, described elsewhere.
363 % [Check out \tr{ghc/compiler/simplCore/SimplCore.lhs} and
364 %\tr{simplStg/SimplStg.lhs} if you {\em really} want to see every
365 %possible Core-to-Core and STG-to-STG pass, respectively. The
366 %on-or-off global flags that effect what happens {\em within} one of
367 %these passes are defined by the \tr{GlobalSwitch} datatype in
368 %\tr{compiler/main/CmdLineOpts.lhs}.]
370 %----------------------------------------------------------------------
371 \subsubsection{\tr{-m*}: platform-specific flags}
372 \index{-m* options (GHC)}
373 \index{platform-specific options}
374 \index{machine-specific options}
376 Some flags only make sense for particular target platforms.
380 (SPARC machines)\index{-mv8 option (SPARC only)}
381 Means to pass the like-named option to GCC; it says to use the
382 Version 8 SPARC instructions, notably integer multiply and divide.
383 The similiar \tr{-m*} GCC options for SPARC also work, actually.
385 \item[\tr{-mlong-calls}:]
386 (HPPA machines)\index{-mlong-calls option (HPPA only)}
387 Means to pass the like-named option to GCC. Required for Very Big
388 modules, maybe. (Probably means you're in trouble...)
390 \item[\tr{-monly-[32]-regs}:]
391 (iX86 machines)\index{-monly-N-regs option (iX86 only)}
392 GHC tries to ``steal'' four registers from GCC, for performance
393 reasons; it almost always works. However, when GCC is compiling some
394 modules with four stolen registers, it will crash, probably saying:
396 Foo.hc:533: fixed or forbidden register was spilled.
397 This may be due to a compiler bug or to impossible asm
398 statements or clauses.
400 Just give some registers back with \tr{-monly-N-regs}. Try `3' first,
401 then `2'. If `2' doesn't work, please report the bug to us.
404 %----------------------------------------------------------------------
405 \subsubsection[optimise-C-compiler]{Code improvement by the C compiler.}
406 \index{optimisation by GCC}
407 \index{GCC optimisation}
409 The C~compiler (GCC) is run with \tr{-O} turned on. (It has
412 If you want to run GCC with \tr{-O2}---which may be worth a few
413 percent in execution speed---you can give a
414 \tr{-O2-for-C}\index{-O2-for-C option} option.
416 %If you are brave or foolish, you might want to omit some checking code
417 % (e.g., for stack-overflow checks), as sketched in
418 %\sectionref{omit-checking}.
420 %************************************************************************
422 \subsection[options-sanity]{Warnings and sanity-checking}
423 \index{sanity-checking options}
426 %************************************************************************
428 GHC has a selection of options that select which types of non-fatal
429 error messages, otherwise known as warnings, can be generated during
430 compilation. By default, you get a standard set of warnings which are
431 generally likely to indicate bugs in your program. These are:
432 \tr{-fwarn-overlpapping-patterns} and \tr{-fwarn-missing-methods}.
433 The following flags are simple ways to select standard ``packages'' of
441 Turns off all warnings, including the standard ones.
446 Provides the standard warnings plus \tr{-fwarn-incomplete-patterns}
447 and \tr{-fwarn-unused-names}.
452 Turns on all warning options.
456 The full set of warning options is described below. To turn off any
457 warning, simply give the corresponding \tr{-fno-warn-...} option on
462 \item[\tr{-fwarn-name-shadowing}:]
463 \index{-fwarn-name-shadowing option}
464 \index{shadowing, warning}
466 This option causes a warning to be emitted whenever an inner-scope
467 value has the same name as an outer-scope value, i.e. the inner value
468 shadows the outer one. This can catch typographical errors that turn
469 into hard-to-find bugs, e.g., in the inadvertent cyclic definition
470 \tr{let x = ... x ... in}.
472 Consequently, this option does {\em not} allow cyclic recursive
475 \item[\tr{-fwarn-overlapping-patterns}:]
476 \index{-fwarn-overlapping-patterns option}
477 \index{overlapping patterns, warning}
478 \index{patterns, overlapping}
480 By default, the compiler will warn you if a set of patterns are either
481 incomplete (i.e., you're only matching on a subset of an algebraic
482 data type's constructors), or overlapping, i.e.,
493 where the last pattern match in \tr{f} won't ever be reached, as the
494 second pattern overlaps it. More often than not, redundant patterns
495 is a programmer mistake/error, so this option is enabled by default.
497 \item[\tr{-fwarn-incomplete-patterns}:]
498 \index{-fwarn-incomplete-patterns option}
499 \index{incomplete patterns, warning}
500 \index{patterns, incomplete}
502 Similarly for incomplete patterns, the function \tr{g} will fail when
503 applied to non-empty lists, so the compiler will emit a warning about
504 this when this option is enabled.
506 \item[\tr{-fwarn-missing-methods}:]
507 \index{-fwarn-missing-methods option}
508 \index{methods, missing}
510 This option is on by default, and warns you whenever an instance
511 declaration is missing one or more methods, and the corresponding
512 class declaration has no default declaration for them.
514 \item[\tr{-fwarn-unused-names}:]
515 \index{-fwarn-unused-names}
516 Have the renamer report which locally defined names are not
517 used/exported. This option is not currently supported.
521 If you would like GHC to check that every top-level value has a type
522 signature, use the \tr{-fsignatures-required}
523 option.\index{-fsignatures-required option}
525 If you're feeling really paranoid, the \tr{-dcore-lint}
526 option\index{-dcore-lint option} is a good choice. It turns on
527 heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
530 %************************************************************************
532 \subsection[options-output]{Re-directing the compilation output(s)}
533 \index{output-directing options}
535 %************************************************************************
537 When compiling a Haskell module, GHC may produce several files of
538 output (usually two).
540 One file is usually an {\em interface file}. If compiling
541 \tr{bar/Foo.hs}, the interface file would normally be \tr{bar/Foo.hi}.
542 The interface output may be directed to another file
543 \tr{bar2/Wurble.iface} with the option
544 \tr{-ohi bar2/Wurble.iface}\index{-ohi <file> option} (not recommended).
546 To avoid generating an interface file at all, use a \tr{-nohi}
547 option.\index{-nohi option}
549 The compiler does not overwrite an existing \tr{.hi} interface file if
550 the new one is byte-for-byte the same as the old one; this is friendly to
551 \tr{make}. When an interface does change, it is often enlightening to
552 be informed. The \tr{-hi-diffs}\index{-hi-diffs option} option will
553 make \tr{ghc} run \tr{diff} on the old and new \tr{.hi} files. You can
554 also record the difference in the interface file itself, the
555 \tr{-keep-hi-diffs}\index{-keep-hi-diffs} option takes care of that.
557 The \tr{.hi} files from GHC 2.xx contain ``usage'' information which
558 changes often and uninterestingly. If you really want to see these
559 changes reported, you need to use the
560 \tr{-hi-diffs-with-usages}\index{-hi-diffs-with-usages option} option.
562 GHC's non-interface output normally goes into a \tr{.hc}, \tr{.o},
563 etc., file, depending on the last-run compilation phase. The option
564 \tr{-o foo}\index{-o option} re-directs the output of that last-run
565 phase to file \tr{foo}.
567 Note: this ``feature'' can be counterintuitive:
568 \tr{ghc -C -o foo.o foo.hs} will put the intermediate C code in the
569 file \tr{foo.o}, name notwithstanding!
571 EXOTICA: But the \tr{-o} option isn't of much use if you have {\em
572 several} input files... Non-interface output files are normally put
573 in the same directory as their corresponding input file came from.
574 You may specify that they be put in another directory using the
575 \tr{-odir <dir>}\index{-odir <dir> option} (the ``Oh, dear'' option).
579 % ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
582 The output files, \tr{Foo.o}, \tr{Bar.o}, and \tr{Bumble.o} would be
583 put into a subdirectory named after the architecture of the executing
584 machine (\tr{sun4}, \tr{mips}, etc). The directory must already
585 exist; it won't be created.
587 Note that the \tr{-odir} option does {\em not} affect where the
588 interface files are put. In the above example, they would still be
589 put in \tr{parse/Foo.hi}, \tr{parse/Bar.hi}, and
590 \tr{gurgle/Bumble.hi}.
592 MORE EXOTICA: The \tr{-osuf <suffix>}\index{-osuf <suffix> option}
593 will change the \tr{.o} file suffix for object files to whatever
594 you specify. (We use this in compiling the prelude.)
596 Similarly, the \tr{-hisuf <suffix>}\index{-hisuf <suffix> option} will
597 change the \tr{.hi} file suffix for non-system interface files. This
598 can be useful when you are trying to compile a program several ways,
599 all in the same directory. The suffix given is used for {\em all}
600 interfaces files written, {\em and} for all non-system interface files
603 The \tr{-hisuf}/\tr{-osuf} game is useful if you want to compile a
604 program with both GHC and HBC (say) in the same directory. Let HBC
605 use the standard \tr{.hi}/\tr{.o} suffixes; add
606 \tr{-hisuf g_hi -osuf g_o} to your \tr{make} rule for GHC compiling...
608 NB: {\em A change from 0.26 and before:} Before, you might have said
609 \tr{-hisuf _g.hi -osuf _g.o}; now, the \tr{.} is assumed and you
610 specify what comes {\em after} it. (This is a more portable solution
613 % THIS SHOULD HAPPEN AUTOMAGICALLY:
614 % If you want to change the suffix looked for on system-supplied
615 % interface files (notably the \tr{Prelude.hi} file), use the
616 % \tr{-hisuf-prelude <suffix>}\index{-hisuf-prelude <suffix> option}
617 % option. (This may be useful if you've built GHC in various funny
618 % ways, and you are running tests in even more funny ways. It happens.)
620 FURTHER EXOTICA: If you are doing a normal \tr{.hs}-to-\tr{.o} compilation
621 but would like to hang onto the intermediate \tr{.hc} C file, just
622 throw in a \tr{-keep-hc-file-too} option\index{-keep-hc-file-too option}.
623 If you would like to look at the assembler output, toss in a
624 \tr{-keep-s-file-too},\index{-keep-hc-file-too option} too.
626 SAVING GHC STDERR OUTPUT: Sometimes, you may cause GHC to be rather
627 chatty on standard error; with \tr{-fshow-import-specs}, for example.
628 You can instruct GHC to {\em append} this output to a particular log
629 file with a \tr{-odump <blah>}\index{-odump <blah> option} option.
631 TEMPORARY FILES: If you have trouble because of running out of space
632 in \tr{/tmp/} (or wherever your installation thinks temporary files
633 should go), you may use the \tr{-tmpdir <dir>}\index{-tmpdir <dir> option}
634 option to specify an alternate directory. For example, \tr{-tmpdir .}
635 says to put temporary files in the current working directory.
637 BETTER IDEA FOR TEMPORARY FILES: Use your \tr{TMPDIR} environment
638 variable.\index{TMPDIR environment variable} Set it to the name of
639 the directory where temporary files should be put. GCC and other
640 programs will honour the \tr{TMPDIR} variable as well.
642 EVEN BETTER IDEA: Set the \tr{TMPDIR} variable when building
643 GHC, and never worry about \tr{TMPDIR} again. (see the build
646 %************************************************************************
648 \subsection[options-finding-imports-etc]{For finding interface files, etc.}
649 \index{interface files, finding them}
650 \index{finding interface files}
652 %************************************************************************
654 In your program, you import a module \tr{Foo} by saying
655 \tr{import Foo}. GHC goes looking for an interface file, \tr{Foo.hi}.
656 It has a builtin list of directories (notably including \tr{.}) where
659 The \tr{-i<dirs>} option\index{-i<dirs> option} prepends a
660 colon-separated list of \tr{dirs} to the ``import directories'' list.
662 A plain \tr{-i} resets the ``import directories'' list back to nothing.
664 GHC normally imports \tr{Prelude.hi} files for you. If you'd rather
665 it didn't, then give it a \tr{-fno-implicit-prelude}
666 option\index{-fno-implicit-prelude option}. You are unlikely to get
667 very far without a Prelude, but, hey, it's a free country.
669 If you are using a system-supplied non-Prelude library (e.g., the HBC
670 library), just use a \tr{-syslib hbc}\index{-syslib <lib> option}
671 option (for example). The right interface files should then be
674 Once a Haskell module has been compiled to C (\tr{.hc} file), you may
675 wish to specify where GHC tells the C compiler to look for \tr{.h}
676 files. (Or, if you are using the \tr{-cpp} option\index{-cpp option},
677 where it tells the C pre-processor to look...) For this purpose, use
678 a \tr{-I<dir>}\index{-I<dir> option} in the usual C-ish way.
680 Pragmas: Interface files are normally jammed full of
681 compiler-produced {\em pragmas}, which record arities, strictness
682 info, etc. If you think these pragmas are messing you up (or you are
683 doing some kind of weird experiment), you can tell GHC to ignore them
684 with the \tr{-fignore-interface-pragmas}\index{-fignore-interface-pragmas option}
687 When compiling without optimisations on, the compiler is extra-careful
688 about not slurping in data constructors and instance declarations that
689 it will not need. If you believe it is getting it wrong and not
690 importing stuff which you think it should, this optimisation can be
691 turned off with \tr{-fno-prune-tydecls} and \tr{-fno-prune-instdecls}.
692 \index{-fno-prune-tydecls option}\index{-fno-prune-instdecls}
694 See also \sectionref{options-linker}, which describes how the linker
695 finds standard Haskell libraries.
697 %************************************************************************
699 %\subsection[options-names]{Fiddling with namespaces}
701 %************************************************************************
703 %-split-objs and -fglobalise-toplev-names. You don't need them and you
704 %don't want to know; used for the prelude (ToDo).
706 %************************************************************************
708 \subsection[options-CPP]{Related to the C pre-processor}
709 \index{C pre-processor options}
710 \index{pre-processor (cpp) options}
712 %************************************************************************
714 The C pre-processor \tr{cpp} is run over your Haskell code only if the
715 \tr{-cpp} option \index{-cpp option} is given. Unless you are
716 building a large system with significant doses of conditional
717 compilation, you really shouldn't need it.
720 \index{-D<name> option}
721 Define macro \tr{<foo>} in the usual way. NB: does {\em not} affect
722 \tr{-D} macros passed to the C~compiler when compiling via C! For
723 those, use the \tr{-optc-Dfoo} hack...
726 \index{-U<name> option}
727 Undefine macro \tr{<foo>} in the usual way.
730 \index{-I<dir> option}
731 Specify a directory in which to look for \tr{#include} files, in
735 The \tr{ghc} driver pre-defines several macros:
737 \item[\tr{__HASKELL1__}:]
738 \index{__HASKELL1__ macro}
739 If defined to $n$, that means GHC supports the
740 Haskell language defined in the Haskell report version $1.n$.
743 NB: This macro is set both when pre-processing Haskell source and
744 when pre-processing generated C (\tr{.hc}) files.
746 % If you give the \tr{-fhaskell-1.3} flag\index{-fhaskell-1.3 option},
747 % then \tr{__HASKELL1__} is set to 3. Obviously.
749 \item[\tr{__GLASGOW_HASKELL__}:]
750 \index{__GLASGOW_HASKELL__ macro}
751 For version $n$ of the GHC system, this will be \tr{#define}d to
752 $100 \times n$. So, for version~2.02, it is 202.
754 This macro is {\em only} set when pre-processing Haskell source.
755 ({\em Not} when pre-processing generated C.)
757 With any luck, \tr{__GLASGOW_HASKELL__} will be undefined in all other
758 implementations that support C-style pre-processing.
760 (For reference: the comparable symbols for other systems are:
761 \tr{__HUGS__} for Hugs and \tr{__HBC__} for Chalmers.)
763 \item[\tr{__CONCURRENT_HASKELL__}:]
764 \index{__CONCURRENT_HASKELL__ macro}
765 Only defined when \tr{-concurrent} is in use!
766 This symbol is defined when pre-processing Haskell (input) and
767 pre-processing C (GHC output).
769 \item[\tr{__PARALLEL_HASKELL__}:]
770 \index{__PARALLEL_HASKELL__ macro}
771 Only defined when \tr{-parallel} is in use! This symbol is defined when
772 pre-processing Haskell (input) and pre-processing C (GHC output).
775 Options other than the above can be forced through to the C
776 pre-processor with the \tr{-opt} flags (see
777 \sectionref{forcing-options-through}).
779 A small word of warning: \tr{-cpp} is not friendly to ``string
780 gaps''.\index{-cpp vs string gaps}\index{string gaps vs -cpp}. In
781 other words, strings such as the following:
789 don't work with \tr{-cpp}; \tr{/usr/bin/cpp} elides the
790 backslash-newline pairs.
792 However, it appears that if you add a space at the end of the line,
793 then \tr{cpp} (at least GNU \tr{cpp} and possibly other \tr{cpp}s)
794 leaves the backslash-space pairs alone and the string gap works as
797 %************************************************************************
799 \subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
800 \index{include-file-option}
801 \index{C compiler options}
804 %************************************************************************
806 At the moment, quite a few common C-compiler options are passed on
807 quietly to the C compilation of Haskell-compiler-generated C files.
808 THIS MAY CHANGE. Meanwhile, options so sent are:
811 \tr{-Wall} & get all warnings from GCC \\
812 \tr{-ansi} & do ANSI C (not K\&R) \\
813 \tr{-pedantic} & be so\\
814 \tr{-dgcc-lint} & (hack) short for ``make GCC very paranoid''\\
816 \index{-Wall option (for GCC)}
817 \index{-ansi option (for GCC)}
818 \index{-pedantic option (for GCC)}
819 \index{-dgcc-lint option (GCC paranoia)}
821 If you are compiling with lots of \tr{ccalls}, etc., you may need to
822 tell the C~compiler about some \tr{#include} files. There is no real
823 pretty way to do this, but you can use this hack from the
826 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
830 %************************************************************************
832 %\subsection[options-native-code]{Options affecting the native-code generator(s)}
834 %************************************************************************
836 %The only option is to select the target architecture. Right now,
837 %you have only at most one choice: \tr{-fasm-sparc}.\index{-fasm-<target> option}
839 %EXPECT this native-code stuff to change in the future.
841 %************************************************************************
843 \subsection[options-linker]{Linking and consistency-checking}
844 \index{linker options}
847 %************************************************************************
849 GHC has to link your code with various libraries, possibly including:
850 user-supplied, GHC-supplied, and system-supplied (\tr{-lm} math
851 library, for example).
855 \index{-l<lib> option}
856 Link in a library named \tr{lib<FOO>.a} which resides somewhere on the
857 library directories path.
859 Because of the sad state of most UNIX linkers, the order of such
860 options does matter. Thus: \tr{ghc -lbar *.o} is almost certainly
861 wrong, because it will search \tr{libbar.a} {\em before} it has
862 collected unresolved symbols from the \tr{*.o} files.
863 \tr{ghc *.o -lbar} is probably better.
865 The linker will of course be informed about some GHC-supplied
866 libraries automatically; these are:
869 -l equivalent & description \\ \hline
871 -lHSrts,-lHSclib & basic runtime libraries \\
872 -lHS & standard Prelude library \\
873 -lHS\_cbits & C support code for standard Prelude library \\
874 -lgmp & GNU multi-precision library (for Integers)\\
877 \index{-lHS_cbits library}
878 \index{-lHSrts library}
879 \index{-lgmp library}
881 \item[\tr{-syslib <name>}:]
882 \index{-syslib <name> option}
884 If you are using a Haskell ``system library'' (e.g., the HBC
885 library), just use the \tr{-syslib hbc} option, and the correct code
888 %Please see \sectionref{syslibs} for information about
889 %``system libraries.''
892 \index{-L<dir> option}
893 Where to find user-supplied libraries... Prepend the directory
894 \tr{<dir>} to the library directories path.
897 \index{-static option}
898 Tell the linker to avoid shared libraries.
900 \item[\tr{-no-link-chk} and \tr{-link-chk}:]
901 \index{-no-link-chk option}
902 \index{-link-chk option}
903 \index{consistency checking of executables}
904 By default, immediately after linking an executable, GHC verifies that
905 the pieces that went into it were compiled with compatible flags; a
906 ``consistency check''.
907 (This is to avoid mysterious failures caused by non-meshing of
908 incompatibly-compiled programs; e.g., if one \tr{.o} file was compiled
909 for a parallel machine and the others weren't.) You may turn off this
910 check with \tr{-no-link-chk}. You can turn it (back) on with
911 \tr{-link-chk} (the default).
914 %************************************************************************
916 \subsection[options-compiler-RTS]{For the compiler's RTS: heap, stack sizes, etc.}
917 \index{heap-size options (for GHC)}
918 \index{stack-size options (for GHC)}
920 %************************************************************************
922 The compiler is itself a Haskell program, so it has a tweakable
923 runtime-system (RTS), just like any other Haskell program.
926 \item[\tr{-H<size>} or \tr{-Rmax-heapsize <size>}:]
927 \index{-H<size> option}
928 \index{-Rmax-heapsize <size> option}
929 Don't use more than \tr{<size>} {\em bytes} for heap space. If more
930 than one of these arguments is given, the largest will be taken.
932 A size of zero can be used to reset the heap size downwards. For
933 example, to run GHC with a heap of 250KB (the default is 6MB), do
936 \item[\tr{-K<size>} or \tr{-Rmax-stksize <size>}:]
937 \index{-K<size> option}
938 \index{-Rmax-stksize <size> option}
939 Set the stack space to \tr{<size>} bytes. If you have to set it very
940 high [a megabyte or two, say], the compiler is probably looping, which
941 is a BUG (please report).
943 A size of zero can be used to rest the stack size downwards, as above.
945 \item[\tr{-Rscale-sizes<factor>}:]
946 \index{-Rscale-sizes<factor> option}
947 Multiply the given (or default) heap and stack sizes by \tr{<factor>}.
948 For example, on a DEC Alpha (a 64-bit machine), you might want to
949 double those space sizes; just use \tr{-Rscale-sizes2}.
951 A non-integral factor is OK, too: \tr{-Rscale-sizes1.2}.
953 \item[\tr{-Rghc-timing}:]
954 \index{-Rghc-timing option}
955 Reports a one-line useful collection of time- and space- statistics
956 for a module's compilation.
958 \item[\tr{-Rgc-stats}:]
959 \index{-Rgc-stats option}
960 Report garbage-collection statistics. It will create a
961 \tr{<foo>.stat} file, in some obvious place (I hope).
963 Alternatively, if you'd rather the GC stats went straight to standard
964 error, you can ``cheat'' by using, instead: \tr{-optCrts-Sstderr}.
967 %\index{-Rhbc option}
968 %Tell the compiler it has an HBC-style RTS; i.e., it was compiled with
969 %HBC. Not used in Real Life.
972 %\index{-Rghc option}
973 %Tell the compiler it has a GHC-style RTS; i.e., it was compiled with
974 %GHC. Not used in Real Life.
977 For all \tr{<size>}s: If the last character of \tr{size} is a K,
978 multiply by 1000; if an M, by 1,000,000; if a G, by 1,000,000,000.
979 Sizes are always in {\em bytes}, not words. Good luck on the G's (I
980 think the counter is still only 32-bits [WDP])!
982 %************************************************************************
984 %\subsection[options-cross-compiling]{For cross-compiling to another architecture}
986 %************************************************************************
988 % (We do this for GRIP at Glasgow; it's hacked in---not proper
989 %cross-compiling support. But you could do the same, if required...)
991 %The \tr{-target <arch>} option\index{-target <arch> option} says to
992 %generate code for the \tr{<arch>} architecture.
994 %************************************************************************
996 \subsection[options-parallel]{For Concurrent and Parallel Haskell}
998 %************************************************************************
1000 For the full story on using GHC for concurrent \& parallel Haskell
1001 programming, please see \Sectionref{concurrent-and-parallel}.
1003 %The \tr{-fparallel} option\index{-fparallel option} tells the compiler
1004 %to generate code for parallel execution. The \tr{-mgrip}
1005 %option\index{-mgrip option} says that the code should be explicitly
1006 %suitable for the GRIP multiprocessor (the one in our Glasgow basement).
1008 %************************************************************************
1010 %\subsection[options-experimental]{For experimental purposes}
1011 %\index{experimental options}
1013 %************************************************************************
1015 %From time to time, we provide GHC options for ``experimenting.'' Easy
1016 %come, easy go. In version~0.26, the ``experimental'' options are:
1017 %\begin{description}
1018 %\item[\tr{-firrefutable-tuples} option:]
1019 %\index{-firrefutable-tuples option (experimental)}
1020 %Pretend that every tuple pattern is irrefutable; i.e., has a
1021 %``twiddle'' (\tr{~}) in front of it.
1023 %Some parts of the GHC system {\em depend} on strictness properties which
1024 %\tr{-firrefutable-tuples} may undo, notably the low-level state-transformer
1025 %stuff, which includes I/O (!). You're on your own...
1027 %\item[\tr{-fall-strict} option:]
1028 %\index{-fall-strict option (experimental)}
1029 % (DOESN'T REALLY WORK, I THINK) Changes the strictness analyser so
1030 %that, when it asks the question ``Is this function argument certain to
1031 %be evaluated?'', the answer is always ``yes''.
1033 %Compilation is changed in no other way.
1036 % -firrefutable-everything
1039 %************************************************************************
1041 \subsection[options-debugging]{For debugging the compiler}
1042 \index{debugging options (for GHC)}
1044 %************************************************************************
1046 HACKER TERRITORY. HACKER TERRITORY.
1049 %----------------------------------------------------------------------
1050 \subsubsection[replacing-phases]{Replacing the program for one or more phases.}
1051 \index{GHC phases, changing}
1052 \index{phases, changing GHC}
1054 You may specify that a different program
1055 be used for one of the phases of the compilation system, in place of
1056 whatever the driver \tr{ghc} has wired into it. For example, you
1057 might want to try a different assembler. The
1058 \tr{-pgm<phase-code><program-name>}\index{-pgm<phase><stuff> option} option to
1059 \tr{ghc} will cause it to use \pl{<program-name>} for phase
1060 \pl{<phase-code>}, where the codes to indicate the phases are:
1063 code & phase \\ \hline
1064 L & literate pre-processor \\
1065 P & C pre-processor (if -cpp only) \\
1066 C & Haskell compiler \\
1072 %----------------------------------------------------------------------
1073 \subsubsection[forcing-options-through]{Forcing options to a particular phase.}
1074 \index{forcing GHC-phase options}
1076 The preceding sections describe driver options that are mostly
1077 applicable to one particular phase. You may also {\em force} a
1078 specific option \tr{<option>} to be passed to a particular phase
1079 \tr{<phase-code>} by feeding the driver the option
1080 \tr{-opt<phase-code><option>}.\index{-opt<phase><stuff> option} The
1081 codes to indicate the phases are the same as in the previous section.
1083 So, for example, to force an \tr{-Ewurble} option to the assembler, you
1084 would tell the driver \tr{-opta-Ewurble} (the dash before the E is
1087 Besides getting options to the Haskell compiler with \tr{-optC<blah>},
1088 you can get options through to its runtime system with
1089 \tr{-optCrts<blah>}\index{-optCrts<blah> option}.
1091 So, for example: when I want to use my normal driver but with my
1092 profiled compiler binary, I use this script:
1095 exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
1096 -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
1102 %----------------------------------------------------------------------
1103 \subsubsection[dumping-output]{Dumping out compiler intermediate structures}
1104 \index{dumping GHC intermediates}
1105 \index{intermediate passes, output}
1110 Don't bother generating C output {\em or} an interface file. Usually
1111 used in conjunction with one or more of the \tr{-ddump-*} options; for
1112 example: \tr{ghc -noC -ddump-simpl Foo.hs}
1116 {\em Do} generate an interface file. This would normally be used in
1117 conjunction with \tr{-noC}, which turns off interface generation;
1118 thus: \tr{-noC -hi}.
1120 \item[\tr{-dshow-passes}:]
1121 \index{-dshow-passes option}
1122 Prints a message to stderr as each pass starts. Gives a warm but
1123 undoubtedly misleading feeling that GHC is telling you what's
1126 \item[\tr{-ddump-<pass>}:]
1127 \index{-ddump-<pass> options}
1128 Make a debugging dump after pass \tr{<pass>} (may be common enough to
1129 need a short form...). Some of the most useful ones are:
1132 \tr{-ddump-rdr} & reader output (earliest stuff in the compiler) \\
1133 \tr{-ddump-rn} & renamer output \\
1134 \tr{-ddump-tc} & typechecker output \\
1135 \tr{-ddump-deriv} & derived instances \\
1136 \tr{-ddump-ds} & desugarer output \\
1137 \tr{-ddump-simpl} & simplifer output (Core-to-Core passes) \\
1138 \tr{-ddump-stranal} & strictness analyser output \\
1139 \tr{-ddump-occur-anal} & `occurrence analysis' output \\
1140 \tr{-ddump-spec} & dump specialisation info \\
1141 \tr{-ddump-stg} & output of STG-to-STG passes \\
1142 \tr{-ddump-absC} & {\em un}flattened Abstract~C \\
1143 \tr{-ddump-flatC} & {\em flattened} Abstract~C \\
1144 \tr{-ddump-realC} & same as what goes to the C compiler \\
1145 \tr{-ddump-asm} & assembly language from the native-code generator \\
1147 \index{-ddump-rdr option}%
1148 \index{-ddump-rn option}%
1149 \index{-ddump-tc option}%
1150 \index{-ddump-deriv option}%
1151 \index{-ddump-ds option}%
1152 \index{-ddump-simpl option}%
1153 \index{-ddump-stranal option}%
1154 \index{-ddump-occur-anal option}%
1155 \index{-ddump-spec option}%
1156 \index{-ddump-stg option}%
1157 \index{-ddump-absC option}%
1158 \index{-ddump-flatC option}%
1159 \index{-ddump-realC option}%
1160 \index{-ddump-asm option}
1162 %For any other \tr{-ddump-*} options: consult the source, notably
1163 %\tr{ghc/compiler/main/CmdLineOpts.lhs}.
1165 \item[\tr{-dverbose-simpl} and \tr{-dverbose-stg}:]
1166 \index{-dverbose-simpl option}
1167 \index{-dverbose-stg option}
1168 Show the output of the intermediate Core-to-Core and STG-to-STG
1169 passes, respectively. ({\em Lots} of output!) So: when we're
1172 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
1175 \item[\tr{-dppr-{user,debug,all}}:]
1176 \index{-dppr-user option}
1177 \index{-dppr-debug option}
1178 \index{-dppr-all option}
1179 Debugging output is in one of several ``styles.'' Take the printing
1180 of types, for example. In the ``user'' style, the compiler's internal
1181 ideas about types are presented in Haskell source-level syntax,
1182 insofar as possible. In the ``debug'' style (which is the default for
1183 debugging output), the types are printed in the most-often-desired
1184 form, with explicit foralls, etc. In the ``show all'' style, very
1185 verbose information about the types (e.g., the Uniques on the
1186 individual type variables) is displayed.
1188 \item[\tr{-ddump-raw-asm}:]
1189 \index{-ddump-raw-asm option}
1190 Dump out the assembly-language stuff, before the ``mangler'' gets it.
1192 \item[\tr{-ddump-rn-trace}:]
1193 \index{-ddump-rn-trace}
1194 Make the renamer be *real* chatty about what it is upto.
1196 \item[\tr{-dshow-rn-stats}:]
1197 \index{-dshow-rn-stats}
1198 Print out summary of what kind of information the renamer had to bring
1200 \item[\tr{-dshow-unused-imports}:]
1201 \index{-dshow-unused-imports}
1202 Have the renamer report what imports does not contribute.
1205 %\item[\tr{-dgc-debug}:]
1206 %\index{-dgc-debug option}
1207 %Enables some debugging code related to the garbage-collector.
1210 %ToDo: -ddump-asm-insn-counts
1211 %-ddump-asm-globals-info
1213 %----------------------------------------------------------------------
1214 \subsubsection{How to read Core syntax (from some \tr{-ddump-*} flags)}
1215 \index{reading Core syntax}
1216 \index{Core syntax, how to read}
1218 Let's do this by commenting an example. It's from doing
1219 \tr{-ddump-ds} on this code:
1221 skip2 m = m : skip2 (m+2)
1224 Before we jump in, a word about names of things. Within GHC,
1225 variables, type constructors, etc., are identified by their
1226 ``Uniques.'' These are of the form `letter' plus `number' (both
1227 loosely interpreted). The `letter' gives some idea of where the
1228 Unique came from; e.g., \tr{_} means ``built-in type variable'';
1229 \tr{t} means ``from the typechecker''; \tr{s} means ``from the
1230 simplifier''; and so on. The `number' is printed fairly compactly in
1231 a `base-62' format, which everyone hates except me (WDP).
1233 Remember, everything has a ``Unique'' and it is usually printed out
1234 when debugging, in some form or another. So here we go...
1238 Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4]
1240 --# `r1L6' is the Unique for Main.skip2;
1241 --# `_4' is the Unique for the type-variable (template) `a'
1242 --# `{{Num a$_4}}' is a dictionary argument
1246 --# `_NI_' means "no (pragmatic) information" yet; it will later
1247 --# evolve into the GHC_PRAGMA info that goes into interface files.
1249 Main.skip2{-r1L6-} =
1250 /\ _4 -> \ d.Num.t4Gt ->
1253 +.t4Hg :: _4 -> _4 -> _4
1255 +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
1257 fromInt.t4GS :: Int{-2i-} -> _4
1259 fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
1261 --# The `+' class method (Unique: r3JH) selects the addition code
1262 --# from a `Num' dictionary (now an explicit lamba'd argument).
1263 --# Because Core is 2nd-order lambda-calculus, type applications
1264 --# and lambdas (/\) are explicit. So `+' is first applied to a
1265 --# type (`_4'), then to a dictionary, yielding the actual addition
1266 --# function that we will use subsequently...
1268 --# We play the exact same game with the (non-standard) class method
1269 --# `fromInt'. Unsurprisingly, the type `Int' is wired into the
1276 ds.d4Qz :: Int{-2i-}
1279 } in fromInt.t4GS ds.d4Qz
1281 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
1282 --# GHC defines `data Int = I# Int#', where Int# is the primitive
1283 --# unboxed type. (see relevant info about unboxed types elsewhere...)
1285 --# The `!' after `I#' indicates that this is a *saturated*
1286 --# application of the `I#' data constructor (i.e., not partially
1289 skip2.t3Ja :: _4 -> [_4]
1293 let { ds.d4QQ :: [_4]
1299 ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
1300 } in skip2.t3Ja ds.d4QY
1302 :! _4 m.r1H4 ds.d4QQ
1308 (``It's just a simple functional language'' is an unregisterised
1309 trademark of Peyton Jones Enterprises, plc.)
1311 %----------------------------------------------------------------------
1312 \subsubsection[source-file-options]{Command line options in source files}
1313 \index{source-file options}
1315 Sometimes it is useful to make the connection between a source file
1316 and the command-line options it requires quite tight. For instance,
1317 if a (Glasgow) Haskell source file uses \tr{casm}s, the C back-end
1318 often needs to be told about which header files to include. Rather than
1319 maintaining the list of files the source depends on in a
1320 \tr{Makefile} (using the \tr{-#include} command-line option), it is
1321 possible to do this directly in the source file using the \tr{OPTIONS}
1322 pragma \index{OPTIONS pragma}:
1325 {-# OPTIONS -#include "foo.h" #-}
1331 \tr{OPTIONS} pragmas are only looked for at the top of your source
1332 files, upto the first (non-literate,non-empty) line not containing
1333 \tr{OPTIONS}. Multiple \tr{OPTIONS} pragmas are recognised. Note
1334 that your command shell does not get to the source file options, they
1335 are just included literally in the array of command-line arguments
1336 the compiler driver maintains internally, so you'll be desperately
1337 disappointed if you try to glob etc. inside \tr{OPTIONS}.
1339 NOTE: the contents of OPTIONS are prepended to the command-line
1340 options, so you *do* have the ability to override OPTIONS settings
1341 via the command line.
1343 It is not recommended to move all the contents of your Makefiles into
1344 your source files, but in some circumstances, the \tr{OPTIONS} pragma
1345 is the Right Thing. (If you use \tr{-keep-hc-file-too} and have OPTION
1346 flags in your module, the OPTIONS will get put into the generated .hc
1349 %----------------------------------------------------------------------
1350 \subsubsection{How to compile mutually recursive modules}
1351 \index{module system, recursion}
1353 Currently, the compiler does not have proper support for dealing with
1354 mutually recursive modules:
1376 When compiling either module A and B, the compiler will try (in vain)
1377 to look for the interface file of the other. So, to get mutually
1378 recursive modules off the ground, you need to hand write an interface
1379 file for A or B, so as to break the loop. For the example at hand, the
1380 boot interface file for A would like the following:
1387 1 newtype A = A PrelBase.Int ;
1388 1 f _:_ B.B -> A.A ;;
1391 To make sure you get the syntax right, tailoring an existing interface
1392 file is a Good Idea.
1394 {\bf Note:} This is all a temporary solution, a version of the compiler
1395 that handles mutually recursive properly without the manual
1396 construction of interface file, is in the works.
1398 %----------------------------------------------------------------------
1399 %\subsubsection[arity-checking]{Options to insert arity-checking code}
1400 %\index{arity checking}
1402 %The \tr{-darity-checks}\index{-darity-checks option} option inserts
1403 %code to check for arity violations. Unfortunately, it's not that
1404 %simple: you have to link with a prelude that was also built with arity
1405 %checks. If you have one, then great; otherwise...
1407 %The \tr{-darity-checks-C-only}\index{-darity-checks-C-only option}
1408 %option inserts the self-same arity checking code into \tr{.hc} files,
1409 %but doesn't compile it into the \tr{.o} files. We use this flag with
1410 %the \tr{-keep-hc-file-too}\index{-keep-hc-file-too option}, where we
1411 %are keeping \tr{.hc} files around for debugging purposes.
1413 %----------------------------------------------------------------------
1414 %\subsubsection[omit-checking]{Options to omit checking code}
1415 %\index{omitting runtime checks}
1417 %By default, the GHC system emits all possible not-too-expensive
1418 %runtime checking code. If you are brave or experimenting, you might
1419 %want to turn off some of this (not recommended):
1421 %\begin{tabular}{ll}
1422 %-dno-black-holing & won't buy you much (even if it works) \\
1423 %-dno-updates & you're crazy if you do this \\
1424 %-dno-stk-stubbing & omit stack stubbing (NOT DONE YET) \\
1426 %\index{-dno-black-holing option}%
1427 %\index{-dno-updates option}%
1428 %\index{-dno-stk-stubbing option}
1430 %Warning: all very lightly tested, if at all...
1432 %% %************************************************************************
1434 %% \subsection[options-GC]{Choosing a garbage collector}
1436 %% %************************************************************************
1438 %% (Note: you need a Good Reason before launching into this territory.)
1440 %% There are up to four garbage collectors to choose from (it depends how
1441 %% your local system was built); the Appel-style generational collector
1444 %% If you choose a non-default collector, you must specify it both when
1445 %% compiling the modules and when linking them together into an
1446 %% executable. Also, the native-code generator only works with the
1447 %% default collector (a small point to bear in mind).
1449 %% \begin{description}
1450 %% \item[\tr{-gc-ap} option:]
1451 %% \index{-gc-ap option}
1452 %% Appel-like generational collector (the default).
1454 %% \item[\tr{-gc-2s} option:]
1455 %% \index{-gc-2s option}
1456 %% Two-space copying collector.
1458 %% \item[\tr{-gc-1s} option:]
1459 %% \index{-gc-1s option}
1460 %% One-space compacting collector.
1462 %% \item[\tr{-gc-du} option:]
1463 %% \index{-gc-du option}
1464 %% Dual-mode collector (swaps between copying and compacting).
1465 %% \end{description}