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>-ddump-hi</option></term>
127 <indexterm><primary><option>-ddump-hi</option></primary>
130 <para>Dumps the new interface to standard output.</para>
135 <term><option>-ddump-hi-diffs</option></term>
136 <indexterm><primary><option>-ddump-hi-diffs</option></primary>
139 <para>The compiler does not overwrite an existing
140 <filename>.hi</filename> interface file if the new one is
141 the same as the old one; this is friendly to
142 <command>make</command>. When an interface does change,
143 it is often enlightening to be informed. The
144 <option>-ddump-hi-diffs</option> option will make GHC run
145 <command>diff</command> on the old and new
146 <filename>.hi</filename> files.</para>
151 <term><option>-ddump-minimal-imports</option></term>
152 <indexterm><primary><option>-ddump-minimal-imports</option></primary>
155 <para>Dump to the file "M.imports" (where M is the module
156 being compiled) a "minimal" set of import declarations.
157 You can safely replace all the import declarations in
158 "M.hs" with those found in "M.imports". Why would you
159 want to do that? Because the "minimal" imports (a) import
160 everything explicitly, by name, and (b) import nothing
161 that is not required. It can be quite painful to maintain
162 this property by hand, so this flag is intended to reduce
171 <title>The recompilation checker</title>
173 <indexterm><primary>recompilation checker</primary></indexterm>
177 <term><option>-no-recomp</option></term>
178 <indexterm><primary><option>-recomp</option></primary></indexterm>
179 <indexterm><primary><option>-no-recomp</option></primary></indexterm>
181 <para>Turn off recompilation checking (which is on by
182 default). Recompilation checking normally stops
183 compilation early, leaving an existing
184 <filename>.o</filename> file in place, if it can be
185 determined that the module does not need to be
191 <para>In the olden days, GHC compared the newly-generated
192 <filename>.hi</filename> file with the previous version; if they
193 were identical, it left the old one alone and didn't change its
194 modification date. In consequence, importers of a module with
195 an unchanged output <filename>.hi</filename> file were not
198 <para>This doesn't work any more. Suppose module
199 <literal>C</literal> imports module <literal>B</literal>, and
200 <literal>B</literal> imports module <literal>A</literal>. So
201 changes to <filename>A.hi</filename> should force a
202 recompilation of <literal>C</literal>. And some changes to
203 <literal>A</literal> (changing the definition of a function that
204 appears in an inlining of a function exported by
205 <literal>B</literal>, say) may conceivably not change
206 <filename>B.hi</filename> one jot. So now…</para>
208 <para>GHC keeps a version number on each interface file, and on
209 each type signature within the interface file. It also keeps in
210 every interface file a list of the version numbers of everything
211 it used when it last compiled the file. If the source file's
212 modification date is earlier than the <filename>.o</filename>
213 file's date (i.e. the source hasn't changed since the file was
214 last compiled), and the reompilation checking is on, GHC will be
215 clever. It compares the version numbers on the things it needs
216 this time with the version numbers on the things it needed last
217 time (gleaned from the interface file of the module being
218 compiled); if they are all the same it stops compiling rather
219 early in the process saying “Compilation IS NOT
220 required”. What a beautiful sight!</para>
222 <para>Patrick Sansom had a workshop paper about how all this is
223 done (though the details have changed quite a bit). <ULink
224 URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a
229 <sect2 id="using-make">
230 <title>Using <command>make</command></title>
232 <indexterm><primary><literal>make</literal></primary></indexterm>
234 <para>It is reasonably straightforward to set up a
235 <filename>Makefile</filename> to use with GHC, assuming you name
236 your source files the same as your modules. Thus:</para>
240 HC_OPTS = -cpp $(EXTRA_HC_OPTS)
242 SRCS = Main.lhs Foo.lhs Bar.lhs
243 OBJS = Main.o Foo.o Bar.o
245 .SUFFIXES : .o .hs .hi .lhs .hc .s
249 $(HC) -o $@ $(HC_OPTS) $(OBJS)
251 # Standard suffix rules
256 $(HC) -c $< $(HC_OPTS)
259 $(HC) -c $< $(HC_OPTS)
261 # Inter-module dependencies
262 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
263 Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
266 <para>(Sophisticated <command>make</command> variants may
267 achieve some of the above more elegantly. Notably,
268 <command>gmake</command>'s pattern rules let you write the more
269 comprehensible:</para>
273 $(HC) -c $< $(HC_OPTS)
276 <para>What we've shown should work with any
277 <command>make</command>.)</para>
279 <para>Note the cheesy <literal>.o.hi</literal> rule: It records
280 the dependency of the interface (<filename>.hi</filename>) file
281 on the source. The rule says a <filename>.hi</filename> file
282 can be made from a <filename>.o</filename> file by
283 doing…nothing. Which is true.</para>
285 <para>Note the inter-module dependencies at the end of the
286 Makefile, which take the form</para>
289 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
292 <para>They tell <command>make</command> that if any of
293 <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
294 <literal>Foo.s</literal> have an earlier modification date than
295 <literal>Baz.hi</literal>, then the out-of-date file must be
296 brought up to date. To bring it up to date,
297 <literal>make</literal> looks for a rule to do so; one of the
298 preceding suffix rules does the job nicely.</para>
300 <sect3 id="sec-makefile-dependencies">
301 <title>Dependency generation</title>
302 <indexterm><primary>dependencies in Makefiles</primary></indexterm>
303 <indexterm><primary>Makefile dependencies</primary></indexterm>
305 <para>Putting inter-dependencies of the form <literal>Foo.o :
306 Bar.hi</literal> into your <filename>Makefile</filename> by
307 hand is rather error-prone. Don't worry, GHC has support for
308 automatically generating the required dependencies. Add the
309 following to your <filename>Makefile</filename>:</para>
313 ghc -M $(HC_OPTS) $(SRCS)
316 <para>Now, before you start compiling, and any time you change
317 the <literal>imports</literal> in your program, do
318 <command>make depend</command> before you do <command>make
319 cool_pgm</command>. <command>ghc -M</command> will
320 append the needed dependencies to your
321 <filename>Makefile</filename>.</para>
323 <para>In general, if module <literal>A</literal> contains the
330 then <command>ghc -M</command> will generate a dependency line
337 If module <literal>A</literal> contains the line
340 import {-# SOURCE #-} B ...blah...
343 then <command>ghc -M</command> will generate a dependency
350 (See <xref linkend="mutual-recursion"> for details of
351 <literal>hi-boot</literal> style interface files.) If
352 <literal>A</literal> imports multiple modules, then there will
353 be multiple lines with <filename>A.o</filename> as the
356 <para>By default, <command>ghc -M</command> generates all the
357 dependencies, and then concatenates them onto the end of
358 <filename>makefile</filename> (or
359 <filename>Makefile</filename> if <filename>makefile</filename>
360 doesn't exist) bracketed by the lines "<literal># DO NOT
361 DELETE: Beginning of Haskell dependencies</literal>" and
362 "<literal># DO NOT DELETE: End of Haskell
363 dependencies</literal>". If these lines already exist in the
364 <filename>makefile</filename>, then the old dependencies are
365 deleted first.</para>
367 <para>Don't forget to use the same <option>-package</option>
368 options on the <literal>ghc -M</literal> command line as you
369 would when compiling; this enables the dependency generator to
370 locate any imported modules that come from packages. The
371 package modules won't be included in the dependencies
372 generated, though (but see the
373 <option>--include-prelude</option> option below).</para>
375 <para>The dependency generation phase of GHC can take some
376 additional options, which you may find useful. For historical
377 reasons, each option passed to the dependency generator from
378 the GHC command line must be preceded by
379 <literal>-optdep</literal>. For example, to pass <literal>-f
380 .depend</literal> to the dependency generator, you say
383 ghc -M -optdep-f -optdep.depend ...
386 The options which affect dependency generation are:</para>
390 <term><option>-w</option></term>
392 <para>Turn off warnings about interface file shadowing.</para>
397 <term><option>-f</option> <replaceable>file</replaceable></term>
399 <para>Use <replaceable>file</replaceable> as the makefile,
400 rather than <filename>makefile</filename> or
401 <filename>Makefile</filename>. If
402 <replaceable>file</replaceable> doesn't exist,
403 <command>mkdependHS</command> creates it. We often use
404 <option>-f .depend</option> to put the dependencies in
405 <filename>.depend</filename> and then
406 <command>include</command> the file
407 <filename>.depend</filename> into
408 <filename>Makefile</filename>.</para>
413 <term><option>-o <osuf></option></term>
415 <para>Use <filename>.<osuf></filename> as the
416 "target file" suffix ( default: <literal>o</literal>).
417 Multiple <option>-o</option> flags are permitted
418 (GHC2.05 onwards). Thus "<option>-o hc -o o</option>"
419 will generate dependencies for <filename>.hc</filename>
420 and <filename>.o</filename> files.</para>
425 <term><option>-s <suf></option></term>
427 <para>Make extra dependencies that declare that files
429 <filename>.<suf>_<osuf></filename>
430 depend on interface files with suffix
431 <filename>.<suf>_hi</filename>, or (for
432 <literal>{-# SOURCE #-}</literal>
433 imports) on <filename>.hi-boot</filename>. Multiple
434 <option>-s</option> flags are permitted. For example,
435 <option>-o hc -s a -s b</option> will make dependencies
436 for <filename>.hc</filename> on
437 <filename>.hi</filename>,
438 <filename>.a_hc</filename> on
439 <filename>.a_hi</filename>, and
440 <filename>.b_hc</filename> on
441 <filename>.b_hi</filename>. (Useful in
442 conjunction with NoFib "ways".)</para>
447 <term><option>--exclude-module=<file></option></term>
449 <para>Regard <filename><file></filename> as
450 "stable"; i.e., exclude it from having dependencies on
456 <term><option>-x</option></term>
458 <para>same as <option>--exclude-module</option></para>
463 <term><option>--exclude-directory=<dirs></option></term>
465 <para>Regard the colon-separated list of directories
466 <filename><dirs></filename> as containing stable,
467 don't generate any dependencies on modules
473 <term><option>--include-module=<file></option></term>
475 <para>Regard <filename><file></filename> as not
476 "stable"; i.e., generate dependencies on it (if
477 any). This option is normally used in conjunction with
478 the <option>--exclude-directory</option> option.</para>
483 <term><option>--include-prelude</option></term>
485 <para>Regard modules imported from packages as unstable,
486 i.e., generate dependencies on the package modules used
487 (including <literal>Prelude</literal>, and all other
488 standard Haskell libraries). This option is normally
489 only used by the various system libraries.</para>
497 <sect2 id="mutual-recursion">
498 <title>How to compile mutually recursive modules</title>
500 <indexterm><primary>module system, recursion</primary></indexterm>
501 <indexterm><primary>recursion, between modules</primary></indexterm>
503 <para>Currently, the compiler does not have proper support for
504 dealing with mutually recursive modules:</para>
511 newtype TA = MkTA Int
526 <para>When compiling either module A and B, the compiler will
527 try (in vain) to look for the interface file of the other. So,
528 to get mutually recursive modules off the ground, you need to
529 hand write an interface file for A or B, so as to break the
530 loop. These hand-written interface files are called
531 <literal>hi-boot</literal> files, and are placed in a file
532 called <filename><module>.hi-boot</filename>. To import
533 from an <literal>hi-boot</literal> file instead of the standard
534 <filename>.hi</filename> file, use the following syntax in the
535 importing module: <indexterm><primary><literal>hi-boot</literal>
536 files</primary></indexterm> <indexterm><primary>importing,
537 <literal>hi-boot</literal> files</primary></indexterm></para>
540 import {-# SOURCE #-} A
543 <para>The hand-written interface need only contain the bare
544 minimum of information needed to get the bootstrapping process
545 started. For example, it doesn't need to contain declarations
546 for <emphasis>everything</emphasis> that module
547 <literal>A</literal> exports, only the things required by the
548 module that imports <literal>A</literal> recursively.</para>
550 <para>For the example at hand, the boot interface file for A
551 would look like the following:</para>
554 __interface A 1 0 where
555 __export A TA{MkTA} ;
556 1 newtype TA = MkTA PrelBase.Int ;
559 <para>The syntax is essentially the same as a normal
560 <filename>.hi</filename> file (unfortunately), so you can
561 usually tailor an existing <filename>.hi</filename> file to make
562 a <filename>.hi-boot</filename> file.</para>
564 <para>Notice that we only put the declaration for the newtype
565 <literal>TA</literal> in the <literal>hi-boot</literal> file,
566 not the signature for <Function>f</Function>, since
567 <Function>f</Function> isn't used by <literal>B</literal>.</para>
569 <para>The number “1” after
570 “__interface A” gives the version
571 number of module A; it is incremented whenever anything in A's
572 interface file changes. In a normal interface file, the
573 “0” is the version number of the compiler which
574 generated the interface file; it is used to ensure that we don't
575 mix-and-match interface files between compiler versions.
576 Leaving it as zero in an <literal>hi-boot</literal> file turns
577 off this check.</para>
579 <para>The number “1” at the beginning of a
580 declaration is the <emphasis>version number</emphasis> of that
581 declaration: for the purposes of <filename>.hi-boot</filename>
582 files these can all be set to 1. All names must be fully
583 qualified with the <emphasis>original</emphasis> module that an
584 object comes from: for example, the reference to
585 <literal>Int</literal> in the interface for <literal>A</literal>
586 comes from <literal>PrelBase</literal>, which is a module
587 internal to GHC's prelude. It's a pain, but that's the way it
590 <para>If you want an <literal>hi-boot</literal> file to export a
591 data type, but you don't want to give its constructors (because
592 the constructors aren't used by the SOURCE-importing module),
593 you can write simply:</para>
596 __interface A 1 0 where
601 <para>(You must write all the type parameters, but leave out the
602 '=' and everything that follows it.)</para>
604 <para><emphasis>Note:</emphasis> This is all a temporary
605 solution, a version of the compiler that handles mutually
606 recursive modules properly without the manual construction of
607 interface files, is (allegedly) in the works.</para>
611 <sect2 id="orphan-modules">
612 <title>Orphan modules and instance declarations</title>
614 <para> Haskell specifies that when compiling module M, any instance
615 declaration in any module "below" M is visible. (Module A is "below"
616 M if A is imported directly by M, or if A is below a module that M imports directly.)
617 In principle, GHC must therefore read the interface files of every module below M,
618 just in case they contain an instance declaration that matters to M. This would
619 be a disaster in practice, so GHC tries to be clever. </para>
621 <para>In particular, if an instance declaration is in the same module as the definition
622 of any type or class mentioned in the head of the instance declaration, then
623 GHC has to visit that interface file anyway. Example:</para>
626 instance C a => D (T a) where ...
629 <para> The instance declaration is only relevant if the type T is in use, and if
630 so, GHC will have visited A's interface file to find T's definition. </para>
632 <para> The only problem comes when a module contains an instance declaration
633 and GHC has no other reason for visiting the module. Example:
636 instance C a => D (T a) where ...
639 Here, neither D nor T is declared in module Orphan.
640 We call such modules ``orphan modules'',
643 <listitem> <para> An <emphasis>orphan module</emphasis>
644 <indexterm><primary>orphan module</primary></indexterm>
645 contains at least one <emphasis>orphan instance</emphasis> or at
646 least one <emphasis>orphan rule</emphasis>.</para> </listitem>
648 <listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if
649 <indexterm><primary>orphan instance</primary></indexterm>
650 none of the type constructors
651 or classes mentioned in the instance head (the part after the ``<literal>=></literal>'') are declared
654 <para> Only the instance head counts. In the example above, it is not good enough for C's declaration
655 to be in module A; it must be the declaration of D or T.</para>
658 <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis>
659 <indexterm><primary>orphan rule</primary></indexterm>
660 if none of the variables, type constructors,
661 or classes that are free in the left hand side of the rule are declared in M.
666 <para> GHC identifies orphan modules, and visits the interface file of
667 every orphan module below the module being compiled. This is usually
668 wasted work, but there is no avoiding it. You should therefore do
669 your best to have as few orphan modules as possible.
672 You can identify an orphan module by looking in its interface file, M.hi. If there is a ``!'' on
673 the first line, GHC considers it an orphan module.
680 ;;; Local Variables: ***
682 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***