1 <sect1 id="separate-compilation">
2 <title>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 how GHC supports separate
12 <title>Interface files</title>
14 <indexterm><primary>interface files</primary></indexterm>
15 <indexterm><primary><literal>.hi</literal> files</primary></indexterm>
17 <para>When GHC compiles a source file <filename>A.hs</filename>
18 which contains a module <literal>A</literal>, say, it generates
19 an object <filename>A.o</filename>, <emphasis>and</emphasis> a
20 companion <emphasis>interface file</emphasis>
21 <filename>A.hi</filename>. The interface file is not intended
22 for human consumption, as you'll see if you take a look at one.
23 It's merely there to help the compiler compile other modules in
24 the same program.</para>
26 <para>NOTE: In general, the name of a file containing module
27 <literal>M</literal> should be named <filename>M.hs</filename>
28 or <literal>M.lhs</literal>. The only exception to this rule is
29 module <literal>Main</literal>, which can be placed in any
30 file.<indexterm><primary>filenames</primary><secondary>for
31 modules</secondary> </indexterm></para>
33 <para>The interface file for <literal>A</literal> contains
34 information needed by the compiler when it compiles any module
35 <literal>B</literal> that imports <literal>A</literal>, whether
36 directly or indirectly. When compiling <literal>B</literal>,
37 GHC will read <filename>A.hi</filename> to find the details that
38 it needs to know about things defined in
39 <literal>A</literal>.</para>
41 <para>The interface file may contain all sorts of things that
42 aren't explicitly exported from <literal>A</literal> by the
43 programmer. For example, even though a data type is exported
44 abstractly, <filename>A.hi</filename> will contain the full data
45 type definition. For small function definitions,
46 <filename>A.hi</filename> will contain the complete definition
47 of the function. For bigger functions,
48 <filename>A.hi</filename> will contain strictness information
49 about the function. And so on. GHC puts much more information
50 into <filename>.hi</filename> files when optimisation is turned
51 on with the <option>-O</option> flag (see <xref
52 linkend="options-optimise">). Without <option>-O</option> it
53 puts in just the minimum; with <option>-O</option> it lobs in a
54 whole pile of stuff. <indexterm><primary>optimsation, effect on
55 .hi files</primary></indexterm></para>
57 <para><filename>A.hi</filename> should really be thought of as a
58 compiler-readable version of <filename>A.o</filename>. If you
59 use a <filename>.hi</filename> file that wasn't generated by the
60 same compilation run that generates the <filename>.o</filename>
61 file the compiler may assume all sorts of incorrect things about
62 <literal>A</literal>, resulting in core dumps and other
63 unpleasant happenings.</para>
67 <sect2 id="options-finding-imports">
68 <title>Finding interface files</title>
70 <indexterm><primary>interface files, finding them</primary></indexterm>
71 <indexterm><primary>finding interface files</primary></indexterm>
73 <para>In your program, you import a module
74 <literal>Foo</literal> by saying <literal>import Foo</literal>.
75 GHC goes looking for an interface file,
76 <filename>Foo.hi</filename>. It has a builtin list of
77 directories (notably including <filename>.</filename>) where it
83 <term><option>-i<dirs></option></term>
85 <para><indexterm><primary><option>-i<dirs></option>
86 </primary></indexterm>This flag appends a colon-separated
87 list of <filename>dirs</filename> to the “import
88 directories” list, which initially contains a single
89 entry: <quote>.</quote>.</para>
91 <para>This list is scanned before any package directories
92 (see <xref linkend="packages">) when looking for imports,
93 but note that if you have a home module with the same name
94 as a package module then this is likely to cause trouble
95 in other ways, with link errors being the least nasty
96 thing that can go wrong...</para>
98 <para>See also <XRef LinkEnd="recomp"> for the
99 significance of using relative and absolute pathnames in
100 the <option>-i</option> list.</para>
105 <term><option>-i</option></term>
107 <para>resets the “import directories” list
108 back to nothing.</para>
114 <para>See also the section on packages (<xref
115 linkend="packages">), which describes how to use installed
120 <Sect2 id="hi-options">
121 <title>Other options related to interface files</title>
122 <indexterm><primary>interface files, options</primary></indexterm>
126 <term><option>-ohi</option> <replaceable>file</replaceable></term>
127 <indexterm><primary><option>-ohi</option></primary>
130 <para>The interface output may be directed to another file
131 <filename>bar2/Wurble.iface</filename> with the option
132 <option>-ohi bar2/Wurble.iface</option> (not recommended).
133 To avoid generating an interface at all, you can say
134 <literal>-ohi /dev/null</literal>, for example.</para>
139 <term><option>-ddump-hi</option></term>
140 <indexterm><primary><option>-ddump-hi</option></primary>
143 <para>Dumps the new interface to standard output.</para>
148 <term><option>-ddump-hi-diffs</option></term>
149 <indexterm><primary><option>-ddump-hi-diffs</option></primary>
152 <para>The compiler does not overwrite an existing
153 <filename>.hi</filename> interface file if the new one is
154 the same as the old one; this is friendly to
155 <command>make</command>. When an interface does change,
156 it is often enlightening to be informed. The
157 <option>-ddump-hi-diffs</option> option will make GHC run
158 <command>diff</command> on the old and new
159 <filename>.hi</filename> files.</para>
164 <term><option>-ddump-minimal-imports</option></term>
165 <indexterm><primary><option>-ddump-minimal-imports</option></primary>
168 <para>Dump to the file "M.imports" (where M is the module
169 being compiled) a "minimal" set of import declarations.
170 You can safely replace all the import declarations in
171 "M.hs" with those found in "M.imports". Why would you
172 want to do that? Because the "minimal" imports (a) import
173 everything explicitly, by name, and (b) import nothing
174 that is not required. It can be quite painful to maintain
175 this property by hand, so this flag is intended to reduce
184 <title>The recompilation checker</title>
186 <indexterm><primary>recompilation checker</primary></indexterm>
190 <term><option>-no-recomp</option></term>
191 <indexterm><primary><option>-recomp</option></primary></indexterm>
192 <indexterm><primary><option>-no-recomp</option></primary></indexterm>
194 <para>Turn off recompilation checking (which is on by
195 default). Recompilation checking normally stops
196 compilation early, leaving an existing
197 <filename>.o</filename> file in place, if it can be
198 determined that the module does not need to be
204 <para>In the olden days, GHC compared the newly-generated
205 <filename>.hi</filename> file with the previous version; if they
206 were identical, it left the old one alone and didn't change its
207 modification date. In consequence, importers of a module with
208 an unchanged output <filename>.hi</filename> file were not
211 <para>This doesn't work any more. Suppose module
212 <literal>C</literal> imports module <literal>B</literal>, and
213 <literal>B</literal> imports module <literal>A</literal>. So
214 changes to <filename>A.hi</filename> should force a
215 recompilation of <literal>C</literal>. And some changes to
216 <literal>A</literal> (changing the definition of a function that
217 appears in an inlining of a function exported by
218 <literal>B</literal>, say) may conceivably not change
219 <filename>B.hi</filename> one jot. So now…</para>
221 <para>GHC keeps a version number on each interface file, and on
222 each type signature within the interface file. It also keeps in
223 every interface file a list of the version numbers of everything
224 it used when it last compiled the file. If the source file's
225 modification date is earlier than the <filename>.o</filename>
226 file's date (i.e. the source hasn't changed since the file was
227 last compiled), and the reompilation checking is on, GHC will be
228 clever. It compares the version numbers on the things it needs
229 this time with the version numbers on the things it needed last
230 time (gleaned from the interface file of the module being
231 compiled); if they are all the same it stops compiling rather
232 early in the process saying “Compilation IS NOT
233 required”. What a beautiful sight!</para>
235 <para>Patrick Sansom had a workshop paper about how all this is
236 done (though the details have changed quite a bit). <ULink
237 URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a
242 <sect2 id="using-make">
243 <title>Using <command>make</command></title>
245 <indexterm><primary><literal>make</literal></primary></indexterm>
247 <para>It is reasonably straightforward to set up a
248 <filename>Makefile</filename> to use with GHC, assuming you name
249 your source files the same as your modules. Thus:</para>
253 HC_OPTS = -cpp $(EXTRA_HC_OPTS)
255 SRCS = Main.lhs Foo.lhs Bar.lhs
256 OBJS = Main.o Foo.o Bar.o
258 .SUFFIXES : .o .hs .hi .lhs .hc .s
262 $(HC) -o $@ $(HC_OPTS) $(OBJS)
264 # Standard suffix rules
269 $(HC) -c $< $(HC_OPTS)
272 $(HC) -c $< $(HC_OPTS)
274 # Inter-module dependencies
275 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
276 Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
279 <para>(Sophisticated <command>make</command> variants may
280 achieve some of the above more elegantly. Notably,
281 <command>gmake</command>'s pattern rules let you write the more
282 comprehensible:</para>
286 $(HC) -c $< $(HC_OPTS)
289 <para>What we've shown should work with any
290 <command>make</command>.)</para>
292 <para>Note the cheesy <literal>.o.hi</literal> rule: It records
293 the dependency of the interface (<filename>.hi</filename>) file
294 on the source. The rule says a <filename>.hi</filename> file
295 can be made from a <filename>.o</filename> file by
296 doing…nothing. Which is true.</para>
298 <para>Note the inter-module dependencies at the end of the
299 Makefile, which take the form</para>
302 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
305 <para>They tell <command>make</command> that if any of
306 <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
307 <literal>Foo.s</literal> have an earlier modification date than
308 <literal>Baz.hi</literal>, then the out-of-date file must be
309 brought up to date. To bring it up to date,
310 <literal>make</literal> looks for a rule to do so; one of the
311 preceding suffix rules does the job nicely.</para>
313 <sect3 id="sec-makefile-dependencies">
314 <title>Dependency generation</title>
315 <indexterm><primary>dependencies in Makefiles</primary></indexterm>
316 <indexterm><primary>Makefile dependencies</primary></indexterm>
318 <para>Putting inter-dependencies of the form <literal>Foo.o :
319 Bar.hi</literal> into your <filename>Makefile</filename> by
320 hand is rather error-prone. Don't worry, GHC has support for
321 automatically generating the required dependencies. Add the
322 following to your <filename>Makefile</filename>:</para>
326 ghc -M $(HC_OPTS) $(SRCS)
329 <para>Now, before you start compiling, and any time you change
330 the <literal>imports</literal> in your program, do
331 <command>make depend</command> before you do <command>make
332 cool_pgm</command>. <command>ghc -M</command> will
333 append the needed dependencies to your
334 <filename>Makefile</filename>.</para>
336 <para>In general, if module <literal>A</literal> contains the
343 then <command>ghc -M</command> will generate a dependency line
350 If module <literal>A</literal> contains the line
353 import {-# SOURCE #-} B ...blah...
356 then <command>ghc -M</command> will generate a dependency
363 (See <xref linkend="mutual-recursion"> for details of
364 <literal>hi-boot</literal> style interface files.) If
365 <literal>A</literal> imports multiple modules, then there will
366 be multiple lines with <filename>A.o</filename> as the
369 <para>By default, <command>ghc -M</command> generates all the
370 dependencies, and then concatenates them onto the end of
371 <filename>makefile</filename> (or
372 <filename>Makefile</filename> if <filename>makefile</filename>
373 doesn't exist) bracketed by the lines "<literal># DO NOT
374 DELETE: Beginning of Haskell dependencies</literal>" and
375 "<literal># DO NOT DELETE: End of Haskell
376 dependencies</literal>". If these lines already exist in the
377 <filename>makefile</filename>, then the old dependencies are
378 deleted first.</para>
380 <para>The dependency generation phase of GHC can take some
381 additional options, which you may find useful. For historical
382 reasons, each option passed to the dependency generator from
383 the GHC command line must be preceded by
384 <literal>-optdep</literal>. For example, to pass <literal>-f
385 .depend</literal> to the dependency generator, you say
388 ghc -M -optdep-f -optdep.depend ...
391 The options which affect dependency generation are:</para>
395 <term><option>-w</option></term>
397 <para>Turn off warnings about interface file shadowing.</para>
402 <term><option>-f</option> <replaceable>file</replaceable></term>
404 <para>Use <replaceable>file</replaceable> as the makefile,
405 rather than <filename>makefile</filename> or
406 <filename>Makefile</filename>. If
407 <replaceable>file</replaceable> doesn't exist,
408 <command>mkdependHS</command> creates it. We often use
409 <option>-f .depend</option> to put the dependencies in
410 <filename>.depend</filename> and then
411 <command>include</command> the file
412 <filename>.depend</filename> into
413 <filename>Makefile</filename>.</para>
418 <term><option>-o <osuf></option></term>
420 <para>Use <filename>.<osuf></filename> as the
421 "target file" suffix ( default: <literal>o</literal>).
422 Multiple <option>-o</option> flags are permitted
423 (GHC2.05 onwards). Thus "<option>-o hc -o o</option>"
424 will generate dependencies for <filename>.hc</filename>
425 and <filename>.o</filename> files.</para>
430 <term><option>-s <suf></option></term>
432 <para>Make extra dependencies that declare that files
434 <filename>.<suf>_<osuf></filename>
435 depend on interface files with suffix
436 <filename>.<suf>_hi</filename>, or (for
437 <literal>{-# SOURCE #-}</literal>
438 imports) on <filename>.hi-boot</filename>. Multiple
439 <option>-s</option> flags are permitted. For example,
440 <option>-o hc -s a -s b</option> will make dependencies
441 for <filename>.hc</filename> on
442 <filename>.hi</filename>,
443 <filename>.a_hc</filename> on
444 <filename>.a_hi</filename>, and
445 <filename>.b_hc</filename> on
446 <filename>.b_hi</filename>. (Useful in
447 conjunction with NoFib "ways".)</para>
452 <term><option>--exclude-module=<file></option></term>
454 <para>Regard <filename><file></filename> as
455 "stable"; i.e., exclude it from having dependencies on
461 <term><option>-x</option></term>
463 <para>same as <option>--exclude-module</option></para>
468 <term><option>--exclude-directory=<dirs></option></term>
470 <para>Regard the colon-separated list of directories
471 <filename><dirs></filename> as containing stable,
472 don't generate any dependencies on modules
478 <term><option>--include-module=<file></option></term>
480 <para>Regard <filename><file></filename> as not
481 "stable"; i.e., generate dependencies on it (if
482 any). This option is normally used in conjunction with
483 the <option>--exclude-directory</option> option.</para>
488 <term><option>--include-prelude</option></term>
490 <para>Regard prelude libraries as unstable, i.e.,
491 generate dependencies on the prelude modules used
492 (including <literal>Prelude</literal>). This option is
493 normally only used by the various system libraries. If a
494 <option>-package</option> option is used, dependencies
495 will also be generated on the library's
504 <sect2 id="mutual-recursion">
505 <title>How to compile mutually recursive modules</title>
507 <indexterm><primary>module system, recursion</primary></indexterm>
508 <indexterm><primary>recursion, between modules</primary></indexterm>
510 <para>Currently, the compiler does not have proper support for
511 dealing with mutually recursive modules:</para>
518 newtype TA = MkTA Int
533 <para>When compiling either module A and B, the compiler will
534 try (in vain) to look for the interface file of the other. So,
535 to get mutually recursive modules off the ground, you need to
536 hand write an interface file for A or B, so as to break the
537 loop. These hand-written interface files are called
538 <literal>hi-boot</literal> files, and are placed in a file
539 called <filename><module>.hi-boot</filename>. To import
540 from an <literal>hi-boot</literal> file instead of the standard
541 <filename>.hi</filename> file, use the following syntax in the
542 importing module: <indexterm><primary><literal>hi-boot</literal>
543 files</primary></indexterm> <indexterm><primary>importing,
544 <literal>hi-boot</literal> files</primary></indexterm></para>
547 import {-# SOURCE #-} A
550 <para>The hand-written interface need only contain the bare
551 minimum of information needed to get the bootstrapping process
552 started. For example, it doesn't need to contain declarations
553 for <emphasis>everything</emphasis> that module
554 <literal>A</literal> exports, only the things required by the
555 module that imports <literal>A</literal> recursively.</para>
557 <para>For the example at hand, the boot interface file for A
558 would look like the following:</para>
561 __interface A 1 0 where
562 __export A TA{MkTA} ;
563 1 newtype TA = MkTA PrelBase.Int ;
566 <para>The syntax is essentially the same as a normal
567 <filename>.hi</filename> file (unfortunately), so you can
568 usually tailor an existing <filename>.hi</filename> file to make
569 a <filename>.hi-boot</filename> file.</para>
571 <para>Notice that we only put the declaration for the newtype
572 <literal>TA</literal> in the <literal>hi-boot</literal> file,
573 not the signature for <Function>f</Function>, since
574 <Function>f</Function> isn't used by <literal>B</literal>.</para>
576 <para>The number “1” after
577 “__interface A” gives the version
578 number of module A; it is incremented whenever anything in A's
579 interface file changes. In a normal interface file, the
580 “0” is the version number of the compiler which
581 generated the interface file; it is used to ensure that we don't
582 mix-and-match interface files between compiler versions.
583 Leaving it as zero in an <literal>hi-boot</literal> file turns
584 off this check.</para>
586 <para>The number “1” at the beginning of a
587 declaration is the <emphasis>version number</emphasis> of that
588 declaration: for the purposes of <filename>.hi-boot</filename>
589 files these can all be set to 1. All names must be fully
590 qualified with the <emphasis>original</emphasis> module that an
591 object comes from: for example, the reference to
592 <literal>Int</literal> in the interface for <literal>A</literal>
593 comes from <literal>PrelBase</literal>, which is a module
594 internal to GHC's prelude. It's a pain, but that's the way it
597 <para>If you want an <literal>hi-boot</literal> file to export a
598 data type, but you don't want to give its constructors (because
599 the constructors aren't used by the SOURCE-importing module),
600 you can write simply:</para>
603 __interface A 1 0 where
608 <para>(You must write all the type parameters, but leave out the
609 '=' and everything that follows it.)</para>
611 <para><emphasis>Note:</emphasis> This is all a temporary
612 solution, a version of the compiler that handles mutually
613 recursive modules properly without the manual construction of
614 interface files, is (allegedly) in the works.</para>
618 <sect2 id="orphan-modules">
619 <title>Orphan modules and instance declarations</title>
621 <para> Haskell specifies that when compiling module M, any instance
622 declaration in any module "below" M is visible. (Module A is "below"
623 M if A is imported directly by M, or if A is below a module that M imports directly.)
624 In principle, GHC must therefore read the interface files of every module below M,
625 just in case they contain an instance declaration that matters to M. This would
626 be a disaster in practice, so GHC tries to be clever. </para>
628 <para>In particular, if an instance declaration is in the same module as the definition
629 of any type or class mentioned in the head of the instance declaration, then
630 GHC has to visit that interface file anyway. Example:</para>
633 instance C a => D (T a) where ...
636 <para> The instance declaration is only relevant if the type T is in use, and if
637 so, GHC will have visited A's interface file to find T's definition. </para>
639 <para> The only problem comes when a module contains an instance declaration
640 and GHC has no other reason for visiting the module. Example:
643 instance C a => D (T a) where ...
646 Here, neither D nor T is declared in module Orphan.
647 We call such modules ``orphan modules'',
650 <listitem> <para> An <emphasis>orphan module</emphasis>
651 <indexterm><primary>orphan module</primary></indexterm>
652 contains at least one <emphasis>orphan instance</emphasis> or at
653 least one <emphasis>orphan rule</emphasis>.</para> </listitem>
655 <listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if
656 <indexterm><primary>orphan instance</primary></indexterm>
657 none of the type constructors
658 or classes mentioned in the instance head (the part after the ``<literal>=></literal>'') are declared
661 <para> Only the instance head counts. In the example above, it is not good enough for C's declaration
662 to be in module A; it must be the declaration of D or T.</para>
665 <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis>
666 <indexterm><primary>orphan rule</primary></indexterm>
667 if none of the variables, type constructors,
668 or classes that are free in the left hand side of the rule are declared in M.
673 <para> GHC identifies orphan modules, and visits the interface file of
674 every orphan module below the module being compiled. This is usually
675 wasted work, but there is no avoiding it. You should therefore do
676 your best to have as few orphan modules as possible.
679 You can identify an orphan module by looking in its interface file, M.hi. If there is a ``!'' on
680 the first line, GHC considers it an orphan module.
687 ;;; Local Variables: ***
689 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***