<sect1 id="separate-compilation">
<title>Filenames and separate compilation</title>
-
+
<indexterm><primary>separate compilation</primary></indexterm>
<indexterm><primary>recompilation checker</primary></indexterm>
<indexterm><primary>make and recompilation</primary></indexterm>
-
+
<para>This section describes what files GHC expects to find, what
files it creates, where these files are stored, and what options
affect this behaviour.</para>
<para>Note that this section is written with
<firstterm>hierarchical modules</firstterm> in mind (see <xref
- linkend="hierarchical-modules">); hierarchical modules are an
+ linkend="hierarchical-modules"/>); hierarchical modules are an
extension to Haskell 98 which extends the lexical syntax of
module names to include a dot ‘.’. Non-hierarchical
modules are thus a special case in which none of the module names
<sect2 id="source-files">
<title>Haskell source files</title>
-
+
<para>Each Haskell source module should be placed in a file on
its own.</para>
should be placed in the file <literal>A/B/C.hs</literal>,
relative to some base directory. GHC's behaviour if this rule
is not followed is fully defined by the following section (<xref
- linkend="output-files">).</para>
+ linkend="output-files"/>).</para>
</sect2>
<sect2 id="output-files">
<indexterm><primary><literal>.hi</literal> files</primary></indexterm>
<indexterm><primary>object files</primary></indexterm>
<indexterm><primary><literal>.o</literal> files</primary></indexterm>
-
+
<para>When asked to compile a source file, GHC normally
generates two files: an <firstterm>object file</firstterm>, and
an <firstterm>interface file</firstterm>. </para>
types of exported functions, definitions of data types, and so
on. It is stored in a binary format, so don't try to read one;
use the <option>--show-iface</option> option instead (see <xref
- linkend="hi-options">).</para>
+ linkend="hi-options"/>).</para>
<para>You should think of the object file and the interface file as a
pair, since the interface file is in a sense a compiler-readable
<para>Every module has a <emphasis>module name</emphasis>
defined in its source code (<literal>module A.B.C where
- ...</literal>). Unless overridden with the
- <literal>-o</literal> and <literal>-ohi</literal> flags
- respectively, GHC always puts the object file for module
- <literal>A.B.C</literal> in
- <replaceable>odir</replaceable><literal>/A/B/C.</literal><replaceable>osuf</replaceable>,
- and the interface file in the file
- <replaceable>hidir</replaceable><literal>/A/B/C.</literal><replaceable>hisuf</replaceable>,
- where <replaceable>hidir</replaceable>,
- <replaceable>hisuf</replaceable>,
- <replaceable>odir</replaceable>, and
- <replaceable>osuf</replaceable>, defined as follows:
+ ...</literal>).</para>
- <variablelist>
- <varlistentry>
- <term><replaceable>hidir</replaceable></term>
- <listitem>
- <para>is the value of the <option>-hidir</option> option if
- one was given (<xref linkend="options-output">), or
- <replaceable>root-path</replaceable> otherwise.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><replaceable>hisuf</replaceable></term>
- <listitem>
- <para>is the value of the <option>-hisuf</option> option if
- one was given (<xref linkend="options-output">), or <literal>hi</literal>
- otherwise.</para>
- </listitem>
- </varlistentry>
+ <para>The name of the object file generated by GHC is derived
+ according to the following rules, where
+ <replaceable>osuf</replaceable> is the object-file suffix (this
+ can be changed with the <option>-osuf</option> option).</para>
- <varlistentry>
- <term><replaceable>odir</replaceable></term>
- <listitem>
- <para>is the value of the <option>-odir</option> option if
- one was given (<xref linkend="options-output">), or
- <replaceable>root-path</replaceable> otherwise.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><replaceable>osuf</replaceable></term>
- <listitem>
- <para>is the value of the <option>-osuf</option> option if
- one was given (<xref linkend="options-output">), or <literal>o</literal>
- otherwise (<literal>obj</literal> on Windows).</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- The <replaceable>root-path</replaceable>, used in the above definitions, is derived from the
- location of the source file, <replaceable>source-filename</replaceable>, as follows:
-
- <variablelist>
- <varlistentry>
- <term>Rule 1</term>
- <listitem>
- <para>GHC matches <replaceable>source-filename</replaceable> against the pattern:
-
- <screen><replaceable>root-path</replaceable>/<literal>A/B/C.</literal><replaceable>extension</replaceable></screen>
-
- where:
+ <itemizedlist>
+ <listitem>
+ <para>If there is no <option>-odir</option> option (the
+ default), then the object filename is derived from the
+ source filename (ignoring the module name) by replacing the
+ suffix with <replaceable>osuf</replaceable>.</para>
+ </listitem>
+ <listitem>
+ <para>If
+ <option>-odir</option> <replaceable>dir</replaceable>
+ has been specified, then the object filename is
+ <replaceable>dir</replaceable>/<replaceable>mod</replaceable>.<replaceable>osuf</replaceable>,
+ where <replaceable>mod</replaceable> is the module name with
+ dots replaced by slashes.</para>
+ </listitem>
+ </itemizedlist>
- <variablelist>
- <varlistentry>
- <term><replaceable>extension</replaceable></term>
- <listitem>
- <para>is the source file extension (usually
- <literal>.hs</literal> or <literal>.lhs</literal>).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><replaceable>root-path</replaceable></term>
- <listitem>
- <para>is what is left after <literal>A/B/C.</literal><replaceable>extension</replaceable>
- has been stripped off the end of <replaceable>source-file</replaceable>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Rule 2</term>
- <listitem>
- <para>If <replaceable>source-filename</replaceable> does not match the pattern
- above (presumably because it doesn't finish with <literal>A/B/C.hs</literal>
- or <literal>A/B/C.lhs</literal>)
- then <replaceable>root-path</replaceable> becomes the
- whole of the directory portion of the filename. </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>The name of the interface file is derived using the same
+ rules, except that the suffix is
+ <replaceable>hisuf</replaceable> (<literal>.hi</literal> by
+ default) instead of <replaceable>osuf</replaceable>, and the
+ relevant options are <option>-hidir</option> and
+ <option>-hisuf</option> instead of <option>-odir</option> and
+ <option>-osuf</option> respectively.</para>
- For example, if GHC compiles the module
+ <para>For example, if GHC compiles the module
<literal>A.B.C</literal> in the file
- <filename>src/A/B/C.hs</filename>, with no <literal>-odir</literal> or <literal>-hidir</literal> flags,
- the interface file will be put in <literal>src/A/B/C.hi</literal> and the object file in
- <literal>src/A/B/C.o</literal> (using Rule 1).
- If the same module <literal>A.B.C</literal> was in file
- <filename>src/ABC.hs</filename>,
- the interface file will still be put in <literal>src/A/B/C.hi</literal> and the object file in
- <literal>src/A/B/C.o</literal> (using Rule 2).
- </para>
- <para>A common use for Rule 2 is to have many modules all called <literal>Main</literal> held in
- files <literal>Test1.hs</literal> <literal>Test2.hs</literal>, etc. Beware, though: when compiling
- (say) <literal>Test2.hs</literal>, GHC will consult <literal>Main.hi</literal> for version information
- from the last recompilation. Currently (a bug, really) GHC is not clever enough to spot that the source file has changed,
- and so there is a danger that the recompilation checker will declare that no recompilation is needed when in fact it is.
- Solution: delete the interface file first.
- </para>
- <para>Notice that (unless overriden with <option>-o</option> or <option>-ohi</option>) the filenames
- of the object and interface files are always based on the module name. The reason for this is so that
- GHC can find the interface file for module <literal>A.B.C</literal> when compiling the declaration
- "<literal>import A.B.C</literal>".
- </para>
+ <filename>src/A/B/C.hs</filename>, with no
+ <literal>-odir</literal> or <literal>-hidir</literal> flags, the
+ interface file will be put in <literal>src/A/B/C.hi</literal>
+ and the object file in <literal>src/A/B/C.o</literal>.</para>
+
+ <para>For any module that is imported, GHC requires that the
+ name of the module in the import statement exactly matches the
+ name of the module in the interface file (or source file) found
+ using the strategy specified in <xref linkend="search-path"/>.
+ This means that for most modules, the source file name should
+ match the module name.</para>
+
+ <para>However, note that it is reasonable to have a module
+ <literal>Main</literal> in a file named
+ <filename>foo.hs</filename>, but this only works because GHC
+ never needs to search for the interface for module
+ <literal>Main</literal> (because it is never imported). It is
+ therefore possible to have several <literal>Main</literal>
+ modules in separate source files in the same directory, and GHC
+ will not get confused.</para>
+
+ <para>In batch compilation mode, the name of the object file can
+ also be overriden using the <option>-o</option> option, and the
+ name of the interface file can be specified directly using the
+ <option>-ohi</option> option.</para>
</sect2>
<sect2 id="search-path">
<para>This isn't the whole story: GHC also looks for modules in
pre-compiled libraries, known as packages. See the section on
- packages (<xref linkend="packages">), for details.</para>
+ packages (<xref linkend="packages"/>), for details.</para>
</sect2>
<sect2 id="options-output">
<para>Redirects object files to directory
<replaceable>dir</replaceable>. For example:</para>
-<Screen>
+<screen>
$ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
-</Screen>
+</screen>
<para>The object files, <filename>Foo.o</filename>,
<filename>Bar.o</filename>, and
example.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><option>-hidir</option> <replaceable>dir</replaceable></term>
<indexterm><primary><option>-hidir</option></primary>
<indexterm><primary><option>-hisuf</option></primary></indexterm>
<indexterm><primary><option>-hcsuf</option></primary></indexterm>
<listitem>
- <para>EXOTICA: The <option>-osuf</option>
+ <para>The <option>-osuf</option>
<replaceable>suffix</replaceable> will change the
<literal>.o</literal> file suffix for object files to
whatever you specify. We use this when compiling
<para>Similarly, the <option>-hisuf</option>
<replaceable>suffix</replaceable> will change the
<literal>.hi</literal> file suffix for non-system
- interface files (see <XRef LinkEnd="hi-options">).</para>
+ interface files (see <xref linkend="hi-options"/>).</para>
<para>Finally, the option <option>-hcsuf</option>
<replaceable>suffix</replaceable> will change the
game is particularly useful if you want to compile a
program both with and without profiling, in the same
directory. You can say:
- <Screen>
- ghc ...</Screen>
+ <screen>
+ ghc ...</screen>
to get the ordinary version, and
- <Screen>
- ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</Screen>
+ <screen>
+ ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</screen>
to get the profiled version.</para>
</listitem>
</varlistentry>
<para>Instructs the GHC driver not to delete any of its
temporary files, which it normally keeps in
<literal>/tmp</literal> (or possibly elsewhere; see <xref
- linkend="temp-files">). Running GHC with
+ linkend="temp-files"/>). Running GHC with
<option>-v</option> will show you what temporary files
were generated along the way.</para>
</listitem>
in <filename>/tmp</filename> (or wherever your
installation thinks temporary files should go), you may
use the <option>-tmpdir
- <dir></option><IndexTerm><Primary>-tmpdir
- <dir> option</Primary></IndexTerm> option to specify
+ <dir></option><indexterm><primary>-tmpdir
+ <dir> option</primary></indexterm> option to specify
an alternate directory. For example, <option>-tmpdir
.</option> says to put temporary files in the current
working directory.</para>
- <para>Alternatively, use your <Constant>TMPDIR</Constant>
- environment variable.<IndexTerm><Primary>TMPDIR
- environment variable</Primary></IndexTerm> Set it to the
+ <para>Alternatively, use your <constant>TMPDIR</constant>
+ environment variable.<indexterm><primary>TMPDIR
+ environment variable</primary></indexterm> Set it to the
name of the directory where temporary files should be put.
GCC and other programs will honour the
- <Constant>TMPDIR</Constant> variable as well.</para>
+ <constant>TMPDIR</constant> variable as well.</para>
<para>Even better idea: Set the
- <Constant>DEFAULT_TMPDIR</Constant> make variable when
+ <constant>DEFAULT_TMPDIR</constant> make variable when
building GHC, and never worry about
- <Constant>TMPDIR</Constant> again. (see the build
+ <constant>TMPDIR</constant> again. (see the build
documentation).</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
- <Sect2 id="hi-options">
+ <sect2 id="hi-options">
<title>Other options related to interface files</title>
<indexterm><primary>interface files, options</primary></indexterm>
</listitem>
</varlistentry>
</variablelist>
-
+
<para>In the olden days, GHC compared the newly-generated
<filename>.hi</filename> file with the previous version; if they
were identical, it left the old one alone and didn't change its
required”. What a beautiful sight!</para>
<para>Patrick Sansom had a workshop paper about how all this is
- done (though the details have changed quite a bit). <ULink
- URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a
+ done (though the details have changed quite a bit). <ulink
+ URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ulink> if you want a
copy.</para>
</sect2>
<filename>Makefile</filename> to use with GHC, assuming you name
your source files the same as your modules. Thus:</para>
-<ProgramListing>
+<programlisting>
HC = ghc
HC_OPTS = -cpp $(EXTRA_HC_OPTS)
# Inter-module dependencies
Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
-</ProgramListing>
+</programlisting>
<para>(Sophisticated <command>make</command> variants may
achieve some of the above more elegantly. Notably,
<command>gmake</command>'s pattern rules let you write the more
comprehensible:</para>
-<ProgramListing>
+<programlisting>
%.o : %.lhs
$(HC) -c $< $(HC_OPTS)
-</ProgramListing>
+</programlisting>
<para>What we've shown should work with any
<command>make</command>.)</para>
<para>Note the inter-module dependencies at the end of the
Makefile, which take the form</para>
-<ProgramListing>
+<programlisting>
Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-</ProgramListing>
+</programlisting>
<para>They tell <command>make</command> that if any of
<literal>Foo.o</literal>, <literal>Foo.hc</literal> or
automatically generating the required dependencies. Add the
following to your <filename>Makefile</filename>:</para>
-<ProgramListing>
+<programlisting>
depend :
ghc -M $(HC_OPTS) $(SRCS)
-</ProgramListing>
+</programlisting>
<para>Now, before you start compiling, and any time you change
the <literal>imports</literal> in your program, do
A.o : B.hi-boot
</programlisting>
- (See <xref linkend="mutual-recursion"> for details of
+ (See <xref linkend="mutual-recursion"/> for details of
<literal>hi-boot</literal> style interface files.) If
<literal>A</literal> imports multiple modules, then there will
be multiple lines with <filename>A.o</filename> as the
<screen>
ghc -M -optdep-f -optdep.depend ...
</screen>
-
+
The options which affect dependency generation are:</para>
-
+
<variablelist>
<varlistentry>
<term><option>-w</option></term>
<para>Turn off warnings about interface file shadowing.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><option>-f</option> <replaceable>file</replaceable></term>
<listitem>
</listitem>
</varlistentry>
+<!-- Retired with the move away from 'mkdependHS'.
<varlistentry>
<term><option>-o <osuf></option></term>
<listitem>
and <filename>.o</filename> files.</para>
</listitem>
</varlistentry>
-
+-->
<varlistentry>
<term><option>-s <suf></option></term>
<listitem>
<para>Currently, the compiler does not have proper support for
dealing with mutually recursive modules:</para>
-<ProgramListing>
+<programlisting>
module A where
import B
g :: TA -> TB
g (MkTA x) = MkTB x
-</ProgramListing>
+</programlisting>
<para>When compiling either module A and B, the compiler will
try (in vain) to look for the interface file of the other. So,
files</primary></indexterm> <indexterm><primary>importing,
<literal>hi-boot</literal> files</primary></indexterm></para>
-<ProgramListing>
+<programlisting>
import {-# SOURCE #-} A
-</ProgramListing>
+</programlisting>
<para>The hand-written interface need only contain the bare
minimum of information needed to get the bootstrapping process
<para>For the example at hand, the boot interface file for A
would look like the following:</para>
-<ProgramListing>
+<programlisting>
module A where
newtype TA = MkTA GHC.Base.Int
-</ProgramListing>
+</programlisting>
<para>The syntax is similar to a normal Haskell source file, but
with some important differences:</para>
<literal>instances</literal> or derive them automatically.
</para>
</listitem>
+
+<listitem> <para>For <literal>data</literal> or <literal>newtype</literal> declaration, you may omit all
+the constructors, by omitting the '=' and everything that follows it:
+<programlisting>
+module A where
+ data TA
+</programlisting>
+ In a <emphasis>source</emphasis> program
+ this would declare TA to have no constructors (a GHC extension: see <xref linkend="nullary-types"/>),
+ but in an hi-boot file it means "I don't know or care what the construtors are".
+ This is the most common form of data type declaration, because it's easy to get right.</para>
+ <para>
+ You <emphasis>can</emphasis> also write out the constructors but, if you do so, you must write
+ it out precisely as in its real definition.
+ It is especially delicate if you use a strictness annotation "!",
+ with or without an <literal>{-# UNPACK #-}</literal> pragma. In a source file
+ GHC may or may not choose to unbox the argument, but in an hi-boot file it's
+ assumed that you express the <emphasis>outcome</emphasis> of this decision.
+ (So in the cases where GHC decided not to unpack, you must not use the pragma.)
+ Tread with care.</para>
+ <para>
+ Regardless of whether you write the constructors, you must write all the type parameters,
+ <emphasis>including their kinds</emphasis>
+ if they are not '*'. (You can give explicit kinds in source files too (<xref linkend="sec-kinding"/>),
+ but you <emphasis>must</emphasis> do so in hi-boot files.)</para>
+ </listitem>
+
+<listitem> <para>For <literal>class</literal> declaration, you may not specify any class
+operations. We could lift this restriction if it became tiresome.</para>
+</listitem>
</itemizedlist>
<para>Notice that we only put the declaration for the newtype
<literal>TA</literal> in the <literal>hi-boot</literal> file,
- not the signature for <Function>f</Function>, since
- <Function>f</Function> isn't used by <literal>B</literal>.</para>
-
- <para>If you want an <literal>hi-boot</literal> file to export a
- data type, but you don't want to give its constructors (because
- the constructors aren't used by the SOURCE-importing module),
- you can write simply:</para>
-
-<ProgramListing>
-module A where
-data TA
-</ProgramListing>
+ not the signature for <function>f</function>, since
+ <function>f</function> isn't used by <literal>B</literal>.</para>
- <para>(You must write all the type parameters, but leave out the
- '=' and everything that follows it.)</para>
</sect2>
<para>In particular, if an instance declaration is in the same module as the definition
of any type or class mentioned in the head of the instance declaration, then
GHC has to visit that interface file anyway. Example:</para>
-<ProgramListing>
+<programlisting>
module A where
instance C a => D (T a) where ...
data T a = ...
-</ProgramListing>
+</programlisting>
<para> The instance declaration is only relevant if the type T is in use, and if
so, GHC will have visited A's interface file to find T's definition. </para>
<para> The only problem comes when a module contains an instance declaration
and GHC has no other reason for visiting the module. Example:
-<ProgramListing>
+<programlisting>
module Orphan where
instance C a => D (T a) where ...
class C a where ...
-</ProgramListing>
+</programlisting>
Here, neither D nor T is declared in module Orphan.
We call such modules ``orphan modules'',
defined thus:</para>
<itemizedlist>
- <listitem> <para> An <emphasis>orphan module</emphasis>
+ <listitem> <para> An <emphasis>orphan module</emphasis>
<indexterm><primary>orphan module</primary></indexterm>
- contains at least one <emphasis>orphan instance</emphasis> or at
+ contains at least one <emphasis>orphan instance</emphasis> or at
least one <emphasis>orphan rule</emphasis>.</para> </listitem>
<listitem><para> An instance declaration in a module M is an <emphasis>orphan instance</emphasis> if
<indexterm><primary>orphan instance</primary></indexterm>
none of the type constructors
or classes mentioned in the instance head (the part after the ``<literal>=></literal>'') are declared
- in M.</para>
+ in M.</para>
- <para> Only the instance head counts. In the example above, it is not good enough for C's declaration
+ <para> Only the instance head counts. In the example above, it is not good enough for C's declaration
to be in module A; it must be the declaration of D or T.</para>
</listitem>
projects / ghc-hetmet.git / blobdiff