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

[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 043a451..e0f92b3 100644 (file)
--- a/ghc/docs/users_guide/phases.sgml
+++ b/ghc/docs/users_guide/phases.sgml
@@ -461,6 +461,19 @@ strmod = "\
        </varlistentry>
 
        <varlistentry>
+         <term><option>-no-link</option></term>
+         <indexterm>
+           <primary><option>-no-link</option></primary>
+         </indexterm>
+         <listitem>
+           <para>Omit the link step.  This flag can be useful if you
+           want to avoid linking in <option>--make</option> mode,
+           where linking is normally done automatically if the program
+           contains a <literal>Main</literal> module.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
          <term><option>-package</option> <replaceable>name</replaceable></term>
          <indexterm><primary><option>-package</option></primary></indexterm>
          <listitem>
@@ -475,6 +488,20 @@ strmod = "\
        </varlistentry>
 
        <varlistentry>
+         <term><option>-framework</option> <replaceable>name</replaceable></term>
+         <indexterm><primary><option>-framework</option></primary></indexterm>
+         <listitem>
+           <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
+           This option corresponds to the <option>-framework</option> option for Apple's Linker.
+           Please note that frameworks and packages are two different things - frameworks don't
+           contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
+           To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
+           <option>-framework Carbon</option>.
+           </para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
          <term><option>-L</option><replaceable>dir</replaceable></term>
          <indexterm><primary><option>-L</option></primary></indexterm>
          <listitem>
@@ -485,6 +512,16 @@ strmod = "\
        </varlistentry>
 
        <varlistentry>
+         <term><option>-framework-path</option><replaceable>dir</replaceable></term>
+         <indexterm><primary><option>-framework-path</option></primary></indexterm>
+         <listitem>
+           <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
+            the framework directories path. This option corresponds to the <option>-F</option>
+           option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
          <term><option>-split-objs</option></term>
          <indexterm><primary><option>-split-objs</option></primary></indexterm>
          <listitem>
@@ -518,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>
@@ -526,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
@@ -536,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>