[project @ 2003-07-21 11:45:47 by simonmar]

[ghc-hetmet.git] / ghc / docs / users_guide / phases.sgml

diff --git a/ghc/docs/users_guide/phases.sgml b/ghc/docs/users_guide/phases.sgml
index fa0ae08..e0f92b3 100644 (file)
--- a/ghc/docs/users_guide/phases.sgml
+++ b/ghc/docs/users_guide/phases.sgml
@@ -555,6 +555,27 @@ strmod = "\
        </varlistentry>
 
        <varlistentry>
+         <term><option>-main-is <replaceable>thing</replaceable></option></term>
+         <indexterm><primary><option>-main-is</option></primary></indexterm>
+         <indexterm><primary>specifying your own main function</primary></indexterm>
+         <listitem>
+           <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
+             function in module <literal>Main</literal>.  When testing, it is often convenient
+             to change which function is the "main" one, and the <option>-main-is</option> flag
+             allows you to do so.  The  <replaceable>thing</replaceable> can be one of:
+             <itemizedlist>
+               <listitem><para>A lower-case identifier <literal>foo</literal>.  GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
+               <listitem><para>An module name <literal>A</literal>.  GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
+               <listitem><para>An qualified name <literal>A.foo</literal>.  GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
+               </itemizedlist>
+             Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
+             The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
+             in the latter two items above.  It has no effect for other modules (and hence can safely be given to <literal>ghc --make</literal>).
+             </para> 
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
          <term><option>-no-hs-main</option></term>
          <indexterm><primary><option>-no-hs-main</option></primary></indexterm>
          <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
@@ -563,8 +584,8 @@ strmod = "\
             as part of another (non-Haskell) program, the RTS will not
             be supplying its definition of <function>main()</function>
             at link-time, you will have to. To signal that to the
-            driver script when linking, use
-            <option>-no-hs-main</option>.</para>
+            compiler when linking, use
+            <option>-no-hs-main</option>. See also <xref linkend="using-own-main">.</para>
 
            <para>Notice that since the command-line passed to the
             linker is rather involved, you probably want to use
@@ -573,6 +594,13 @@ strmod = "\
             though, just try linking once with <option>-v</option> on
             to see what options the driver passes through to the
             linker.</para>
+
+           <para>The <option>-no-hs-main</option> flag can also be
+           used to persuade the compiler to do the link step in
+           <option>--make</option> mode when there is no Haskell
+           <literal>Main</literal> module present (normally the
+           compiler will not attempt linking when there is no
+           <literal>Main</literal>).</para>
          </listitem>
        </varlistentry>
       </variablelist>