[project @ 1997-06-05 23:38:01 by sof]
[ghc-hetmet.git] / ghc / docs / users_guide / how_to_run.lit
1 \section[invoking-GHC]{Invoking GHC: Command-line options}
2 \index{command-line options}
3 \index{options, GHC command-line}
4
5 Command-line arguments are either options or file names.
6
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.)
15
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.
20
21 %************************************************************************
22 %*                                                                      *
23 \subsection[file-suffixes]{Meaningful file suffixes}
24 \index{suffixes, file}
25 \index{file suffixes for GHC}
26 %*                                                                      *
27 %************************************************************************
28
29 File names with ``meaningful'' suffixes (e.g., \tr{.lhs} or \tr{.o})
30 cause the ``right thing'' to happen to those files.
31
32 \begin{description}
33 \item[\tr{.lhs}:]
34 \index{lhs suffix@.lhs suffix}
35 A ``literate Haskell'' module.
36
37 \item[\tr{.hs}:] 
38 A not-so-literate Haskell module.
39
40 \item[\tr{.hi}:]
41 A Haskell interface file, probably compiler-generated.
42
43 \item[\tr{.hc}:]
44 Intermediate C file produced by the Haskell compiler.
45
46 \item[\tr{.c}:]
47 A C~file not produced by the Haskell compiler.
48
49 % \item[\tr{.i}:]
50 % C code after it has be preprocessed by the C compiler (using the
51 % \tr{-E} flag).
52
53 \item[\tr{.s}:]
54 An assembly-language source file, usually
55 produced by the compiler.
56
57 \item[\tr{.o}:]
58 An object file, produced by an assembler.
59 \end{description}
60
61 Files with other suffixes (or without suffixes) are passed straight
62 to the linker.
63
64 %************************************************************************
65 %*                                                                      *
66 \subsection[options-help]{Help and verbosity options}
67 \index{help options (GHC)}
68 \index{verbose option (GHC)}
69 %*                                                                      *
70 %************************************************************************
71
72 A good option to start with is the \tr{-help} (or \tr{-?}) option.
73 \index{-help option}
74 \index{-? option}
75 GHC spews a long message to standard output and then exits.
76
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).
82
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.
86
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.
90
91 %************************************************************************
92 %*                                                                      *
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}
96 %*                                                                      *
97 %************************************************************************
98
99 The basic task of the \tr{ghc} driver is to run each input file
100 through the right phases (parsing, linking, etc.).
101
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:
105
106 \begin{tabular}{llll}
107 phase of the       & suffix saying & flag saying   & (suffix of) \\
108 compilation system & ``start here''& ``stop after''& output file \\ \hline
109
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 \\
116 \end{tabular}
117 \index{-C option}
118 \index{-S option}
119 \index{-c option}
120
121 Thus, a common invocation would be: \tr{ghc -c Foo.hs}
122
123 Note: What the Haskell compiler proper produces depends on whether a
124 native-code generator is used (producing assembly language) or not
125 (producing C).
126
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]
130
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.
134
135 The option \tr{-E}\index{-E option} runs just the C-preprocessor part
136 of the C-compiling phase, sending the result to stdout [I think].  (For
137 debugging, usually.)
138
139 %************************************************************************
140 %*                                                                      *
141 \subsection[options-optimise]{Optimisation (code improvement)}
142 \index{optimisation (GHC)}
143 \index{improvement, code (GHC)}
144 %*                                                                      *
145 %************************************************************************
146
147 The \tr{-O*} options specify convenient ``packages'' of optimisation
148 flags; the \tr{-f*} options described later on specify {\em individual}
149 optimisations to be turned on/off; the \tr{-m*} options specify {\em
150 machine-specific} optimisations to be turned on/off.
151
152 %----------------------------------------------------------------------
153 \subsubsection[optimise-pkgs]{\tr{-O*}: convenient ``packages'' of optimisation flags.}
154 \index{-O options (GHC)}
155
156 There are {\em many} options that affect the quality of code produced by
157 GHC.  Most people only have a general goal, something like ``Compile
158 quickly'' or ``Make my program run like greased lightning.''  The
159 following ``packages'' of optimisations (or lack thereof) should suffice.
160
161 Once you choose a \tr{-O*} ``package,'' stick with it---don't chop and
162 change.  Modules' interfaces {\em will} change with a shift to a new
163 \tr{-O*} option, and you may have to recompile a large chunk of all
164 importing modules before your program can again be run
165 safely\sectionref{recomp}.
166
167 \begin{description}
168 \item[No \tr{-O*}-type option specified:]
169 \index{-O* not specified}
170 This is taken to mean: ``Please compile quickly; I'm not over-bothered
171 about compiled-code quality.''  So, for example: \tr{ghc -c Foo.hs}
172
173 \item[\tr{-O} or \tr{-O1}:]
174 \index{-O option}
175 \index{-O1 option}
176 \index{optimise normally}
177 Means: ``Generate good-quality code without taking too long about it.''
178 Thus, for example: \tr{ghc -c -O Main.lhs}
179
180 \item[\tr{-O2}:]
181 \index{-O2 option}
182 \index{optimise aggressively}
183 Means: ``Apply every non-dangerous optimisation, even if it means
184 significantly longer compile times.''
185
186 The avoided ``dangerous'' optimisations are those that can make
187 runtime or space {\em worse} if you're unlucky.  They are
188 normally turned on or off individually.
189
190 At the moment, \tr{-O2} is {\em unlikely} to produce
191 better code than \tr{-O}.
192
193 % \item[\tr{-O0}:]
194 % \index{-O0 option}
195 % \index{optimise minimally}
196 % [``Oh zero''] Means: ``Turn {\em off} as many optimisations (e.g.,
197 % simplifications) as possible.''  This is the only optimisation level
198 % at which the GCC-register-trickery is turned off.  {\em You can't use
199 % it unless you have a suitably-built Prelude to match.} Intended for
200 % hard-core debugging.
201
202 \item[\tr{-fvia-C}:]
203 \index{-fvia-C option}
204 Compile via C, and don't use the native-code generator.
205 (There are many cases when GHC does this on its own.)  You might
206 pick up a little bit of speed by compiling via C.  If you use
207 \tr{_ccall_}s or \tr{_casm_}s, you probably {\em have to} use
208 \tr{-fvia-C}.
209
210 \item[\tr{-O2-for-C}:]
211 \index{-O2-for-C option}
212 Says to run GCC with \tr{-O2}, which may be worth a few percent in
213 execution speed.  Don't forget \tr{-fvia-C}, lest you use the
214 native-code generator and bypass GCC altogether!
215
216 \item[\tr{-Onot}:]
217 \index{-Onot option}
218 \index{optimising, reset}
219 This option will make GHC ``forget'' any -Oish options it has seen
220 so far.  Sometimes useful; for example: \tr{make all EXTRA_HC_OPTS=-Onot}.
221
222 \item[\tr{-Ofile <file>}:]
223 \index{-Ofile <file> option}
224 \index{optimising, customised}
225 For those who need {\em absolute} control over {\em exactly} what
226 options are used (e.g., compiler writers, sometimes :-), a list of
227 options can be put in a file and then slurped in with \tr{-Ofile}.
228
229 In that file, comments are of the \tr{#}-to-end-of-line variety; blank
230 lines and most whitespace is ignored.
231
232 Please ask if you are baffled and would like an example of \tr{-Ofile}!
233 \end{description}
234
235 At Glasgow, we don't use a \tr{-O*} flag for day-to-day work.  We use
236 \tr{-O} to get respectable speed; e.g., when we want to measure
237 something.  When we want to go for broke, we tend to use
238 \tr{-O -fvia-C -O2-for-C} (and we go for lots of coffee breaks).
239
240 %Here is a table to summarise whether pragmatic interface information
241 %is used or not, whether the native-code generator is used (if
242 %available), and whether we use GCC register tricks (for speed!) on the
243 %generated C code:
244 %
245 %\begin{tabular}{lccl}
246 %\tr{-O*}    & Interface & Native code & `Registerised' C \\
247 %            & pragmas?  & (if avail.) & (if avail.) \\ \hline
248 %%
249 %\pl{<none>} & no        & yes         & yes, only if \tr{-fvia-C} \\
250 %\tr{-O,-O1} & yes       & yes         & yes, only if \tr{-fvia-C} \\
251 %\tr{-O2}    & yes       & no         & yes \\
252 %\tr{-Ofile} & yes      & yes         & yes, only if \tr{-fvia-C} \\
253 %\end{tabular}
254
255 The easiest way to see what \tr{-O} (etc) ``really mean'' is to run
256 with \tr{-v}, then stand back in amazement.
257 Alternatively, just look at the
258 \tr{@HsC_minus<blah>} lists in the \tr{ghc} driver script.
259
260 %----------------------------------------------------------------------
261 \subsubsection{\tr{-f*}: platform-independent flags}
262 \index{-f* options (GHC)}
263 \index{-fno-* options (GHC)}
264
265 Flags can be turned {\em off} individually.  (NB: I hope
266 you have a good reason for doing this....) To turn off the \tr{-ffoo}
267 flag, just use the \tr{-fno-foo} flag.\index{-fno-<opt> anti-option}
268 So, for example, you can say
269 \tr{-O2 -fno-strictness}, which will then drop out any running of the
270 strictness analyser.
271
272 The options you are most likely to want to turn off are:
273 \tr{-fno-strictness}\index{-fno-strictness option} (strictness
274 analyser [because it is sometimes slow]),
275 \tr{-fno-specialise}\index{-fno-specialise option} (automatic
276 specialisation of overloaded functions [because it makes your code
277 bigger]) [US spelling also accepted],
278 and
279 \tr{-fno-foldr-build}\index{-fno-foldr-build option}.
280
281 Should you wish to turn individual flags {\em on}, you are advised to
282 use the \tr{-Ofile} option, described above.  Because the order in
283 which optimisation passes are run is sometimes crucial, it's quite
284 hard to do with command-line options.
285
286 Here are some ``dangerous'' optimisations you {\em might} want to try:
287 \begin{description}
288 %------------------------------------------------------------------
289 \item[\tr{-funfolding-creation-threshold<n>}:]
290 (Default: 30) By raising or lowering this number, you can raise or
291 lower the amount of pragmatic junk that gets spewed into interface
292 files.  (An unfolding has a ``size'' that reflects the cost in terms
293 of ``code bloat'' of expanding that unfolding in another module.  A
294 bigger Core expression would be assigned a bigger cost.)
295
296 \item[\tr{-funfolding-use-threshold<n>}:]
297 (Default: 3) By raising or lowering this number, you can make the
298 compiler more or less keen to expand unfoldings.
299
300 OK, folks, these magic numbers `30' and `3' are mildly arbitrary; they
301 are of the ``seem to be OK'' variety.  The `3' is the more critical
302 one; it's what determines how eager GHC is about expanding unfoldings.
303
304 \item[\tr{-funfolding-override-threshold<n>}:]
305 (Default: 8) [Pretty obscure]
306 When deciding what unfoldings from a module should be made available
307 to the rest of the world (via this module's interface), the compiler
308 normally likes ``small'' expressions.
309
310 For example, if it sees \tr{foo = bar}, it will decide that the very
311 small expression \tr{bar} is a great unfolding for \tr{foo}.  But if
312 \tr{bar} turns out to be \tr{(True,False,True)}, we would probably
313 prefer {\em that} for the unfolding for \tr{foo}.
314
315 Should we ``override'' the initial small unfolding from \tr{foo=bar}
316 with the bigger-but-better one?  Yes, if the bigger one's ``size'' is
317 still under the ``override threshold.''  You can use this flag to
318 adjust this threshold (why, I'm not sure).
319
320 % \item[\tr{-fliberated-case-threshold<n>}:]
321 % (Default: 12) [Vastly obscure: NOT IMPLEMENTED YET]
322 % ``Case liberation'' lifts evaluation out of recursive functions; it
323 % does this by duplicating code.  Done without constraint, you can get
324 % serious code bloat; so we only do it if the ``size'' of the duplicated
325 % code is smaller than some ``threshold.''  This flag can fiddle that
326 % threshold.
327
328 \item[\tr{-fsemi-tagging}:]
329 This option (which {\em does not work} with the native-code generator)
330 tells the compiler to add extra code to test for already-evaluated
331 values.  You win if you have lots of such values during a run of your
332 program, you lose otherwise.  (And you pay in extra code space.)
333
334 We have not played with \tr{-fsemi-tagging} enough to recommend it.
335 (For all we know, it doesn't even work anymore...  Sigh.)
336 \end{description}
337
338 %----------------------------------------------------------------------
339 % \subsubsection[optimise-simplifier]{Controlling ``simplification'' in the Haskell compiler.}
340 %
341 %Almost everyone turns program transformation
342 % (a.k.a. ``simplification'') on/off via one of the ``packages'' above,
343 %but you can exert absolute control if you want to.  Do a \tr{ghc -v -O ...},
344 %and you'll see there are plenty of knobs to turn!
345 %
346 %The Core-to-Core and STG-to-STG passes can be run multiple times, and
347 %in varying orders (though you may live to regret it).  The on-or-off
348 %global flags, however, are simply, well, on or off.
349 %
350 %The best way to give an exact list of options is the \tr{-Ofile}
351 %option, described elsewhere.
352 %
353 % [Check out \tr{ghc/compiler/simplCore/SimplCore.lhs} and
354 %\tr{simplStg/SimplStg.lhs} if you {\em really} want to see every
355 %possible Core-to-Core and STG-to-STG pass, respectively.  The
356 %on-or-off global flags that effect what happens {\em within} one of
357 %these passes are defined by the \tr{GlobalSwitch} datatype in
358 %\tr{compiler/main/CmdLineOpts.lhs}.]
359
360 %----------------------------------------------------------------------
361 \subsubsection{\tr{-m*}: platform-specific flags}
362 \index{-m* options (GHC)}
363 \index{platform-specific options}
364 \index{machine-specific options}
365
366 Some flags only make sense for particular target platforms.
367
368 \begin{description}
369 \item[\tr{-mv8}:]
370 (SPARC machines)\index{-mv8 option (SPARC only)}
371 Means to pass the like-named option to GCC; it says to use the
372 Version 8 SPARC instructions, notably integer multiply and divide.
373 The similiar \tr{-m*} GCC options for SPARC also work, actually.
374
375 \item[\tr{-mlong-calls}:]
376 (HPPA machines)\index{-mlong-calls option (HPPA only)}
377 Means to pass the like-named option to GCC.  Required for Very Big
378 modules, maybe.  (Probably means you're in trouble...)
379
380 \item[\tr{-monly-[32]-regs}:]
381 (iX86 machines)\index{-monly-N-regs option (iX86 only)}
382 GHC tries to ``steal'' four registers from GCC, for performance
383 reasons; it almost always works.  However, when GCC is compiling some
384 modules with four stolen registers, it will crash, probably saying:
385 \begin{verbatim}
386 Foo.hc:533: fixed or forbidden register was spilled.
387 This may be due to a compiler bug or to impossible asm
388 statements or clauses.
389 \end{verbatim}
390 Just give some registers back with \tr{-monly-N-regs}.  Try `3' first,
391 then `2'.  If `2' doesn't work, please report the bug to us.
392 \end{description}
393
394 %----------------------------------------------------------------------
395 \subsubsection[optimise-C-compiler]{Code improvement by the C compiler.}
396 \index{optimisation by GCC}
397 \index{GCC optimisation}
398
399 The C~compiler (GCC) is run with \tr{-O} turned on.  (It has
400 to be, actually).
401
402 If you want to run GCC with \tr{-O2}---which may be worth a few
403 percent in execution speed---you can give a
404 \tr{-O2-for-C}\index{-O2-for-C option} option.
405
406 %If you are brave or foolish, you might want to omit some checking code
407 % (e.g., for stack-overflow checks), as sketched in
408 %\sectionref{omit-checking}.
409
410 %************************************************************************
411 %*                                                                      *
412 \subsection[options-sanity]{Warnings and sanity-checking}
413 \index{sanity-checking options}
414 %*                                                                      *
415 %************************************************************************
416
417 If you would like GHC to check that every top-level value has a type
418 signature, use the \tr{-fsignatures-required}
419 option.\index{-fsignatures-required option}
420
421 If you would like to disallow ``name shadowing,'' i.e., an inner-scope
422 value has the same name as an outer-scope value, then use the
423 \tr{-fwarn-name-shadowing}
424 option.\index{-fwarn-name-shadowing option}
425 This option catches typographical errors that turn into hard-to-find
426 bugs, e.g., in the inadvertent cyclic definition \tr{let x = ... x ... in}.
427
428 Consequently, this option does {\em not} allow cyclic recursive
429 definitions.
430
431 By default, the compiler will warn you if a set of patterns are either
432 incomplete (i.e., you're only matching on a subset of an algebraic
433 data type's constructors), or overlapping, i.e.,
434
435 \begin{verbatim}
436 f :: String -> Int
437 f []     = 0
438 f (_:xs) = 1
439 f "2"    = 2
440
441 g [] = 2
442 \end{verbatim}
443
444 where the last pattern match in \tr{f} won't ever be reached, as the
445 second pattern overlaps it. More often than not, redundant patterns
446 is a programmer mistake/error, but if you don't want the compiler to
447 ``baby-sit'', use the \tr{-fno-warn-overlapping-patterns} option to
448 turn these warnings off.\index{-fno-warn-overlapping-patterns option}
449
450 Similarly for incomplete patterns, the function \tr{g} will fail when
451 applied to non-empty lists, so the compiler will by default emit a
452 warning about this. The option \tr{-fno-warn-incomplete-patterns}
453 turns rhis off.\index{-fno-warn-incomplete-pattern option}
454
455
456 If you're feeling really paranoid, the \tr{-dcore-lint}
457 option\index{-dcore-lint option} is a good choice.  It turns on
458 heavyweight intra-pass sanity-checking within GHC.  (It checks GHC's
459 sanity, not yours.)
460
461 %************************************************************************
462 %*                                                                      *
463 \subsection[options-output]{Re-directing the compilation output(s)}
464 \index{output-directing options}
465 %*                                                                      *
466 %************************************************************************
467
468 When compiling a Haskell module, GHC may produce several files of
469 output (usually two).
470
471 One file is usually an {\em interface file}.  If compiling
472 \tr{bar/Foo.hs}, the interface file would normally be \tr{bar/Foo.hi}.
473 The interface output may be directed to another file
474 \tr{bar2/Wurble.iface} with the option
475 \tr{-ohi bar2/Wurble.iface}\index{-ohi <file> option} (not recommended).
476
477 To avoid generating an interface file at all, use a \tr{-nohi}
478 option.\index{-nohi option}
479
480 The compiler does not overwrite an existing \tr{.hi} interface file if
481 the new one is byte-for-byte the same as the old one; this is friendly to
482 \tr{make}.  When an interface does change, it is often enlightening to
483 be informed.  The \tr{-hi-diffs}\index{-hi-diffs option} option will
484 make \tr{ghc} run \tr{diff} on the old and new \tr{.hi} files.
485
486 The \tr{.hi} files from GHC 2.xx contain ``usage'' information which
487 changes often and uninterestingly.  If you really want to see these
488 changes reported, you need to use the
489 \tr{-hi-diffs-with-usages}\index{-hi-diffs-with-usages option} option.
490
491 GHC's non-interface output normally goes into a \tr{.hc}, \tr{.o},
492 etc., file, depending on the last-run compilation phase.  The option
493 \tr{-o foo}\index{-o option} re-directs the output of that last-run
494 phase to file \tr{foo}.
495
496 Note: this ``feature'' can be counterintuitive:
497 \tr{ghc -C -o foo.o foo.hs} will put the intermediate C code in the
498 file \tr{foo.o}, name notwithstanding!
499
500 EXOTICA: But the \tr{-o} option isn't of much use if you have {\em
501 several} input files... Non-interface output files are normally put
502 in the same directory as their corresponding input file came from.
503 You may specify that they be put in another directory using the
504 \tr{-odir <dir>}\index{-odir <dir> option} (the ``Oh, dear'' option).
505 For example:
506
507 \begin{verbatim}
508 % ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
509 \end{verbatim}
510
511 The output files, \tr{Foo.o}, \tr{Bar.o}, and \tr{Bumble.o} would be
512 put into a subdirectory named after the architecture of the executing
513 machine (\tr{sun4}, \tr{mips}, etc).  The directory must already
514 exist; it won't be created.
515
516 Note that the \tr{-odir} option does {\em not} affect where the
517 interface files are put.  In the above example, they would still be
518 put in \tr{parse/Foo.hi}, \tr{parse/Bar.hi}, and
519 \tr{gurgle/Bumble.hi}.
520
521 MORE EXOTICA: The \tr{-osuf <suffix>}\index{-osuf <suffix> option}
522 will change the \tr{.o} file suffix for object files to whatever
523 you specify.  (We use this in compiling the prelude.)
524
525 Similarly, the \tr{-hisuf <suffix>}\index{-hisuf <suffix> option} will
526 change the \tr{.hi} file suffix for non-system interface files.  This
527 can be useful when you are trying to compile a program several ways,
528 all in the same directory.  The suffix given is used for {\em all}
529 interfaces files written, {\em and} for all non-system interface files
530 that your read.
531
532 The \tr{-hisuf}/\tr{-osuf} game is useful if you want to compile a
533 program with both GHC and HBC (say) in the same directory.  Let HBC
534 use the standard \tr{.hi}/\tr{.o} suffixes; add
535 \tr{-hisuf g_hi -osuf g_o} to your \tr{make} rule for GHC compiling...
536
537 NB: {\em A change from 0.26 and before:} Before, you might have said
538 \tr{-hisuf _g.hi -osuf _g.o}; now, the \tr{.} is assumed and you
539 specify what comes {\em after} it.  (This is a more portable solution
540 for the long term.)
541
542 % THIS SHOULD HAPPEN AUTOMAGICALLY:
543 % If you want to change the suffix looked for on system-supplied
544 % interface files (notably the \tr{Prelude.hi} file), use the
545 % \tr{-hisuf-prelude <suffix>}\index{-hisuf-prelude <suffix> option}
546 % option.  (This may be useful if you've built GHC in various funny
547 % ways, and you are running tests in even more funny ways.  It happens.)
548
549 FURTHER EXOTICA: If you are doing a normal \tr{.hs}-to-\tr{.o} compilation
550 but would like to hang onto the intermediate \tr{.hc} C file, just
551 throw in a \tr{-keep-hc-file-too} option\index{-keep-hc-file-too option}.
552 If you would like to look at the assembler output, toss in a
553 \tr{-keep-s-file-too},\index{-keep-hc-file-too option} too.
554
555 SAVING GHC STDERR OUTPUT: Sometimes, you may cause GHC to be rather
556 chatty on standard error; with \tr{-fshow-import-specs}, for example.
557 You can instruct GHC to {\em append} this output to a particular log
558 file with a \tr{-odump <blah>}\index{-odump <blah> option} option.
559
560 TEMPORARY FILES: If you have trouble because of running out of space
561 in \tr{/tmp/} (or wherever your installation thinks temporary files
562 should go), you may use the \tr{-tmpdir <dir>}\index{-tmpdir <dir> option}
563 option to specify an alternate directory.  For example, \tr{-tmpdir .}
564 says to put temporary files in the current working directory.
565
566 BETTER IDEA FOR TEMPORARY FILES: Use your \tr{TMPDIR} environment
567 variable.\index{TMPDIR environment variable}  Set it to the name of
568 the directory where temporary files should be put.  GCC and other
569 programs will honour the \tr{TMPDIR} variable as well.
570
571 EVEN BETTER IDEA: Set the \tr{TMPDIR} variable when building
572 GHC, and never worry about \tr{TMPDIR} again. (see the build
573 documentation).
574
575 %************************************************************************
576 %*                                                                      *
577 \subsection[options-finding-imports-etc]{For finding interface files, etc.}
578 \index{interface files, finding them}
579 \index{finding interface files}
580 %*                                                                      *
581 %************************************************************************
582
583 In your program, you import a module \tr{Foo} by saying
584 \tr{import Foo}.  GHC goes looking for an interface file, \tr{Foo.hi}.
585 It has a builtin list of directories (notably including \tr{.}) where
586 it looks.
587
588 The \tr{-i<dirs>} option\index{-i<dirs> option} prepends a
589 colon-separated list of \tr{dirs} to the ``import directories'' list.
590
591 A plain \tr{-i} resets the ``import directories'' list back to nothing.
592
593 GHC normally imports \tr{Prelude.hi} files for you.  If you'd rather
594 it didn't, then give it a \tr{-fno-implicit-prelude}
595 option\index{-fno-implicit-prelude option}.  You are unlikely to get
596 very far without a Prelude, but, hey, it's a free country.
597
598 If you are using a system-supplied non-Prelude library (e.g., the HBC
599 library), just use a \tr{-syslib hbc}\index{-syslib <lib> option}
600 option (for example).  The right interface files should then be
601 available.
602
603 Once a Haskell module has been compiled to C (\tr{.hc} file), you may
604 wish to specify where GHC tells the C compiler to look for \tr{.h}
605 files.  (Or, if you are using the \tr{-cpp} option\index{-cpp option},
606 where it tells the C pre-processor to look...)  For this purpose, use
607 a \tr{-I<dir>}\index{-I<dir> option} in the usual C-ish way.
608
609 Pragmas: Interface files are normally jammed full of
610 compiler-produced {\em pragmas}, which record arities, strictness
611 info, etc.  If you think these pragmas are messing you up (or you are
612 doing some kind of weird experiment), you can tell GHC to ignore them
613 with the \tr{-fignore-interface-pragmas}\index{-fignore-interface-pragmas option}
614 option.
615
616 When compiling without optimisations on, the compiler is extra-careful
617 about not slurping in data constructors and instance declarations that
618 it will not need. If you believe it is getting it wrong and not
619 importing stuff which you think it should, this optimisation can be
620 turned off with \tr{-fno-prune-tydecls} and \tr{-fno-prune-instdecls}.
621 \index{-fno-prune-tydecls option}\index{-fno-prune-instdecls}
622
623 See also \sectionref{options-linker}, which describes how the linker
624 finds standard Haskell libraries.
625
626 %************************************************************************
627 %*                                                                      *
628 %\subsection[options-names]{Fiddling with namespaces}
629 %*                                                                      *
630 %************************************************************************
631
632 %-split-objs and -fglobalise-toplev-names.  You don't need them and you
633 %don't want to know; used for the prelude (ToDo).
634
635 %************************************************************************
636 %*                                                                      *
637 \subsection[options-CPP]{Related to the C pre-processor}
638 \index{C pre-processor options}
639 \index{pre-processor (cpp) options}
640 %*                                                                      *
641 %************************************************************************
642
643 The C pre-processor \tr{cpp} is run over your Haskell code only if the
644 \tr{-cpp} option \index{-cpp option} is given.  Unless you are
645 building a large system with significant doses of conditional
646 compilation, you really shouldn't need it.
647 \begin{description}
648 \item[\tr{-D<foo>}:]
649 \index{-D<name> option}
650 Define macro \tr{<foo>} in the usual way.  NB: does {\em not} affect
651 \tr{-D} macros passed to the C~compiler when compiling via C!  For
652 those, use the \tr{-optc-Dfoo} hack...
653
654 \item[\tr{-U<foo>}:]
655 \index{-U<name> option}
656 Undefine macro \tr{<foo>} in the usual way.
657
658 \item[\tr{-I<dir>}:]
659 \index{-I<dir> option}
660 Specify a directory in which to look for \tr{#include} files, in
661 the usual C way.
662 \end{description}
663
664 The \tr{ghc} driver pre-defines several macros:
665 \begin{description}
666 \item[\tr{__HASKELL1__}:]
667 \index{__HASKELL1__ macro}
668 If defined to $n$, that means GHC supports the
669 Haskell language defined in the Haskell report version $1.n$.
670 Currently 4.
671
672 NB: This macro is set both when pre-processing Haskell source and
673 when pre-processing generated C (\tr{.hc}) files.
674
675 % If you give the \tr{-fhaskell-1.3} flag\index{-fhaskell-1.3 option},
676 % then \tr{__HASKELL1__} is set to 3.  Obviously.
677
678 \item[\tr{__GLASGOW_HASKELL__}:]
679 \index{__GLASGOW_HASKELL__ macro}
680 For version $n$ of the GHC system, this will be \tr{#define}d to
681 $100 \times n$.  So, for version~2.02, it is 202.
682
683 This macro is {\em only} set when pre-processing Haskell source.
684 ({\em Not} when pre-processing generated C.)
685
686 With any luck, \tr{__GLASGOW_HASKELL__} will be undefined in all other
687 implementations that support C-style pre-processing.
688
689 (For reference: the comparable symbols for other systems are:
690 \tr{__HUGS__} for Hugs and \tr{__HBC__} for Chalmers.)
691
692 \item[\tr{__CONCURRENT_HASKELL__}:]
693 \index{__CONCURRENT_HASKELL__ macro}
694 Only defined when \tr{-concurrent} is in use!
695 This symbol is defined when pre-processing Haskell (input) and
696 pre-processing C (GHC output).
697
698 \item[\tr{__PARALLEL_HASKELL__}:]
699 \index{__PARALLEL_HASKELL__ macro}
700 Only defined when \tr{-parallel} is in use!  This symbol is defined when
701 pre-processing Haskell (input) and pre-processing C (GHC output).
702 \end{description}
703
704 Options other than the above can be forced through to the C
705 pre-processor with the \tr{-opt} flags (see
706 \sectionref{forcing-options-through}).
707
708 A small word of warning: \tr{-cpp} is not friendly to
709 ``string gaps''.\index{-cpp vs string gaps}\index{string gaps vs -cpp}
710
711
712 %************************************************************************
713 %*                                                                      *
714 \subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
715 \index{include-file-option}
716 \index{C compiler options}
717 \index{GCC options}
718 %*                                                                      *
719 %************************************************************************
720
721 At the moment, quite a few common C-compiler options are passed on
722 quietly to the C compilation of Haskell-compiler-generated C files.
723 THIS MAY CHANGE.  Meanwhile, options so sent are:
724
725 \begin{tabular}{ll}
726 \tr{-Wall}      & get all warnings from GCC \\
727 \tr{-ansi}      & do ANSI C (not K\&R) \\
728 \tr{-pedantic}  & be so\\
729 \tr{-dgcc-lint} & (hack) short for ``make GCC very paranoid''\\
730 \end{tabular}
731 \index{-Wall option (for GCC)}
732 \index{-ansi option (for GCC)}
733 \index{-pedantic option (for GCC)}
734 \index{-dgcc-lint option (GCC paranoia)}
735
736 If you are compiling with lots of \tr{ccalls}, etc., you may need to
737 tell the C~compiler about some \tr{#include} files.  There is no real
738 pretty way to do this, but you can use this hack from the
739 command-line:
740 \begin{verbatim}
741 % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
742 \end{verbatim}
743
744
745 %************************************************************************
746 %*                                                                      *
747 %\subsection[options-native-code]{Options affecting the native-code generator(s)}
748 %*                                                                      *
749 %************************************************************************
750
751 %The only option is to select the target architecture.  Right now,
752 %you have only at most one choice: \tr{-fasm-sparc}.\index{-fasm-<target> option}
753 %
754 %EXPECT this native-code stuff to change in the future.
755
756 %************************************************************************
757 %*                                                                      *
758 \subsection[options-linker]{Linking and consistency-checking}
759 \index{linker options}
760 \index{ld options}
761 %*                                                                      *
762 %************************************************************************
763
764 GHC has to link your code with various libraries, possibly including:
765 user-supplied, GHC-supplied, and system-supplied (\tr{-lm} math
766 library, for example).
767
768 \begin{description}
769 \item[\tr{-l<FOO>}:]
770 \index{-l<lib> option}
771 Link in a library named \tr{lib<FOO>.a} which resides somewhere on the
772 library directories path.
773
774 Because of the sad state of most UNIX linkers, the order of such
775 options does matter.  Thus: \tr{ghc -lbar *.o} is almost certainly
776 wrong, because it will search \tr{libbar.a} {\em before} it has
777 collected unresolved symbols from the \tr{*.o} files.
778 \tr{ghc *.o -lbar} is probably better.
779
780 The linker will of course be informed about some GHC-supplied
781 libraries automatically; these are:
782
783 \begin{tabular}{ll}
784 -l equivalent & description \\ \hline
785
786 -lHSrts,-lHSclib & basic runtime libraries \\
787 -lHS         & standard Prelude library \\
788 -lHS\_cbits  & C support code for standard Prelude library \\
789 -lgmp        & GNU multi-precision library (for Integers)\\
790 \end{tabular}
791 \index{-lHS library}
792 \index{-lHS_cbits library}
793 \index{-lHSrts library}
794 \index{-lgmp library}
795
796 \item[\tr{-syslib <name>}:]
797 \index{-syslib <name> option}
798
799 If you are using a Haskell ``system library'' (e.g., the HBC
800 library), just use the \tr{-syslib hbc} option, and the correct code
801 should be linked in.
802
803 %Please see \sectionref{syslibs} for information about
804 %``system libraries.''
805
806 \item[\tr{-L<dir>}:]
807 \index{-L<dir> option}
808 Where to find user-supplied libraries...  Prepend the directory
809 \tr{<dir>} to the library directories path.
810
811 \item[\tr{-static}:]
812 \index{-static option}
813 Tell the linker to avoid shared libraries.
814
815 \item[\tr{-no-link-chk} and \tr{-link-chk}:]
816 \index{-no-link-chk option}
817 \index{-link-chk option}
818 \index{consistency checking of executables}
819 By default, immediately after linking an executable, GHC verifies that
820 the pieces that went into it were compiled with compatible flags; a
821 ``consistency check''.
822 (This is to avoid mysterious failures caused by non-meshing of
823 incompatibly-compiled programs; e.g., if one \tr{.o} file was compiled
824 for a parallel machine and the others weren't.)  You may turn off this
825 check with \tr{-no-link-chk}.  You can turn it (back) on with
826 \tr{-link-chk} (the default).
827 \end{description}
828
829 %************************************************************************
830 %*                                                                      *
831 \subsection[options-compiler-RTS]{For the compiler's RTS: heap, stack sizes, etc.}
832 \index{heap-size options (for GHC)}
833 \index{stack-size options (for GHC)}
834 %*                                                                      *
835 %************************************************************************
836
837 The compiler is itself a Haskell program, so it has a tweakable
838 runtime-system (RTS), just like any other Haskell program.
839
840 \begin{description}
841 \item[\tr{-H<size>} or \tr{-Rmax-heapsize <size>}:]
842 \index{-H<size> option}
843 \index{-Rmax-heapsize <size> option}
844 Don't use more than \tr{<size>} {\em bytes} for heap space.  If more
845 than one of these arguments is given, the largest will be taken.
846
847 A size of zero can be used to reset the heap size downwards.  For
848 example, to run GHC with a heap of 250KB (the default is 6MB), do
849 \tr{-H0 -H250k}.
850
851 \item[\tr{-K<size>} or \tr{-Rmax-stksize <size>}:]
852 \index{-K<size> option}
853 \index{-Rmax-stksize <size> option}
854 Set the stack space to \tr{<size>} bytes.  If you have to set it very
855 high [a megabyte or two, say], the compiler is probably looping, which
856 is a BUG (please report).
857
858 A size of zero can be used to rest the stack size downwards, as above.
859
860 \item[\tr{-Rscale-sizes<factor>}:]
861 \index{-Rscale-sizes<factor> option}
862 Multiply the given (or default) heap and stack sizes by \tr{<factor>}.
863 For example, on a DEC Alpha (a 64-bit machine), you might want to
864 double those space sizes; just use \tr{-Rscale-sizes2}.
865
866 A non-integral factor is OK, too: \tr{-Rscale-sizes1.2}.
867
868 \item[\tr{-Rghc-timing}:]
869 \index{-Rghc-timing option}
870 Reports a one-line useful collection of time- and space- statistics
871 for a module's compilation.
872
873 \item[\tr{-Rgc-stats}:]
874 \index{-Rgc-stats option}
875 Report garbage-collection statistics.  It will create a
876 \tr{<foo>.stat} file, in some obvious place (I hope).
877
878 Alternatively, if you'd rather the GC stats went straight to standard
879 error, you can ``cheat'' by using, instead: \tr{-optCrts-Sstderr}.
880 %
881 %\item[\tr{-Rhbc}:]
882 %\index{-Rhbc option}
883 %Tell the compiler it has an HBC-style RTS; i.e., it was compiled with
884 %HBC.  Not used in Real Life.
885 %
886 %\item[\tr{-Rghc}:]
887 %\index{-Rghc option}
888 %Tell the compiler it has a GHC-style RTS; i.e., it was compiled with
889 %GHC.  Not used in Real Life.
890 \end{description}
891
892 For all \tr{<size>}s: If the last character of \tr{size} is a K,
893 multiply by 1000; if an M, by 1,000,000; if a G, by 1,000,000,000.
894 Sizes are always in {\em bytes}, not words.  Good luck on the G's (I
895 think the counter is still only 32-bits [WDP])!
896
897 %************************************************************************
898 %*                                                                      *
899 %\subsection[options-cross-compiling]{For cross-compiling to another architecture}
900 %*                                                                      *
901 %************************************************************************
902 %
903 % (We do this for GRIP at Glasgow; it's hacked in---not proper
904 %cross-compiling support.  But you could do the same, if required...)
905 %
906 %The \tr{-target <arch>} option\index{-target <arch> option} says to
907 %generate code for the \tr{<arch>} architecture.
908
909 %************************************************************************
910 %*                                                                      *
911 \subsection[options-parallel]{For Concurrent and Parallel Haskell}
912 %*                                                                      *
913 %************************************************************************
914
915 For the full story on using GHC for concurrent \& parallel Haskell
916 programming, please see \Sectionref{concurrent-and-parallel}.
917
918 %The \tr{-fparallel} option\index{-fparallel option} tells the compiler
919 %to generate code for parallel execution.  The \tr{-mgrip}
920 %option\index{-mgrip option} says that the code should be explicitly
921 %suitable for the GRIP multiprocessor (the one in our Glasgow basement).
922
923 %************************************************************************
924 %*                                                                      *
925 %\subsection[options-experimental]{For experimental purposes}
926 %\index{experimental options}
927 %*                                                                      *
928 %************************************************************************
929
930 %From time to time, we provide GHC options for ``experimenting.''  Easy
931 %come, easy go.  In version~0.26, the ``experimental'' options are:
932 %\begin{description}
933 %\item[\tr{-firrefutable-tuples} option:]
934 %\index{-firrefutable-tuples option (experimental)}
935 %Pretend that every tuple pattern is irrefutable; i.e., has a
936 %``twiddle'' (\tr{~}) in front of it.
937 %
938 %Some parts of the GHC system {\em depend} on strictness properties which
939 %\tr{-firrefutable-tuples} may undo, notably the low-level state-transformer
940 %stuff, which includes I/O (!).  You're on your own...
941 %
942 %\item[\tr{-fall-strict} option:]
943 %\index{-fall-strict option (experimental)}
944 % (DOESN'T REALLY WORK, I THINK) Changes the strictness analyser so
945 %that, when it asks the question ``Is this function argument certain to
946 %be evaluated?'', the answer is always ``yes''.
947 %
948 %Compilation is changed in no other way.
949 %\end{description}
950
951 % -firrefutable-everything
952 % -fall-demanded
953
954 %************************************************************************
955 %*                                                                      *
956 \subsection[options-debugging]{For debugging the compiler}
957 \index{debugging options (for GHC)}
958 %*                                                                      *
959 %************************************************************************
960
961 HACKER TERRITORY. HACKER TERRITORY.
962 (You were warned.)
963
964 %----------------------------------------------------------------------
965 \subsubsection[replacing-phases]{Replacing the program for one or more phases.}
966 \index{GHC phases, changing}
967 \index{phases, changing GHC}
968
969 You may specify that a different program
970 be used for one of the phases of the compilation system, in place of
971 whatever the driver \tr{ghc} has wired into it.  For example, you
972 might want to try a different assembler.  The
973 \tr{-pgm<phase-code><program-name>}\index{-pgm<phase><stuff> option} option to
974 \tr{ghc} will cause it to use \pl{<program-name>} for phase
975 \pl{<phase-code>}, where the codes to indicate the phases are:
976
977 \begin{tabular}{ll}
978 code & phase \\ \hline
979 L    & literate pre-processor \\
980 P    & C pre-processor (if -cpp only) \\
981 C    & Haskell compiler \\
982 c    & C compiler\\
983 a    & assembler \\
984 l    & linker \\
985 \end{tabular}
986
987 %----------------------------------------------------------------------
988 \subsubsection[forcing-options-through]{Forcing options to a particular phase.}
989 \index{forcing GHC-phase options}
990
991 The preceding sections describe driver options that are mostly
992 applicable to one particular phase.  You may also {\em force} a
993 specific option \tr{<option>} to be passed to a particular phase
994 \tr{<phase-code>} by feeding the driver the option
995 \tr{-opt<phase-code><option>}.\index{-opt<phase><stuff> option} The
996 codes to indicate the phases are the same as in the previous section.
997
998 So, for example, to force an \tr{-Ewurble} option to the assembler, you
999 would tell the driver \tr{-opta-Ewurble} (the dash before the E is
1000 required).
1001
1002 Besides getting options to the Haskell compiler with \tr{-optC<blah>},
1003 you can get options through to its runtime system with
1004 \tr{-optCrts<blah>}\index{-optCrts<blah> option}.
1005
1006 So, for example: when I want to use my normal driver but with my
1007 profiled compiler binary, I use this script:
1008 \begin{verbatim}
1009 #! /bin/sh
1010 exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
1011      -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
1012      -optCrts-i0.5 \
1013      -optCrts-PT \
1014      "$@"
1015 \end{verbatim}
1016
1017 %----------------------------------------------------------------------
1018 \subsubsection[dumping-output]{Dumping out compiler intermediate structures}
1019 \index{dumping GHC intermediates}
1020 \index{intermediate passes, output}
1021
1022 \begin{description}
1023 \item[\tr{-noC}:]
1024 \index{-noC option}
1025 Don't bother generating C output {\em or} an interface file.  Usually
1026 used in conjunction with one or more of the \tr{-ddump-*} options; for
1027 example: \tr{ghc -noC -ddump-simpl Foo.hs}
1028
1029 \item[\tr{-hi}:]
1030 \index{-hi option}
1031 {\em Do} generate an interface file.  This would normally be used in
1032 conjunction with \tr{-noC}, which turns off interface generation;
1033 thus: \tr{-noC -hi}.
1034
1035 \item[\tr{-dshow-passes}:]
1036 \index{-dshow-passes option}
1037 Prints a message to stderr as each pass starts.  Gives a warm but
1038 undoubtedly misleading feeling that GHC is telling you what's
1039 happening.
1040
1041 \item[\tr{-ddump-<pass>}:]
1042 \index{-ddump-<pass> options}
1043 Make a debugging dump after pass \tr{<pass>} (may be common enough to
1044 need a short form...).  Some of the most useful ones are:
1045
1046 \begin{tabular}{ll}
1047 \tr{-ddump-rdr} & reader output (earliest stuff in the compiler) \\
1048 \tr{-ddump-rn} & renamer output \\
1049 \tr{-ddump-tc} & typechecker output \\
1050 \tr{-ddump-deriv} & derived instances \\
1051 \tr{-ddump-ds} & desugarer output \\
1052 \tr{-ddump-simpl} & simplifer output (Core-to-Core passes) \\
1053 \tr{-ddump-stranal} & strictness analyser output \\
1054 \tr{-ddump-occur-anal} & `occurrence analysis' output \\
1055 \tr{-ddump-spec} & dump specialisation info \\
1056 \tr{-ddump-stg} & output of STG-to-STG passes \\
1057 \tr{-ddump-absC} & {\em un}flattened Abstract~C \\
1058 \tr{-ddump-flatC} & {\em flattened} Abstract~C \\
1059 \tr{-ddump-realC} & same as what goes to the C compiler \\
1060 \tr{-ddump-asm} & assembly language from the native-code generator \\
1061 \end{tabular}
1062 \index{-ddump-rdr option}%
1063 \index{-ddump-rn option}%
1064 \index{-ddump-tc option}%
1065 \index{-ddump-deriv option}%
1066 \index{-ddump-ds option}%
1067 \index{-ddump-simpl option}%
1068 \index{-ddump-stranal option}%
1069 \index{-ddump-occur-anal option}%
1070 \index{-ddump-spec option}%
1071 \index{-ddump-stg option}%
1072 \index{-ddump-absC option}%
1073 \index{-ddump-flatC option}%
1074 \index{-ddump-realC option}%
1075 \index{-ddump-asm option}
1076
1077 %For any other \tr{-ddump-*} options: consult the source, notably
1078 %\tr{ghc/compiler/main/CmdLineOpts.lhs}.
1079
1080 \item[\tr{-dverbose-simpl} and \tr{-dverbose-stg}:]
1081 \index{-dverbose-simpl option}
1082 \index{-dverbose-stg option}
1083 Show the output of the intermediate Core-to-Core and STG-to-STG
1084 passes, respectively.  ({\em Lots} of output!) So: when we're 
1085 really desperate:
1086 \begin{verbatim}
1087 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
1088 \end{verbatim}
1089
1090 \item[\tr{-dppr-{user,debug,all}}:]
1091 \index{-dppr-user option}
1092 \index{-dppr-debug option}
1093 \index{-dppr-all option}
1094 Debugging output is in one of several ``styles.''  Take the printing
1095 of types, for example.  In the ``user'' style, the compiler's internal
1096 ideas about types are presented in Haskell source-level syntax,
1097 insofar as possible.  In the ``debug'' style (which is the default for
1098 debugging output), the types are printed in the most-often-desired
1099 form, with explicit foralls, etc.  In the ``show all'' style, very
1100 verbose information about the types (e.g., the Uniques on the
1101 individual type variables) is displayed.
1102
1103 \item[\tr{-ddump-raw-asm}:]
1104 \index{-ddump-raw-asm option}
1105 Dump out the assembly-language stuff, before the ``mangler'' gets it.
1106
1107 \item[\tr{-ddump-rn-trace}:]
1108 \index{-ddump-rn-trace}
1109 Make the renamer be *real* chatty about what it is upto.
1110
1111 \item[\tr{-dshow-rn-stats}:]
1112 \index{-dshow-rn-stats}
1113 Print out summary of what kind of information the renamer had to bring
1114 in.
1115 \item[\tr{-dshow-unused-imports}:]
1116 \index{-dshow-unused-imports}
1117 Have the renamer report what imports does not contribute.
1118
1119 \item[\tr{-fwarn-unused-names}:]
1120 \index{-fwarn-unused-names}
1121 Have the renamer report which locally defined names are not used/exported.
1122
1123 %
1124 %\item[\tr{-dgc-debug}:]
1125 %\index{-dgc-debug option}
1126 %Enables some debugging code related to the garbage-collector.
1127 \end{description}
1128
1129 %ToDo: -ddump-asm-insn-counts
1130 %-ddump-asm-globals-info
1131
1132 %----------------------------------------------------------------------
1133 \subsubsection{How to read Core syntax (from some \tr{-ddump-*} flags)}
1134 \index{reading Core syntax}
1135 \index{Core syntax, how to read}
1136
1137 Let's do this by commenting an example.  It's from doing
1138 \tr{-ddump-ds} on this code:
1139 \begin{verbatim}
1140 skip2 m = m : skip2 (m+2)
1141 \end{verbatim}
1142
1143 Before we jump in, a word about names of things.  Within GHC,
1144 variables, type constructors, etc., are identified by their
1145 ``Uniques.''  These are of the form `letter' plus `number' (both
1146 loosely interpreted).  The `letter' gives some idea of where the
1147 Unique came from; e.g., \tr{_} means ``built-in type variable'';
1148 \tr{t} means ``from the typechecker''; \tr{s} means ``from the
1149 simplifier''; and so on.  The `number' is printed fairly compactly in
1150 a `base-62' format, which everyone hates except me (WDP).
1151
1152 Remember, everything has a ``Unique'' and it is usually printed out
1153 when debugging, in some form or another.  So here we go...
1154
1155 \begin{verbatim}
1156 Desugared:
1157 Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4]
1158
1159 --# `r1L6' is the Unique for Main.skip2;
1160 --# `_4' is the Unique for the type-variable (template) `a'
1161 --# `{{Num a$_4}}' is a dictionary argument
1162
1163 _NI_
1164
1165 --# `_NI_' means "no (pragmatic) information" yet; it will later
1166 --# evolve into the GHC_PRAGMA info that goes into interface files.
1167
1168 Main.skip2{-r1L6-} =
1169     /\ _4 -> \ d.Num.t4Gt ->
1170         let {
1171           {- CoRec -}
1172           +.t4Hg :: _4 -> _4 -> _4
1173           _NI_
1174           +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
1175
1176           fromInt.t4GS :: Int{-2i-} -> _4
1177           _NI_
1178           fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
1179
1180 --# The `+' class method (Unique: r3JH) selects the addition code
1181 --# from a `Num' dictionary (now an explicit lamba'd argument).
1182 --# Because Core is 2nd-order lambda-calculus, type applications
1183 --# and lambdas (/\) are explicit.  So `+' is first applied to a
1184 --# type (`_4'), then to a dictionary, yielding the actual addition
1185 --# function that we will use subsequently...
1186
1187 --# We play the exact same game with the (non-standard) class method
1188 --# `fromInt'.  Unsurprisingly, the type `Int' is wired into the
1189 --# compiler.
1190
1191           lit.t4Hb :: _4
1192           _NI_
1193           lit.t4Hb =
1194               let {
1195                 ds.d4Qz :: Int{-2i-}
1196                 _NI_
1197                 ds.d4Qz = I#! 2#
1198               } in  fromInt.t4GS ds.d4Qz
1199
1200 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
1201 --# GHC defines `data Int = I# Int#', where Int# is the primitive
1202 --# unboxed type.  (see relevant info about unboxed types elsewhere...)
1203
1204 --# The `!' after `I#' indicates that this is a *saturated*
1205 --# application of the `I#' data constructor (i.e., not partially
1206 --# applied).
1207
1208           skip2.t3Ja :: _4 -> [_4]
1209           _NI_
1210           skip2.t3Ja =
1211               \ m.r1H4 ->
1212                   let { ds.d4QQ :: [_4]
1213                         _NI_
1214                         ds.d4QQ =
1215                     let {
1216                       ds.d4QY :: _4
1217                       _NI_
1218                       ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
1219                     } in  skip2.t3Ja ds.d4QY
1220                   } in
1221                   :! _4 m.r1H4 ds.d4QQ
1222
1223           {- end CoRec -}
1224         } in  skip2.t3Ja
1225 \end{verbatim}
1226
1227 (``It's just a simple functional language'' is an unregisterised
1228 trademark of Peyton Jones Enterprises, plc.)
1229
1230 %----------------------------------------------------------------------
1231 \subsubsection[source-file-options]{Command line options in source files}
1232 \index{source-file options}
1233
1234 Sometimes it is useful to make the connection between a source file
1235 and the command-line options it requires, quite tight. For instance,
1236 if a (Glasgow) Haskell source file uses \tr{casm}s, the C back-end
1237 often needs to be told about which header files to include. Rather than
1238 maintaining the list of files the source depends on in a
1239 \tr{Makefile} (using the \tr{-#include} command-line option), it is
1240 possible to do this directly in the source file using the \tr{OPTIONS}
1241 pragma \index{OPTIONS pragma}: 
1242
1243 \begin{verbatim}
1244 {-# OPTIONS -#include "foo.h" #-}
1245 module X where
1246
1247 ...
1248 \end{verbatim}
1249
1250 \tr{OPTIONS} pragmas are only looked for at the top of your source
1251 files, upto the first (non-literate,non-empty) line not containing
1252 \tr{OPTIONS}. Multiple \tr{OPTIONS} pragmas are recognised. Note
1253 that your command shell does not get to the source file options, they
1254 are just included literally in the array of command-line arguments
1255 the compiler driver maintains internally, so you'll be desperately
1256 disappointed if you try to glob etc. inside \tr{OPTIONS}.
1257
1258 It is not recommended to move all the contents of your Makefiles into
1259 your source files, but in some circumstances, the \tr{OPTIONS} pragma
1260 is the Right Thing. (If you use \tr{-keep-hc-file-too} and have OPTION
1261 flags in your module, the OPTIONS will get put into the generated .hc
1262 file).
1263
1264 %----------------------------------------------------------------------
1265 \subsubsection{How to compile mutually recursive modules}
1266 \index{module system, recursion}
1267
1268 Currently, the compiler does not have proper support for dealing with
1269 mutually recursive modules:
1270
1271 \begin{verbatim}
1272 module A where
1273
1274 import B
1275
1276 newtype A = A Int
1277
1278 f :: B -> A
1279 f (B x) = A x
1280 --------
1281 module B where
1282
1283 import A
1284
1285 data B = B !Int
1286
1287 g :: A -> B
1288 g (A x) = B x
1289 \end{verbatim}
1290
1291 When compiling either module A and B, the compiler will try (in vain)
1292 to look for the interface file of the other. So, to get mutually
1293 recursive modules off the ground, you need to hand write an interface
1294 file for A or B, so as to break the loop. For the example at hand, the
1295 boot interface file for A would like the following:
1296
1297 \begin{verbatim}
1298 _interface_ A 1
1299 _exports_
1300 A A(A) f;
1301 _declarations_
1302 1 newtype A = A PrelBase.Int ;
1303 1 f _:_ B.B -> A.A ;;
1304 \end{verbatim}
1305
1306 To make sure you get the syntax right, tailoring an existing interface
1307 file is a Good Idea.
1308
1309 {\bf Note:} This is all a temporary solution, a version of the compiler
1310 that handles mutually recursive properly without the manual
1311 construction of interface file, is in the works.
1312
1313 %----------------------------------------------------------------------
1314 %\subsubsection[arity-checking]{Options to insert arity-checking code}
1315 %\index{arity checking}
1316 %
1317 %The \tr{-darity-checks}\index{-darity-checks option} option inserts
1318 %code to check for arity violations.  Unfortunately, it's not that
1319 %simple: you have to link with a prelude that was also built with arity
1320 %checks.  If you have one, then great; otherwise...
1321 %
1322 %The \tr{-darity-checks-C-only}\index{-darity-checks-C-only option}
1323 %option inserts the self-same arity checking code into \tr{.hc} files,
1324 %but doesn't compile it into the \tr{.o} files.  We use this flag with
1325 %the \tr{-keep-hc-file-too}\index{-keep-hc-file-too option}, where we
1326 %are keeping \tr{.hc} files around for debugging purposes.
1327
1328 %----------------------------------------------------------------------
1329 %\subsubsection[omit-checking]{Options to omit checking code}
1330 %\index{omitting runtime checks}
1331 %
1332 %By default, the GHC system emits all possible not-too-expensive
1333 %runtime checking code.  If you are brave or experimenting, you might
1334 %want to turn off some of this (not recommended):
1335 %
1336 %\begin{tabular}{ll}
1337 %-dno-black-holing & won't buy you much (even if it works) \\
1338 %-dno-updates & you're crazy if you do this \\
1339 %-dno-stk-stubbing & omit stack stubbing (NOT DONE YET) \\
1340 %\end{tabular}
1341 %\index{-dno-black-holing option}%
1342 %\index{-dno-updates option}%
1343 %\index{-dno-stk-stubbing option}
1344 %
1345 %Warning: all very lightly tested, if at all...
1346
1347 %% %************************************************************************
1348 %% %*                                                                   *
1349 %% \subsection[options-GC]{Choosing a garbage collector}
1350 %% %*                                                                   *
1351 %% %************************************************************************
1352 %% 
1353 %% (Note: you need a Good Reason before launching into this territory.)
1354 %% 
1355 %% There are up to four garbage collectors to choose from (it depends how
1356 %% your local system was built); the Appel-style generational collector
1357 %% is the default.
1358 %% 
1359 %% If you choose a non-default collector, you must specify it both when
1360 %% compiling the modules and when linking them together into an
1361 %% executable.  Also, the native-code generator only works with the
1362 %% default collector (a small point to bear in mind).
1363 %% 
1364 %% \begin{description}
1365 %% \item[\tr{-gc-ap} option:]
1366 %% \index{-gc-ap option}
1367 %% Appel-like generational collector (the default).
1368 %% 
1369 %% \item[\tr{-gc-2s} option:]
1370 %% \index{-gc-2s option}
1371 %% Two-space copying collector.
1372 %% 
1373 %% \item[\tr{-gc-1s} option:]
1374 %% \index{-gc-1s option}
1375 %% One-space compacting collector.
1376 %% 
1377 %% \item[\tr{-gc-du} option:]
1378 %% \index{-gc-du option}
1379 %% Dual-mode collector (swaps between copying and compacting).
1380 %% \end{description}