[project @ 2005-03-31 08:46:05 by simonmar]

[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 17a896c..97fe772 100644 (file)
--- a/ghc/docs/users_guide/separate_compilation.xml
+++ b/ghc/docs/users_guide/separate_compilation.xml
@@ -369,7 +369,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>

@@ -682,33 +682,49 @@ When a hs-boot file <filename>A.hs-boot</filename>
    an error is reported if the two are inconsistent.
    </para></listitem>
    
    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
 
    <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>

@@ -718,7 +734,7 @@ 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>
 <listitem><para> The module header (including the export list), and import statements, are exactly as in
 <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

@@ -850,6 +866,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>

@@ -905,6 +922,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

@@ -922,7 +947,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

@@ -946,6 +971,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,

@@ -1033,12 +1069,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>