1 <sect1 id="separate-compilation">
2 <title>Filenames and separate compilation</title>
4 <indexterm><primary>separate compilation</primary></indexterm>
5 <indexterm><primary>recompilation checker</primary></indexterm>
6 <indexterm><primary>make and recompilation</primary></indexterm>
8 <para>This section describes what files GHC expects to find, what
9 files it creates, where these files are stored, and what options
10 affect this behaviour.</para>
12 <para>Note that this section is written with
13 <firstterm>hierarchical modules</firstterm> in mind (see <xref
14 linkend="hierarchical-modules">); hierarchical modules are an
15 extension to Haskell 98 which extends the lexical syntax of
16 module names to include a dot ‘.’. Non-hierarchical
17 modules are thus a special case in which none of the module names
20 <para>Pathname conventions vary from system to system. In
21 particular, the directory separator is
22 ‘<literal>/</literal>’ on Unix systems and
23 ‘<literal>\</literal>’ on Windows systems. In the
24 sections that follow, we shall consistently use
25 ‘<literal>/</literal>’ as the directory separator;
26 substitute this for the appropriate character for your
29 <sect2 id="source-files">
30 <title>Haskell source files</title>
32 <para>Each Haskell source module should be placed in a file on
35 <para>The file should usually be named after the module name, by
36 replacing dots in the module name by directory separators. For
37 example, on a Unix system, the module <literal>A.B.C</literal>
38 should be placed in the file <literal>A/B/C.hs</literal>,
39 relative to some base directory. GHC's behaviour if this rule
40 is not followed is fully defined by the following section (<xref
41 linkend="output-files">).</para>
44 <sect2 id="output-files">
45 <title>Output files</title>
47 <indexterm><primary>interface files</primary></indexterm>
48 <indexterm><primary><literal>.hi</literal> files</primary></indexterm>
49 <indexterm><primary>object files</primary></indexterm>
50 <indexterm><primary><literal>.o</literal> files</primary></indexterm>
52 <para>When asked to compile a source file, GHC normally
53 generates two files: an <firstterm>object file</firstterm>, and
54 an <firstterm>interface file</firstterm>. </para>
56 <para>The object file, which normally ends in a
57 <literal>.o</literal> suffix (or <literal>.obj</literal> if
58 you're on Windows), contains the compiled code for the module.</para>
60 <para>The interface file,
61 which normally ends in a <literal>.hi</literal> suffix, contains
62 the information that GHC needs in order to compile further
63 modules that depend on this module. It contains things like the
64 types of exported functions, definitions of data types, and so
65 on. It is stored in a binary format, so don't try to read one;
66 use the <option>--show-iface</option> option instead (see <xref
67 linkend="hi-options">).</para>
69 <para>You should think of the object file and the interface file as a
70 pair, since the interface file is in a sense a compiler-readable
71 description of the contents of the object file. If the
72 interface file and object file get out of sync for any reason,
73 then the compiler may end up making assumptions about the object
74 file that aren't true; trouble will almost certainly follow.
75 For this reason, we recommend keeping object files and interface
76 files in the same place (GHC does this by default, but it is
77 possible to override the defaults as we'll explain
80 <para>Every module has a <emphasis>module name</emphasis>
81 defined in its source code (<literal>module A.B.C where
82 ...</literal>).</para>
84 <para>The name of the object file generated by GHC is derived
85 according to the following rules, where
86 <replaceable>osuf</replaceable> is the object-file suffix (this
87 can be changed with the <option>-osuf</option> option).</para>
91 <para>If there is no <option>-odir</option> option (the
92 default), then the object filename is derived from the
93 source filename by replacing the suffix with
94 <replaceable>osuf</replaceable>.</para>
98 <option>-odir</option> <replaceable>dir</replaceable>
99 has been specified, then the object filename is
100 <replaceable>dir</replaceable>/<replaceable>mod</replaceable>.<replaceable>osuf</replaceable>,
101 where <replaceable>mod</replaceable> is the module name with
102 dots replaced by slashes.</para>
106 <para>The name of the interface file is derived using the same
107 rules, except that the suffix is
108 <replaceable>hisuf</replaceable> (<literal>.hi</literal> by
109 default) instead of <replaceable>osuf</replaceable>, and the
110 relevant options are <option>-hidir</option> and
111 <option>-hisuf</option> instead of <option>-odir</option> and
112 <option>-osuf</option> respectively.</para>
114 <para>For example, if GHC compiles the module
115 <literal>A.B.C</literal> in the file
116 <filename>src/A/B/C.hs</filename>, with no
117 <literal>-odir</literal> or <literal>-hidir</literal> flags, the
118 interface file will be put in <literal>src/A/B/C.hi</literal>
119 and the object file in <literal>src/A/B/C.o</literal>.</para>
121 <para>Note that it is reasonable to have a module
122 <literal>Main</literal> in a file named
123 <filename>foo.hs</filename>, but this only works because GHC
124 never needs to search for the interface for module
125 <literal>Main</literal> (because it is never imported). It is
126 therefore possible to have several <literal>Main</literal>
127 modules in separate source files in the same directory, and GHC
128 will not get confused. For modules other than
129 <literal>Main</literal>, it is strongly recommended that you
130 name the source file after the module name, replacing dots with
131 slashes in hierarchical module names.</para>
133 <para>In batch compilation mode, the name of the object file can
134 also be overriden using the <option>-o</option> option, and the
135 name of the interface file can be specified directly using the
136 <option>-ohi</option> option.</para>
139 <sect2 id="search-path">
140 <title>The search path</title>
142 <indexterm><primary>search path</primary>
144 <indexterm><primary>interface files, finding them</primary></indexterm>
145 <indexterm><primary>finding interface files</primary></indexterm>
147 <para>In your program, you import a module
148 <literal>Foo</literal> by saying <literal>import Foo</literal>.
149 In <option>--make</option> mode or GHCi, GHC will look for a
150 source file for <literal>Foo</literal> and arrange to compile it
151 first. Without <option>--make</option>, GHC will look for the
152 interface file for <literal>Foo</literal>, which should have
153 been created by an earlier compilation of
154 <literal>Foo</literal>. GHC uses the same strategy in each of
155 these cases for finding the appropriate file.</para>
157 <para>This strategy is as follows: GHC keeps a list of
158 directories called the <firstterm>search path</firstterm>. For
159 each of these directories, it tries appending
160 <replaceable>basename</replaceable><literal>.</literal><replaceable>extension</replaceable>
161 to the directory, and checks whether the file exists. The value
162 of <replaceable>basename</replaceable> is the module name with
163 dots replaced by the directory separator ('/' or '\', depending
164 on the system), and <replaceable>extension</replaceable> is a
165 source extension (<literal>hs</literal>, <literal>lhs</literal>)
166 if we are in <option>--make</option> mode and GHCi, or
167 <replaceable>hisuf</replaceable> otherwise.</para>
169 <para>For example, suppose the search path contains directories
170 <literal>d1</literal>, <literal>d2</literal>, and
171 <literal>d3</literal>, and we are in <literal>--make</literal>
172 mode looking for the source file for a module
173 <literal>A.B.C</literal>. GHC will look in
174 <literal>d1/A/B/C.hs</literal>, <literal>d1/A/B/C.lhs</literal>,
175 <literal>d2/A/B/C.hs</literal>, and so on.</para>
177 <para>The search path by default contains a single directory:
178 <quote>.</quote> (i.e. the current directory). The following
179 options can be used to add to or change the contents of the
184 <term><option>-i<replaceable>dirs</replaceable></option></term>
186 <para><indexterm><primary><option>-i<replaceable>dirs</replaceable></option>
187 </primary></indexterm>This flag appends a colon-separated
188 list of <filename>dirs</filename> to the search path.</para>
193 <term><option>-i</option></term>
195 <para>resets the search path back to nothing.</para>
200 <para>This isn't the whole story: GHC also looks for modules in
201 pre-compiled libraries, known as packages. See the section on
202 packages (<xref linkend="packages">), for details.</para>
205 <sect2 id="options-output">
206 <title>Redirecting the compilation output(s)</title>
208 <indexterm><primary>output-directing options</primary></indexterm>
209 <indexterm><primary>redirecting compilation output</primary></indexterm>
213 <term><option>-o</option> <replaceable>file</replaceable></term>
214 <indexterm><primary><option>-o</option></primary></indexterm>
216 <para>GHC's compiled output normally goes into a
217 <filename>.hc</filename>, <filename>.o</filename>, etc.,
218 file, depending on the last-run compilation phase. The
219 option <option>-o <replaceable>file</replaceable></option>
220 re-directs the output of that last-run phase to
221 <replaceable>file</replaceable>.</para>
223 <para>Note: this “feature” can be
224 counterintuitive: <command>ghc -C -o foo.o
225 foo.hs</command> will put the intermediate C code in the
226 file <filename>foo.o</filename>, name
227 notwithstanding!</para>
229 <para>This option is most often used when creating an
230 executable file, to set the filename of the executable.
232 <screen> ghc -o prog --make Main</screen>
234 will compile the program starting with module
235 <literal>Main</literal> and put the executable in the
236 file <literal>prog</literal>.</para>
238 <para>Note: on Windows, if the result is an executable
239 file, the extension "<filename>.exe</filename>" is added
240 if the specified filename does not already have an
245 will compile and link the module
246 <filename>Main.hs</filename>, and put the resulting
247 executable in <filename>foo.exe</filename> (not
248 <filename>foo</filename>).</para>
253 <term><option>-odir</option> <replaceable>dir</replaceable></term>
254 <indexterm><primary><option>-odir</option></primary></indexterm>
256 <para>Redirects object files to directory
257 <replaceable>dir</replaceable>. For example:</para>
260 $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
263 <para>The object files, <filename>Foo.o</filename>,
264 <filename>Bar.o</filename>, and
265 <filename>Bumble.o</filename> would be put into a
266 subdirectory named after the architecture of the executing
267 machine (<filename>x86</filename>,
268 <filename>mips</filename>, etc).</para>
270 <para>Note that the <option>-odir</option> option does
271 <emphasis>not</emphasis> affect where the interface files
272 are put; use the <option>-hidir</option> option for that.
273 In the above example, they would still be put in
274 <filename>parse/Foo.hi</filename>,
275 <filename>parse/Bar.hi</filename>, and
276 <filename>gurgle/Bumble.hi</filename>.</para>
281 <term><option>-ohi</option> <replaceable>file</replaceable></term>
282 <indexterm><primary><option>-ohi</option></primary>
285 <para>The interface output may be directed to another file
286 <filename>bar2/Wurble.iface</filename> with the option
287 <option>-ohi bar2/Wurble.iface</option> (not
290 <para>WARNING: if you redirect the interface file
291 somewhere that GHC can't find it, then the recompilation
292 checker may get confused (at the least, you won't get any
293 recompilation avoidance). We recommend using a
294 combination of <option>-hidir</option> and
295 <option>-hisuf</option> options instead, if
298 <para>To avoid generating an interface at all, you could
299 use this option to redirect the interface into the bit
300 bucket: <literal>-ohi /dev/null</literal>, for
306 <term><option>-hidir</option> <replaceable>dir</replaceable></term>
307 <indexterm><primary><option>-hidir</option></primary>
310 <para>Redirects all generated interface files into
311 <replaceable>dir</replaceable>, instead of the
317 <term><option>-osuf</option> <replaceable>suffix</replaceable></term>
318 <term><option>-hisuf</option> <replaceable>suffix</replaceable></term>
319 <term><option>-hcsuf</option> <replaceable>suffix</replaceable></term>
320 <indexterm><primary><option>-osuf</option></primary></indexterm>
321 <indexterm><primary><option>-hisuf</option></primary></indexterm>
322 <indexterm><primary><option>-hcsuf</option></primary></indexterm>
324 <para>EXOTICA: The <option>-osuf</option>
325 <replaceable>suffix</replaceable> will change the
326 <literal>.o</literal> file suffix for object files to
327 whatever you specify. We use this when compiling
328 libraries, so that objects for the profiling versions of
329 the libraries don't clobber the normal ones.</para>
331 <para>Similarly, the <option>-hisuf</option>
332 <replaceable>suffix</replaceable> will change the
333 <literal>.hi</literal> file suffix for non-system
334 interface files (see <XRef LinkEnd="hi-options">).</para>
336 <para>Finally, the option <option>-hcsuf</option>
337 <replaceable>suffix</replaceable> will change the
338 <literal>.hc</literal> file suffix for compiler-generated
339 intermediate C files.</para>
341 <para>The <option>-hisuf</option>/<option>-osuf</option>
342 game is particularly useful if you want to compile a
343 program both with and without profiling, in the same
344 directory. You can say:
347 to get the ordinary version, and
349 ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</Screen>
350 to get the profiled version.</para>
356 <sect2 id="keeping-intermediates">
357 <title>Keeping Intermediate Files</title>
358 <indexterm><primary>intermediate files, saving</primary>
360 <indexterm><primary><literal>.hc</literal> files, saving</primary>
362 <indexterm><primary><literal>.s</literal> files, saving</primary>
365 <para>The following options are useful for keeping certain
366 intermediate files around, when normally GHC would throw these
367 away after compilation:</para>
371 <term><option>-keep-hc-files</option></term>
373 <primary><option>-keep-hc-files</option></primary>
376 <para>Keep intermediate <literal>.hc</literal> files when
377 doing <literal>.hs</literal>-to-<literal>.o</literal>
378 compilations via C (NOTE: <literal>.hc</literal> files
379 aren't generated when using the native code generator, you
380 may need to use <option>-fvia-C</option> to force them
381 to be produced).</para>
386 <term><option>-keep-s-files</option></term>
388 <primary><option>-keep-s-files</option></primary>
391 <para>Keep intermediate <literal>.s</literal> files.</para>
396 <term><option>-keep-raw-s-files</option></term>
398 <primary><option>-keep-raw-s-files</option></primary>
401 <para>Keep intermediate <literal>.raw-s</literal> files.
402 These are the direct output from the C compiler, before
403 GHC does “assembly mangling” to produce the
404 <literal>.s</literal> file. Again, these are not produced
405 when using the native code generator.</para>
410 <term><option>-keep-tmp-files</option></term>
412 <primary><option>-keep-tmp-files</option></primary>
415 <primary>temporary files</primary>
416 <secondary>keeping</secondary>
419 <para>Instructs the GHC driver not to delete any of its
420 temporary files, which it normally keeps in
421 <literal>/tmp</literal> (or possibly elsewhere; see <xref
422 linkend="temp-files">). Running GHC with
423 <option>-v</option> will show you what temporary files
424 were generated along the way.</para>
430 <sect2 id="temp-files">
431 <title>Redirecting temporary files</title>
434 <primary>temporary files</primary>
435 <secondary>redirecting</secondary>
440 <term><option>-tmpdir</option></term>
441 <indexterm><primary><option>-tmpdir</option></primary></indexterm>
443 <para>If you have trouble because of running out of space
444 in <filename>/tmp</filename> (or wherever your
445 installation thinks temporary files should go), you may
446 use the <option>-tmpdir
447 <dir></option><IndexTerm><Primary>-tmpdir
448 <dir> option</Primary></IndexTerm> option to specify
449 an alternate directory. For example, <option>-tmpdir
450 .</option> says to put temporary files in the current
451 working directory.</para>
453 <para>Alternatively, use your <Constant>TMPDIR</Constant>
454 environment variable.<IndexTerm><Primary>TMPDIR
455 environment variable</Primary></IndexTerm> Set it to the
456 name of the directory where temporary files should be put.
457 GCC and other programs will honour the
458 <Constant>TMPDIR</Constant> variable as well.</para>
460 <para>Even better idea: Set the
461 <Constant>DEFAULT_TMPDIR</Constant> make variable when
462 building GHC, and never worry about
463 <Constant>TMPDIR</Constant> again. (see the build
464 documentation).</para>
470 <Sect2 id="hi-options">
471 <title>Other options related to interface files</title>
472 <indexterm><primary>interface files, options</primary></indexterm>
476 <term><option>-ddump-hi</option></term>
477 <indexterm><primary><option>-ddump-hi</option></primary>
480 <para>Dumps the new interface to standard output.</para>
485 <term><option>-ddump-hi-diffs</option></term>
486 <indexterm><primary><option>-ddump-hi-diffs</option></primary>
489 <para>The compiler does not overwrite an existing
490 <filename>.hi</filename> interface file if the new one is
491 the same as the old one; this is friendly to
492 <command>make</command>. When an interface does change,
493 it is often enlightening to be informed. The
494 <option>-ddump-hi-diffs</option> option will make GHC run
495 <command>diff</command> on the old and new
496 <filename>.hi</filename> files.</para>
501 <term><option>-ddump-minimal-imports</option></term>
502 <indexterm><primary><option>-ddump-minimal-imports</option></primary>
505 <para>Dump to the file "M.imports" (where M is the module
506 being compiled) a "minimal" set of import declarations.
507 You can safely replace all the import declarations in
508 "M.hs" with those found in "M.imports". Why would you
509 want to do that? Because the "minimal" imports (a) import
510 everything explicitly, by name, and (b) import nothing
511 that is not required. It can be quite painful to maintain
512 this property by hand, so this flag is intended to reduce
518 <term><option>--show-iface</option>
519 <replaceable>file</replaceable></term>
520 <indexterm><primary><option>--show-iface</option></primary>
523 <para>Where <replaceable>file</replaceable> is the name of
524 an interface file, dumps the contents of that interface in
525 a human-readable (ish) format.</para>
532 <title>The recompilation checker</title>
534 <indexterm><primary>recompilation checker</primary></indexterm>
538 <term><option>-no-recomp</option></term>
539 <indexterm><primary><option>-recomp</option></primary></indexterm>
540 <indexterm><primary><option>-no-recomp</option></primary></indexterm>
542 <para>Turn off recompilation checking (which is on by
543 default). Recompilation checking normally stops
544 compilation early, leaving an existing
545 <filename>.o</filename> file in place, if it can be
546 determined that the module does not need to be
552 <para>In the olden days, GHC compared the newly-generated
553 <filename>.hi</filename> file with the previous version; if they
554 were identical, it left the old one alone and didn't change its
555 modification date. In consequence, importers of a module with
556 an unchanged output <filename>.hi</filename> file were not
559 <para>This doesn't work any more. Suppose module
560 <literal>C</literal> imports module <literal>B</literal>, and
561 <literal>B</literal> imports module <literal>A</literal>. So
562 changes to module <literal>A</literal> might require module
563 <literal>C</literal> to be recompiled, and hence when
564 <filename>A.hi</filename> changes we should check whether
565 <literal>C</literal> should be recompiled. However, the
566 dependencies of <literal>C</literal> will only list
567 <literal>B.hi</literal>, not <literal>A.hi</literal>, and some
568 changes to <literal>A</literal> (changing the definition of a
569 function that appears in an inlining of a function exported by
570 <literal>B</literal>, say) may conceivably not change
571 <filename>B.hi</filename> one jot. So now…</para>
573 <para>GHC keeps a version number on each interface file, and on
574 each type signature within the interface file. It also keeps in
575 every interface file a list of the version numbers of everything
576 it used when it last compiled the file. If the source file's
577 modification date is earlier than the <filename>.o</filename>
578 file's date (i.e. the source hasn't changed since the file was
579 last compiled), and the reompilation checking is on, GHC will be
580 clever. It compares the version numbers on the things it needs
581 this time with the version numbers on the things it needed last
582 time (gleaned from the interface file of the module being
583 compiled); if they are all the same it stops compiling rather
584 early in the process saying “Compilation IS NOT
585 required”. What a beautiful sight!</para>
587 <para>Patrick Sansom had a workshop paper about how all this is
588 done (though the details have changed quite a bit). <ULink
589 URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a
594 <sect2 id="using-make">
595 <title>Using <command>make</command></title>
597 <indexterm><primary><literal>make</literal></primary></indexterm>
599 <para>It is reasonably straightforward to set up a
600 <filename>Makefile</filename> to use with GHC, assuming you name
601 your source files the same as your modules. Thus:</para>
605 HC_OPTS = -cpp $(EXTRA_HC_OPTS)
607 SRCS = Main.lhs Foo.lhs Bar.lhs
608 OBJS = Main.o Foo.o Bar.o
610 .SUFFIXES : .o .hs .hi .lhs .hc .s
614 $(HC) -o $@ $(HC_OPTS) $(OBJS)
616 # Standard suffix rules
621 $(HC) -c $< $(HC_OPTS)
624 $(HC) -c $< $(HC_OPTS)
626 # Inter-module dependencies
627 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
628 Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
631 <para>(Sophisticated <command>make</command> variants may
632 achieve some of the above more elegantly. Notably,
633 <command>gmake</command>'s pattern rules let you write the more
634 comprehensible:</para>
638 $(HC) -c $< $(HC_OPTS)
641 <para>What we've shown should work with any
642 <command>make</command>.)</para>
644 <para>Note the cheesy <literal>.o.hi</literal> rule: It records
645 the dependency of the interface (<filename>.hi</filename>) file
646 on the source. The rule says a <filename>.hi</filename> file
647 can be made from a <filename>.o</filename> file by
648 doing…nothing. Which is true.</para>
650 <para>Note the inter-module dependencies at the end of the
651 Makefile, which take the form</para>
654 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
657 <para>They tell <command>make</command> that if any of
658 <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
659 <literal>Foo.s</literal> have an earlier modification date than
660 <literal>Baz.hi</literal>, then the out-of-date file must be
661 brought up to date. To bring it up to date,
662 <literal>make</literal> looks for a rule to do so; one of the
663 preceding suffix rules does the job nicely.</para>
665 <sect3 id="sec-makefile-dependencies">
666 <title>Dependency generation</title>
667 <indexterm><primary>dependencies in Makefiles</primary></indexterm>
668 <indexterm><primary>Makefile dependencies</primary></indexterm>
670 <para>Putting inter-dependencies of the form <literal>Foo.o :
671 Bar.hi</literal> into your <filename>Makefile</filename> by
672 hand is rather error-prone. Don't worry, GHC has support for
673 automatically generating the required dependencies. Add the
674 following to your <filename>Makefile</filename>:</para>
678 ghc -M $(HC_OPTS) $(SRCS)
681 <para>Now, before you start compiling, and any time you change
682 the <literal>imports</literal> in your program, do
683 <command>make depend</command> before you do <command>make
684 cool_pgm</command>. <command>ghc -M</command> will
685 append the needed dependencies to your
686 <filename>Makefile</filename>.</para>
688 <para>In general, if module <literal>A</literal> contains the
695 then <command>ghc -M</command> will generate a dependency line
702 If module <literal>A</literal> contains the line
705 import {-# SOURCE #-} B ...blah...
708 then <command>ghc -M</command> will generate a dependency
715 (See <xref linkend="mutual-recursion"> for details of
716 <literal>hi-boot</literal> style interface files.) If
717 <literal>A</literal> imports multiple modules, then there will
718 be multiple lines with <filename>A.o</filename> as the
721 <para>By default, <command>ghc -M</command> generates all the
722 dependencies, and then concatenates them onto the end of
723 <filename>makefile</filename> (or
724 <filename>Makefile</filename> if <filename>makefile</filename>
725 doesn't exist) bracketed by the lines "<literal># DO NOT
726 DELETE: Beginning of Haskell dependencies</literal>" and
727 "<literal># DO NOT DELETE: End of Haskell
728 dependencies</literal>". If these lines already exist in the
729 <filename>makefile</filename>, then the old dependencies are
730 deleted first.</para>
732 <para>Don't forget to use the same <option>-package</option>
733 options on the <literal>ghc -M</literal> command line as you
734 would when compiling; this enables the dependency generator to
735 locate any imported modules that come from packages. The
736 package modules won't be included in the dependencies
737 generated, though (but see the
738 <option>––include-prelude</option> option below).</para>
740 <para>The dependency generation phase of GHC can take some
741 additional options, which you may find useful. For historical
742 reasons, each option passed to the dependency generator from
743 the GHC command line must be preceded by
744 <literal>-optdep</literal>. For example, to pass <literal>-f
745 .depend</literal> to the dependency generator, you say
748 ghc -M -optdep-f -optdep.depend ...
751 The options which affect dependency generation are:</para>
755 <term><option>-w</option></term>
757 <para>Turn off warnings about interface file shadowing.</para>
762 <term><option>-f</option> <replaceable>file</replaceable></term>
764 <para>Use <replaceable>file</replaceable> as the makefile,
765 rather than <filename>makefile</filename> or
766 <filename>Makefile</filename>. If
767 <replaceable>file</replaceable> doesn't exist,
768 <command>mkdependHS</command> creates it. We often use
769 <option>-f .depend</option> to put the dependencies in
770 <filename>.depend</filename> and then
771 <command>include</command> the file
772 <filename>.depend</filename> into
773 <filename>Makefile</filename>.</para>
778 <term><option>-o <osuf></option></term>
780 <para>Use <filename>.<osuf></filename> as the
781 "target file" suffix ( default: <literal>o</literal>).
782 Multiple <option>-o</option> flags are permitted
783 (GHC2.05 onwards). Thus "<option>-o hc -o o</option>"
784 will generate dependencies for <filename>.hc</filename>
785 and <filename>.o</filename> files.</para>
790 <term><option>-s <suf></option></term>
792 <para>Make extra dependencies that declare that files
794 <filename>.<suf>_<osuf></filename>
795 depend on interface files with suffix
796 <filename>.<suf>_hi</filename>, or (for
797 <literal>{-# SOURCE #-}</literal>
798 imports) on <filename>.hi-boot</filename>. Multiple
799 <option>-s</option> flags are permitted. For example,
800 <option>-o hc -s a -s b</option> will make dependencies
801 for <filename>.hc</filename> on
802 <filename>.hi</filename>,
803 <filename>.a_hc</filename> on
804 <filename>.a_hi</filename>, and
805 <filename>.b_hc</filename> on
806 <filename>.b_hi</filename>. (Useful in
807 conjunction with NoFib "ways".)</para>
812 <term><option>––exclude-module=<file></option></term>
814 <para>Regard <filename><file></filename> as
815 "stable"; i.e., exclude it from having dependencies on
821 <term><option>-x</option></term>
823 <para>same as <option>––exclude-module</option></para>
828 <term><option>––exclude-directory=<dirs></option></term>
830 <para>Regard the colon-separated list of directories
831 <filename><dirs></filename> as containing stable,
832 don't generate any dependencies on modules
838 <term><option>––include-module=<file></option></term>
840 <para>Regard <filename><file></filename> as not
841 "stable"; i.e., generate dependencies on it (if
842 any). This option is normally used in conjunction with
843 the <option>––exclude-directory</option> option.</para>
848 <term><option>––include-prelude</option></term>
850 <para>Regard modules imported from packages as unstable,
851 i.e., generate dependencies on the package modules used
852 (including <literal>Prelude</literal>, and all other
853 standard Haskell libraries). This option is normally
854 only used by the various system libraries.</para>
862 <sect2 id="mutual-recursion">
863 <title>How to compile mutually recursive modules</title>
865 <indexterm><primary>module system, recursion</primary></indexterm>
866 <indexterm><primary>recursion, between modules</primary></indexterm>
868 <para>Currently, the compiler does not have proper support for
869 dealing with mutually recursive modules:</para>
876 newtype TA = MkTA Int
891 <para>When compiling either module A and B, the compiler will
892 try (in vain) to look for the interface file of the other. So,
893 to get mutually recursive modules off the ground, you need to
894 hand write an interface file for A or B, so as to break the
895 loop. These hand-written interface files are called
896 <literal>hi-boot</literal> files, and are placed in a file
897 called <filename><module>.hi-boot</filename>. To import
898 from an <literal>hi-boot</literal> file instead of the standard
899 <filename>.hi</filename> file, use the following syntax in the
900 importing module: <indexterm><primary><literal>hi-boot</literal>
901 files</primary></indexterm> <indexterm><primary>importing,
902 <literal>hi-boot</literal> files</primary></indexterm></para>
905 import {-# SOURCE #-} A
908 <para>The hand-written interface need only contain the bare
909 minimum of information needed to get the bootstrapping process
910 started. For example, it doesn't need to contain declarations
911 for <emphasis>everything</emphasis> that module
912 <literal>A</literal> exports, only the things required by the
913 module that imports <literal>A</literal> recursively.</para>
915 <para>For the example at hand, the boot interface file for A
916 would look like the following:</para>
920 newtype TA = MkTA GHC.Base.Int
923 <para>The syntax is similar to a normal Haskell source file, but
924 with some important differences:</para>
928 <para>Non-local entities must be qualified with their
929 <emphasis>original</emphasis> defining module. Qualifying
930 by a module which just re-exports the entity won't do. In
931 particular, most <literal>Prelude</literal> entities aren't
932 actually defined in the <literal>Prelude</literal> (see for
933 example <literal>GHC.Base.Int</literal> in the above
934 example). HINT: to find out the fully-qualified name for
935 entities in the <literal>Prelude</literal> (or anywhere for
936 that matter), try using GHCi's
937 <literal>:info</literal> command, eg.</para>
938 <programlisting>Prelude> :m -Prelude
940 -- GHC.IOBase.IO is a type constructor
941 newtype GHC.IOBase.IO a
945 <para>Only <literal>data</literal>, <literal>type</literal>,
946 <literal>newtype</literal>, <literal>class</literal>, and
947 type signature declarations may be included. You cannot declare
948 <literal>instances</literal> or derive them automatically.
953 <para>Notice that we only put the declaration for the newtype
954 <literal>TA</literal> in the <literal>hi-boot</literal> file,
955 not the signature for <Function>f</Function>, since
956 <Function>f</Function> isn't used by <literal>B</literal>.</para>
958 <para>If you want an <literal>hi-boot</literal> file to export a
959 data type, but you don't want to give its constructors (because
960 the constructors aren't used by the SOURCE-importing module),
961 you can write simply:</para>
968 <para>(You must write all the type parameters, but leave out the
969 '=' and everything that follows it.)</para>
973 <sect2 id="orphan-modules">
974 <title>Orphan modules and instance declarations</title>
976 <para> Haskell specifies that when compiling module M, any instance
977 declaration in any module "below" M is visible. (Module A is "below"
978 M if A is imported directly by M, or if A is below a module that M imports directly.)
979 In principle, GHC must therefore read the interface files of every module below M,
980 just in case they contain an instance declaration that matters to M. This would
981 be a disaster in practice, so GHC tries to be clever. </para>
983 <para>In particular, if an instance declaration is in the same module as the definition
984 of any type or class mentioned in the head of the instance declaration, then
985 GHC has to visit that interface file anyway. Example:</para>
988 instance C a => D (T a) where ...
991 <para> The instance declaration is only relevant if the type T is in use, and if
992 so, GHC will have visited A's interface file to find T's definition. </para>
994 <para> The only problem comes when a module contains an instance declaration
995 and GHC has no other reason for visiting the module. Example:
998 instance C a => D (T a) where ...
1001 Here, neither D nor T is declared in module Orphan.
1002 We call such modules ``orphan modules'',
1003 defined thus:</para>
1005 <listitem> <para> An <emphasis>orphan module</emphasis>
1006 <indexterm><primary>orphan module</primary></indexterm>
1007 contains at least one <emphasis>orphan instance</emphasis> or at
1008 least one <emphasis>orphan rule</emphasis>.</para> </listitem>
1010 <listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if
1011 <indexterm><primary>orphan instance</primary></indexterm>
1012 none of the type constructors
1013 or classes mentioned in the instance head (the part after the ``<literal>=></literal>'') are declared
1016 <para> Only the instance head counts. In the example above, it is not good enough for C's declaration
1017 to be in module A; it must be the declaration of D or T.</para>
1020 <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis>
1021 <indexterm><primary>orphan rule</primary></indexterm>
1022 if none of the variables, type constructors,
1023 or classes that are free in the left hand side of the rule are declared in M.
1028 <para> GHC identifies orphan modules, and visits the interface file of
1029 every orphan module below the module being compiled. This is usually
1030 wasted work, but there is no avoiding it. You should therefore do
1031 your best to have as few orphan modules as possible.
1035 <para> You can identify an orphan module by looking in its interface
1036 file, <filename>M.hi</filename>, using the
1037 <option>--show-iface</option>. If there is a ``!'' on the first line,
1038 GHC considers it an orphan module.
1045 ;;; Local Variables: ***
1047 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***