<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>
<sect2 id="source-files">
<title>Haskell source files</title>
-
+
<para>Each Haskell source module should be placed in a file on
its own.</para>
<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>
<listitem>
<para>If there is no <option>-odir</option> option (the
default), then the object filename is derived from the
- source filename by replacing the suffix with
- <replaceable>osuf</replaceable>.</para>
+ source filename (ignoring the module name) by replacing the
+ suffix with <replaceable>osuf</replaceable>.</para>
</listitem>
<listitem>
<para>If
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>Note that it is reasonable to have a module
+ <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. For modules other than
- <literal>Main</literal>, it is strongly recommended that you
- name the source file after the module name, replacing dots with
- slashes in hierarchical module names.</para>
+ 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
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
</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
<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>
</listitem>
<listitem> <para>For <literal>data</literal> or <literal>newtype</literal> declaration, you may omit all
-the constructors, thus:
+the constructors, by omitting the '=' and everything that follows it:
<ProgramListing>
module A where
data TA
</ProgramListing>
- (You must write all the type parameters, but omit the
- '=' and everything that follows it.) In a <emphasis>source</emphasis> program
+ 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 "!",
+ 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.
+ 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
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