[project @ 2005-10-28 15:51:15 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 f750128..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>
+
+          <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>
 
@@ -326,6 +343,23 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
 
        <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>
@@ -719,12 +753,12 @@ When a hs-boot file <filename>A.hs-boot</filename>
    <command>ghc -M</command> will report an error if a cycle is found.
    </para></listitem>
 
-   <listitem><para> Every module that is 
-   <literal>{-# SOURCE #-}</literal>-imported in a program must also be ordinarily imported (or
-   else be one of the root modules).  To put it another way, if <literal>M.hs-boot</literal> is
-   reachable in the import graph, then <literal>M.hs</literal> must also be reachable.
-   The command <command>ghc --make</command> will report an error if this
-   condition is not satisfied.
+   <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>
@@ -922,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>
 
+    <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