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 prepends a colon-separated
87 list of <filename>dirs</filename> to the “import
88 directories” list. See also <XRef LinkEnd="recomp">
89 for the significance of using relative and absolute
90 pathnames in the <option>-i</option> list.</para>
95 <term><option>-i</option></term>
97 <para>resets the “import directories” list
98 back to nothing.</para>
104 <para>See also the section on packages (<xref
105 linkend="packages">), which describes how to use installed
110 <Sect2 id="hi-options">
111 <title>Other options related to interface files</title>
112 <indexterm><primary>interface files, options</primary></indexterm>
116 <term><option>-ohi</option> <replaceable>file</replaceable></term>
117 <indexterm><primary><option>-ohi</option></primary>
120 <para>The interface output may be directed to another file
121 <filename>bar2/Wurble.iface</filename> with the option
122 <option>-ohi bar2/Wurble.iface</option> (not recommended).
123 To avoid generating an interface at all, you can say
124 <literal>-ohi /dev/null</literal>, for example.</para>
129 <term><option>-ddump-hi</option></term>
130 <indexterm><primary><option>-ddump-hi</option></primary>
133 <para>Dumps the new interface to standard output.</para>
138 <term><option>-ddump-hi-diffs</option></term>
139 <indexterm><primary><option>-ddump-hi-diffs</option></primary>
142 <para>The compiler does not overwrite an existing
143 <filename>.hi</filename> interface file if the new one is
144 the same as the old one; this is friendly to
145 <command>make</command>. When an interface does change,
146 it is often enlightening to be informed. The
147 <option>-ddump-hi-diffs</option> option will make GHC run
148 <command>diff</command> on the old and new
149 <filename>.hi</filename> files.</para>
154 <term><option>-ddump-minimal-imports</option></term>
155 <indexterm><primary><option>-ddump-minimal-imports</option></primary>
158 <para>Dump to the file "M.imports" (where M is the module
159 being compiled) a "minimal" set of import declarations.
160 You can safely replace all the import declarations in
161 "M.hs" with those found in "M.imports". Why would you
162 want to do that? Because the "minimal" imports (a) import
163 everything explicitly, by name, and (b) import nothing
164 that is not required. It can be quite painful to maintain
165 this property by hand, so this flag is intended to reduce
174 <title>The recompilation checker</title>
176 <indexterm><primary>recompilation checker</primary></indexterm>
180 <term><option>-no-recomp</option></term>
181 <indexterm><primary><option>-recomp</option></primary></indexterm>
182 <indexterm><primary><option>-no-recomp</option></primary></indexterm>
184 <para>Turn off recompilation checking (which is on by
185 default). Recompilation checking normally stops
186 compilation early, leaving an existing
187 <filename>.o</filename> file in place, if it can be
188 determined that the module does not need to be
194 <para>In the olden days, GHC compared the newly-generated
195 <filename>.hi</filename> file with the previous version; if they
196 were identical, it left the old one alone and didn't change its
197 modification date. In consequence, importers of a module with
198 an unchanged output <filename>.hi</filename> file were not
201 <para>This doesn't work any more. Suppose module
202 <literal>C</literal> imports module <literal>B</literal>, and
203 <literal>B</literal> imports module <literal>A</literal>. So
204 changes to <filename>A.hi</filename> should force a
205 recompilation of <literal>C</literal>. And some changes to
206 <literal>A</literal> (changing the definition of a function that
207 appears in an inlining of a function exported by
208 <literal>B</literal>, say) may conceivably not change
209 <filename>B.hi</filename> one jot. So now…</para>
211 <para>GHC keeps a version number on each interface file, and on
212 each type signature within the interface file. It also keeps in
213 every interface file a list of the version numbers of everything
214 it used when it last compiled the file. If the source file's
215 modification date is earlier than the <filename>.o</filename>
216 file's date (i.e. the source hasn't changed since the file was
217 last compiled), and the reompilation checking is on, GHC will be
218 clever. It compares the version numbers on the things it needs
219 this time with the version numbers on the things it needed last
220 time (gleaned from the interface file of the module being
221 compiled); if they are all the same it stops compiling rather
222 early in the process saying “Compilation IS NOT
223 required”. What a beautiful sight!</para>
225 <para>Patrick Sansom had a workshop paper about how all this is
226 done (though the details have changed quite a bit). <ULink
227 URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a
232 <sect2 id="using-make">
233 <title>Using <command>make</command></title>
235 <indexterm><primary><literal>make</literal></primary></indexterm>
237 <para>It is reasonably straightforward to set up a
238 <filename>Makefile</filename> to use with GHC, assuming you name
239 your source files the same as your modules. Thus:</para>
243 HC_OPTS = -cpp $(EXTRA_HC_OPTS)
245 SRCS = Main.lhs Foo.lhs Bar.lhs
246 OBJS = Main.o Foo.o Bar.o
248 .SUFFIXES : .o .hs .hi .lhs .hc .s
252 $(HC) -o $@ $(HC_OPTS) $(OBJS)
254 # Standard suffix rules
259 $(HC) -c $< $(HC_OPTS)
262 $(HC) -c $< $(HC_OPTS)
264 # Inter-module dependencies
265 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
266 Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
269 <para>(Sophisticated <command>make</command> variants may
270 achieve some of the above more elegantly. Notably,
271 <command>gmake</command>'s pattern rules let you write the more
272 comprehensible:</para>
276 $(HC) -c $< $(HC_OPTS)
279 <para>What we've shown should work with any
280 <command>make</command>.)</para>
282 <para>Note the cheesy <literal>.o.hi</literal> rule: It records
283 the dependency of the interface (<filename>.hi</filename>) file
284 on the source. The rule says a <filename>.hi</filename> file
285 can be made from a <filename>.o</filename> file by
286 doing…nothing. Which is true.</para>
288 <para>Note the inter-module dependencies at the end of the
289 Makefile, which take the form</para>
292 Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
295 <para>They tell <command>make</command> that if any of
296 <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
297 <literal>Foo.s</literal> have an earlier modification date than
298 <literal>Baz.hi</literal>, then the out-of-date file must be
299 brought up to date. To bring it up to date,
300 <literal>make</literal> looks for a rule to do so; one of the
301 preceding suffix rules does the job nicely.</para>
303 <sect3 id="sec-makefile-dependencies">
304 <title>Dependency generation</title>
305 <indexterm><primary>dependencies in Makefiles</primary></indexterm>
306 <indexterm><primary>Makefile dependencies</primary></indexterm>
308 <para>Putting inter-dependencies of the form <literal>Foo.o :
309 Bar.hi</literal> into your <filename>Makefile</filename> by
310 hand is rather error-prone. Don't worry, GHC has support for
311 automatically generating the required dependencies. Add the
312 following to your <filename>Makefile</filename>:</para>
316 ghc -M $(HC_OPTS) $(SRCS)
319 <para>Now, before you start compiling, and any time you change
320 the <literal>imports</literal> in your program, do
321 <command>make depend</command> before you do <command>make
322 cool_pgm</command>. <command>ghc -M</command> will
323 append the needed dependencies to your
324 <filename>Makefile</filename>.</para>
326 <para>In general, if module <literal>A</literal> contains the
333 then <command>ghc -M</command> will generate a dependency line
340 If module <literal>A</literal> contains the line
343 import {-# SOURCE #-} B ...blah...
346 then <command>ghc -M</command> will generate a dependency
353 (See <xref linkend="mutual-recursion"> for details of
354 <literal>hi-boot</literal> style interface files.) If
355 <literal>A</literal> imports multiple modules, then there will
356 be multiple lines with <filename>A.o</filename> as the
359 <para>By default, <command>ghc -M</command> generates all the
360 dependencies, and then concatenates them onto the end of
361 <filename>makefile</filename> (or
362 <filename>Makefile</filename> if <filename>makefile</filename>
363 doesn't exist) bracketed by the lines "<literal># DO NOT
364 DELETE: Beginning of Haskell dependencies</literal>" and
365 "<literal># DO NOT DELETE: End of Haskell
366 dependencies</literal>". If these lines already exist in the
367 <filename>makefile</filename>, then the old dependencies are
368 deleted first.</para>
370 <para>The dependency generation phase of GHC can take some
371 additional options, which you may find useful. For historical
372 reasons, each option passed to the dependency generator from
373 the GHC command line must be preceded by
374 <literal>-optdep</literal>. For example, to pass <literal>-f
375 .depend</literal> to the dependency generator, you say
378 ghc -M -optdep-f -optdep.depend ...
381 The options which affect dependency generation are:</para>
385 <term><option>-w</option></term>
387 <para>Turn off warnings about interface file shadowing.</para>
392 <term><option>-f</option> <replaceable>file</replaceable></term>
394 <para>Use <replaceable>file</replaceable> as the makefile,
395 rather than <filename>makefile</filename> or
396 <filename>Makefile</filename>. If
397 <replaceable>file</replaceable> doesn't exist,
398 <command>mkdependHS</command> creates it. We often use
399 <option>-f .depend</option> to put the dependencies in
400 <filename>.depend</filename> and then
401 <command>include</command> the file
402 <filename>.depend</filename> into
403 <filename>Makefile</filename>.</para>
408 <term><option>-o <osuf></option></term>
410 <para>Use <filename>.<osuf></filename> as the
411 "target file" suffix ( default: <literal>o</literal>).
412 Multiple <option>-o</option> flags are permitted
413 (GHC2.05 onwards). Thus "<option>-o hc -o o</option>"
414 will generate dependencies for <filename>.hc</filename>
415 and <filename>.o</filename> files.</para>
420 <term><option>-s <suf></option></term>
422 <para>Make extra dependencies that declare that files
424 <filename>.<suf>_<osuf></filename>
425 depend on interface files with suffix
426 <filename>.<suf>_hi</filename>, or (for
427 <literal>{-# SOURCE #-}</literal>
428 imports) on <filename>.hi-boot</filename>. Multiple
429 <option>-s</option> flags are permitted. For example,
430 <option>-o hc -s a -s b</option> will make dependencies
431 for <filename>.hc</filename> on
432 <filename>.hi</filename>,
433 <filename>.a_hc</filename> on
434 <filename>.a_hi</filename>, and
435 <filename>.b_hc</filename> on
436 <filename>.b_hi</filename>. (Useful in
437 conjunction with NoFib "ways".)</para>
442 <term><option>--exclude-module=<file></option></term>
444 <para>Regard <filename><file></filename> as
445 "stable"; i.e., exclude it from having dependencies on
451 <term><option>-x</option></term>
453 <para>same as <option>--exclude-module</option></para>
458 <term><option>--exclude-directory=<dirs></option></term>
460 <para>Regard the colon-separated list of directories
461 <filename><dirs></filename> as containing stable,
462 don't generate any dependencies on modules
468 <term><option>--include-module=<file></option></term>
470 <para>Regard <filename><file></filename> as not
471 "stable"; i.e., generate dependencies on it (if
472 any). This option is normally used in conjunction with
473 the <option>--exclude-directory</option> option.</para>
478 <term><option>--include-prelude</option></term>
480 <para>Regard prelude libraries as unstable, i.e.,
481 generate dependencies on the prelude modules used
482 (including <literal>Prelude</literal>). This option is
483 normally only used by the various system libraries. If a
484 <option>-package</option> option is used, dependencies
485 will also be generated on the library's
494 <sect2 id="mutual-recursion">
495 <title>How to compile mutually recursive modules</title>
497 <indexterm><primary>module system, recursion</primary></indexterm>
498 <indexterm><primary>recursion, between modules</primary></indexterm>
500 <para>Currently, the compiler does not have proper support for
501 dealing with mutually recursive modules:</para>
508 newtype TA = MkTA Int
523 <para>When compiling either module A and B, the compiler will
524 try (in vain) to look for the interface file of the other. So,
525 to get mutually recursive modules off the ground, you need to
526 hand write an interface file for A or B, so as to break the
527 loop. These hand-written interface files are called
528 <literal>hi-boot</literal> files, and are placed in a file
529 called <filename><module>.hi-boot</filename>. To import
530 from an <literal>hi-boot</literal> file instead of the standard
531 <filename>.hi</filename> file, use the following syntax in the
532 importing module: <indexterm><primary><literal>hi-boot</literal>
533 files</primary></indexterm> <indexterm><primary>importing,
534 <literal>hi-boot</literal> files</primary></indexterm></para>
537 import {-# SOURCE #-} A
540 <para>The hand-written interface need only contain the bare
541 minimum of information needed to get the bootstrapping process
542 started. For example, it doesn't need to contain declarations
543 for <emphasis>everything</emphasis> that module
544 <literal>A</literal> exports, only the things required by the
545 module that imports <literal>A</literal> recursively.</para>
547 <para>For the example at hand, the boot interface file for A
548 would look like the following:</para>
551 __interface A 1 0 where
552 __export A TA{MkTA} ;
553 1 newtype TA = MkTA PrelBase.Int ;
556 <para>The syntax is essentially the same as a normal
557 <filename>.hi</filename> file (unfortunately), so you can
558 usually tailor an existing <filename>.hi</filename> file to make
559 a <filename>.hi-boot</filename> file.</para>
561 <para>Notice that we only put the declaration for the newtype
562 <literal>TA</literal> in the <literal>hi-boot</literal> file,
563 not the signature for <Function>f</Function>, since
564 <Function>f</Function> isn't used by <literal>B</literal>.</para>
566 <para>The number “1” after
567 “__interface A” gives the version
568 number of module A; it is incremented whenever anything in A's
569 interface file changes. In a normal interface file, the
570 “0” is the version number of the compiler which
571 generated the interface file; it is used to ensure that we don't
572 mix-and-match interface files between compiler versions.
573 Leaving it as zero in an <literal>hi-boot</literal> file turns
574 off this check.</para>
576 <para>The number “1” at the beginning of a
577 declaration is the <emphasis>version number</emphasis> of that
578 declaration: for the purposes of <filename>.hi-boot</filename>
579 files these can all be set to 1. All names must be fully
580 qualified with the <emphasis>original</emphasis> module that an
581 object comes from: for example, the reference to
582 <literal>Int</literal> in the interface for <literal>A</literal>
583 comes from <literal>PrelBase</literal>, which is a module
584 internal to GHC's prelude. It's a pain, but that's the way it
587 <para>If you want an <literal>hi-boot</literal> file to export a
588 data type, but you don't want to give its constructors (because
589 the constructors aren't used by the SOURCE-importing module),
590 you can write simply:</para>
593 __interface A 1 0 where
598 <para>(You must write all the type parameters, but leave out the
599 '=' and everything that follows it.)</para>
601 <para><emphasis>Note:</emphasis> This is all a temporary
602 solution, a version of the compiler that handles mutually
603 recursive modules properly without the manual construction of
604 interface files, is (allegedly) in the works.</para>
609 ;;; Local Variables: ***
611 ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***