<sect1 id="separate-compilation">
- <title>Separate compilation</title>
-
+ <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 how GHC supports separate
- compilation.</para>
- <sect2 id="hi-files">
- <title>Interface files</title>
-
+ <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
+ 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
+ contain dots.</para>
+
+ <para>Pathname conventions vary from system to system. In
+ particular, the directory separator is
+ ‘<literal>/</literal>’ on Unix systems and
+ ‘<literal>\</literal>’ on Windows systems. In the
+ sections that follow, we shall consistently use
+ ‘<literal>/</literal>’ as the directory separator;
+ substitute this for the appropriate character for your
+ system.</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>
+
+ <para>The file should usually be named after the module name, by
+ replacing dots in the module name by directory separators. For
+ example, on a Unix system, the module <literal>A.B.C</literal>
+ 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>
+ </sect2>
+
+ <sect2 id="output-files">
+ <title>Output files</title>
+
<indexterm><primary>interface files</primary></indexterm>
<indexterm><primary><literal>.hi</literal> files</primary></indexterm>
-
- <para>When GHC compiles a source file <filename>A.hs</filename>
- which contains a module <literal>A</literal>, say, it generates
- an object <filename>A.o</filename>, <emphasis>and</emphasis> a
- companion <emphasis>interface file</emphasis>
- <filename>A.hi</filename>. The interface file is merely there
- to help the compiler compile other modules in the same program.
- Interfaces are in a binary format, so don't try to look at one;
- however you <emphasis>can</emphasis> see the contents of an
- interface file by using GHC with the
- <option>--show-iface</option> option (see <xref
- linkend="hi-options">, below).</para>
-
- <para>NOTE: In general, the name of a file containing module
- <literal>M</literal> should be named <filename>M.hs</filename>
- or <literal>M.lhs</literal>. The only exception to this rule is
- module <literal>Main</literal>, which can be placed in any
- file.<indexterm><primary>filenames</primary><secondary>for
- modules</secondary> </indexterm></para>
-
- <para>The interface file for <literal>A</literal> contains
- information needed by the compiler when it compiles any module
- <literal>B</literal> that imports <literal>A</literal>, whether
- directly or indirectly. When compiling <literal>B</literal>,
- GHC will read <filename>A.hi</filename> to find the details that
- it needs to know about things defined in
- <literal>A</literal>.</para>
-
- <para>The interface file may contain all sorts of things that
- aren't explicitly exported from <literal>A</literal> by the
- programmer. For example, even though a data type is exported
- abstractly, <filename>A.hi</filename> will contain the full data
- type definition. For small function definitions,
- <filename>A.hi</filename> will contain the complete definition
- of the function. For bigger functions,
- <filename>A.hi</filename> will contain strictness information
- about the function. And so on. GHC puts much more information
- into <filename>.hi</filename> files when optimisation is turned
- on with the <option>-O</option> flag (see <xref
- linkend="options-optimise">). Without <option>-O</option> it
- puts in just the minimum; with <option>-O</option> it lobs in a
- whole pile of stuff. <indexterm><primary>optimsation, effect on
- .hi files</primary></indexterm></para>
-
- <para><filename>A.hi</filename> should really be thought of as a
- compiler-readable version of <filename>A.o</filename>. If you
- use a <filename>.hi</filename> file that wasn't generated by the
- same compilation run that generates the <filename>.o</filename>
- file the compiler may assume all sorts of incorrect things about
- <literal>A</literal>, resulting in core dumps and other
- unpleasant happenings.</para>
+ <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>
+
+ <para>The object file, which normally ends in a
+ <literal>.o</literal> suffix (or <literal>.obj</literal> if
+ you're on Windows), contains the compiled code for the module.</para>
+
+ <para>The interface file,
+ which normally ends in a <literal>.hi</literal> suffix, contains
+ the information that GHC needs in order to compile further
+ modules that depend on this module. It contains things like the
+ 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>
+
+ <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
+ description of the contents of the object file. If the
+ interface file and object file get out of sync for any reason,
+ then the compiler may end up making assumptions about the object
+ file that aren't true; trouble will almost certainly follow.
+ For this reason, we recommend keeping object files and interface
+ files in the same place (GHC does this by default, but it is
+ possible to override the defaults as we'll explain
+ shortly).</para>
+
+ <para>Every module has a <emphasis>module name</emphasis>
+ defined in its source code (<literal>module A.B.C where
+ ...</literal>).</para>
+
+ <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>
+ <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>
+
+ <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>
+
+ <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>.</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="options-finding-imports">
- <title>Finding interface files</title>
+ <sect2 id="search-path">
+ <title>The search path</title>
+ <indexterm><primary>search path</primary>
+ </indexterm>
<indexterm><primary>interface files, finding them</primary></indexterm>
<indexterm><primary>finding interface files</primary></indexterm>
<para>In your program, you import a module
<literal>Foo</literal> by saying <literal>import Foo</literal>.
- GHC goes looking for an interface file,
- <filename>Foo.hi</filename>. It has a builtin list of
- directories (notably including <filename>.</filename>) where it
- looks.</para>
+ In <option>--make</option> mode or GHCi, GHC will look for a
+ source file for <literal>Foo</literal> and arrange to compile it
+ first. Without <option>--make</option>, GHC will look for the
+ interface file for <literal>Foo</literal>, which should have
+ been created by an earlier compilation of
+ <literal>Foo</literal>. GHC uses the same strategy in each of
+ these cases for finding the appropriate file.</para>
+
+ <para>This strategy is as follows: GHC keeps a list of
+ directories called the <firstterm>search path</firstterm>. For
+ each of these directories, it tries appending
+ <replaceable>basename</replaceable><literal>.</literal><replaceable>extension</replaceable>
+ to the directory, and checks whether the file exists. The value
+ of <replaceable>basename</replaceable> is the module name with
+ dots replaced by the directory separator ('/' or '\', depending
+ on the system), and <replaceable>extension</replaceable> is a
+ source extension (<literal>hs</literal>, <literal>lhs</literal>)
+ if we are in <option>--make</option> mode and GHCi, or
+ <replaceable>hisuf</replaceable> otherwise.</para>
+
+ <para>For example, suppose the search path contains directories
+ <literal>d1</literal>, <literal>d2</literal>, and
+ <literal>d3</literal>, and we are in <literal>--make</literal>
+ mode looking for the source file for a module
+ <literal>A.B.C</literal>. GHC will look in
+ <literal>d1/A/B/C.hs</literal>, <literal>d1/A/B/C.lhs</literal>,
+ <literal>d2/A/B/C.hs</literal>, and so on.</para>
+
+ <para>The search path by default contains a single directory:
+ <quote>.</quote> (i.e. the current directory). The following
+ options can be used to add to or change the contents of the
+ search path:</para>
<variablelist>
-
<varlistentry>
- <term><option>-i<dirs></option></term>
+ <term><option>-i<replaceable>dirs</replaceable></option></term>
<listitem>
- <para><indexterm><primary><option>-i<dirs></option>
+ <para><indexterm><primary><option>-i<replaceable>dirs</replaceable></option>
</primary></indexterm>This flag appends a colon-separated
- list of <filename>dirs</filename> to the “import
- directories” list, which initially contains a single
- entry: <quote>.</quote>.</para>
-
- <para>This list is scanned before any package directories
- (see <xref linkend="packages">) when looking for imports,
- but note that if you have a home module with the same name
- as a package module then this is likely to cause trouble
- in other ways, with link errors being the least nasty
- thing that can go wrong...</para>
-
- <para>See also <XRef LinkEnd="recomp"> for the
- significance of using relative and absolute pathnames in
- the <option>-i</option> list.</para>
+ list of <filename>dirs</filename> to the search path.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option></term>
<listitem>
- <para>resets the “import directories” list
- back to nothing.</para>
+ <para>resets the search path back to nothing.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <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>
+ </sect2>
+
+ <sect2 id="options-output">
+ <title>Redirecting the compilation output(s)</title>
+
+ <indexterm><primary>output-directing options</primary></indexterm>
+ <indexterm><primary>redirecting compilation output</primary></indexterm>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-o</option> <replaceable>file</replaceable></term>
+ <indexterm><primary><option>-o</option></primary></indexterm>
+ <listitem>
+ <para>GHC's compiled output normally goes into a
+ <filename>.hc</filename>, <filename>.o</filename>, etc.,
+ file, depending on the last-run compilation phase. The
+ option <option>-o <replaceable>file</replaceable></option>
+ re-directs the output of that last-run phase to
+ <replaceable>file</replaceable>.</para>
+
+ <para>Note: this “feature” can be
+ counterintuitive: <command>ghc -C -o foo.o
+ foo.hs</command> will put the intermediate C code in the
+ file <filename>foo.o</filename>, name
+ notwithstanding!</para>
+
+ <para>This option is most often used when creating an
+ executable file, to set the filename of the executable.
+ For example:
+<screen> ghc -o prog --make Main</screen>
+
+ will compile the program starting with module
+ <literal>Main</literal> and put the executable in the
+ file <literal>prog</literal>.</para>
+
+ <para>Note: on Windows, if the result is an executable
+ file, the extension "<filename>.exe</filename>" is added
+ if the specified filename does not already have an
+ extension. Thus
+<programlisting>
+ ghc -o foo Main.hs
+</programlisting>
+ will compile and link the module
+ <filename>Main.hs</filename>, and put the resulting
+ executable in <filename>foo.exe</filename> (not
+ <filename>foo</filename>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-odir</option> <replaceable>dir</replaceable></term>
+ <indexterm><primary><option>-odir</option></primary></indexterm>
+ <listitem>
+ <para>Redirects object files to directory
+ <replaceable>dir</replaceable>. For example:</para>
+
+<Screen>
+$ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
+</Screen>
+
+ <para>The object files, <filename>Foo.o</filename>,
+ <filename>Bar.o</filename>, and
+ <filename>Bumble.o</filename> would be put into a
+ subdirectory named after the architecture of the executing
+ machine (<filename>x86</filename>,
+ <filename>mips</filename>, etc).</para>
+
+ <para>Note that the <option>-odir</option> option does
+ <emphasis>not</emphasis> affect where the interface files
+ are put; use the <option>-hidir</option> option for that.
+ In the above example, they would still be put in
+ <filename>parse/Foo.hi</filename>,
+ <filename>parse/Bar.hi</filename>, and
+ <filename>gurgle/Bumble.hi</filename>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ohi</option> <replaceable>file</replaceable></term>
+ <indexterm><primary><option>-ohi</option></primary>
+ </indexterm>
+ <listitem>
+ <para>The interface output may be directed to another file
+ <filename>bar2/Wurble.iface</filename> with the option
+ <option>-ohi bar2/Wurble.iface</option> (not
+ recommended).</para>
+
+ <para>WARNING: if you redirect the interface file
+ somewhere that GHC can't find it, then the recompilation
+ checker may get confused (at the least, you won't get any
+ recompilation avoidance). We recommend using a
+ combination of <option>-hidir</option> and
+ <option>-hisuf</option> options instead, if
+ possible.</para>
+
+ <para>To avoid generating an interface at all, you could
+ use this option to redirect the interface into the bit
+ bucket: <literal>-ohi /dev/null</literal>, for
+ example.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-hidir</option> <replaceable>dir</replaceable></term>
+ <indexterm><primary><option>-hidir</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Redirects all generated interface files into
+ <replaceable>dir</replaceable>, instead of the
+ default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-osuf</option> <replaceable>suffix</replaceable></term>
+ <term><option>-hisuf</option> <replaceable>suffix</replaceable></term>
+ <term><option>-hcsuf</option> <replaceable>suffix</replaceable></term>
+ <indexterm><primary><option>-osuf</option></primary></indexterm>
+ <indexterm><primary><option>-hisuf</option></primary></indexterm>
+ <indexterm><primary><option>-hcsuf</option></primary></indexterm>
+ <listitem>
+ <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
+ libraries, so that objects for the profiling versions of
+ the libraries don't clobber the normal ones.</para>
+
+ <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>
+
+ <para>Finally, the option <option>-hcsuf</option>
+ <replaceable>suffix</replaceable> will change the
+ <literal>.hc</literal> file suffix for compiler-generated
+ intermediate C files.</para>
+
+ <para>The <option>-hisuf</option>/<option>-osuf</option>
+ 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>
+ to get the ordinary version, and
+ <Screen>
+ ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</Screen>
+ to get the profiled version.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="keeping-intermediates">
+ <title>Keeping Intermediate Files</title>
+ <indexterm><primary>intermediate files, saving</primary>
+ </indexterm>
+ <indexterm><primary><literal>.hc</literal> files, saving</primary>
+ </indexterm>
+ <indexterm><primary><literal>.s</literal> files, saving</primary>
+ </indexterm>
+
+ <para>The following options are useful for keeping certain
+ intermediate files around, when normally GHC would throw these
+ away after compilation:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-keep-hc-files</option></term>
+ <indexterm>
+ <primary><option>-keep-hc-files</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Keep intermediate <literal>.hc</literal> files when
+ doing <literal>.hs</literal>-to-<literal>.o</literal>
+ compilations via C (NOTE: <literal>.hc</literal> files
+ aren't generated when using the native code generator, you
+ may need to use <option>-fvia-C</option> to force them
+ to be produced).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-keep-s-files</option></term>
+ <indexterm>
+ <primary><option>-keep-s-files</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Keep intermediate <literal>.s</literal> files.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-keep-raw-s-files</option></term>
+ <indexterm>
+ <primary><option>-keep-raw-s-files</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Keep intermediate <literal>.raw-s</literal> files.
+ These are the direct output from the C compiler, before
+ GHC does “assembly mangling” to produce the
+ <literal>.s</literal> file. Again, these are not produced
+ when using the native code generator.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-keep-tmp-files</option></term>
+ <indexterm>
+ <primary><option>-keep-tmp-files</option></primary>
+ </indexterm>
+ <indexterm>
+ <primary>temporary files</primary>
+ <secondary>keeping</secondary>
+ </indexterm>
+ <listitem>
+ <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
+ <option>-v</option> will show you what temporary files
+ were generated along the way.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
+ </sect2>
+
+ <sect2 id="temp-files">
+ <title>Redirecting temporary files</title>
- <para>See also the section on packages (<xref
- linkend="packages">), which describes how to use installed
- libraries.</para>
+ <indexterm>
+ <primary>temporary files</primary>
+ <secondary>redirecting</secondary>
+ </indexterm>
+ <variablelist>
+ <varlistentry>
+ <term><option>-tmpdir</option></term>
+ <indexterm><primary><option>-tmpdir</option></primary></indexterm>
+ <listitem>
+ <para>If you have trouble because of running out of space
+ 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
+ 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
+ name of the directory where temporary files should be put.
+ GCC and other programs will honour the
+ <Constant>TMPDIR</Constant> variable as well.</para>
+
+ <para>Even better idea: Set the
+ <Constant>DEFAULT_TMPDIR</Constant> make variable when
+ building GHC, and never worry about
+ <Constant>TMPDIR</Constant> again. (see the build
+ documentation).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect2>
<Sect2 id="hi-options">
</listitem>
</varlistentry>
</variablelist>
-
</sect2>
<sect2 id="recomp">
</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
<para>This doesn't work any more. Suppose module
<literal>C</literal> imports module <literal>B</literal>, and
<literal>B</literal> imports module <literal>A</literal>. So
- changes to <filename>A.hi</filename> should force a
- recompilation of <literal>C</literal>. And some changes to
- <literal>A</literal> (changing the definition of a function that
- appears in an inlining of a function exported by
+ changes to module <literal>A</literal> might require module
+ <literal>C</literal> to be recompiled, and hence when
+ <filename>A.hi</filename> changes we should check whether
+ <literal>C</literal> should be recompiled. However, the
+ dependencies of <literal>C</literal> will only list
+ <literal>B.hi</literal>, not <literal>A.hi</literal>, and some
+ changes to <literal>A</literal> (changing the definition of a
+ function that appears in an inlining of a function exported by
<literal>B</literal>, say) may conceivably not change
<filename>B.hi</filename> one jot. So now…</para>
.SUFFIXES : .o .hs .hi .lhs .hc .s
cool_pgm : $(OBJS)
- rm $@
+ rm -f $@
$(HC) -o $@ $(HC_OPTS) $(OBJS)
# Standard suffix rules
<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>
particular, most <literal>Prelude</literal> entities aren't
actually defined in the <literal>Prelude</literal> (see for
example <literal>GHC.Base.Int</literal> in the above
- example).</para>
+ example). HINT: to find out the fully-qualified name for
+ entities in the <literal>Prelude</literal> (or anywhere for
+ that matter), try using GHCi's
+ <literal>:info</literal> command, eg.</para>
+<programlisting>Prelude> :m -Prelude
+> :i IO.IO
+-- GHC.IOBase.IO is a type constructor
+newtype GHC.IOBase.IO a
+...</programlisting>
</listitem>
<listitem>
<para>Only <literal>data</literal>, <literal>type</literal>,
<literal>newtype</literal>, <literal>class</literal>, and
- type signature declarations may be included.</para>
+ type signature declarations may be included. You cannot declare
+ <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
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>
-
- <para>(You must write all the type parameters, but leave out the
- '=' and everything that follows it.)</para>
</sect2>
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>
wasted work, but there is no avoiding it. You should therefore do
your best to have as few orphan modules as possible.
-</para><para>
-You can identify an orphan module by looking in its interface file, M.hi. If there is a ``!'' on
-the first line, GHC considers it an orphan module.
+</para>
+
+<para> You can identify an orphan module by looking in its interface
+file, <filename>M.hi</filename>, using the
+<option>--show-iface</option>. If there is a ``!'' on the first line,
+GHC considers it an orphan module.
</para>
</sect2>
projects / ghc-hetmet.git / blobdiff