Revert "Revert "Revert "Support for multiple signature files in scope."""
[ghc.git] / docs / users_guide / separate_compilation.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <sect1 id="separate-compilation">
3 <title>Filenames and separate compilation</title>
4
5 <indexterm><primary>separate compilation</primary></indexterm>
6 <indexterm><primary>recompilation checker</primary></indexterm>
7 <indexterm><primary>make and recompilation</primary></indexterm>
8
9 <para>This section describes what files GHC expects to find, what
10 files it creates, where these files are stored, and what options
11 affect this behaviour.</para>
12
13 <para>Note that this section is written with
14 <firstterm>hierarchical modules</firstterm> in mind (see <xref
15 linkend="hierarchical-modules"/>); hierarchical modules are an
16 extension to Haskell 98 which extends the lexical syntax of
17 module names to include a dot &lsquo;.&rsquo;. Non-hierarchical
18 modules are thus a special case in which none of the module names
19 contain dots.</para>
20
21 <para>Pathname conventions vary from system to system. In
22 particular, the directory separator is
23 &lsquo;<literal>/</literal>&rsquo; on Unix systems and
24 &lsquo;<literal>\</literal>&rsquo; on Windows systems. In the
25 sections that follow, we shall consistently use
26 &lsquo;<literal>/</literal>&rsquo; as the directory separator;
27 substitute this for the appropriate character for your
28 system.</para>
29
30 <sect2 id="source-files">
31 <title>Haskell source files</title>
32
33 <indexterm><primary>filenames</primary></indexterm>
34
35 <para>Each Haskell source module should be placed in a file on
36 its own.</para>
37
38 <para>Usually, the file should be named after the module name,
39 replacing dots in the module name by directory separators. For
40 example, on a Unix system, the module <literal>A.B.C</literal>
41 should be placed in the file <literal>A/B/C.hs</literal>,
42 relative to some base directory. If the module is not going to
43 be imported by another module (<literal>Main</literal>, for
44 example), then you are free to use any filename for it.</para>
45
46 <indexterm><primary>unicode</primary></indexterm>
47
48 <para> GHC assumes that source files are
49 ASCII<indexterm><primary>ASCII</primary></indexterm> or
50 UTF-8<indexterm><primary>UTF-8</primary></indexterm> only, other
51 encodings<indexterm><primary>encoding</primary></indexterm> are
52 not recognised. However, invalid UTF-8 sequences will be
53 ignored in comments, so it is possible to use other encodings
54 such as
55 Latin-1<indexterm><primary>Latin-1</primary></indexterm>, as
56 long as the non-comment source code is ASCII only.</para>
57 </sect2>
58
59 <sect2 id="output-files">
60 <title>Output files</title>
61
62 <indexterm><primary>interface files</primary></indexterm>
63 <indexterm><primary><literal>.hi</literal> files</primary></indexterm>
64 <indexterm><primary>object files</primary></indexterm>
65 <indexterm><primary><literal>.o</literal> files</primary></indexterm>
66
67 <para>When asked to compile a source file, GHC normally
68 generates two files: an <firstterm>object file</firstterm>, and
69 an <firstterm>interface file</firstterm>. </para>
70
71 <para>The object file, which normally ends in a
72 <literal>.o</literal> suffix, contains the compiled code for the
73 module.</para>
74
75 <para>The interface file,
76 which normally ends in a <literal>.hi</literal> suffix, contains
77 the information that GHC needs in order to compile further
78 modules that depend on this module. It contains things like the
79 types of exported functions, definitions of data types, and so
80 on. It is stored in a binary format, so don't try to read one;
81 use the <option>--show-iface</option> option instead (see <xref
82 linkend="hi-options"/>).</para>
83
84 <para>You should think of the object file and the interface file as a
85 pair, since the interface file is in a sense a compiler-readable
86 description of the contents of the object file. If the
87 interface file and object file get out of sync for any reason,
88 then the compiler may end up making assumptions about the object
89 file that aren't true; trouble will almost certainly follow.
90 For this reason, we recommend keeping object files and interface
91 files in the same place (GHC does this by default, but it is
92 possible to override the defaults as we'll explain
93 shortly).</para>
94
95 <para>Every module has a <emphasis>module name</emphasis>
96 defined in its source code (<literal>module A.B.C where
97 ...</literal>).</para>
98
99 <para>The name of the object file generated by GHC is derived
100 according to the following rules, where
101 <replaceable>osuf</replaceable> is the object-file suffix (this
102 can be changed with the <option>-osuf</option> option).</para>
103
104 <itemizedlist>
105 <listitem>
106 <para>If there is no <option>-odir</option> option (the
107 default), then the object filename is derived from the
108 source filename (ignoring the module name) by replacing the
109 suffix with <replaceable>osuf</replaceable>.</para>
110 </listitem>
111 <listitem>
112 <para>If
113 <option>-odir</option>&nbsp;<replaceable>dir</replaceable>
114 has been specified, then the object filename is
115 <replaceable>dir</replaceable>/<replaceable>mod</replaceable>.<replaceable>osuf</replaceable>,
116 where <replaceable>mod</replaceable> is the module name with
117 dots replaced by slashes. GHC will silently create the necessary directory
118 structure underneath <replaceable>dir</replaceable>, if it does not
119 already exist.</para>
120 </listitem>
121 </itemizedlist>
122
123 <para>The name of the interface file is derived using the same
124 rules, except that the suffix is
125 <replaceable>hisuf</replaceable> (<literal>.hi</literal> by
126 default) instead of <replaceable>osuf</replaceable>, and the
127 relevant options are <option>-hidir</option> and
128 <option>-hisuf</option> instead of <option>-odir</option> and
129 <option>-osuf</option> respectively.</para>
130
131 <para>For example, if GHC compiles the module
132 <literal>A.B.C</literal> in the file
133 <filename>src/A/B/C.hs</filename>, with no
134 <literal>-odir</literal> or <literal>-hidir</literal> flags, the
135 interface file will be put in <literal>src/A/B/C.hi</literal>
136 and the object file in <literal>src/A/B/C.o</literal>.</para>
137
138 <para>For any module that is imported, GHC requires that the
139 name of the module in the import statement exactly matches the
140 name of the module in the interface file (or source file) found
141 using the strategy specified in <xref linkend="search-path"/>.
142 This means that for most modules, the source file name should
143 match the module name.</para>
144
145 <para>However, note that it is reasonable to have a module
146 <literal>Main</literal> in a file named
147 <filename>foo.hs</filename>, but this only works because GHC
148 never needs to search for the interface for module
149 <literal>Main</literal> (because it is never imported). It is
150 therefore possible to have several <literal>Main</literal>
151 modules in separate source files in the same directory, and GHC
152 will not get confused.</para>
153
154 <para>In batch compilation mode, the name of the object file can
155 also be overridden using the <option>-o</option> option, and the
156 name of the interface file can be specified directly using the
157 <option>-ohi</option> option.</para>
158 </sect2>
159
160 <sect2 id="search-path">
161 <title>The search path</title>
162
163 <indexterm><primary>search path</primary>
164 </indexterm>
165 <indexterm><primary>interface files, finding them</primary></indexterm>
166 <indexterm><primary>finding interface files</primary></indexterm>
167
168 <para>In your program, you import a module
169 <literal>Foo</literal> by saying <literal>import Foo</literal>.
170 In <option>--make</option> mode or GHCi, GHC will look for a
171 source file for <literal>Foo</literal> and arrange to compile it
172 first. Without <option>--make</option>, GHC will look for the
173 interface file for <literal>Foo</literal>, which should have
174 been created by an earlier compilation of
175 <literal>Foo</literal>. GHC uses the same strategy in each of
176 these cases for finding the appropriate file.</para>
177
178 <para>This strategy is as follows: GHC keeps a list of
179 directories called the <firstterm>search path</firstterm>. For
180 each of these directories, it tries appending
181 <replaceable>basename</replaceable><literal>.</literal><replaceable>extension</replaceable>
182 to the directory, and checks whether the file exists. The value
183 of <replaceable>basename</replaceable> is the module name with
184 dots replaced by the directory separator ('/' or '\', depending
185 on the system), and <replaceable>extension</replaceable> is a
186 source extension (<literal>hs</literal>, <literal>lhs</literal>)
187 if we are in <option>--make</option> mode or GHCi, or
188 <replaceable>hisuf</replaceable> otherwise.</para>
189
190 <para>For example, suppose the search path contains directories
191 <literal>d1</literal>, <literal>d2</literal>, and
192 <literal>d3</literal>, and we are in <literal>--make</literal>
193 mode looking for the source file for a module
194 <literal>A.B.C</literal>. GHC will look in
195 <literal>d1/A/B/C.hs</literal>, <literal>d1/A/B/C.lhs</literal>,
196 <literal>d2/A/B/C.hs</literal>, and so on.</para>
197
198 <para>The search path by default contains a single directory:
199 <quote>.</quote> (i.e. the current directory). The following
200 options can be used to add to or change the contents of the
201 search path:</para>
202
203 <variablelist>
204 <varlistentry>
205 <term><option>-i<replaceable>dirs</replaceable></option></term>
206 <listitem>
207 <para><indexterm><primary><option>-i<replaceable>dirs</replaceable></option>
208 </primary></indexterm>This flag appends a colon-separated
209 list of <filename>dirs</filename> to the search path.</para>
210 </listitem>
211 </varlistentry>
212
213 <varlistentry>
214 <term><option>-i</option></term>
215 <listitem>
216 <para>resets the search path back to nothing.</para>
217 </listitem>
218 </varlistentry>
219 </variablelist>
220
221 <para>This isn't the whole story: GHC also looks for modules in
222 pre-compiled libraries, known as packages. See the section on
223 packages (<xref linkend="packages"/>) for details.</para>
224 </sect2>
225
226 <sect2 id="options-output">
227 <title>Redirecting the compilation output(s)</title>
228
229 <indexterm><primary>output-directing options</primary></indexterm>
230 <indexterm><primary>redirecting compilation output</primary></indexterm>
231
232 <variablelist>
233 <varlistentry>
234 <term>
235 <option>-o</option> <replaceable>file</replaceable>
236 <indexterm><primary><option>-o</option></primary></indexterm>
237 </term>
238 <listitem>
239 <para>GHC's compiled output normally goes into a
240 <filename>.hc</filename>, <filename>.o</filename>, etc.,
241 file, depending on the last-run compilation phase. The
242 option <option>-o <replaceable>file</replaceable></option>
243 re-directs the output of that last-run phase to
244 <replaceable>file</replaceable>.</para>
245
246 <para>Note: this &ldquo;feature&rdquo; can be
247 counterintuitive: <command>ghc -C -o foo.o
248 foo.hs</command> will put the intermediate C code in the
249 file <filename>foo.o</filename>, name
250 notwithstanding!</para>
251
252 <para>This option is most often used when creating an
253 executable file, to set the filename of the executable.
254 For example:
255 <screen> ghc -o prog --make Main</screen>
256
257 will compile the program starting with module
258 <literal>Main</literal> and put the executable in the
259 file <literal>prog</literal>.</para>
260
261 <para>Note: on Windows, if the result is an executable
262 file, the extension "<filename>.exe</filename>" is added
263 if the specified filename does not already have an
264 extension. Thus
265 <programlisting>
266 ghc -o foo Main.hs
267 </programlisting>
268 will compile and link the module
269 <filename>Main.hs</filename>, and put the resulting
270 executable in <filename>foo.exe</filename> (not
271 <filename>foo</filename>).</para>
272
273 <para>If you use <command>ghc --make</command> and you don't
274 use the <option>-o</option>, the name GHC will choose
275 for the executable will be based on the name of the file
276 containing the module <literal>Main</literal>.
277 Note that with GHC the <literal>Main</literal> module doesn't
278 have to be put in file <filename>Main.hs</filename>.
279 Thus both
280 <programlisting>
281 ghc --make Prog
282 </programlisting>
283 and
284 <programlisting>
285 ghc --make Prog.hs
286 </programlisting>
287 will produce <filename>Prog</filename> (or
288 <filename>Prog.exe</filename> if you are on Windows).</para>
289 </listitem>
290 </varlistentry>
291
292 <varlistentry>
293 <term>
294 <option>-odir</option> <replaceable>dir</replaceable>
295 <indexterm><primary><option>-odir</option></primary></indexterm>
296 </term>
297 <listitem>
298 <para>Redirects object files to directory
299 <replaceable>dir</replaceable>. For example:</para>
300
301 <screen>
302 $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m`
303 </screen>
304
305 <para>The object files, <filename>Foo.o</filename>,
306 <filename>Bar.o</filename>, and
307 <filename>Bumble.o</filename> would be put into a
308 subdirectory named after the architecture of the executing
309 machine (<filename>x86</filename>,
310 <filename>mips</filename>, etc).</para>
311
312 <para>Note that the <option>-odir</option> option does
313 <emphasis>not</emphasis> affect where the interface files
314 are put; use the <option>-hidir</option> option for that.
315 In the above example, they would still be put in
316 <filename>parse/Foo.hi</filename>,
317 <filename>parse/Bar.hi</filename>, and
318 <filename>gurgle/Bumble.hi</filename>.</para>
319 </listitem>
320 </varlistentry>
321
322 <varlistentry>
323 <term>
324 <option>-ohi</option> <replaceable>file</replaceable>
325 <indexterm><primary><option>-ohi</option></primary></indexterm>
326 </term>
327 <listitem>
328 <para>The interface output may be directed to another file
329 <filename>bar2/Wurble.iface</filename> with the option
330 <option>-ohi bar2/Wurble.iface</option> (not
331 recommended).</para>
332
333 <para>WARNING: if you redirect the interface file
334 somewhere that GHC can't find it, then the recompilation
335 checker may get confused (at the least, you won't get any
336 recompilation avoidance). We recommend using a
337 combination of <option>-hidir</option> and
338 <option>-hisuf</option> options instead, if
339 possible.</para>
340
341 <para>To avoid generating an interface at all, you could
342 use this option to redirect the interface into the bit
343 bucket: <literal>-ohi /dev/null</literal>, for
344 example.</para>
345 </listitem>
346 </varlistentry>
347
348 <varlistentry>
349 <term>
350 <option>-hidir</option> <replaceable>dir</replaceable>
351 <indexterm><primary><option>-hidir</option></primary></indexterm>
352 </term>
353 <listitem>
354 <para>Redirects all generated interface files into
355 <replaceable>dir</replaceable>, instead of the
356 default.</para>
357 </listitem>
358 </varlistentry>
359
360 <varlistentry>
361 <term>
362 <option>-stubdir</option> <replaceable>dir</replaceable>
363 <indexterm><primary><option>-stubdir</option></primary></indexterm>
364 </term>
365 <listitem>
366 <para>Redirects all generated FFI stub files into
367 <replaceable>dir</replaceable>. Stub files are generated when the
368 Haskell source contains a <literal>foreign export</literal> or
369 <literal>foreign import "&amp;wrapper"</literal> declaration (see <xref
370 linkend="foreign-export-ghc" />). The <option>-stubdir</option>
371 option behaves in exactly the same way as <option>-odir</option>
372 and <option>-hidir</option> with respect to hierarchical
373 modules.</para>
374 </listitem>
375 </varlistentry>
376
377 <varlistentry>
378 <term>
379 <option>-dumpdir</option> <replaceable>dir</replaceable>
380 <indexterm><primary><option>-dumpdir</option></primary></indexterm>
381 </term>
382 <listitem>
383 <para>Redirects all dump files into
384 <replaceable>dir</replaceable>. Dump files are generated when
385 <literal>-ddump-to-file</literal> is used with other
386 <literal>-ddump-*</literal> flags.</para>
387 </listitem>
388 </varlistentry>
389
390 <varlistentry>
391 <term>
392 <option>-outputdir</option> <replaceable>dir</replaceable>
393 <indexterm><primary><option>-outputdir</option></primary></indexterm>
394 </term>
395 <listitem>
396 <para>The <option>-outputdir</option> option is shorthand for
397 the combination
398 of <option>-odir</option>, <option>-hidir</option>,
399 <option>-stubdir</option> and <option>-dumpdir</option>.
400 </para>
401 </listitem>
402 </varlistentry>
403
404 <varlistentry>
405 <term>
406 <option>-osuf</option> <replaceable>suffix</replaceable>
407 <indexterm><primary><option>-osuf</option></primary></indexterm>
408 </term>
409 <term>
410 <option>-hisuf</option> <replaceable>suffix</replaceable>
411 <indexterm><primary><option>-hisuf</option></primary></indexterm>
412 </term>
413 <term>
414 <option>-hcsuf</option> <replaceable>suffix</replaceable>
415 <indexterm><primary><option>-hcsuf</option></primary></indexterm>
416 </term>
417 <listitem>
418 <para>The <option>-osuf</option>
419 <replaceable>suffix</replaceable> will change the
420 <literal>.o</literal> file suffix for object files to
421 whatever you specify. We use this when compiling
422 libraries, so that objects for the profiling versions of
423 the libraries don't clobber the normal ones.</para>
424
425 <para>Similarly, the <option>-hisuf</option>
426 <replaceable>suffix</replaceable> will change the
427 <literal>.hi</literal> file suffix for non-system
428 interface files (see <xref linkend="hi-options"/>).</para>
429
430 <para>Finally, the option <option>-hcsuf</option>
431 <replaceable>suffix</replaceable> will change the
432 <literal>.hc</literal> file suffix for compiler-generated
433 intermediate C files.</para>
434
435 <para>The <option>-hisuf</option>/<option>-osuf</option>
436 game is particularly useful if you want to compile a
437 program both with and without profiling, in the same
438 directory. You can say:
439 <screen>
440 ghc ...</screen>
441 to get the ordinary version, and
442 <screen>
443 ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</screen>
444 to get the profiled version.</para>
445 </listitem>
446 </varlistentry>
447 </variablelist>
448 </sect2>
449
450 <sect2 id="keeping-intermediates">
451 <title>Keeping Intermediate Files</title>
452 <indexterm><primary>intermediate files, saving</primary>
453 </indexterm>
454 <indexterm><primary><literal>.hc</literal> files, saving</primary>
455 </indexterm>
456 <indexterm><primary><literal>.ll</literal> files, saving</primary>
457 </indexterm>
458 <indexterm><primary><literal>.s</literal> files, saving</primary>
459 </indexterm>
460
461 <para>The following options are useful for keeping certain
462 intermediate files around, when normally GHC would throw these
463 away after compilation:</para>
464
465 <variablelist>
466 <varlistentry>
467 <term>
468 <option>-keep-hc-file</option>,
469 <option>-keep-hc-files</option>
470 <indexterm><primary><option>-keep-hc-file</option></primary></indexterm>
471 <indexterm><primary><option>-keep-hc-files</option></primary></indexterm>
472 </term>
473 <listitem>
474 <para>Keep intermediate <literal>.hc</literal> files when
475 doing <literal>.hs</literal>-to-<literal>.o</literal>
476 compilations via <link linkend="c-code-gen">C</link> (NOTE:
477 <literal>.hc</literal> files are only generated by
478 <link linkend="unreg">unregisterised</link> compilers).</para>
479 </listitem>
480 </varlistentry>
481
482 <varlistentry>
483 <term>
484 <option>-keep-llvm-file</option>,
485 <option>-keep-llvm-files</option>
486 <indexterm><primary><option>-keep-llvm-file</option></primary></indexterm>
487 <indexterm><primary><option>-keep-llvm-files</option></primary></indexterm>
488 </term>
489 <listitem>
490 <para>Keep intermediate <literal>.ll</literal> files when
491 doing <literal>.hs</literal>-to-<literal>.o</literal>
492 compilations via <link linkend="llvm-code-gen">LLVM</link>
493 (NOTE: <literal>.ll</literal> files aren't generated when using the
494 native code generator, you may need to use <option>-fllvm</option> to
495 force them to be produced).</para>
496 </listitem>
497 </varlistentry>
498
499 <varlistentry>
500 <term>
501 <option>-keep-s-file</option>,
502 <option>-keep-s-files</option>
503 <indexterm><primary><option>-keep-s-file</option></primary></indexterm>
504 <indexterm><primary><option>-keep-s-files</option></primary></indexterm>
505 </term>
506 <listitem>
507 <para>Keep intermediate <literal>.s</literal> files.</para>
508 </listitem>
509 </varlistentry>
510
511 <varlistentry>
512 <term>
513 <option>-keep-tmp-files</option>
514 <indexterm><primary><option>-keep-tmp-files</option></primary></indexterm>
515 <indexterm><primary>temporary files</primary><secondary>keeping</secondary></indexterm>
516 </term>
517 <listitem>
518 <para>Instructs the GHC driver not to delete any of its
519 temporary files, which it normally keeps in
520 <literal>/tmp</literal> (or possibly elsewhere; see <xref
521 linkend="temp-files"/>). Running GHC with
522 <option>-v</option> will show you what temporary files
523 were generated along the way.</para>
524 </listitem>
525 </varlistentry>
526 </variablelist>
527 </sect2>
528
529 <sect2 id="temp-files">
530 <title>Redirecting temporary files</title>
531
532 <indexterm>
533 <primary>temporary files</primary>
534 <secondary>redirecting</secondary>
535 </indexterm>
536
537 <variablelist>
538 <varlistentry>
539 <term>
540 <option>-tmpdir</option>
541 <indexterm><primary><option>-tmpdir</option></primary></indexterm>
542 </term>
543 <listitem>
544 <para>If you have trouble because of running out of space
545 in <filename>/tmp</filename> (or wherever your
546 installation thinks temporary files should go), you may
547 use the <option>-tmpdir
548 &lt;dir&gt;</option><indexterm><primary>-tmpdir
549 &lt;dir&gt; option</primary></indexterm> option to specify
550 an alternate directory. For example, <option>-tmpdir
551 .</option> says to put temporary files in the current
552 working directory.</para>
553
554 <para>Alternatively, use your <constant>TMPDIR</constant>
555 environment variable.<indexterm><primary>TMPDIR
556 environment variable</primary></indexterm> Set it to the
557 name of the directory where temporary files should be put.
558 GCC and other programs will honour the
559 <constant>TMPDIR</constant> variable as well.</para>
560
561 <para>Even better idea: Set the
562 <constant>DEFAULT_TMPDIR</constant> make variable when
563 building GHC, and never worry about
564 <constant>TMPDIR</constant> again. (see the build
565 documentation).</para>
566 </listitem>
567 </varlistentry>
568 </variablelist>
569 </sect2>
570
571 <sect2 id="hi-options">
572 <title>Other options related to interface files</title>
573 <indexterm><primary>interface files, options</primary></indexterm>
574
575 <variablelist>
576 <varlistentry>
577 <term>
578 <option>-ddump-hi</option>
579 <indexterm><primary><option>-ddump-hi</option></primary></indexterm>
580 </term>
581 <listitem>
582 <para>Dumps the new interface to standard output.</para>
583 </listitem>
584 </varlistentry>
585
586 <varlistentry>
587 <term>
588 <option>-ddump-hi-diffs</option>
589 <indexterm><primary><option>-ddump-hi-diffs</option></primary></indexterm>
590 </term>
591 <listitem>
592 <para>The compiler does not overwrite an existing
593 <filename>.hi</filename> interface file if the new one is
594 the same as the old one; this is friendly to
595 <command>make</command>. When an interface does change,
596 it is often enlightening to be informed. The
597 <option>-ddump-hi-diffs</option> option will make GHC
598 report the differences between the old and
599 new <filename>.hi</filename> files.</para>
600 </listitem>
601 </varlistentry>
602
603 <varlistentry>
604 <term>
605 <option>-ddump-minimal-imports</option>
606 <indexterm><primary><option>-ddump-minimal-imports</option></primary></indexterm>
607 </term>
608 <listitem>
609 <para>Dump to the file
610 <filename><replaceable>M</replaceable>.imports</filename>
611 (where <replaceable>M</replaceable> is the name of the
612 module being compiled) a "minimal" set of import
613 declarations. The directory where the
614 <filename>.imports</filename> files are created can be
615 controlled via the <option>-dumpdir</option>
616 option.</para> <para>You can safely replace all the import
617 declarations in
618 <filename><replaceable>M</replaceable>.hs</filename> with
619 those found in its respective <filename>.imports</filename>
620 file. Why would you want to do that? Because the
621 "minimal" imports (a) import everything explicitly, by
622 name, and (b) import nothing that is not required. It can
623 be quite painful to maintain this property by hand, so
624 this flag is intended to reduce the labour.</para>
625 </listitem>
626 </varlistentry>
627
628 <varlistentry>
629 <term>
630 <option>--show-iface</option> <replaceable>file</replaceable>
631 <indexterm><primary><option>--show-iface</option></primary></indexterm>
632 </term>
633 <listitem>
634 <para>where <replaceable>file</replaceable> is the name of
635 an interface file, dumps the contents of that interface in
636 a human-readable (ish) format. See <xref linkend="modes"/>.</para>
637 </listitem>
638 </varlistentry>
639 </variablelist>
640 </sect2>
641
642 <sect2 id="recomp">
643 <title>The recompilation checker</title>
644
645 <indexterm><primary>recompilation checker</primary></indexterm>
646
647 <variablelist>
648 <varlistentry>
649 <term>
650 <option>-fforce-recomp</option>
651 <indexterm><primary><option>-fforce-recomp</option></primary></indexterm>
652 <indexterm><primary><option>-fno-force-recomp</option></primary></indexterm>
653 </term>
654 <listitem>
655 <para>Turn off recompilation checking (which is on by
656 default). Recompilation checking normally stops
657 compilation early, leaving an existing
658 <filename>.o</filename> file in place, if it can be
659 determined that the module does not need to be
660 recompiled.</para>
661 </listitem>
662 </varlistentry>
663 </variablelist>
664
665 <para>In the olden days, GHC compared the newly-generated
666 <filename>.hi</filename> file with the previous version; if they
667 were identical, it left the old one alone and didn't change its
668 modification date. In consequence, importers of a module with
669 an unchanged output <filename>.hi</filename> file were not
670 recompiled.</para>
671
672 <para>This doesn't work any more. Suppose module
673 <literal>C</literal> imports module <literal>B</literal>, and
674 <literal>B</literal> imports module <literal>A</literal>. So
675 changes to module <literal>A</literal> might require module
676 <literal>C</literal> to be recompiled, and hence when
677 <filename>A.hi</filename> changes we should check whether
678 <literal>C</literal> should be recompiled. However, the
679 dependencies of <literal>C</literal> will only list
680 <literal>B.hi</literal>, not <literal>A.hi</literal>, and some
681 changes to <literal>A</literal> (changing the definition of a
682 function that appears in an inlining of a function exported by
683 <literal>B</literal>, say) may conceivably not change
684 <filename>B.hi</filename> one jot. So now&hellip;</para>
685
686 <para>GHC calculates a fingerprint (in fact an MD5 hash) of each
687 interface file, and of each declaration within the interface
688 file. It also keeps in every interface file a list of the
689 fingerprints of everything it used when it last compiled the
690 file. If the source file's modification date is earlier than
691 the <filename>.o</filename> file's date (i.e. the source hasn't
692 changed since the file was last compiled), and the recompilation
693 checking is on, GHC will be clever. It compares the fingerprints
694 on the things it needs this time with the fingerprints
695 on the things it needed last time (gleaned from the
696 interface file of the module being compiled); if they are all
697 the same it stops compiling early in the process saying
698 &ldquo;Compilation IS NOT required&rdquo;. What a beautiful
699 sight!</para>
700
701 <para>You can read
702 about <ulink url="http://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/RecompilationAvoidance">how
703 all this works</ulink> in the GHC commentary.</para>
704
705 </sect2>
706
707 <sect2 id="mutual-recursion">
708 <title>How to compile mutually recursive modules</title>
709
710 <indexterm><primary>module system, recursion</primary></indexterm>
711 <indexterm><primary>recursion, between modules</primary></indexterm>
712
713 <para>GHC supports the compilation of mutually recursive modules.
714 This section explains how.</para>
715
716 <para>Every cycle in the module import graph must be broken by a <filename>hs-boot</filename> file.
717 Suppose that modules <filename>A.hs</filename> and <filename>B.hs</filename> are Haskell source files,
718 thus:
719 <programlisting>
720 module A where
721 import B( TB(..) )
722
723 newtype TA = MkTA Int
724
725 f :: TB -&#62; TA
726 f (MkTB x) = MkTA x
727
728 module B where
729 import {-# SOURCE #-} A( TA(..) )
730
731 data TB = MkTB !Int
732
733 g :: TA -&#62; TB
734 g (MkTA x) = MkTB x
735 </programlisting>
736 <indexterm><primary><literal>hs-boot</literal>
737 files</primary></indexterm> <indexterm><primary>importing,
738 <literal>hi-boot</literal> files</primary></indexterm>
739 Here <filename>A</filename> imports <filename>B</filename>, but <filename>B</filename> imports
740 <filename>A</filename> with a <literal>{-# SOURCE #-}</literal> pragma, which breaks the
741 circular dependency. Every loop in the module import graph must be broken by a <literal>{-# SOURCE #-}</literal> import;
742 or, equivalently, the module import graph must be acyclic if <literal>{-# SOURCE #-}</literal> imports are ignored.
743 </para>
744 <para>For every module <filename>A.hs</filename> that is <literal>{-# SOURCE #-}</literal>-imported
745 in this way there must exist a source file <literal>A.hs-boot</literal>. This file contains an abbreviated
746 version of <filename>A.hs</filename>, thus:
747 <programlisting>
748 module A where
749 newtype TA = MkTA Int
750 </programlisting>
751 </para>
752 <para>To compile these three files, issue the following commands:
753 <programlisting>
754 ghc -c A.hs-boot -- Produces A.hi-boot, A.o-boot
755 ghc -c B.hs -- Consumes A.hi-boot, produces B.hi, B.o
756 ghc -c A.hs -- Consumes B.hi, produces A.hi, A.o
757 ghc -o foo A.o B.o -- Linking the program
758 </programlisting>
759 </para>
760 <para>There are several points to note here:
761 <itemizedlist>
762 <listitem>
763 <para>The file <filename>A.hs-boot</filename> is a programmer-written source file.
764 It must live in the same directory as its parent source file <filename>A.hs</filename>.
765 Currently, if you use a literate source file <filename>A.lhs</filename> you must
766 also use a literate boot file, <filename>A.lhs-boot</filename>; and vice versa.
767 </para></listitem>
768
769 <listitem><para>
770 A <filename>hs-boot</filename> file is compiled by GHC, just like a <filename>hs</filename> file:
771 <programlisting>
772 ghc -c A.hs-boot
773 </programlisting>
774 When a hs-boot file <filename>A.hs-boot</filename>
775 is compiled, it is checked for scope and type errors.
776 When its parent module <filename>A.hs</filename> is compiled, the two are compared, and
777 an error is reported if the two are inconsistent.
778 </para></listitem>
779
780 <listitem>
781 <para> Just as compiling <filename>A.hs</filename> produces an
782 interface file <filename>A.hi</filename>, and an object file
783 <filename>A.o</filename>, so compiling
784 <filename>A.hs-boot</filename> produces an interface file
785 <filename>A.hi-boot</filename>, and an pseudo-object file
786 <filename>A.o-boot</filename>: </para>
787
788 <itemizedlist>
789 <listitem>
790 <para>The pseudo-object file <filename>A.o-boot</filename> is
791 empty (don't link it!), but it is very useful when using a
792 Makefile, to record when the <filename>A.hi-boot</filename> was
793 last brought up to date (see <xref
794 linkend="using-make"/>).</para>
795 </listitem>
796
797 <listitem>
798 <para>The <filename>hi-boot</filename> generated by compiling a
799 <filename>hs-boot</filename> file is in the same
800 machine-generated binary format as any other GHC-generated
801 interface file (e.g. <filename>B.hi</filename>). You can
802 display its contents with <command>ghc
803 --show-iface</command>. If you specify a directory for
804 interface files, the <option>-ohidir</option> flag, then that
805 affects <filename>hi-boot</filename> files
806 too.</para>
807 </listitem>
808 </itemizedlist>
809 </listitem>
810
811 <listitem><para> If hs-boot files are considered distinct from their parent source
812 files, and if a <literal>{-# SOURCE #-}</literal> import is considered to refer to the
813 hs-boot file, then the module import graph must have no cycles. The command
814 <command>ghc -M</command> will report an error if a cycle is found.
815 </para></listitem>
816
817 <listitem><para> A module <literal>M</literal> that is
818 <literal>{-# SOURCE #-}</literal>-imported in a program will usually also be
819 ordinarily imported elsewhere. If not, <command>ghc --make</command>
820 automatically adds <literal>M</literal> to the set of modules it tries to
821 compile and link, to ensure that <literal>M</literal>'s implementation is included in
822 the final program.
823 </para></listitem>
824 </itemizedlist>
825 </para>
826 <para>
827 A hs-boot file need only contain the bare
828 minimum of information needed to get the bootstrapping process
829 started. For example, it doesn't need to contain declarations
830 for <emphasis>everything</emphasis> that module
831 <literal>A</literal> exports, only the things required by the
832 module(s) that import <literal>A</literal> recursively.</para>
833 <para>A hs-boot file is written in a subset of Haskell:
834 <itemizedlist>
835 <listitem><para> The module header (including the export list), and import statements, are exactly as in
836 Haskell, and so are the scoping rules.
837 Hence, to mention a non-Prelude type or class, you must import it.</para></listitem>
838
839 <listitem><para> There must be no value declarations, but there can be type signatures for
840 values. For example:
841 <programlisting>
842 double :: Int -&#62; Int
843 </programlisting>
844 </para></listitem>
845 <listitem><para> Fixity declarations are exactly as in Haskell.</para></listitem>
846 <listitem><para> Vanilla type synonym declarations are exactly as in Haskell.</para></listitem>
847 <listitem><para> Open type and data family declarations are exactly as in Haskell.</para></listitem>
848 <listitem><para> A closed type family may optionally omit its equations, as in the following example:
849 <programlisting>
850 type family ClosedFam a where ..
851 </programlisting>
852 The <literal>..</literal> is meant literally -- you should write two dots in your file. Note that the <literal>where</literal> clause is still necessary to distinguish closed families from open ones. If you give any equations of a closed family, you must give all of them, in the same order as they appear in the accompanying Haskell file.</para></listitem>
853 <listitem><para> A data type declaration can either be given in full, exactly as in Haskell, or it
854 can be given abstractly, by omitting the '=' sign and everything that follows. For example:
855 <programlisting>
856 data T a b
857 </programlisting>
858 In a <emphasis>source</emphasis> program
859 this would declare TA to have no constructors (a GHC extension: see <xref linkend="nullary-types"/>),
860 but in an hi-boot file it means "I don't know or care what the constructors are".
861 This is the most common form of data type declaration, because it's easy to get right.
862 You <emphasis>can</emphasis> also write out the constructors but, if you do so, you must write
863 it out precisely as in its real definition.</para>
864 <para>
865 If you do not write out the constructors, you may need to give a kind
866 annotation (<xref linkend="kinding"/>), to tell
867 GHC the kind of the type variable, if it is not "*". (In source files, this is worked out
868 from the way the type variable is used in the constructors.) For example:
869 <programlisting>
870 data R (x :: * -&#62; *) y
871 </programlisting>
872 You cannot use <literal>deriving</literal> on a data type declaration; write an
873 <literal>instance</literal> declaration instead.
874 </para></listitem>
875 <listitem><para> Class declarations is exactly as in Haskell, except that you may not put
876 default method declarations. You can also omit all the superclasses and class
877 methods entirely; but you must either omit them all or put them all in.
878 </para></listitem>
879 <listitem><para> You can include instance declarations just as in Haskell; but omit the "where" part.
880 </para></listitem>
881 <listitem><para>The default role for abstract datatype parameters is now representational. (An abstract datatype is one with no constructors listed.) To get another role, use a role annotation. (See <xref linkend="roles"/>.)</para></listitem>
882 </itemizedlist>
883 </para>
884 </sect2>
885
886 <sect2 id="module-signatures">
887 <title>Module signatures</title>
888 <para>GHC supports the specification of module signatures, which
889 both implementations and users can typecheck against separately.
890 This functionality should be considered experimental for now; some
891 details, especially for type classes and type families, may change.
892 This system was originally described in <ulink
893 url="http://plv.mpi-sws.org/backpack/">Backpack: Retrofitting Haskell with
894 Interfaces</ulink>. Signature files are somewhat similar to
895 <literal>hs-boot</literal> files, but have the <literal>hsig</literal>
896 extension and behave slightly differently.
897 </para>
898
899 <para>Suppose that I have modules <filename>String.hs</filename> and
900 <filename>A.hs</filename>, thus:</para>
901
902 <programlisting>
903 module Text where
904 data Text = Text String
905
906 empty :: Text
907 empty = Text ""
908
909 toString :: Text -> String
910 toString (Text s) = s
911
912 module A where
913 import Text
914 z = toString empty
915 </programlisting>
916
917 <para>Presently, module <literal>A</literal> depends explicitly on
918 a concrete implementation of <literal>Text</literal>. What if we wanted
919 to a signature <literal>Text</literal>, so we could vary the
920 implementation with other possibilities (e.g. packed UTF-8 encoded
921 bytestrings)? To do this, we can write a signature
922 <filename>TextSig.hsig</filename>, and modify <literal>A</literal>
923 to include the signature instead:
924 </para>
925
926 <programlisting>
927 module TextSig where
928 data Text
929 empty :: Text
930 toString :: Text -> String
931
932 module A where
933 import TextSig
934 z = toString empty
935 </programlisting>
936
937 <para>To compile these two files, we need to specify what module we
938 would like to use to implement the signature. This can be done by
939 compiling the implementation, and then using the <literal>-sig-of</literal>
940 flag to specify the implementation backing a signature:</para>
941
942 <programlisting>
943 ghc -c Text.hs
944 ghc -c TextSig.hsig -sig-of "TextSig is main:Text"
945 ghc -c A.hs
946 </programlisting>
947
948 <para>To specify multiple signatures, use a comma-separated list.
949 The <literal>-sig-of</literal> parameter is required to specify
950 the backing implementations of all home modules, even in one-shot
951 compilation mode.
952 At the moment, you must specify the full module name (package key,
953 colon, and then module name), although in the future we may support
954 more user-friendly syntax.</para>
955
956 <para>To just type-check an interface file, no <literal>-sig-of</literal>
957 is necessary; instead, just pass the options
958 <literal>-fno-code -fwrite-interface</literal>. <literal>hsig</literal>
959 files will generate normal interface files which other files can
960 also use to type-check against. However, at the moment, we always
961 assume that an entity defined in a signature is a unique identifier
962 (even though we may happen to know it is type equal with another
963 identifier). In the future, we will support passing shaping information
964 to the compiler in order to let it know about these type
965 equalities.</para>
966
967 <para>Just like <literal>hs-boot</literal> files, when an
968 <literal>hsig</literal> file is compiled it is checked for type
969 consistency against the backing implementation. Signature files are also
970 written in a subset of Haskell essentially identical to that of
971 <literal>hs-boot</literal> files.</para>
972
973 <para>There is one important gotcha with the current implementation:
974 currently, instances from backing implementations will "leak" code that
975 uses signatures, and explicit instance declarations in signatures are
976 forbidden. This behavior will be subject to change.</para>
977
978 </sect2>
979
980
981 <sect2 id="using-make">
982 <title>Using <command>make</command></title>
983
984 <indexterm><primary><literal>make</literal></primary></indexterm>
985
986 <para>It is reasonably straightforward to set up a
987 <filename>Makefile</filename> to use with GHC, assuming you name
988 your source files the same as your modules. Thus:</para>
989
990 <programlisting>
991 HC = ghc
992 HC_OPTS = -cpp $(EXTRA_HC_OPTS)
993
994 SRCS = Main.lhs Foo.lhs Bar.lhs
995 OBJS = Main.o Foo.o Bar.o
996
997 .SUFFIXES : .o .hs .hi .lhs .hc .s
998
999 cool_pgm : $(OBJS)
1000 rm -f $@
1001 $(HC) -o $@ $(HC_OPTS) $(OBJS)
1002
1003 # Standard suffix rules
1004 .o.hi:
1005 @:
1006
1007 .lhs.o:
1008 $(HC) -c $&#60; $(HC_OPTS)
1009
1010 .hs.o:
1011 $(HC) -c $&#60; $(HC_OPTS)
1012
1013 .o-boot.hi-boot:
1014 @:
1015
1016 .lhs-boot.o-boot:
1017 $(HC) -c $&#60; $(HC_OPTS)
1018
1019 .hs-boot.o-boot:
1020 $(HC) -c $&#60; $(HC_OPTS)
1021
1022 # Inter-module dependencies
1023 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
1024 Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
1025 </programlisting>
1026
1027 <para>(Sophisticated <command>make</command> variants may
1028 achieve some of the above more elegantly. Notably,
1029 <command>gmake</command>'s pattern rules let you write the more
1030 comprehensible:</para>
1031
1032 <programlisting>
1033 %.o : %.lhs
1034 $(HC) -c $&#60; $(HC_OPTS)
1035 </programlisting>
1036
1037 <para>What we've shown should work with any
1038 <command>make</command>.)</para>
1039
1040 <para>Note the cheesy <literal>.o.hi</literal> rule: It records
1041 the dependency of the interface (<filename>.hi</filename>) file
1042 on the source. The rule says a <filename>.hi</filename> file
1043 can be made from a <filename>.o</filename> file by
1044 doing&hellip;nothing. Which is true.</para>
1045 <para> Note that the suffix rules are all repeated twice, once
1046 for normal Haskell source files, and once for <filename>hs-boot</filename>
1047 files (see <xref linkend="mutual-recursion"/>).</para>
1048
1049 <para>Note also the inter-module dependencies at the end of the
1050 Makefile, which take the form
1051
1052 <programlisting>
1053 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
1054 </programlisting>
1055
1056 They tell <command>make</command> that if any of
1057 <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
1058 <literal>Foo.s</literal> have an earlier modification date than
1059 <literal>Baz.hi</literal>, then the out-of-date file must be
1060 brought up to date. To bring it up to date,
1061 <literal>make</literal> looks for a rule to do so; one of the
1062 preceding suffix rules does the job nicely. These dependencies
1063 can be generated automatically by <command>ghc</command>; see
1064 <xref linkend="makefile-dependencies"/></para>
1065
1066 </sect2>
1067
1068 <sect2 id="makefile-dependencies">
1069 <title>Dependency generation</title>
1070 <indexterm><primary>dependencies in Makefiles</primary></indexterm>
1071 <indexterm><primary>Makefile dependencies</primary></indexterm>
1072
1073 <para>Putting inter-dependencies of the form <literal>Foo.o :
1074 Bar.hi</literal> into your <filename>Makefile</filename> by
1075 hand is rather error-prone. Don't worry, GHC has support for
1076 automatically generating the required dependencies. Add the
1077 following to your <filename>Makefile</filename>:</para>
1078
1079 <programlisting>
1080 depend :
1081 ghc -M $(HC_OPTS) $(SRCS)
1082 </programlisting>
1083
1084 <para>Now, before you start compiling, and any time you change
1085 the <literal>imports</literal> in your program, do
1086 <command>make depend</command> before you do <command>make
1087 cool&lowbar;pgm</command>. The command <command>ghc -M</command> will
1088 append the needed dependencies to your
1089 <filename>Makefile</filename>.</para>
1090
1091 <para>In general, <command>ghc -M Foo</command> does the following.
1092 For each module <literal>M</literal> in the set
1093 <literal>Foo</literal> plus all its imports (transitively),
1094 it adds to the Makefile:
1095 <itemizedlist>
1096 <listitem><para>A line recording the dependence of the object file on the source file.
1097 <programlisting>
1098 M.o : M.hs
1099 </programlisting>
1100 (or <literal>M.lhs</literal> if that is the filename you used).
1101 </para></listitem>
1102 <listitem><para> For each import declaration <literal>import X</literal> in <literal>M</literal>,
1103 a line recording the dependence of <literal>M</literal> on <literal>X</literal>:
1104 <programlisting>
1105 M.o : X.hi
1106 </programlisting></para></listitem>
1107 <listitem><para> For each import declaration <literal>import {-# SOURCE #-} X</literal> in <literal>M</literal>,
1108 a line recording the dependence of <literal>M</literal> on <literal>X</literal>:
1109 <programlisting>
1110 M.o : X.hi-boot
1111 </programlisting>
1112 (See <xref linkend="mutual-recursion"/> for details of
1113 <literal>hi-boot</literal> style interface files.)
1114 </para></listitem>
1115 </itemizedlist>
1116 If <literal>M</literal> imports multiple modules, then there will
1117 be multiple lines with <filename>M.o</filename> as the
1118 target.</para>
1119 <para>There is no need to list all of the source files as arguments to the <command>ghc -M</command> command;
1120 <command>ghc</command> traces the dependencies, just like <command>ghc --make</command>
1121 (a new feature in GHC 6.4).</para>
1122
1123 <para>Note that <literal>ghc -M</literal> needs to find a <emphasis>source
1124 file</emphasis> for each module in the dependency graph, so that it can
1125 parse the import declarations and follow dependencies. Any pre-compiled
1126 modules without source files must therefore belong to a
1127 package<footnote><para>This is a change in behaviour relative to 6.2 and
1128 earlier.</para>
1129 </footnote>.</para>
1130
1131 <para>By default, <command>ghc -M</command> generates all the
1132 dependencies, and then concatenates them onto the end of
1133 <filename>makefile</filename> (or
1134 <filename>Makefile</filename> if <filename>makefile</filename>
1135 doesn't exist) bracketed by the lines "<literal>&num; DO NOT
1136 DELETE: Beginning of Haskell dependencies</literal>" and
1137 "<literal>&num; DO NOT DELETE: End of Haskell
1138 dependencies</literal>". If these lines already exist in the
1139 <filename>makefile</filename>, then the old dependencies are
1140 deleted first.</para>
1141
1142 <para>Don't forget to use the same <option>-package</option>
1143 options on the <literal>ghc -M</literal> command line as you
1144 would when compiling; this enables the dependency generator to
1145 locate any imported modules that come from packages. The
1146 package modules won't be included in the dependencies
1147 generated, though (but see the
1148 <option>-include-pkg-deps</option> option below).</para>
1149
1150 <para>The dependency generation phase of GHC can take some
1151 additional options, which you may find useful.
1152
1153 The options which affect dependency generation are:</para>
1154
1155 <variablelist>
1156 <varlistentry>
1157 <term><option>-ddump-mod-cycles</option></term>
1158 <listitem>
1159 <para>Display a list of the cycles in the module graph. This is
1160 useful when trying to eliminate such cycles.</para>
1161 </listitem>
1162 </varlistentry>
1163
1164 <varlistentry>
1165 <term><option>-v2</option></term>
1166 <listitem>
1167 <para>Print a full list of the module dependencies to stdout.
1168 (This is the standard verbosity flag, so the list will
1169 also be displayed with <option>-v3</option> and
1170 <option>-v4</option>;
1171 <xref linkend ="options-help"/>.)</para>
1172 </listitem>
1173 </varlistentry>
1174
1175 <varlistentry>
1176 <term><option>-dep-makefile</option> <replaceable>file</replaceable></term>
1177 <listitem>
1178 <para>Use <replaceable>file</replaceable> as the makefile,
1179 rather than <filename>makefile</filename> or
1180 <filename>Makefile</filename>. If
1181 <replaceable>file</replaceable> doesn't exist,
1182 <command>mkdependHS</command> creates it. We often use
1183 <option>-dep-makefile .depend</option> to put the dependencies in
1184 <filename>.depend</filename> and then
1185 <command>include</command> the file
1186 <filename>.depend</filename> into
1187 <filename>Makefile</filename>.</para>
1188 </listitem>
1189 </varlistentry>
1190
1191 <varlistentry>
1192 <term><option>-dep-suffix &lt;suf&gt;</option></term>
1193 <listitem>
1194 <para>Make extra dependencies that declare that files
1195 with suffix
1196 <filename>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</filename>
1197 depend on interface files with suffix
1198 <filename>.&lt;suf&gt;&lowbar;hi</filename>, or (for
1199 <literal>&lcub;-&num; SOURCE &num;-&rcub;</literal>
1200 imports) on <filename>.hi-boot</filename>. Multiple
1201 <option>-dep-suffix</option> flags are permitted. For example,
1202 <option>-dep-suffix a -dep-suffix b</option>
1203 will make dependencies
1204 for <filename>.hs</filename> on
1205 <filename>.hi</filename>,
1206 <filename>.a&lowbar;hs</filename> on
1207 <filename>.a&lowbar;hi</filename>, and
1208 <filename>.b&lowbar;hs</filename> on
1209 <filename>.b&lowbar;hi</filename>. (Useful in
1210 conjunction with NoFib "ways".)</para>
1211 </listitem>
1212 </varlistentry>
1213
1214 <varlistentry>
1215 <term><option>--exclude-module=&lt;file&gt;</option></term>
1216 <listitem>
1217 <para>Regard <filename>&lt;file&gt;</filename> as
1218 "stable"; i.e., exclude it from having dependencies on
1219 it.</para>
1220 </listitem>
1221 </varlistentry>
1222
1223 <varlistentry>
1224 <term><option>-include-pkg-deps</option></term>
1225 <listitem>
1226 <para>Regard modules imported from packages as unstable,
1227 i.e., generate dependencies on any imported package modules
1228 (including <literal>Prelude</literal>, and all other
1229 standard Haskell libraries). Dependencies are not traced
1230 recursively into packages; dependencies are only generated for
1231 home-package modules on external-package modules directly imported
1232 by the home package module.
1233 This option is normally
1234 only used by the various system libraries.</para>
1235 </listitem>
1236 </varlistentry>
1237 </variablelist>
1238
1239 </sect2>
1240
1241 <sect2 id="orphan-modules">
1242 <title>Orphan modules and instance declarations</title>
1243
1244 <para> Haskell specifies that when compiling module M, any instance
1245 declaration in any module "below" M is visible. (Module A is "below"
1246 M if A is imported directly by M, or if A is below a module that M imports directly.)
1247 In principle, GHC must therefore read the interface files of every module below M,
1248 just in case they contain an instance declaration that matters to M. This would
1249 be a disaster in practice, so GHC tries to be clever. </para>
1250
1251 <para>In particular, if an instance declaration is in the same module as the definition
1252 of any type or class mentioned in the <emphasis>head</emphasis> of the instance declaration
1253 (the part after the &ldquo;<literal>=&gt;</literal>&rdquo;; see <xref linkend="instance-rules"/>), then
1254 GHC has to visit that interface file anyway. Example:</para>
1255 <programlisting>
1256 module A where
1257 instance C a =&gt; D (T a) where ...
1258 data T a = ...
1259 </programlisting>
1260 <para> The instance declaration is only relevant if the type T is in use, and if
1261 so, GHC will have visited A's interface file to find T's definition. </para>
1262
1263 <para> The only problem comes when a module contains an instance declaration
1264 and GHC has no other reason for visiting the module. Example:
1265 <programlisting>
1266 module Orphan where
1267 instance C a =&gt; D (T a) where ...
1268 class C a where ...
1269 </programlisting>
1270 Here, neither D nor T is declared in module Orphan.
1271 We call such modules &ldquo;orphan modules&rdquo;.
1272 GHC identifies orphan modules, and visits the interface file of
1273 every orphan module below the module being compiled. This is usually
1274 wasted work, but there is no avoiding it. You should therefore do
1275 your best to have as few orphan modules as possible.
1276 </para>
1277 <para>
1278 Functional dependencies complicate matters. Suppose we have:
1279 <programlisting>
1280 module B where
1281 instance E T Int where ...
1282 data T = ...
1283 </programlisting>
1284 Is this an orphan module? Apparently not, because <literal>T</literal>
1285 is declared in the same module. But suppose class <literal>E</literal> had a
1286 functional dependency:
1287 <programlisting>
1288 module Lib where
1289 class E x y | y -> x where ...
1290 </programlisting>
1291 Then in some importing module M, the constraint <literal>(E a Int)</literal> should be "improved" by setting
1292 <literal>a = T</literal>, <emphasis>even though there is no explicit mention
1293 of <literal>T</literal> in M</emphasis>.</para>
1294
1295 These considerations lead to the following definition of an orphan module:
1296 <itemizedlist>
1297 <listitem> <para> An <emphasis>orphan module</emphasis>
1298 <indexterm><primary>orphan module</primary></indexterm>
1299 contains at least one <emphasis>orphan instance</emphasis> or at
1300 least one <emphasis>orphan rule</emphasis>.</para> </listitem>
1301
1302 <listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if
1303 <indexterm><primary>orphan instance</primary></indexterm>
1304 <itemizedlist>
1305 <listitem><para>
1306 The class of the instance declaration is not declared in M, and
1307 </para></listitem>
1308 <listitem>
1309 <para> <emphasis>Either</emphasis> the class has no functional dependencies, and none of the type constructors
1310 in the instance head is declared in M; <emphasis>or</emphasis> there
1311 is a functional dependency for which none of the type constructors mentioned
1312 in the <emphasis>non-determined</emphasis> part of the instance head is defined in M.
1313 </para></listitem>
1314 </itemizedlist>
1315 </para>
1316 <para> Only the instance head
1317 counts. In the example above, it is not good enough for C's declaration
1318 to be in module A; it must be the declaration of D or T.</para>
1319 </listitem>
1320
1321 <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis>
1322 <indexterm><primary>orphan rule</primary></indexterm>
1323 if none of the variables, type constructors,
1324 or classes that are free in the left hand side of the rule are declared in M.
1325 </para> </listitem>
1326 </itemizedlist>
1327
1328
1329
1330 <para>If you use the flag <option>-fwarn-orphans</option>, GHC will warn you
1331 if you are creating an orphan module.
1332 Like any warning, you can switch the warning off with <option>-fno-warn-orphans</option>,
1333 and <option>-Werror</option>
1334 will make the compilation fail if the warning is issued.
1335 </para>
1336 <para>
1337 You can identify an orphan module by looking in its interface
1338 file, <filename>M.hi</filename>, using the
1339 <link linkend="modes"><option>--show-iface</option> mode</link>. If there is a <literal>[orphan module]</literal> on the
1340 first line, GHC considers it an orphan module.
1341 </para>
1342 </sect2>
1343
1344 </sect1>
1345
1346 <!-- Emacs stuff:
1347 ;;; Local Variables: ***
1348 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
1349 ;;; ispell-local-dictionary: "british" ***
1350 ;;; End: ***
1351 -->