<sect2 id="source-files">
<title>Haskell source files</title>
+ <indexterm><primary>filenames</primary></indexterm>
+
<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
+ <para>Usually, the file should be named after the module name,
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>
+ relative to some base directory. If the module is not going to
+ be imported by another module (<literal>Main</literal>, for
+ example), then you are free to use any filename for it.</para>
+
+ <indexterm><primary>unicode</primary></indexterm>
+
+ <para> GHC assumes that source files are
+ ASCII<indexterm><primary>ASCII</primary></indexterm> or
+ UTF-8<indexterm><primary>UTF-8</primary></indexterm> only, other
+ encodings<indexterm><primary>encoding</primary></indexterm> are
+ not recognised. However, invalid UTF-8 sequences will be
+ ignored in comments, so it is possible to use other encodings
+ such as
+ Latin-1<indexterm><primary>Latin-1</primary></indexterm>, as
+ long as the non-comment source code is ASCII only.</para>
</sect2>
<sect2 id="output-files">
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>
+ <literal>.o</literal> suffix, contains the compiled code for the
+ module.</para>
<para>The interface file,
which normally ends in a <literal>.hi</literal> suffix, contains
<filename>Main.hs</filename>, and put the resulting
executable in <filename>foo.exe</filename> (not
<filename>foo</filename>).</para>
+
+ <para>If you use <command>ghc --make</command> and you don't
+ use the <option>-o</option>, the name GHC will choose
+ for the executable will be based on the name of the file
+ containing the module <literal>Main</literal>.
+ Note that with GHC the <literal>Main</literal> module doesn't
+ have to be put in file <filename>Main.hs</filename>.
+ Thus both
+<programlisting>
+ ghc --make Prog
+</programlisting>
+ and
+<programlisting>
+ ghc --make Prog.hs
+</programlisting>
+ will produce <filename>Prog</filename> (or
+ <filename>Prog.exe</filename> if you are on Windows).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
+ <option>-stubdir</option> <replaceable>dir</replaceable>
+ <indexterm><primary><option>-stubdir</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Redirects all generated FFI stub files into
+ <replaceable>dir</replaceable>. Stub files are generated when the
+ Haskell source contains a <literal>foreign export</literal> or
+ <literal>foreign import "&wrapper"</literal> declaration (see <xref
+ linkend="foreign-export-ghc" />). The <option>-stubdir</option>
+ option behaves in exactly the same way as <option>-odir</option>
+ and <option>-hidir</option> with respect to hierarchical
+ modules.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<option>-osuf</option> <replaceable>suffix</replaceable>
<indexterm><primary><option>-osuf</option></primary></indexterm>
</term>
</varlistentry>
</variablelist>
</sect2>
-
+
<sect2 id="keeping-intermediates">
<title>Keeping Intermediate Files</title>
<indexterm><primary>intermediate files, saving</primary>
an error is reported if the two are inconsistent.
</para></listitem>
-<listitem><para> Just as compiling <filename>A.hs</filename> produces an
-interface file <filename>A.hi</filename>, and an object file
-<filename>A.o</filename>, so compiling <filename>A.hs-boot</filename>
-produces an interface file
-<filename>A.hi-boot</filename>, and an pseudo-object file
-<filename>A.o-boot</filename>:
-<itemizedlist>
-<listitem><para>
-The pseudo-object file <filename>A.o-boot</filename> is empty (don't link it!), but it is
-very useful when using a Makefile, to record when the <filename>A.hi-boot</filename> was
-last brought up to date (see <xref linkend="using-make"/>).
-</para>
-</listitem>
-
- <listitem><para> The <filename>hi-boot</filename> generated by compiling a <filename>hs-boot</filename>
- file is in the same machine-generated binary format as any other
- GHC-generated interface file (e.g. <filename>B.hi</filename>).
- You can display its contents with <command>ghc --show-iface</command>. If you
- specify a directory for interface files, the <option>-ohidir</option> flag, then that affects
- <filename>hi-boot</filename> files too.</para></listitem>b
-</itemizedlist>
-</para></listitem>
+ <listitem>
+ <para> Just as compiling <filename>A.hs</filename> produces an
+ interface file <filename>A.hi</filename>, and an object file
+ <filename>A.o</filename>, so compiling
+ <filename>A.hs-boot</filename> produces an interface file
+ <filename>A.hi-boot</filename>, and an pseudo-object file
+ <filename>A.o-boot</filename>: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The pseudo-object file <filename>A.o-boot</filename> is
+ empty (don't link it!), but it is very useful when using a
+ Makefile, to record when the <filename>A.hi-boot</filename> was
+ last brought up to date (see <xref
+ linkend="using-make"/>).</para>
+ </listitem>
+
+ <listitem>
+ <para>The <filename>hi-boot</filename> generated by compiling a
+ <filename>hs-boot</filename> file is in the same
+ machine-generated binary format as any other GHC-generated
+ interface file (e.g. <filename>B.hi</filename>). You can
+ display its contents with <command>ghc
+ --show-iface</command>. If you specify a directory for
+ interface files, the <option>-ohidir</option> flag, then that
+ affects <filename>hi-boot</filename> files
+ too.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
<listitem><para> If hs-boot files are considered distinct from their parent source
files, and if a <literal>{-# SOURCE #-}</literal> import is considered to refer to the
- hs-boot file, then the module import graph must have no cycles. The <command>ghc -M</command>
- will report an error if a cycle is found.
+ hs-boot file, then the module import graph must have no cycles. The command
+ <command>ghc -M</command> will report an error if a cycle is found.
+ </para></listitem>
+
+ <listitem><para> A module <literal>M</literal> that is
+ <literal>{-# SOURCE #-}</literal>-imported in a program will usually also be
+ ordinarily imported elsewhere. If not, <command>ghc --make</command>
+ automatically adds <literal>M</literal> to the set of moudles it tries to
+ compile and link, to ensure that <literal>M</literal>'s implementation is included in
+ the final program.
</para></listitem>
</itemizedlist>
</para>
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>
+ module(s) that import <literal>A</literal> recursively.</para>
<para>A hs-boot file is written in a subset of Haskell:
<itemizedlist>
<listitem><para> The module header (including the export list), and import statements, are exactly as in
<xref linkend="sec-makefile-dependencies"/></para>
</sect2>
+
<sect2 id="sec-makefile-dependencies">
<title>Dependency generation</title>
<indexterm><primary>dependencies in Makefiles</primary></indexterm>
<command>ghc</command> traces the dependencies, just like <command>ghc --make</command>
(a new feature in GHC 6.4).</para>
+ <para>Note that <literal>ghc -M</literal> needs to find a <emphasis>source
+ file</emphasis> for each module in the dependency graph, so that it can
+ parse the import declarations and follow dependencies. Any pre-compiled
+ modules without source files must therefore belong to a
+ package<footnote><para>This is a change in behaviour relative to 6.2 and
+ earlier.</para>
+ </footnote>.</para>
+
<para>By default, <command>ghc -M</command> generates all the
dependencies, and then concatenates them onto the end of
<filename>makefile</filename> (or
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>
+ <option>––include-pkg-deps</option> option below).</para>
<para>The dependency generation phase of GHC can take some
additional options, which you may find useful. For historical
</varlistentry>
<varlistentry>
- <term><option>––include-prelude</option></term>
+ <term><option>––include-pkg-deps</option></term>
<listitem>
<para>Regard modules imported from packages as unstable,
- i.e., generate dependencies on the package modules used
+ i.e., generate dependencies on any imported package modules
(including <literal>Prelude</literal>, and all other
- standard Haskell libraries). This option is normally
+ standard Haskell libraries). Dependencies are not traced
+ recursively into packages; dependencies are only generated for
+ home-package modules on external-package modules directly imported
+ by the home package module.
+ This option is normally
only used by the various system libraries.</para>
</listitem>
</varlistentry>