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 merely there
22 to help the compiler compile other modules in the same program.
23 Interfaces are in a binary format, so don't try to look at one;
24 however you <emphasis>can</emphasis> see the contents of an
25 interface file by using GHC with the
26 <option>--show-iface</option> option (see <xref
27 linkend="hi-options">, below).</para>
29 <para>NOTE: In general, the name of a file containing module
30 <literal>M</literal> should be named <filename>M.hs</filename>
31 or <literal>M.lhs</literal>. The only exception to this rule is
32 module <literal>Main</literal>, which can be placed in any
33 file.<indexterm><primary>filenames</primary><secondary>for
34 modules</secondary> </indexterm></para>
36 <para>The interface file for <literal>A</literal> contains
37 information needed by the compiler when it compiles any module
38 <literal>B</literal> that imports <literal>A</literal>, whether
39 directly or indirectly. When compiling <literal>B</literal>,
40 GHC will read <filename>A.hi</filename> to find the details that
41 it needs to know about things defined in
42 <literal>A</literal>.</para>
44 <para>The interface file may contain all sorts of things that
45 aren't explicitly exported from <literal>A</literal> by the
46 programmer. For example, even though a data type is exported
47 abstractly, <filename>A.hi</filename> will contain the full data
48 type definition. For small function definitions,
49 <filename>A.hi</filename> will contain the complete definition
50 of the function. For bigger functions,
51 <filename>A.hi</filename> will contain strictness information
52 about the function. And so on. GHC puts much more information
53 into <filename>.hi</filename> files when optimisation is turned
54 on with the <option>-O</option> flag (see <xref
55 linkend="options-optimise">). Without <option>-O</option> it
56 puts in just the minimum; with <option>-O</option> it lobs in a
57 whole pile of stuff. <indexterm><primary>optimsation, effect on
58 .hi files</primary></indexterm></para>
60 <para><filename>A.hi</filename> should really be thought of as a
61 compiler-readable version of <filename>A.o</filename>. If you
62 use a <filename>.hi</filename> file that wasn't generated by the
63 same compilation run that generates the <filename>.o</filename>
64 file the compiler may assume all sorts of incorrect things about
65 <literal>A</literal>, resulting in core dumps and other
66 unpleasant happenings.</para>
70 <sect2 id="options-finding-imports">
71 <title>Finding interface files</title>
73 <indexterm><primary>interface files, finding them</primary></indexterm>
74 <indexterm><primary>finding interface files</primary></indexterm>
76 <para>In your program, you import a module
77 <literal>Foo</literal> by saying <literal>import Foo</literal>.
78 GHC goes looking for an interface file,
79 <filename>Foo.hi</filename>. It has a builtin list of
80 directories (notably including <filename>.</filename>) where it
86 <term><option>-i<dirs></option></term>
88 <para><indexterm><primary><option>-i<dirs></option>
89 </primary></indexterm>This flag appends a colon-separated
90 list of <filename>dirs</filename> to the “import
91 directories” list, which initially contains a single
92 entry: <quote>.</quote>.</para>
94 <para>This list is scanned before any package directories
95 (see <xref linkend="packages">) when looking for imports,
96 but note that if you have a home module with the same name
97 as a package module then this is likely to cause trouble
98 in other ways, with link errors being the least nasty
99 thing that can go wrong...</para>
101 <para>See also <XRef LinkEnd="recomp"> for the
102 significance of using relative and absolute pathnames in
103 the <option>-i</option> list.</para>
108 <term><option>-i</option></term>
110 <para>resets the “import directories” list
111 back to nothing.</para>
117 <para>See also the section on packages (<xref
118 linkend="packages">), which describes how to use installed
123 <sect2 id="finding-hierarchical-modules">
124 <title>Finding interfaces for hierarchical modules</title>
126 <para>GHC supports a hierarchical module namespace as an
127 extension to Haskell 98 (see <xref
128 linkend="hierarchical-modules">).</para>
130 <para>A module name in general consists of a sequence of
131 components separated by dots
132 (‘<literal>.</literal>’). When looking for
133 interface files for a hierarchical module, the compiler turns
134 the dots into path separators, so for example a module
135 <literal>A.B.C</literal> becomes <literal>A/B/C</literal> (or
136 <literal>A\B\C</literal> under Windows). Then each component of
137 the import directories list is tested in turn; so for example if
138 the list contains directories
139 <literal>D<subscript>1</subscript></literal> to
140 <literal>D<subscript>n</subscript></literal>, then the compiler
141 will look for the interface in
142 <literal>D<subscript>1</subscript>/A/B/C.hi</literal> first,
143 then <literal>D<subscript>2</subscript>/A/B/C.hi</literal> and
146 <para>Note that it's perfectly reasonable to have a module which
147 is both a leaf and a branch of the tree. For example, if we
148 have modules <literal>A.B</literal> and
149 <literal>A.B.C</literal>, then <literal>A.B</literal>'s
150 interface file will be in <literal>A/B.hi</literal> and
151 <literal>A.B.C</literal>'s interface file will be in
152 <literal>A/B/C.hi</literal>.</para>
154 <para>For GHCi and <option>--make</option>, the search strategy
155 for source files is exactly the same, just replace the
156 <literal>.hi</literal> suffix in the above description with
157 <literal>.hs</literal> or <literal>.lhs</literal>.</para>
160 <Sect2 id="hi-options">
161 <title>Other options related to interface files</title>
162 <indexterm><primary>interface files, options</primary></indexterm>
166 <term><option>-ddump-hi</option></term>
167 <indexterm><primary><option>-ddump-hi</option></primary>
170 <para>Dumps the new interface to standard output.</para>
175 <term><option>-ddump-hi-diffs</option></term>
176 <indexterm><primary><option>-ddump-hi-diffs</option></primary>
179 <para>The compiler does not overwrite an existing
180 <filename>.hi</filename> interface file if the new one is
181 the same as the old one; this is friendly to
182 <command>make</command>. When an interface does change,
183 it is often enlightening to be informed. The
184 <option>-ddump-hi-diffs</option> option will make GHC run
185 <command>diff</command> on the old and new
186 <filename>.hi</filename> files.</para>
191 <term><option>-ddump-minimal-imports</option></term>
192 <indexterm><primary><option>-ddump-minimal-imports</option></primary>
195 <para>Dump to the file "M.imports" (where M is the module
196 being compiled) a "minimal" set of import declarations.
197 You can safely replace all the import declarations in
198 "M.hs" with those found in "M.imports". Why would you
199 want to do that? Because the "minimal" imports (a) import
200 everything explicitly, by name, and (b) import nothing
201 that is not required. It can be quite painful to maintain
202 this property by hand, so this flag is intended to reduce
208 <term><option>--show-iface</option>
209 <replaceable>file</replaceable></term>
210 <indexterm><primary><option>--show-iface</option></primary>
213 <para>Where <replaceable>file</replaceable> is the name of
214 an interface file, dumps the contents of that interface in
215 a human-readable (ish) format.</para>
223 <title>The recompilation checker</title>
225 <indexterm><primary>recompilation checker</primary></indexterm>
229 <term><option>-no-recomp</option></term>
230 <indexterm><primary><option>-recomp</option></primary></indexterm>
231 <indexterm><primary><option>-no-recomp</option></primary></indexterm>
233 <para>Turn off recompilation checking (which is on by
234 default). Recompilation checking normally stops
235 compilation early, leaving an existing
236 <filename>.o</filename> file in place, if it can be
237 determined that the module does not need to be
243 <para>In the olden days, GHC compared the newly-generated
244 <filename>.hi</filename> file with the previous version; if they
245 were identical, it left the old one alone and didn't change its
246 modification date. In consequence, importers of a module with
247 an unchanged output <filename>.hi</filename> file were not
250 <para>This doesn't work any more. Suppose module
251 <literal>C</literal> imports module <literal>B</literal>, and
252 <literal>B</literal> imports module <literal>A</literal>. So
253 changes to <filename>A.hi</filename> should force a
254 recompilation of <literal>C</literal>. And some changes to
255 <literal>A</literal> (changing the definition of a function that
256 appears in an inlining of a function exported by
257 <literal>B</literal>, say) may conceivably not change
258 <filename>B.hi</filename> one jot. So now…</para>
260 <para>GHC keeps a version number on each interface file, and on
261 each type signature within the interface file. It also keeps in
262 every interface file a list of the version numbers of everything
263 it used when it last compiled the file. If the source file's
264 modification date is earlier than the <filename>.o</filename>
265 file's date (i.e. the source hasn't changed since the file was
266 last compiled), and the reompilation checking is on, GHC will be
267 clever. It compares the version numbers on the things it needs
268 this time with the version numbers on the things it needed last
269 time (gleaned from the interface file of the module being
270 compiled); if they are all the same it stops compiling rather
271 early in the process saying “Compilation IS NOT
272 required”. What a beautiful sight!</para>
274 <para>Patrick Sansom had a workshop paper about how all this is
275 done (though the details have changed quite a bit). <ULink
276 URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a
281 <sect2 id="using-make">
282 <title>Using <command>make</command></title>
284 <indexterm><primary><literal>make</literal></primary></indexterm>
286 <para>It is reasonably straightforward to set up a
287 <filename>Makefile</filename> to use with GHC, assuming you name
288 your source files the same as your modules. Thus:</para>
292 HC_OPTS = -cpp $(EXTRA_HC_OPTS)
294 SRCS = Main.lhs Foo.lhs Bar.lhs
295 OBJS = Main.o Foo.o Bar.o
297 .SUFFIXES : .o .hs .hi .lhs .hc .s
301 $(HC) -o $@ $(HC_OPTS) $(OBJS)
303 # Standard suffix rules
308 $(HC) -c $< $(HC_OPTS)
311 $(HC) -c $< $(HC_OPTS)
313 # Inter-module dependencies
314 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
315 Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
318 <para>(Sophisticated <command>make</command> variants may
319 achieve some of the above more elegantly. Notably,
320 <command>gmake</command>'s pattern rules let you write the more
321 comprehensible:</para>
325 $(HC) -c $< $(HC_OPTS)
328 <para>What we've shown should work with any
329 <command>make</command>.)</para>
331 <para>Note the cheesy <literal>.o.hi</literal> rule: It records
332 the dependency of the interface (<filename>.hi</filename>) file
333 on the source. The rule says a <filename>.hi</filename> file
334 can be made from a <filename>.o</filename> file by
335 doing…nothing. Which is true.</para>
337 <para>Note the inter-module dependencies at the end of the
338 Makefile, which take the form</para>
341 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
344 <para>They tell <command>make</command> that if any of
345 <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
346 <literal>Foo.s</literal> have an earlier modification date than
347 <literal>Baz.hi</literal>, then the out-of-date file must be
348 brought up to date. To bring it up to date,
349 <literal>make</literal> looks for a rule to do so; one of the
350 preceding suffix rules does the job nicely.</para>
352 <sect3 id="sec-makefile-dependencies">
353 <title>Dependency generation</title>
354 <indexterm><primary>dependencies in Makefiles</primary></indexterm>
355 <indexterm><primary>Makefile dependencies</primary></indexterm>
357 <para>Putting inter-dependencies of the form <literal>Foo.o :
358 Bar.hi</literal> into your <filename>Makefile</filename> by
359 hand is rather error-prone. Don't worry, GHC has support for
360 automatically generating the required dependencies. Add the
361 following to your <filename>Makefile</filename>:</para>
365 ghc -M $(HC_OPTS) $(SRCS)
368 <para>Now, before you start compiling, and any time you change
369 the <literal>imports</literal> in your program, do
370 <command>make depend</command> before you do <command>make
371 cool_pgm</command>. <command>ghc -M</command> will
372 append the needed dependencies to your
373 <filename>Makefile</filename>.</para>
375 <para>In general, if module <literal>A</literal> contains the
382 then <command>ghc -M</command> will generate a dependency line
389 If module <literal>A</literal> contains the line
392 import {-# SOURCE #-} B ...blah...
395 then <command>ghc -M</command> will generate a dependency
402 (See <xref linkend="mutual-recursion"> for details of
403 <literal>hi-boot</literal> style interface files.) If
404 <literal>A</literal> imports multiple modules, then there will
405 be multiple lines with <filename>A.o</filename> as the
408 <para>By default, <command>ghc -M</command> generates all the
409 dependencies, and then concatenates them onto the end of
410 <filename>makefile</filename> (or
411 <filename>Makefile</filename> if <filename>makefile</filename>
412 doesn't exist) bracketed by the lines "<literal># DO NOT
413 DELETE: Beginning of Haskell dependencies</literal>" and
414 "<literal># DO NOT DELETE: End of Haskell
415 dependencies</literal>". If these lines already exist in the
416 <filename>makefile</filename>, then the old dependencies are
417 deleted first.</para>
419 <para>Don't forget to use the same <option>-package</option>
420 options on the <literal>ghc -M</literal> command line as you
421 would when compiling; this enables the dependency generator to
422 locate any imported modules that come from packages. The
423 package modules won't be included in the dependencies
424 generated, though (but see the
425 <option>––include-prelude</option> option below).</para>
427 <para>The dependency generation phase of GHC can take some
428 additional options, which you may find useful. For historical
429 reasons, each option passed to the dependency generator from
430 the GHC command line must be preceded by
431 <literal>-optdep</literal>. For example, to pass <literal>-f
432 .depend</literal> to the dependency generator, you say
435 ghc -M -optdep-f -optdep.depend ...
438 The options which affect dependency generation are:</para>
442 <term><option>-w</option></term>
444 <para>Turn off warnings about interface file shadowing.</para>
449 <term><option>-f</option> <replaceable>file</replaceable></term>
451 <para>Use <replaceable>file</replaceable> as the makefile,
452 rather than <filename>makefile</filename> or
453 <filename>Makefile</filename>. If
454 <replaceable>file</replaceable> doesn't exist,
455 <command>mkdependHS</command> creates it. We often use
456 <option>-f .depend</option> to put the dependencies in
457 <filename>.depend</filename> and then
458 <command>include</command> the file
459 <filename>.depend</filename> into
460 <filename>Makefile</filename>.</para>
465 <term><option>-o <osuf></option></term>
467 <para>Use <filename>.<osuf></filename> as the
468 "target file" suffix ( default: <literal>o</literal>).
469 Multiple <option>-o</option> flags are permitted
470 (GHC2.05 onwards). Thus "<option>-o hc -o o</option>"
471 will generate dependencies for <filename>.hc</filename>
472 and <filename>.o</filename> files.</para>
477 <term><option>-s <suf></option></term>
479 <para>Make extra dependencies that declare that files
481 <filename>.<suf>_<osuf></filename>
482 depend on interface files with suffix
483 <filename>.<suf>_hi</filename>, or (for
484 <literal>{-# SOURCE #-}</literal>
485 imports) on <filename>.hi-boot</filename>. Multiple
486 <option>-s</option> flags are permitted. For example,
487 <option>-o hc -s a -s b</option> will make dependencies
488 for <filename>.hc</filename> on
489 <filename>.hi</filename>,
490 <filename>.a_hc</filename> on
491 <filename>.a_hi</filename>, and
492 <filename>.b_hc</filename> on
493 <filename>.b_hi</filename>. (Useful in
494 conjunction with NoFib "ways".)</para>
499 <term><option>––exclude-module=<file></option></term>
501 <para>Regard <filename><file></filename> as
502 "stable"; i.e., exclude it from having dependencies on
508 <term><option>-x</option></term>
510 <para>same as <option>––exclude-module</option></para>
515 <term><option>––exclude-directory=<dirs></option></term>
517 <para>Regard the colon-separated list of directories
518 <filename><dirs></filename> as containing stable,
519 don't generate any dependencies on modules
525 <term><option>––include-module=<file></option></term>
527 <para>Regard <filename><file></filename> as not
528 "stable"; i.e., generate dependencies on it (if
529 any). This option is normally used in conjunction with
530 the <option>––exclude-directory</option> option.</para>
535 <term><option>––include-prelude</option></term>
537 <para>Regard modules imported from packages as unstable,
538 i.e., generate dependencies on the package modules used
539 (including <literal>Prelude</literal>, and all other
540 standard Haskell libraries). This option is normally
541 only used by the various system libraries.</para>
549 <sect2 id="mutual-recursion">
550 <title>How to compile mutually recursive modules</title>
552 <indexterm><primary>module system, recursion</primary></indexterm>
553 <indexterm><primary>recursion, between modules</primary></indexterm>
555 <para>Currently, the compiler does not have proper support for
556 dealing with mutually recursive modules:</para>
563 newtype TA = MkTA Int
578 <para>When compiling either module A and B, the compiler will
579 try (in vain) to look for the interface file of the other. So,
580 to get mutually recursive modules off the ground, you need to
581 hand write an interface file for A or B, so as to break the
582 loop. These hand-written interface files are called
583 <literal>hi-boot</literal> files, and are placed in a file
584 called <filename><module>.hi-boot</filename>. To import
585 from an <literal>hi-boot</literal> file instead of the standard
586 <filename>.hi</filename> file, use the following syntax in the
587 importing module: <indexterm><primary><literal>hi-boot</literal>
588 files</primary></indexterm> <indexterm><primary>importing,
589 <literal>hi-boot</literal> files</primary></indexterm></para>
592 import {-# SOURCE #-} A
595 <para>The hand-written interface need only contain the bare
596 minimum of information needed to get the bootstrapping process
597 started. For example, it doesn't need to contain declarations
598 for <emphasis>everything</emphasis> that module
599 <literal>A</literal> exports, only the things required by the
600 module that imports <literal>A</literal> recursively.</para>
602 <para>For the example at hand, the boot interface file for A
603 would look like the following:</para>
607 newtype TA = MkTA GHC.Base.Int
610 <para>The syntax is similar to a normal Haskell source file, but
611 with some important differences:</para>
615 <para>Non-local entities must be qualified with their
616 <emphasis>original</emphasis> defining module. Qualifying
617 by a module which just re-exports the entity won't do. In
618 particular, most <literal>Prelude</literal> entities aren't
619 actually defined in the <literal>Prelude</literal> (see for
620 example <literal>GHC.Base.Int</literal> in the above
624 <para>Only <literal>data</literal>, <literal>type</literal>,
625 <literal>newtype</literal>, <literal>class</literal>, and
626 type signature declarations may be included.</para>
630 <para>Notice that we only put the declaration for the newtype
631 <literal>TA</literal> in the <literal>hi-boot</literal> file,
632 not the signature for <Function>f</Function>, since
633 <Function>f</Function> isn't used by <literal>B</literal>.</para>
635 <para>If you want an <literal>hi-boot</literal> file to export a
636 data type, but you don't want to give its constructors (because
637 the constructors aren't used by the SOURCE-importing module),
638 you can write simply:</para>
645 <para>(You must write all the type parameters, but leave out the
646 '=' and everything that follows it.)</para>
650 <sect2 id="orphan-modules">
651 <title>Orphan modules and instance declarations</title>
653 <para> Haskell specifies that when compiling module M, any instance
654 declaration in any module "below" M is visible. (Module A is "below"
655 M if A is imported directly by M, or if A is below a module that M imports directly.)
656 In principle, GHC must therefore read the interface files of every module below M,
657 just in case they contain an instance declaration that matters to M. This would
658 be a disaster in practice, so GHC tries to be clever. </para>
660 <para>In particular, if an instance declaration is in the same module as the definition
661 of any type or class mentioned in the head of the instance declaration, then
662 GHC has to visit that interface file anyway. Example:</para>
665 instance C a => D (T a) where ...
668 <para> The instance declaration is only relevant if the type T is in use, and if
669 so, GHC will have visited A's interface file to find T's definition. </para>
671 <para> The only problem comes when a module contains an instance declaration
672 and GHC has no other reason for visiting the module. Example:
675 instance C a => D (T a) where ...
678 Here, neither D nor T is declared in module Orphan.
679 We call such modules ``orphan modules'',
682 <listitem> <para> An <emphasis>orphan module</emphasis>
683 <indexterm><primary>orphan module</primary></indexterm>
684 contains at least one <emphasis>orphan instance</emphasis> or at
685 least one <emphasis>orphan rule</emphasis>.</para> </listitem>
687 <listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if
688 <indexterm><primary>orphan instance</primary></indexterm>
689 none of the type constructors
690 or classes mentioned in the instance head (the part after the ``<literal>=></literal>'') are declared
693 <para> Only the instance head counts. In the example above, it is not good enough for C's declaration
694 to be in module A; it must be the declaration of D or T.</para>
697 <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis>
698 <indexterm><primary>orphan rule</primary></indexterm>
699 if none of the variables, type constructors,
700 or classes that are free in the left hand side of the rule are declared in M.
705 <para> GHC identifies orphan modules, and visits the interface file of
706 every orphan module below the module being compiled. This is usually
707 wasted work, but there is no avoiding it. You should therefore do
708 your best to have as few orphan modules as possible.
712 <para> You can identify an orphan module by looking in its interface
713 file, <filename>M.hi</filename>, using the
714 <option>--show-iface</option>. If there is a ``!'' on the first line,
715 GHC considers it an orphan module.
722 ;;; Local Variables: ***
724 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***