<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:
+ ...</literal>).</para>
- <variablelist>
- <varlistentry>
- <term><replaceable>hidir</replaceable></term>
- <listitem>
- <para>is the value of the <option>-hidir</option> option if
- one was given (see below), 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 (see below), or <literal>hi</literal>
- otherwise.</para>
- </listitem>
- </varlistentry>
+ <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>
- <varlistentry>
- <term><replaceable>odir</replaceable></term>
- <listitem>
- <para>is the value of the <option>-odir</option> option if
- one was given (see below), 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 (see below), 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:
+ <itemizedlist>
+ <listitem>
+ <para>If there is no <option>-odir</option> option (the
+ default), then the object filename is derived from the
+ source filename 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>
- <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>
+ <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>
- For example, if GHC compiles the module
+ <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> (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>
+ <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>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. For modules other than
+ <literal>Main</literal>, it is strongly recommended that you
+ name the source file after the module name, replacing dots with
+ slashes in hierarchical module names.</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">
<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>
<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, thus:
+<ProgramListing>
+module A where
+ data TA
+</ProgramListing>
+ (You must write all the type parameters, but omit the
+ '=' and everything that follows it.) 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>
+ </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>
projects / ghc-hetmet.git / blobdiff