Commit fc37fb19 authored by simonpj's avatar simonpj
Browse files

[project @ 2005-02-01 17:49:02 by simonpj]

Finish docs for hs-boot files; please review!
parent 60bbba36
......@@ -653,20 +653,6 @@ version of <filename>A.hs</filename>, thus:
module A where
newtype TA = MkTA Int
</programlisting>
A <filename>hs-boot</filename> file is compiled by GHC, just like a <filename>hs</filename> file:
<programlisting>
ghc -c A.hs-boot
</programlisting>
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>. The interface file
<filename>A.hi-boot</filename> has exactly the same format as any
other interface file. The pseudo-object file 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.
</para>
<para>To compile these three files, issue the following commands:
<programlisting>
......@@ -681,26 +667,44 @@ last brought up to date.
<listitem>
<para>The file <filename>A.hs-boot</filename> is a programmer-written source file.
It must live in the same directory as its parent source file <filename>A.hs</filename>.
(Currently, if you use a literate source file <filename>A.lhs</filename> you must
also use a literate boot file, <filename>A.lhs-boot</filename>.)
Currently, if you use a literate source file <filename>A.lhs</filename> you must
also use a literate boot file, <filename>A.lhs-boot</filename>; and vice versa.
</para></listitem>
<listitem><para> The <filename>hi-boot</filename> generated by compiling a <filename>hs-boot</filename>
file is in machine-generated binary format.
You can display its contents with <command>ghc --show-iface</commaond>. 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
<listitem><para> Hs-boot files are written in a subset of Haskell. In particular, the module
exports and imports, and the scoping rules are exactly the same as in Haskell. Hence, to
mention a non-Prelude type or class, you must import it.</para></listitem>
<listitem><para> When a hs-boot file <filename>A.hs-boot</filename>
<listitem><para>
A <filename>hs-boot</filename> file is compiled by GHC, just like a <filename>hs</filename> file:
<programlisting>
ghc -c A.hs-boot
</programlisting>
When a hs-boot file <filename>A.hs-boot</filename>
is compiled, it is checked for scope and type errors.
When its parent module <filename>A.hs</filename> is compiled, the two are compared, and
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> 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>
......@@ -717,7 +721,10 @@ A hs-boot file need only contain the bare
module that imports <literal>A</literal> recursively.</para>
<para>A hs-boot file is written in a subset of Haskell:
<itemizedlist>
<listitem><para> The module header, and import statements, are exactly as in Haskell.</para></listitem>
<listitem><para> The module header (including the export list), and import statements, are exactly as in
Haskell, and so are the scoping rules.
Hence, to mention a non-Prelude type or class, you must import it.</para></listitem>
<listitem><para> There must be no value declarations, but there can be type signatures for
values. For example:
<programlisting>
......@@ -823,16 +830,16 @@ Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
doing&hellip;nothing. Which is true.</para>
<para> Note that the suffix rules are all repeated twice, once
for normal Haskell source files, and once for <filename>hs-boot</filename>
files (see <xref linkend="mutual-recursion"/>).
files (see <xref linkend="mutual-recursion"/>).</para>
<para>Note the inter-module dependencies at the end of the
Makefile, which take the form</para>
<para>Note also the inter-module dependencies at the end of the
Makefile, which take the form
<programlisting>
Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
</programlisting>
<para>They tell <command>make</command> that if any of
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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment