[project @ 2005-11-10 10:50:39 by simonmar]

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

diff --git a/ghc/docs/users_guide/using.xml b/ghc/docs/users_guide/using.xml
index 80b8790..f9deafe 100644 (file)
--- a/ghc/docs/users_guide/using.xml
+++ b/ghc/docs/users_guide/using.xml
@@ -96,21 +96,47 @@ module X where
   </sect1>
     
   <sect1 id="static-dynamic-flags">
-    <title>Static vs. Dynamic options</title>
+    <title>Static, Dynamic, and Mode options</title>
     <indexterm><primary>static</primary><secondary>options</secondary>
     </indexterm>
     <indexterm><primary>dynamic</primary><secondary>options</secondary>
     </indexterm>
+    <indexterm><primary>mode</primary><secondary>options</secondary>
+    </indexterm>
 
     <para>Each of GHC's command line options is classified as either
-    <firstterm>static</firstterm> or <firstterm>dynamic</firstterm>.
-    A static flag may only be specified on the command line, whereas a
-    dynamic flag may also be given in an <literal>OPTIONS_GHC</literal>
-    pragma in a source file or set from the GHCi command-line with
-    <literal>:set</literal>.</para>
-
-    <para>As a rule of thumb, options which relate to filenames are
-    static, and the rest are dynamic. The flag reference tables (<xref
+    <firstterm>static</firstterm> or <firstterm>dynamic</firstterm> or
+      <firstterm>mode</firstterm>:</para>
+
+    <variablelist>
+      <varlistentry>
+       <term>Mode flags</term>
+       <listitem>
+         <para>For example, <option>--make</option> or <option>-E</option>.
+           There may be only a single mode flag on the command line.  The
+           available modes are listed in <xref linkend="modes"/>.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>Dynamic Flags</term>
+       <listitem>
+         <para>Most non-mode flags fall into this category.  A dynamic flag
+           may be used on the command line, in a
+           <literal>GHC_OPTIONS</literal> pragma in a source file, or set
+           using <literal>:set</literal> in GHCi.</para>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>Static Flags</term>
+       <listitem>
+         <para>A few flags are "static", which means they can only be used on
+           the command-line, and remain in force over the entire GHC/GHCi
+           run.</para>
+       </listitem>
+      </varlistentry>
+    </variablelist>
+    
+    <para>The flag reference tables (<xref
     linkend="flag-reference"/>) lists the status of each flag.</para>
   </sect1>
 
@@ -515,6 +541,30 @@ ghc -c Foo.hs</screen>
       of the compiler, dumping the result in a file.  Note that this
       differs from the previous behaviour of dumping the file to
       standard output.</para>
+
+      <sect3 id="overriding-suffixes">
+       <title>Overriding the default behaviour for a file</title>
+
+       <para>As described above, the way in which a file is processed by GHC
+         depends on its suffix.  This behaviour can be overriden using the
+         <option>-x</option> option:</para>
+
+       <variablelist>
+         <varlistentry>
+           <term><option>-x</option> <replaceable>suffix</replaceable>
+                     <indexterm><primary><option>-x</option></primary>
+             </indexterm></term>
+             <listitem>
+               <para>Causes all files following this option on the command
+                 line to be processed as if they had the suffix
+                 <replaceable>suffix</replaceable>.  For example, to compile a
+                 Haskell module in the file <literal>M.my-hs</literal>,
+                 use <literal>ghc -c -x hs M.my-hs</literal>.</para>
+             </listitem>
+         </varlistentry>
+       </variablelist>
+      </sect3>
+
     </sect2>
   </sect1>
 
@@ -1290,6 +1340,18 @@ f "2"    = 2
 
        <varlistentry>
          <term>
+            <option>-fno-cse</option>
+            <indexterm><primary><option>-fno-cse</option></primary></indexterm>
+          </term>
+         <listitem>
+           <para>Turns off the common-sub-expression elimination optimisation.
+             Can be useful if you have some <literal>unsafePerformIO</literal>
+           expressions that you don't want commoned-up.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>
             <option>-fno-strictness</option>
             <indexterm><primary><option>-fno-strictness</option></primary></indexterm>
           </term>
@@ -1301,12 +1363,27 @@ f "2"    = 2
 
        <varlistentry>
          <term>
-            <option>-fno-cpr-analyse</option>
-            <indexterm><primary><option>-fno-cpr-analyse</option></primary></indexterm>
+            <option>-fno-full-laziness</option>
+            <indexterm><primary><option>-fno-full-laziness</option></primary></indexterm>
+          </term>
+         <listitem>
+           <para>Turns off the full laziness optimisation (also known as
+             let-floating).  Full laziness increases sharing, which can lead
+             to increased memory residency.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>
+            <option>-fno-state-hack</option>
+            <indexterm><primary><option>-fno-state-hack</option></primary></indexterm>
           </term>
          <listitem>
-           <para>Turns off the CPR (constructed product result)
-           analysis; it is somewhat experimental.</para>
+           <para>Turn off the "state hack" whereby any lambda with a
+             <literal>State#</literal> token as argument is considered to be
+             single-entry, hence it is considered OK to inline things inside
+             it.  This can improve performance of IO and ST monad code, but it
+           runs the risk of reducing sharing.</para> 
          </listitem>
        </varlistentry>