[project @ 2003-06-23 10:35:15 by simonpj]

-------------------
	Dealing with 'main'
	-------------------

1.  In GHC 6.0, a module with no "module Main ... where" header
    elicited an error "main is not in scope" if 'main' is not defined.  We
    don't want this behaviour in GHCi.  This happened because the parser
    expanded the (absent) header to "module Main( main ) where", and the
    'main' in the export list isn't.

Solution: elaborate HsModule to record whether the 'module ..." header was
given explicitly by the user or not.


2.  Add a -main-is flag, and document it, so that you can have a 'main' function
that is not Main.main.  Summary of changes

* The -main-is flag nominates what the main function is to be (see the documentation).
	No -main-is flag 	says that the main function is Main.main
	-main-is Foo.baz	says that the main function is Foo.baz
	-main-is Foo		says that the main function is Foo.main
	-main-is baz		says that the main function is Main.baz

  Let's say  you say -main-is Foo.baz

* TcRnDriver injects the extra definition
	$Mian.main :: IO t
	$Main.main = baz
  in the module Foo.   Note the naming, which is a bit different than before;
  previously the extra defn was for Main.$main.  The RTS invokes zdMain_main_closure.

* CodeGen injects an extra initialisation block into module Foo, thus
	stginit_zdMain {
		stginit_Foo
	}
  That ensures that the RTS can initialise stginit_zdMain.

2 files changed, 23 insertions, 2 deletions

diff --git a/ghc/docs/users_guide/ffi-chap.sgml b/ghc/docs/users_guide/ffi-chap.sgml
index 0aaeabd8a6..99d21a3cc1 100644
--- a/ghc/docs/users_guide/ffi-chap.sgml
+++ b/ghc/docs/users_guide/ffi-chap.sgml
@@ -101,7 +101,7 @@ extern HsInt foo(HsInt a0);</programlisting>
       invoke <literal>foo()</literal> from C, just <literal>#include
       "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
 
-      <sect3> 
+      <sect3 id="using-own-main"> 
 	<title>Using your own <literal>main()</literal></title>
 
 	<para>Normally, GHC's runtime system provides a
diff --git a/ghc/docs/users_guide/phases.sgml b/ghc/docs/users_guide/phases.sgml
index 0dee0c1f8f..e0f92b3fd2 100644
--- 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>
@@ -564,7 +585,7 @@ strmod = "\
             be supplying its definition of <function>main()</function>
             at link-time, you will have to. To signal that to the
             compiler when linking, use
-            <option>-no-hs-main</option>.</para>
+            <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