-
- <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>
-
+ <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>