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