ghc/docs/users_guide/recomp.lit

   1 %************************************************************************
   2 %*                                                                      *
   3 \section[separate-compilation]{Separate compilation}
   4 \index{separate compilation}
   5 \index{recompilation checker}
   6 \index{make and recompilation}
   7 %*                                                                      *
   8 %************************************************************************
   9
  10 This section describes how GHC supports separate compilation.
  11
  12 \subsection[hi-files]{Interface files}
  13
  14 When GHC compiles a source module @A@, it generates an object @A.o@, {\em and} a
  15 companion {\em interface file} @A.hi@.   The interface file
  16 contains information needed by the compiler when it compiles any module @B@ that
  17 imports @A@, whether directly or indirectly.  When compiling @B@, GHC will
  18 read @A.hi@ to find the details that it needs to know about things defined in @A@.
  19
  20 Furthermore, when compiling module @C@ which imports @B@, GHC may decide that it
  21 needs to know something about @A@ --- for example, @B@ might export a function
  22 that involves a type defined in @A@.  In this case, GHC will go and read @A.hi@ even
  23 though @C@ does not explicitly import @A@ at all.
  24
  25 The interface file may contain all sorts of things that aren't explicitly
  26 exported from @A@ by the programmer.  For example, even though a data type is exported
  27 abstractly, @A.hi@ will contain the full data type definition.  For small function
  28 definitions, @A.hi@ will contain the complete definition of the function.  For
  29 bigger functions, @A.hi@ will contain strictness information about the function.  And so on.
  30 GHC puts much more information into @.hi@ files when you use @-O@.  Without @-O@
  31 it puts in just the minimum; with @-O@ it lobs in a whole pile of stuff.
  32
  33 @A.hi@ should really be thought of as a compiler-readable version of @A.o@.
  34 If you use a @.hi@ file that wasn't generated by the same compilation run that
  35 generates the @.o@ file the compiler may assume all sorts of incorrect things about @A@,
  36 resulting in core dumps and other unpleasant happenings.
  37
  38 In the olden days, GHC compared the newly-generated @.hi@ file with the previous version;
  39 if they were identical, it left the old one alone and didn't change its modification date.
  40 In consequence, importers of a module with an unchanged output @.hi@ file were not recompiled.
  41
  42 This doesn't work any more.  In our earlier example, module @C@ does
  43 not import module @A@ directly, yet changes to @A.hi@ should force a
  44 recompilation of @C@.  And some changes to @A@ (changing the
  45 definition of a function that appears in an inlining of a function
  46 exported by @B@, say) may conceivably not change @B.hi@ one jot.  So
  47 now
  48
  49
  50 \subsection[recomp]{The recompilation checker}
  51
  52 GHC keeps a version number on each interface file, and on each type
  53 signature within the interface file.  It also keeps in every interface
  54 file a list of the version numbers of everything it used when it last
  55 compiled the file.  If the source file's modification date is earlier
  56 than the @.o@ file's date (i.e. the source hasn't changed since the
  57 file was last compiled), and you give GHC the @-recomp@ flag, then GHC
  58 will be clever.  It compares the version numbers on the things it
  59 needs this time with the version numbers on the things it needed last
  60 time (gleaned from the interface file of the module being compiled);
  61 if they are all the same it stops compiling rather early in the
  62 process saying ``Recompilation not required''.  What a beautiful
  63 sight!
  64
  65 It's still an experimental feature (that's why @-recomp@ is off by
  66 default), so tell us if you think it doesn't work.
  67
  68 Patrick Sansom has a workshop paper about how all this is
  69 done.  Ask him (email: \tr{sansom}) if you want a copy.
  70
  71 \subsection{Using @make@}
  72
  73 It is reasonably straightforward to set up a \tr{Makefile} to use with
  74 GHC, assuming you name your source files the same as your modules.
  75 Thus:
  76 \begin{verbatim}
  77 HC      = ghc
  78 HC_OPTS = -cpp $(EXTRA_HC_OPTS)
  79
  80 SRCS = Main.lhs Foo.lhs Bar.lhs
  81 OBJS = Main.o   Foo.o   Bar.o
  82
  83 .SUFFIXES : .o .hi .lhs .hc .s
  84
  85 cool_pgm : $(OBJS)
  86         $(RM) $@
  87         $(HC) -o $@ $(HC_OPTS) $(OBJS)
  88
  89 # Standard suffix rules
  90 .o.hi:
  91         @:
  92
  93 .lhs.o:
  94         $(RM) $@
  95         $(HC) -c $< $(HC_OPTS)
  96
  97 .hs.o:
  98         $(RM) $@
  99         $(HC) -c $< $(HC_OPTS)
 100
 101 # Optional
 102 .hc.o:
 103         $(RM) $@
 104         $(HC) -c $< $(HC_OPTS)
 105
 106 # Optional
 107 .s.o:
 108         $(RM) $@
 109         $(HC) -c $< $(HC_OPTS)
 110
 111
 112 # Inter-module dependencies
 113 Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
 114 Main.o Main.hc Main.s : Foo.hi Baz.hi   # Main imports Foo and Baz
 115 \end{verbatim}
 116
 117 (Sophisticated \tr{make} variants may achieve some of the above more
 118 elegantly.  Notably, @gmake@'s pattern rules let you write the more comprehensible:
 119 \begin{verbatim}
 120 %.o : %.lhs
 121         $(RM) $@
 122         $(HC) -c $< $(HC_OPTS)
 123 \end{verbatim}
 124 What we've shown should work with any \tr{make}.)
 125
 126 Note the cheesy \tr{.o.hi} rule: It records the dependency of the
 127 interface (\tr{.hi}) file on the source.  The rule says a \tr{.hi}
 128 file can be made from a \tr{.o} file by doing... nothing.  Which is
 129 true.
 130
 131 Note the inter-module dependencies at the end of the Makefile, which take the form
 132 \begin{verbatim}
 133 Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
 134 \end{verbatim}
 135 They tell @make@ that if any of @Foo.o@, @Foo.hc@ or @Foo.s@ have
 136 an earlier modification date than @Baz.hi@, then the out-of-date
 137 file must be brought up to date.  To bring it up to date, @make@ looks
 138 for a rule to do so; one of the preceding suffix rules does the job nicely.
 139
 140 Putting inter-dependencies of the form \tr{Foo.o : Bar.hi} into your
 141 \tr{Makefile} by hand is rather error-prone.  Don't worry---never
 142 fear, \tr{mkdependHS} is here! (and is distributed as part of GHC)
 143 Add the following to your \tr{Makefile}:
 144 \begin{verbatim}
 145 depend :
 146         mkdependHS -- $(HC_OPTS) -- $(SRCS)
 147 \end{verbatim}
 148 Now, before you start compiling, and any time you change the
 149 \tr{imports} in your program, do \tr{make depend} before you do
 150 \tr{make cool_pgm}.  \tr{mkdependHS} will append the needed
 151 dependencies to your \tr{Makefile}.  @mkdependHS@ is fully
 152 describe in \Sectionref{mkdependHS}.
 153
 154
 155
 156
 157
 158
 159 A few caveats about this simple scheme: (a)~You may need to compile
 160 some modules explicitly to create their interfaces in the first place
 161 (e.g., \tr{make Bar.o} to create \tr{Bar.hi}).  (b)~You may have to
 162 type \tr{make} more than once for the dependencies to have full
 163 effect.  However, a \tr{make} run that does nothing {\em does} mean
 164 ``everything's up-to-date.''  (c) This scheme will work with
 165 mutually-recursive modules but, again, it may take multiple
 166 iterations to ``settle.''
 167
 168
 169