+++ /dev/null
- <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
- 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>
- <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="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>.
- 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<replaceable>dirs</replaceable></option></term>
- <listitem>
- <para><indexterm><primary><option>-i<replaceable>dirs</replaceable></option>
- </primary></indexterm>This flag appends a colon-separated
- list of <filename>dirs</filename> to the search path.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-i</option></term>
- <listitem>
- <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>
-
- <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">
- <title>Other options related to interface files</title>
- <indexterm><primary>interface files, options</primary></indexterm>
-
- <variablelist>
- <varlistentry>
- <term><option>-ddump-hi</option></term>
- <indexterm><primary><option>-ddump-hi</option></primary>
- </indexterm>
- <listitem>
- <para>Dumps the new interface to standard output.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-ddump-hi-diffs</option></term>
- <indexterm><primary><option>-ddump-hi-diffs</option></primary>
- </indexterm>
- <listitem>
- <para>The compiler does not overwrite an existing
- <filename>.hi</filename> interface file if the new one is
- the same as the old one; this is friendly to
- <command>make</command>. When an interface does change,
- it is often enlightening to be informed. The
- <option>-ddump-hi-diffs</option> option will make GHC run
- <command>diff</command> on the old and new
- <filename>.hi</filename> files.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-ddump-minimal-imports</option></term>
- <indexterm><primary><option>-ddump-minimal-imports</option></primary>
- </indexterm>
- <listitem>
- <para>Dump to the file "M.imports" (where M is the module
- being compiled) a "minimal" set of import declarations.
- You can safely replace all the import declarations in
- "M.hs" with those found in "M.imports". Why would you
- want to do that? Because the "minimal" imports (a) import
- everything explicitly, by name, and (b) import nothing
- that is not required. It can be quite painful to maintain
- this property by hand, so this flag is intended to reduce
- 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">
- <title>The recompilation checker</title>
-
- <indexterm><primary>recompilation checker</primary></indexterm>
-
- <variablelist>
- <varlistentry>
- <term><option>-no-recomp</option></term>
- <indexterm><primary><option>-recomp</option></primary></indexterm>
- <indexterm><primary><option>-no-recomp</option></primary></indexterm>
- <listitem>
- <para>Turn off recompilation checking (which is on by
- default). Recompilation checking normally stops
- compilation early, leaving an existing
- <filename>.o</filename> file in place, if it can be
- determined that the module does not need to be
- recompiled.</para>
- </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
- modification date. In consequence, importers of a module with
- an unchanged output <filename>.hi</filename> file were not
- recompiled.</para>
-
- <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 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>
-
- <para>GHC keeps a version number on each interface file, and on
- each type signature within the interface file. It also keeps in
- every interface file a list of the version numbers of everything
- it used when it last compiled the file. If the source file's
- modification date is earlier than the <filename>.o</filename>
- file's date (i.e. the source hasn't changed since the file was
- last compiled), and the reompilation checking is on, GHC will be
- clever. It compares the version numbers on the things it needs
- this time with the version numbers on the things it needed last
- time (gleaned from the interface file of the module being
- compiled); if they are all the same it stops compiling rather
- early in the process saying “Compilation IS NOT
- 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
- copy.</para>
-
- </sect2>
-
- <sect2 id="using-make">
- <title>Using <command>make</command></title>
-
- <indexterm><primary><literal>make</literal></primary></indexterm>
-
- <para>It is reasonably straightforward to set up a
- <filename>Makefile</filename> to use with GHC, assuming you name
- your source files the same as your modules. Thus:</para>
-
-<programlisting>
-HC = ghc
-HC_OPTS = -cpp $(EXTRA_HC_OPTS)
-
-SRCS = Main.lhs Foo.lhs Bar.lhs
-OBJS = Main.o Foo.o Bar.o
-
-.SUFFIXES : .o .hs .hi .lhs .hc .s
-
-cool_pgm : $(OBJS)
- rm -f $@
- $(HC) -o $@ $(HC_OPTS) $(OBJS)
-
-# Standard suffix rules
-.o.hi:
- @:
-
-.lhs.o:
- $(HC) -c $< $(HC_OPTS)
-
-.hs.o:
- $(HC) -c $< $(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>
-
- <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>
-%.o : %.lhs
- $(HC) -c $< $(HC_OPTS)
-</programlisting>
-
- <para>What we've shown should work with any
- <command>make</command>.)</para>
-
- <para>Note the cheesy <literal>.o.hi</literal> rule: It records
- the dependency of the interface (<filename>.hi</filename>) file
- on the source. The rule says a <filename>.hi</filename> file
- can be made from a <filename>.o</filename> file by
- doing…nothing. Which is true.</para>
-
- <para>Note the inter-module dependencies at the end of the
- Makefile, which take the form</para>
-
-<programlisting>
-Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-</programlisting>
-
- <para>They tell <command>make</command> that if any of
- <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
- <literal>Foo.s</literal> have an earlier modification date than
- <literal>Baz.hi</literal>, then the out-of-date file must be
- brought up to date. To bring it up to date,
- <literal>make</literal> looks for a rule to do so; one of the
- preceding suffix rules does the job nicely.</para>
-
- <sect3 id="sec-makefile-dependencies">
- <title>Dependency generation</title>
- <indexterm><primary>dependencies in Makefiles</primary></indexterm>
- <indexterm><primary>Makefile dependencies</primary></indexterm>
-
- <para>Putting inter-dependencies of the form <literal>Foo.o :
- Bar.hi</literal> into your <filename>Makefile</filename> by
- hand is rather error-prone. Don't worry, GHC has support for
- automatically generating the required dependencies. Add the
- following to your <filename>Makefile</filename>:</para>
-
-<programlisting>
-depend :
- ghc -M $(HC_OPTS) $(SRCS)
-</programlisting>
-
- <para>Now, before you start compiling, and any time you change
- the <literal>imports</literal> in your program, do
- <command>make depend</command> before you do <command>make
- cool_pgm</command>. <command>ghc -M</command> will
- append the needed dependencies to your
- <filename>Makefile</filename>.</para>
-
- <para>In general, if module <literal>A</literal> contains the
- line
-
-<programlisting>
-import B ...blah...
-</programlisting>
-
- then <command>ghc -M</command> will generate a dependency line
- of the form:
-
-<programlisting>
-A.o : B.hi
-</programlisting>
-
- If module <literal>A</literal> contains the line
-
-<programlisting>
-import {-# SOURCE #-} B ...blah...
-</programlisting>
-
- then <command>ghc -M</command> will generate a dependency
- line of the form:
-
-<programlisting>
-A.o : B.hi-boot
-</programlisting>
-
- (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
- target.</para>
-
- <para>By default, <command>ghc -M</command> generates all the
- dependencies, and then concatenates them onto the end of
- <filename>makefile</filename> (or
- <filename>Makefile</filename> if <filename>makefile</filename>
- doesn't exist) bracketed by the lines "<literal># DO NOT
- DELETE: Beginning of Haskell dependencies</literal>" and
- "<literal># DO NOT DELETE: End of Haskell
- dependencies</literal>". If these lines already exist in the
- <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
- the GHC command line must be preceded by
- <literal>-optdep</literal>. For example, to pass <literal>-f
- .depend</literal> to the dependency generator, you say
-
-<screen>
-ghc -M -optdep-f -optdep.depend ...
-</screen>
-
- The options which affect dependency generation are:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-w</option></term>
- <listitem>
- <para>Turn off warnings about interface file shadowing.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-f</option> <replaceable>file</replaceable></term>
- <listitem>
- <para>Use <replaceable>file</replaceable> as the makefile,
- rather than <filename>makefile</filename> or
- <filename>Makefile</filename>. If
- <replaceable>file</replaceable> doesn't exist,
- <command>mkdependHS</command> creates it. We often use
- <option>-f .depend</option> to put the dependencies in
- <filename>.depend</filename> and then
- <command>include</command> the file
- <filename>.depend</filename> into
- <filename>Makefile</filename>.</para>
- </listitem>
- </varlistentry>
-
-<!-- Retired with the move away from 'mkdependHS'.
- <varlistentry>
- <term><option>-o <osuf></option></term>
- <listitem>
- <para>Use <filename>.<osuf></filename> as the
- "target file" suffix ( default: <literal>o</literal>).
- Multiple <option>-o</option> flags are permitted
- (GHC2.05 onwards). Thus "<option>-o hc -o o</option>"
- will generate dependencies for <filename>.hc</filename>
- and <filename>.o</filename> files.</para>
- </listitem>
- </varlistentry>
--->
- <varlistentry>
- <term><option>-s <suf></option></term>
- <listitem>
- <para>Make extra dependencies that declare that files
- with suffix
- <filename>.<suf>_<osuf></filename>
- depend on interface files with suffix
- <filename>.<suf>_hi</filename>, or (for
- <literal>{-# SOURCE #-}</literal>
- imports) on <filename>.hi-boot</filename>. Multiple
- <option>-s</option> flags are permitted. For example,
- <option>-o hc -s a -s b</option> will make dependencies
- for <filename>.hc</filename> on
- <filename>.hi</filename>,
- <filename>.a_hc</filename> on
- <filename>.a_hi</filename>, and
- <filename>.b_hc</filename> on
- <filename>.b_hi</filename>. (Useful in
- conjunction with NoFib "ways".)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>––exclude-module=<file></option></term>
- <listitem>
- <para>Regard <filename><file></filename> as
- "stable"; i.e., exclude it from having dependencies on
- it.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-x</option></term>
- <listitem>
- <para>same as <option>––exclude-module</option></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>––exclude-directory=<dirs></option></term>
- <listitem>
- <para>Regard the colon-separated list of directories
- <filename><dirs></filename> as containing stable,
- don't generate any dependencies on modules
- therein.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <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>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>––include-prelude</option></term>
- <listitem>
- <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>
-
- </sect3>
- </sect2>
-
- <sect2 id="mutual-recursion">
- <title>How to compile mutually recursive modules</title>
-
- <indexterm><primary>module system, recursion</primary></indexterm>
- <indexterm><primary>recursion, between modules</primary></indexterm>
-
- <para>Currently, the compiler does not have proper support for
- dealing with mutually recursive modules:</para>
-
-<programlisting>
-module A where
-
-import B
-
-newtype TA = MkTA Int
-
-f :: TB -> TA
-f (MkTB x) = MkTA x
---------
-module B where
-
-import A
-
-data TB = MkTB !Int
-
-g :: TA -> TB
-g (MkTA x) = MkTB x
-</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,
- to get mutually recursive modules off the ground, you need to
- hand write an interface file for A or B, so as to break the
- loop. These hand-written interface files are called
- <literal>hi-boot</literal> files, and are placed in a file
- called <filename><module>.hi-boot</filename>. To import
- from an <literal>hi-boot</literal> file instead of the standard
- <filename>.hi</filename> file, use the following syntax in the
- importing module: <indexterm><primary><literal>hi-boot</literal>
- files</primary></indexterm> <indexterm><primary>importing,
- <literal>hi-boot</literal> files</primary></indexterm></para>
-
-<programlisting>
-import {-# SOURCE #-} A
-</programlisting>
-
- <para>The hand-written interface need only contain the bare
- minimum of information needed to get the bootstrapping process
- started. For example, it doesn't need to contain declarations
- for <emphasis>everything</emphasis> that module
- <literal>A</literal> exports, only the things required by the
- module that imports <literal>A</literal> recursively.</para>
-
- <para>For the example at hand, the boot interface file for A
- would look like the following:</para>
-
-<programlisting>
-module A where
-newtype TA = MkTA GHC.Base.Int
-</programlisting>
-
- <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>
-
-<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>
-
- </sect2>
-
-
- <sect2 id="orphan-modules">
- <title>Orphan modules and instance declarations</title>
-
-<para> Haskell specifies that when compiling module M, any instance
-declaration in any module "below" M is visible. (Module A is "below"
-M if A is imported directly by M, or if A is below a module that M imports directly.)
-In principle, GHC must therefore read the interface files of every module below M,
-just in case they contain an instance declaration that matters to M. This would
-be a disaster in practice, so GHC tries to be clever. </para>
-
-<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>
- module A where
- instance C a => D (T a) where ...
- data T a = ...
-</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>
- module Orphan where
- instance C a => D (T a) where ...
- class C a where ...
-</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>
- <indexterm><primary>orphan module</primary></indexterm>
- 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>
-
- <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>
-
- <listitem><para> A rewrite rule in a module M is an <emphasis>orphan rule</emphasis>
- <indexterm><primary>orphan rule</primary></indexterm>
- if none of the variables, type constructors,
- or classes that are free in the left hand side of the rule are declared in M.
- </para> </listitem>
- </itemizedlist>
-
-
-<para> GHC identifies orphan modules, and visits the interface file of
-every orphan module below the module being compiled. This is usually
-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, <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>
-
- </sect1>
-
-<!-- Emacs stuff:
- ;;; Local Variables: ***
- ;;; mode: sgml ***
- ;;; sgml-parent-document: ("using.sgml" "book" "chapter") ***
- ;;; End: ***
- -->
projects / ghc-hetmet.git / blobdiff