[project @ 2000-04-18 11:01:24 by simonmar]
[ghc-hetmet.git] / ghc / docs / users_guide / debugging.sgml
1 <Sect1 id="options-debugging">
2 <Title>Debugging the compiler
3 </Title>
4
5 <Para>
6 <IndexTerm><Primary>debugging options (for GHC)</Primary></IndexTerm>
7 </Para>
8
9 <Para>
10 HACKER TERRITORY. HACKER TERRITORY.
11 (You were warned.)
12 </Para>
13
14 <Sect2 id="replacing-phases">
15 <Title>Replacing the program for one or more phases.
16 </Title>
17
18 <Para>
19 <IndexTerm><Primary>GHC phases, changing</Primary></IndexTerm>
20 <IndexTerm><Primary>phases, changing GHC</Primary></IndexTerm>
21 You may specify that a different program be used for one of the phases
22 of the compilation system, in place of whatever the driver <Command>ghc</Command> has
23 wired into it.  For example, you might want to try a different
24 assembler.  The
25 <Option>-pgm&lt;phase-code&gt;&lt;program-name&gt;</Option><IndexTerm><Primary>-pgm&lt;phase&gt;&lt;stuff&gt;
26 option</Primary></IndexTerm> option to <Command>ghc</Command> will cause it to use <Literal>&lt;program-name&gt;</Literal>
27 for phase <Literal>&lt;phase-code&gt;</Literal>, where the codes to indicate the phases are:
28 </Para>
29
30 <Para>
31 <InformalTable>
32 <TGroup Cols="2">
33 <ColSpec Align="Left" Colsep="0">
34 <ColSpec Align="Left" Colsep="0">
35 <TBody>
36 <Row>
37 <Entry><Emphasis>code</Emphasis> </Entry>
38 <Entry><Emphasis>phase</Emphasis> </Entry>
39 </Row>
40
41 <Row>
42 <Entry>
43 L </Entry>
44 <Entry> literate pre-processor </Entry>
45 </Row>
46 <Row>
47 <Entry>
48 P </Entry>
49 <Entry> C pre-processor (if -cpp only) </Entry>
50 </Row>
51 <Row>
52 <Entry>
53 C </Entry>
54 <Entry> Haskell compiler </Entry>
55 </Row>
56 <Row>
57 <Entry>
58 c </Entry>
59 <Entry> C compiler</Entry>
60 </Row>
61 <Row>
62 <Entry>
63 a </Entry>
64 <Entry> assembler </Entry>
65 </Row>
66 <Row>
67 <Entry>
68 l </Entry>
69 <Entry> linker </Entry>
70 </Row>
71 <Row>
72 <Entry>
73 dep </Entry>
74 <Entry> Makefile dependency generator </Entry>
75 </Row>
76
77 </TBody>
78
79 </TGroup>
80 </InformalTable>
81 </Para>
82
83 </Sect2>
84
85 <Sect2 id="forcing-options-through">
86 <Title>Forcing options to a particular phase.
87 </Title>
88
89 <Para>
90 <IndexTerm><Primary>forcing GHC-phase options</Primary></IndexTerm>
91 </Para>
92
93 <Para>
94 The preceding sections describe driver options that are mostly
95 applicable to one particular phase.  You may also <Emphasis>force</Emphasis> a
96 specific option <Option>&lt;option&gt;</Option> to be passed to a particular phase
97 <Literal>&lt;phase-code&gt;</Literal> by feeding the driver the option
98 <Option>-opt&lt;phase-code&gt;&lt;option&gt;</Option>.<IndexTerm><Primary>-opt&lt;phase&gt;&lt;stuff&gt;
99 option</Primary></IndexTerm> The codes to indicate the phases are the same as in the
100 previous section.
101 </Para>
102
103 <Para>
104 So, for example, to force an <Option>-Ewurble</Option> option to the assembler, you
105 would tell the driver <Option>-opta-Ewurble</Option> (the dash before the E is
106 required).
107 </Para>
108
109 <Para>
110 Besides getting options to the Haskell compiler with <Option>-optC&lt;blah&gt;</Option>,
111 you can get options through to its runtime system with
112 <Option>-optCrts&lt;blah&gt;</Option><IndexTerm><Primary>-optCrts&lt;blah&gt; option</Primary></IndexTerm>.
113 </Para>
114
115 <Para>
116 So, for example: when I want to use my normal driver but with my
117 profiled compiler binary, I use this script:
118
119 <ProgramListing>
120 #! /bin/sh
121 exec /local/grasp_tmp3/simonpj/ghc-BUILDS/working-alpha/ghc/driver/ghc \
122      -pgmC/local/grasp_tmp3/simonpj/ghc-BUILDS/working-hsc-prof/hsc \
123      -optCrts-i0.5 \
124      -optCrts-PT \
125      "$@"
126 </ProgramListing>
127
128 </Para>
129
130 </Sect2>
131
132 <Sect2 id="dumping-output">
133 <Title>Dumping out compiler intermediate structures
134 </Title>
135
136 <Para>
137 <IndexTerm><Primary>dumping GHC intermediates</Primary></IndexTerm>
138 <IndexTerm><Primary>intermediate passes, output</Primary></IndexTerm>
139 </Para>
140
141 <Para>
142 <VariableList>
143
144 <VarListEntry>
145 <Term><Option>-noC</Option>:</Term>
146 <ListItem>
147 <Para>
148 <IndexTerm><Primary>-noC option</Primary></IndexTerm>
149 Don't bother generating C output <Emphasis>or</Emphasis> an interface file.  Usually
150 used in conjunction with one or more of the <Option>-ddump-*</Option> options; for
151 example: <Command>ghc -noC -ddump-simpl Foo.hs</Command>
152 </Para>
153 </ListItem>
154 </VarListEntry>
155 <VarListEntry>
156 <Term><Option>-hi</Option>:</Term>
157 <ListItem>
158 <Para>
159 <IndexTerm><Primary>-hi option</Primary></IndexTerm>
160 <Emphasis>Do</Emphasis> generate an interface file.  This would normally be used in
161 conjunction with <Option>-noC</Option>, which turns off interface generation;
162 thus: <Option>-noC -hi</Option>.
163 </Para>
164 </ListItem>
165 </VarListEntry>
166 <VarListEntry>
167 <Term><Option>-dshow-passes</Option>:</Term>
168 <ListItem>
169 <Para>
170 <IndexTerm><Primary>-dshow-passes option</Primary></IndexTerm>
171 Prints a message to stderr as each pass starts.  Gives a warm but
172 undoubtedly misleading feeling that GHC is telling you what's
173 happening.
174 </Para>
175 </ListItem>
176 </VarListEntry>
177 <VarListEntry>
178 <Term><Option>-ddump-&lt;pass&gt;</Option>:</Term>
179 <ListItem>
180 <Para>
181 <IndexTerm><Primary>-ddump-&lt;pass&gt; options</Primary></IndexTerm>
182 Make a debugging dump after pass <Literal>&lt;pass&gt;</Literal> (may be common enough to
183 need a short form&hellip;).  You can get all of these at once (<Emphasis>lots</Emphasis> of
184 output) by using <Option>-ddump-all</Option>, or most of them with <Option>-ddump-most</Option>.
185 Some of the most useful ones are:
186 </Para>
187
188 <Para>
189 <VariableList>
190
191 <VarListEntry>
192 <Term><Option>-ddump-parsed</Option>:</Term>
193 <ListItem>
194 <Para>
195 oarser output
196 </Para>
197 </ListItem>
198 </VarListEntry>
199 <VarListEntry>
200 <Term><Option>-ddump-rn</Option>:</Term>
201 <ListItem>
202 <Para>
203 renamer output
204 </Para>
205 </ListItem>
206 </VarListEntry>
207 <VarListEntry>
208 <Term><Option>-ddump-tc</Option>:</Term>
209 <ListItem>
210 <Para>
211 typechecker output
212 </Para>
213 </ListItem>
214 </VarListEntry>
215 <VarListEntry>
216 <Term><Option>-ddump-deriv</Option>:</Term>
217 <ListItem>
218 <Para>
219 derived instances
220 </Para>
221 </ListItem>
222 </VarListEntry>
223 <VarListEntry>
224 <Term><Option>-ddump-ds</Option>:</Term>
225 <ListItem>
226 <Para>
227 desugarer output
228 </Para>
229 </ListItem>
230 </VarListEntry>
231 <VarListEntry>
232 <Term><Option>-ddump-spec</Option>:</Term>
233 <ListItem>
234 <Para>
235 output of specialisation pass
236 </Para>
237 </ListItem>
238 </VarListEntry>
239 <VarListEntry>
240 <Term><Option>-ddump-rules</Option>:</Term>
241 <ListItem>
242 <Para>
243 dumps all rewrite rules (including those generated by the specialisation pass)
244 </Para>
245 </ListItem>
246 </VarListEntry>
247 <VarListEntry>
248 <Term><Option>-ddump-simpl</Option>:</Term>
249 <ListItem>
250 <Para>
251 simplifer output (Core-to-Core passes)
252 </Para>
253 </ListItem>
254 </VarListEntry>
255 <VarListEntry>
256 <Term><Option>-ddump-usagesp</Option>:</Term>
257 <ListItem>
258 <Para>
259 UsageSP inference pre-inf and output
260 </Para>
261 </ListItem>
262 </VarListEntry>
263 <VarListEntry>
264 <Term><Option>-ddump-cpranal</Option>:</Term>
265 <ListItem>
266 <Para>
267 CPR analyser output
268 </Para>
269 </ListItem>
270 </VarListEntry>
271 <VarListEntry>
272 <Term><Option>-ddump-stranal</Option>:</Term>
273 <ListItem>
274 <Para>
275 strictness analyser output
276 </Para>
277 </ListItem>
278 </VarListEntry>
279 <VarListEntry>
280 <Term><Option>-ddump-workwrap</Option>:</Term>
281 <ListItem>
282 <Para>
283 worker/wrapper split output
284 </Para>
285 </ListItem>
286 </VarListEntry>
287 <VarListEntry>
288 <Term><Option>-ddump-occur-anal</Option>:</Term>
289 <ListItem>
290 <Para>
291 `occurrence analysis' output
292 </Para>
293 </ListItem>
294 </VarListEntry>
295 <VarListEntry>
296 <Term><Option>-ddump-stg</Option>:</Term>
297 <ListItem>
298 <Para>
299 output of STG-to-STG passes
300 </Para>
301 </ListItem>
302 </VarListEntry>
303 <VarListEntry>
304 <Term><Option>-ddump-absC</Option>:</Term>
305 <ListItem>
306 <Para>
307 <Emphasis>un</Emphasis>flattened Abstract&nbsp;C
308 </Para>
309 </ListItem>
310 </VarListEntry>
311 <VarListEntry>
312 <Term><Option>-ddump-flatC</Option>:</Term>
313 <ListItem>
314 <Para>
315 <Emphasis>flattened</Emphasis> Abstract&nbsp;C
316 </Para>
317 </ListItem>
318 </VarListEntry>
319 <VarListEntry>
320 <Term><Option>-ddump-realC</Option>:</Term>
321 <ListItem>
322 <Para>
323 same as what goes to the C compiler
324 </Para>
325 </ListItem>
326 </VarListEntry>
327 <VarListEntry>
328 <Term><Option>-ddump-asm</Option>:</Term>
329 <ListItem>
330 <Para>
331 assembly language from the native-code generator
332 </Para>
333 </ListItem>
334 </VarListEntry>
335 </VariableList>
336 <IndexTerm><Primary>-ddump-all option</Primary></IndexTerm>
337 <IndexTerm><Primary>-ddump-most option</Primary></IndexTerm>
338 <IndexTerm><Primary>-ddump-parsed option</Primary></IndexTerm>
339 <IndexTerm><Primary>-ddump-rn option</Primary></IndexTerm>
340 <IndexTerm><Primary>-ddump-tc option</Primary></IndexTerm>
341 <IndexTerm><Primary>-ddump-deriv option</Primary></IndexTerm>
342 <IndexTerm><Primary>-ddump-ds option</Primary></IndexTerm>
343 <IndexTerm><Primary>-ddump-simpl option</Primary></IndexTerm>
344 <IndexTerm><Primary>-ddump-cpranal option</Primary></IndexTerm>
345 <IndexTerm><Primary>-ddump-workwrap option</Primary></IndexTerm>
346 <IndexTerm><Primary>-ddump-rules option</Primary></IndexTerm>
347 <IndexTerm><Primary>-ddump-usagesp option</Primary></IndexTerm>
348 <IndexTerm><Primary>-ddump-stranal option</Primary></IndexTerm>
349 <IndexTerm><Primary>-ddump-occur-anal option</Primary></IndexTerm>
350 <IndexTerm><Primary>-ddump-spec option</Primary></IndexTerm>
351 <IndexTerm><Primary>-ddump-stg option</Primary></IndexTerm>
352 <IndexTerm><Primary>-ddump-absC option</Primary></IndexTerm>
353 <IndexTerm><Primary>-ddump-flatC option</Primary></IndexTerm>
354 <IndexTerm><Primary>-ddump-realC option</Primary></IndexTerm>
355 <IndexTerm><Primary>-ddump-asm option</Primary></IndexTerm>
356 </Para>
357 </ListItem>
358 </VarListEntry>
359 <VarListEntry>
360 <Term><Option>-dverbose-simpl</Option> and <Option>-dverbose-stg</Option>:</Term>
361 <ListItem>
362 <Para>
363 <IndexTerm><Primary>-dverbose-simpl option</Primary></IndexTerm>
364 <IndexTerm><Primary>-dverbose-stg option</Primary></IndexTerm>
365 Show the output of the intermediate Core-to-Core and STG-to-STG
366 passes, respectively.  (<Emphasis>Lots</Emphasis> of output!) So: when we're 
367 really desperate:
368
369 <Screen>
370 % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
371 </Screen>
372
373 </Para>
374 </ListItem>
375 </VarListEntry>
376 <VarListEntry>
377 <Term><Option>-ddump-simpl-iterations</Option>:</Term>
378 <ListItem>
379 <Para>
380 <IndexTerm><Primary>-ddump-simpl-iterations option</Primary></IndexTerm>
381 Show the output of each <Emphasis>iteration</Emphasis> of the simplifier (each run of
382 the simplifier has a maximum number of iterations, normally 4).  Used
383 when even <Option>-dverbose-simpl</Option> doesn't cut it.
384 </Para>
385 </ListItem>
386 </VarListEntry>
387 <VarListEntry>
388 <Term><Option>-dppr-&lcub;user,debug</Option>&rcub;:</Term>
389 <ListItem>
390 <Para>
391 <IndexTerm><Primary>-dppr-user option</Primary></IndexTerm>
392 <IndexTerm><Primary>-dppr-debug option</Primary></IndexTerm>
393 Debugging output is in one of several &ldquo;styles.&rdquo;  Take the printing
394 of types, for example.  In the &ldquo;user&rdquo; style, the compiler's internal
395 ideas about types are presented in Haskell source-level syntax,
396 insofar as possible.  In the &ldquo;debug&rdquo; style (which is the default for
397 debugging output), the types are printed in with
398 explicit foralls, and variables have their unique-id attached (so you
399 can check for things that look the same but aren't).
400 </Para>
401 </ListItem>
402 </VarListEntry>
403 <VarListEntry>
404 <Term><Option>-ddump-simpl-stats</Option>:</Term>
405 <ListItem>
406 <Para>
407 <IndexTerm><Primary>-ddump-simpl-stats option</Primary></IndexTerm>
408 Dump statistics about how many of each kind
409 of transformation too place.  If you add <Option>-dppr-debug</Option> you get more detailed information.
410 </Para>
411 </ListItem>
412 </VarListEntry>
413 <VarListEntry>
414 <Term><Option>-ddump-raw-asm</Option>:</Term>
415 <ListItem>
416 <Para>
417 <IndexTerm><Primary>-ddump-raw-asm option</Primary></IndexTerm>
418 Dump out the assembly-language stuff, before the &ldquo;mangler&rdquo; gets it.
419 </Para>
420 </ListItem>
421 </VarListEntry>
422 <VarListEntry>
423 <Term><Option>-ddump-rn-trace</Option>:</Term>
424 <ListItem>
425 <Para>
426 <IndexTerm><Primary>-ddump-rn-trace</Primary></IndexTerm>
427 Make the renamer be *real* chatty about what it is upto.
428 </Para>
429 </ListItem>
430 </VarListEntry>
431 <VarListEntry>
432 <Term><Option>-dshow-rn-stats</Option>:</Term>
433 <ListItem>
434 <Para>
435 <IndexTerm><Primary>-dshow-rn-stats</Primary></IndexTerm>
436 Print out summary of what kind of information the renamer had to bring
437 in.
438 </Para>
439 </ListItem>
440 </VarListEntry>
441 <VarListEntry>
442 <Term><Option>-dshow-unused-imports</Option>:</Term>
443 <ListItem>
444 <Para>
445 <IndexTerm><Primary>-dshow-unused-imports</Primary></IndexTerm>
446 Have the renamer report what imports does not contribute.
447 </Para>
448 </ListItem>
449 </VarListEntry>
450 </VariableList>
451 </Para>
452
453 </Sect2>
454
455 <Sect2 id="checking-consistency">
456 <Title>Checking for consistency
457 </Title>
458
459 <Para>
460 <IndexTerm><Primary>consistency checks</Primary></IndexTerm>
461 <IndexTerm><Primary>lint</Primary></IndexTerm>
462 </Para>
463
464 <Para>
465 <VariableList>
466
467 <VarListEntry>
468 <Term><Option>-dcore-lint</Option>:</Term>
469 <ListItem>
470 <Para>
471 <IndexTerm><Primary>-dcore-lint option</Primary></IndexTerm>
472 Turn on heavyweight intra-pass sanity-checking within GHC, at Core
473 level.  (It checks GHC's sanity, not yours.)
474 </Para>
475 </ListItem>
476 </VarListEntry>
477 <VarListEntry>
478 <Term><Option>-dstg-lint</Option>:</Term>
479 <ListItem>
480 <Para>
481 <IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
482 Ditto for STG level.
483 </Para>
484 </ListItem>
485 </VarListEntry>
486 <VarListEntry>
487 <Term><Option>-dusagesp-lint</Option>:</Term>
488 <ListItem>
489 <Para>
490 <IndexTerm><Primary>-dstg-lint option</Primary></IndexTerm>
491 Turn on checks around UsageSP inference (<Option>-fusagesp</Option>).  This verifies
492 various simple properties of the results of the inference, and also
493 warns if any identifier with a used-once annotation before the
494 inference has a used-many annotation afterwards; this could indicate a
495 non-worksafe transformation is being applied.
496 </Para>
497 </ListItem>
498 </VarListEntry>
499 </VariableList>
500 </Para>
501
502 </Sect2>
503
504 <Sect2>
505 <Title>How to read Core syntax (from some <Option>-ddump-*</Option> flags)</Title>
506
507 <Para>
508 <IndexTerm><Primary>reading Core syntax</Primary></IndexTerm>
509 <IndexTerm><Primary>Core syntax, how to read</Primary></IndexTerm>
510 </Para>
511
512 <Para>
513 Let's do this by commenting an example.  It's from doing
514 <Option>-ddump-ds</Option> on this code:
515
516 <ProgramListing>
517 skip2 m = m : skip2 (m+2)
518 </ProgramListing>
519
520 </Para>
521
522 <Para>
523 Before we jump in, a word about names of things.  Within GHC,
524 variables, type constructors, etc., are identified by their
525 &ldquo;Uniques.&rdquo;  These are of the form `letter' plus `number' (both
526 loosely interpreted).  The `letter' gives some idea of where the
527 Unique came from; e.g., <Literal>&lowbar;</Literal> means &ldquo;built-in type variable&rdquo;;
528 <Literal>t</Literal> means &ldquo;from the typechecker&rdquo;; <Literal>s</Literal> means &ldquo;from the
529 simplifier&rdquo;; and so on.  The `number' is printed fairly compactly in
530 a `base-62' format, which everyone hates except me (WDP).
531 </Para>
532
533 <Para>
534 Remember, everything has a &ldquo;Unique&rdquo; and it is usually printed out
535 when debugging, in some form or another.  So here we go&hellip;
536 </Para>
537
538 <Para>
539 <ProgramListing>
540 Desugared:
541 Main.skip2{-r1L6-} :: _forall_ a$_4 =&#62;{{Num a$_4}} -&#62; a$_4 -&#62; [a$_4]
542
543 --# `r1L6' is the Unique for Main.skip2;
544 --# `_4' is the Unique for the type-variable (template) `a'
545 --# `{{Num a$_4}}' is a dictionary argument
546
547 _NI_
548
549 --# `_NI_' means "no (pragmatic) information" yet; it will later
550 --# evolve into the GHC_PRAGMA info that goes into interface files.
551
552 Main.skip2{-r1L6-} =
553     /\ _4 -&#62; \ d.Num.t4Gt -&#62;
554         let {
555           {- CoRec -}
556           +.t4Hg :: _4 -&#62; _4 -&#62; _4
557           _NI_
558           +.t4Hg = (+{-r3JH-} _4) d.Num.t4Gt
559
560           fromInt.t4GS :: Int{-2i-} -&#62; _4
561           _NI_
562           fromInt.t4GS = (fromInt{-r3JX-} _4) d.Num.t4Gt
563
564 --# The `+' class method (Unique: r3JH) selects the addition code
565 --# from a `Num' dictionary (now an explicit lamba'd argument).
566 --# Because Core is 2nd-order lambda-calculus, type applications
567 --# and lambdas (/\) are explicit.  So `+' is first applied to a
568 --# type (`_4'), then to a dictionary, yielding the actual addition
569 --# function that we will use subsequently...
570
571 --# We play the exact same game with the (non-standard) class method
572 --# `fromInt'.  Unsurprisingly, the type `Int' is wired into the
573 --# compiler.
574
575           lit.t4Hb :: _4
576           _NI_
577           lit.t4Hb =
578               let {
579                 ds.d4Qz :: Int{-2i-}
580                 _NI_
581                 ds.d4Qz = I#! 2#
582               } in  fromInt.t4GS ds.d4Qz
583
584 --# `I# 2#' is just the literal Int `2'; it reflects the fact that
585 --# GHC defines `data Int = I# Int#', where Int# is the primitive
586 --# unboxed type.  (see relevant info about unboxed types elsewhere...)
587
588 --# The `!' after `I#' indicates that this is a *saturated*
589 --# application of the `I#' data constructor (i.e., not partially
590 --# applied).
591
592           skip2.t3Ja :: _4 -&#62; [_4]
593           _NI_
594           skip2.t3Ja =
595               \ m.r1H4 -&#62;
596                   let { ds.d4QQ :: [_4]
597                         _NI_
598                         ds.d4QQ =
599                     let {
600                       ds.d4QY :: _4
601                       _NI_
602                       ds.d4QY = +.t4Hg m.r1H4 lit.t4Hb
603                     } in  skip2.t3Ja ds.d4QY
604                   } in
605                   :! _4 m.r1H4 ds.d4QQ
606
607           {- end CoRec -}
608         } in  skip2.t3Ja
609 </ProgramListing>
610 </Para>
611
612 <Para>
613 (&ldquo;It's just a simple functional language&rdquo; is an unregisterised
614 trademark of Peyton Jones Enterprises, plc.)
615 </Para>
616
617 </Sect2>
618
619 <Sect2 id="source-file-options">
620 <Title>Command line options in source files
621 </Title>
622
623 <Para>
624 <IndexTerm><Primary>source-file options</Primary></IndexTerm>
625 </Para>
626
627 <Para>
628 Sometimes it is useful to make the connection between a source file
629 and the command-line options it requires quite tight. For instance,
630 if a (Glasgow) Haskell source file uses <Literal>casm</Literal>s, the C back-end
631 often needs to be told about which header files to include. Rather than
632 maintaining the list of files the source depends on in a
633 <Filename>Makefile</Filename> (using the <Option>-&num;include</Option> command-line option), it is
634 possible to do this directly in the source file using the <Literal>OPTIONS</Literal>
635 pragma <IndexTerm><Primary>OPTIONS pragma</Primary></IndexTerm>: 
636 </Para>
637
638 <Para>
639 <ProgramListing>
640 {-# OPTIONS -#include "foo.h" #-}
641 module X where
642
643 ...
644 </ProgramListing>
645 </Para>
646
647 <Para>
648 <Literal>OPTIONS</Literal> pragmas are only looked for at the top of your source
649 files, upto the first (non-literate,non-empty) line not containing
650 <Literal>OPTIONS</Literal>. Multiple <Literal>OPTIONS</Literal> pragmas are recognised. Note
651 that your command shell does not get to the source file options, they
652 are just included literally in the array of command-line arguments
653 the compiler driver maintains internally, so you'll be desperately
654 disappointed if you try to glob etc. inside <Literal>OPTIONS</Literal>.
655 </Para>
656
657 <Para>
658 NOTE: the contents of OPTIONS are prepended to the command-line
659 options, so you *do* have the ability to override OPTIONS settings
660 via the command line.
661 </Para>
662
663 <Para>
664 It is not recommended to move all the contents of your Makefiles into
665 your source files, but in some circumstances, the <Literal>OPTIONS</Literal> pragma
666 is the Right Thing. (If you use <Option>-keep-hc-file-too</Option> and have OPTION
667 flags in your module, the OPTIONS will get put into the generated .hc
668 file).
669 </Para>
670
671 </Sect2>
672
673 </Sect1>
674
675 <!-- Emacs stuff:
676      ;;; Local Variables: ***
677      ;;; mode: sgml ***
678      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***
679      ;;; End: ***
680  -->