[project @ 2005-03-09 04:13:13 by wolfgang]

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

diff --git a/ghc/docs/users_guide/phases.xml b/ghc/docs/users_guide/phases.xml
index c214c11..af80577 100644 (file)
--- a/ghc/docs/users_guide/phases.xml
+++ b/ghc/docs/users_guide/phases.xml
@@ -276,10 +276,8 @@
     symbols are defined by your local GHC installation, the following
     trick is useful:</para>
 
-<screen>
-  $ ghc -E -optP-dM -cpp foo.hs
-  $ cat foo.hspp
-</screen>
+<screen>$ ghc -E -optP-dM -cpp foo.hs
+$ cat foo.hspp</screen>
 
     <para>(you need a file <filename>foo.hs</filename>, but it isn't
     actually used).</para>
@@ -389,7 +387,7 @@
 
       <varlistentry>
        <term>
-          <constant><replaceable>os</replaceable>_TARGET_OS=1</constant>
+          <constant><replaceable>os</replaceable>_OS=1</constant>
         </term>
        <listitem>
          <para>This define allows conditional compilation based on
@@ -402,7 +400,7 @@
        
       <varlistentry>
        <term>
-          <constant><replaceable>arch</replaceable>_TARGET_ARCH=1</constant>
+          <constant><replaceable>arch</replaceable>_ARCH=1</constant>
         </term>
        <listitem>
          <para>This define allows conditional compilation based on
@@ -424,11 +422,9 @@
       gaps vs -cpp</primary></indexterm>.  In other words, strings
       such as the following:</para>
 
-rogramlisting>
-rmod = "\
-p \
-"
-programlisting>
+<programlisting>strmod = "\
+\ p \
+\ "</programlisting>
       
       <para>don't work with <option>-cpp</option>;
       <filename>/usr/bin/cpp</filename> elides the backslash-newline
@@ -504,13 +500,19 @@ programlisting>
 
     <para>If you are compiling with lots of foreign calls, you may
     need to tell the C&nbsp;compiler about some
-    <literal>&num;include</literal> files.  There is no real pretty
-    way to do this, but you can use this hack from the
-    command-line:</para>
+    <literal>&num;include</literal> files.  The Right Way to do this is to
+      add an <literal>INCLUDE</literal> pragma to the top of your source file
+      (<xref linkend="include-pragma" />):</para>
 
-creen>
-ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs
-screen>
+<programlisting>{-# INCLUDE &lt;X/Xlib.h&gt; #-}</programlisting>
+      
+    <para>Sometimes this isn't convenient.  In those cases there's an
+      equivalent command-line option:</para>
+
+<screen>% ghc -c '-#include &lt;X/Xlib.h&gt;' Xstuff.lhs</screen>
+
+    <indexterm><primary><option>-#include</option></primary>
+    </indexterm>
 
   </sect2>
 
@@ -557,6 +559,38 @@ screen>
           dumps of the intermediate compilation phases.</para>
         </listitem>
       </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>-fPIC</option>
+          <indexterm><primary><option>-fPIC</option></primary></indexterm>
+        </term>
+        <listitem>
+          <para>Generate position-independent code (code that can be put into
+          shared libraries). This currently works on Mac OS X; it works on
+          PowerPC Linux when using the native code generator (-fasm).
+          It is not quite ready to be used yet for x86 Linux.
+          On Windows, position-independent code is never used,
+          and on PowerPC64 Linux, position-independent code is always used,
+          so the flag is a no-op on those platforms.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>-dynamic</option>
+        </term>
+        <listitem>
+          <para>When generating code, assume that entities imported from a
+          different package will reside in a different shared library or
+          binary. This currently works on Mac OS X; it works on PowerPC Linux when
+          using the native code generator. As with <option>-fPIC</option>,
+          x86 Linux support is not quite ready yet. Windows is not supported,
+          and it is a no-op on PowerPC64 Linux.</para>
+          <para>Note that this option also causes GHC to use shared libraries
+          when linking.</para>
+        </listitem>
+      </varlistentry>
     </variablelist>
   </sect2>
 
@@ -615,15 +649,15 @@ screen>
 
       <varlistentry>
         <term>
-          <option>-no-link</option>
-          <indexterm><primary><option>-no-link</option></primary></indexterm>
+          <option>-c</option>
+          <indexterm><primary><option>-c</option></primary></indexterm>
         </term>
         <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>
+          <para>Omits the link step.  This option can be used with
+           <option>&ndash;&ndash;make</option> to avoid the automatic linking
+           that takes place if the program contains a <literal>Main</literal>
+           module.</para>
+       </listitem>
       </varlistentry>
 
       <varlistentry>
@@ -715,9 +749,11 @@ screen>
         </term>
         <listitem>
           <para>Tell the linker to use shared Haskell libraries, if
-          available (this option is only supported on Windows at the
+          available (this option is only supported on Mac OS X at the
           moment, and also note that your distribution of GHC may
           not have been supplied with shared libraries).</para>
+          <para>Note that this option also has an effect on
+          code generation (see above).</para>
         </listitem>
       </varlistentry>