<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>
+ <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>
- <sect2 id="hi-files">
- <title>Interface files</title>
-
<indexterm><primary>interface files</primary></indexterm>
<indexterm><primary><literal>.hi</literal> files</primary></indexterm>
+ <indexterm><primary>object files</primary></indexterm>
+ <indexterm><primary><literal>.o</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 not intended
- for human consumption, as you'll see if you take a look at one.
- It's merely there to help the compiler compile other modules in
- the same program.</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>
+ <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>). 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:
+
+ <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>
+
+ <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:
+ <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>
+
+ 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>
</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>EXOTICA: 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>
- <para>See also the section on packages (<xref
- linkend="packages">), which describes how to use installed
- libraries.</para>
+ <sect2 id="temp-files">
+ <title>Redirecting temporary files</title>
+ <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">
the labour.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>--show-iface</option>
+ <replaceable>file</replaceable></term>
+ <indexterm><primary><option>--show-iface</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Where <replaceable>file</replaceable> is the name of
+ an interface file, dumps the contents of that interface in
+ a human-readable (ish) format.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
-
</sect2>
<sect2 id="recomp">
.SUFFIXES : .o .hs .hi .lhs .hc .s
cool_pgm : $(OBJS)
- rm $@
+ rm -f $@
$(HC) -o $@ $(HC_OPTS) $(OBJS)
# Standard suffix rules
<filename>makefile</filename>, then the old dependencies are
deleted first.</para>
+ <para>Don't forget to use the same <option>-package</option>
+ options on the <literal>ghc -M</literal> command line as you
+ would when compiling; this enables the dependency generator to
+ locate any imported modules that come from packages. The
+ package modules won't be included in the dependencies
+ generated, though (but see the
+ <option>––include-prelude</option> option below).</para>
+
<para>The dependency generation phase of GHC can take some
additional options, which you may find useful. For historical
reasons, each option passed to the dependency generator from
</varlistentry>
<varlistentry>
- <term><option>--exclude-module=<file></option></term>
+ <term><option>––exclude-module=<file></option></term>
<listitem>
<para>Regard <filename><file></filename> as
"stable"; i.e., exclude it from having dependencies on
<varlistentry>
<term><option>-x</option></term>
<listitem>
- <para>same as <option>--exclude-module</option></para>
+ <para>same as <option>––exclude-module</option></para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--exclude-directory=<dirs></option></term>
+ <term><option>––exclude-directory=<dirs></option></term>
<listitem>
<para>Regard the colon-separated list of directories
<filename><dirs></filename> as containing stable,
</varlistentry>
<varlistentry>
- <term><option>--include-module=<file></option></term>
+ <term><option>––include-module=<file></option></term>
<listitem>
<para>Regard <filename><file></filename> as not
"stable"; i.e., generate dependencies on it (if
any). This option is normally used in conjunction with
- the <option>--exclude-directory</option> option.</para>
+ the <option>––exclude-directory</option> option.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--include-prelude</option></term>
+ <term><option>––include-prelude</option></term>
<listitem>
- <para>Regard prelude libraries as unstable, i.e.,
- generate dependencies on the prelude modules used
- (including <literal>Prelude</literal>). This option is
- normally only used by the various system libraries. If a
- <option>-package</option> option is used, dependencies
- will also be generated on the library's
- interfaces.</para>
+ <para>Regard modules imported from packages as unstable,
+ i.e., generate dependencies on the package modules used
+ (including <literal>Prelude</literal>, and all other
+ standard Haskell libraries). This option is normally
+ only used by the various system libraries.</para>
</listitem>
</varlistentry>
</variablelist>
would look like the following:</para>
<ProgramListing>
-__interface A 1 0 where
-__export A TA{MkTA} ;
-1 newtype TA = MkTA PrelBase.Int ;
+module A where
+newtype TA = MkTA GHC.Base.Int
</ProgramListing>
- <para>The syntax is essentially the same as a normal
- <filename>.hi</filename> file (unfortunately), so you can
- usually tailor an existing <filename>.hi</filename> file to make
- a <filename>.hi-boot</filename> file.</para>
+ <para>The syntax is similar to a normal Haskell source file, but
+ with some important differences:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Non-local entities must be qualified with their
+ <emphasis>original</emphasis> defining module. Qualifying
+ by a module which just re-exports the entity won't do. In
+ 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). 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. You cannot declare
+ <literal>instances</literal> or derive them automatically.
+</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>The number “1” after
- “__interface A” gives the version
- number of module A; it is incremented whenever anything in A's
- interface file changes. In a normal interface file, the
- “0” is the version number of the compiler which
- generated the interface file; it is used to ensure that we don't
- mix-and-match interface files between compiler versions.
- Leaving it as zero in an <literal>hi-boot</literal> file turns
- off this check.</para>
-
- <para>The number “1” at the beginning of a
- declaration is the <emphasis>version number</emphasis> of that
- declaration: for the purposes of <filename>.hi-boot</filename>
- files these can all be set to 1. All names must be fully
- qualified with the <emphasis>original</emphasis> module that an
- object comes from: for example, the reference to
- <literal>Int</literal> in the interface for <literal>A</literal>
- comes from <literal>PrelBase</literal>, which is a module
- internal to GHC's prelude. It's a pain, but that's the way it
- is.</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>
-__interface A 1 0 where
-__export A TA;
-1 data TA
+module A where
+data TA
</ProgramListing>
<para>(You must write all the type parameters, but leave out the
'=' and everything that follows it.)</para>
-
- <para><emphasis>Note:</emphasis> This is all a temporary
- solution, a version of the compiler that handles mutually
- recursive modules properly without the manual construction of
- interface files, is (allegedly) in the works.</para>
</sect2>
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