[project @ 2005-11-24 09:46:01 by simonpj]

[ghc-hetmet.git] / ghc / docs / users_guide / separate_compilation.xml

diff --git a/ghc/docs/users_guide/separate_compilation.xml b/ghc/docs/users_guide/separate_compilation.xml
index cb80aad..fc44fe6 100644 (file)
--- a/ghc/docs/users_guide/separate_compilation.xml
+++ b/ghc/docs/users_guide/separate_compilation.xml
@@ -253,6 +253,23 @@
           <filename>Main.hs</filename>, and put the resulting
           executable in <filename>foo.exe</filename> (not
           <filename>foo</filename>).</para>
           <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>
 
          </listitem>
        </varlistentry>
 

@@ -326,6 +343,23 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
 
        <varlistentry>
          <term>
 
        <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 "&amp;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>
             <option>-osuf</option> <replaceable>suffix</replaceable>
             <indexterm><primary><option>-osuf</option></primary></indexterm>
           </term>

@@ -369,7 +403,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
        </varlistentry>
       </variablelist>
     </sect2>
        </varlistentry>
       </variablelist>
     </sect2>

-
+  

     <sect2 id="keeping-intermediates">
       <title>Keeping Intermediate Files</title>
       <indexterm><primary>intermediate files, saving</primary>
     <sect2 id="keeping-intermediates">
       <title>Keeping Intermediate Files</title>
       <indexterm><primary>intermediate files, saving</primary>

@@ -653,20 +687,6 @@ version of <filename>A.hs</filename>, thus:
 module A where
     newtype TA = MkTA Int
 </programlisting>
 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>
 </para>
 <para>To compile these three files, issue the following commands:
 <programlisting>

@@ -681,30 +701,64 @@ 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>.
 <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>
 
   </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>
    
    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>: </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
    <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>
    </para></listitem>
 </itemizedlist>
 </para>

@@ -714,10 +768,13 @@ A hs-boot file need only contain the bare
       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
       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>
 <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>
 <listitem><para> There must be no value declarations, but there can be type signatures for
 values.  For example:
 <programlisting>

@@ -823,16 +880,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>
       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>
 
 
 <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
       <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

@@ -843,6 +900,7 @@ Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
       <xref linkend="sec-makefile-dependencies"/></para>
 
  </sect2>
       <xref linkend="sec-makefile-dependencies"/></para>
 
  </sect2>

+

       <sect2 id="sec-makefile-dependencies">
        <title>Dependency generation</title>
        <indexterm><primary>dependencies in Makefiles</primary></indexterm>
       <sect2 id="sec-makefile-dependencies">
        <title>Dependency generation</title>
        <indexterm><primary>dependencies in Makefiles</primary></indexterm>

@@ -898,6 +956,14 @@ M.o : X.hi-boot
        <command>ghc</command> traces the dependencies, just like <command>ghc --make</command>
        (a new feature in GHC 6.4).</para>
 
        <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
         <para>By default, <command>ghc -M</command> generates all the
         dependencies, and then concatenates them onto the end of
         <filename>makefile</filename> (or

@@ -915,7 +981,7 @@ M.o : X.hi-boot
        locate any imported modules that come from packages.  The
        package modules won't be included in the dependencies
        generated, though (but see the
        locate any imported modules that come from packages.  The
        package modules won't be included in the dependencies
        generated, though (but see the

-       <option>&ndash;&ndash;include-prelude</option> option below).</para>
+       <option>&ndash;&ndash;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
 
        <para>The dependency generation phase of GHC can take some
         additional options, which you may find useful.  For historical

@@ -939,6 +1005,17 @@ ghc -M -optdep-f -optdep.depend ...
          </varlistentry>
 
          <varlistentry>
          </varlistentry>
 
          <varlistentry>

+           <term><option>-v2</option></term>
+           <listitem>
+             <para>Print a full list of the module depenencies to stdout.
+                   (This is the standard verbosity flag, so the list will
+             also be displayed with <option>-v3</option> and
+             <option>-v4</option>;
+             <xref linkend ="options-help"/>.)</para>
+           </listitem>
+         </varlistentry>
+
+         <varlistentry>

            <term><option>-f</option> <replaceable>file</replaceable></term>
            <listitem>
              <para>Use <replaceable>file</replaceable> as the makefile,
            <term><option>-f</option> <replaceable>file</replaceable></term>
            <listitem>
              <para>Use <replaceable>file</replaceable> as the makefile,

@@ -1026,12 +1103,16 @@ ghc -M -optdep-f -optdep.depend ...
          </varlistentry>
 
          <varlistentry>
          </varlistentry>
 
          <varlistentry>

-           <term><option>&ndash;&ndash;include-prelude</option></term>
+           <term><option>&ndash;&ndash;include-pkg-deps</option></term>

            <listitem>
              <para>Regard modules imported from packages as unstable,
            <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
               (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>
               only used by the various system libraries.</para>
            </listitem>
          </varlistentry>