more typos (#5225)
[ghc-hetmet.git] / docs / users_guide / phases.xml
index 81be0a5..863838c 100644 (file)
@@ -5,7 +5,7 @@
   <sect2 id="replacing-phases">
     <title>Replacing the program for one or more phases</title>
     <indexterm><primary>phases, changing</primary></indexterm>
-    
+
     <para>You may specify that a different program be used for one
     of the phases of the compilation system, in place of whatever
     the <command>ghc</command> has wired into it.  For example, you
 
       <varlistentry>
         <term>
-          <option>-pgmm</option> <replaceable>cmd</replaceable>
-          <indexterm><primary><option>-pgmm</option></primary></indexterm>
-        </term>
-        <listitem>
-          <para>Use <replaceable>cmd</replaceable> as the
-          mangler.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
           <option>-pgms</option> <replaceable>cmd</replaceable>
           <indexterm><primary><option>-pgms</option></primary></indexterm>
         </term>
@@ -359,44 +348,6 @@ $ cat foo.hspp</screen>
     <variablelist>
       <varlistentry>
         <term>
-          <constant>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</constant>
-          <indexterm><primary><literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</literal></primary></indexterm>
-        </term>
-        <listitem>
-          <para>If defined, this means that GHC supports the
-          language defined by the Haskell 98 report.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant>
-          <indexterm><primary><constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;=98</constant></primary></indexterm>
-        </term>
-        <listitem>
-          <para>In GHC 4.04 and later, the
-          <constant>&lowbar;&lowbar;HASKELL&lowbar;&lowbar;</constant>
-          macro is defined as having the value
-          <constant>98</constant>.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant>
-          <indexterm><primary><constant>&lowbar;&lowbar;HASKELL1&lowbar;&lowbar;</constant></primary></indexterm>
-        </term>
-        <listitem>
-          <para>If defined to <replaceable>n</replaceable>, that
-          means GHC supports the Haskell language defined in the
-          Haskell report version <emphasis>1.n</emphasis>.
-          Currently 5.  This macro is deprecated, and will probably
-          disappear in future versions.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
           <constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant>
           <indexterm><primary><constant>&lowbar;&lowbar;GLASGOW&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
         </term>
@@ -435,19 +386,6 @@ $ cat foo.hspp</screen>
       </varlistentry>
 
       <varlistentry>
-      <term>
-          <constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant>
-          <indexterm><primary><constant>&lowbar;&lowbar;CONCURRENT&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
-        </term>
-      <listitem>
-        <para>This symbol is defined when pre-processing Haskell
-          (input) and pre-processing C (GHC output).  Since GHC from
-          version 4.00 now supports concurrent haskell by default,
-          this symbol is always defined.</para>
-        </listitem>
-      </varlistentry>
-      
-      <varlistentry>
         <term>
           <constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant>
           <indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
@@ -471,7 +409,7 @@ $ cat foo.hspp</screen>
           for Windows, <literal>solaris</literal>, etc.).</para>
         </listitem>
       </varlistentry>
-        
+
       <varlistentry>
         <term>
           <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
@@ -499,7 +437,7 @@ $ cat foo.hspp</screen>
 <programlisting>strmod = "\
 \ p \
 \ "</programlisting>
-      
+
       <para>don't work with <option>-cpp</option>;
       <filename>/usr/bin/cpp</filename> elides the backslash-newline
       pairs.</para>
@@ -514,7 +452,7 @@ $ cat foo.hspp</screen>
 
   <sect2 id="pre-processor">
     <title>Options affecting a Haskell pre-processor</title>
-    
+
     <indexterm><primary>pre-processing: custom</primary></indexterm>
     <indexterm><primary>Pre-processor options</primary></indexterm>
 
@@ -594,21 +532,8 @@ $ cat foo.hspp</screen>
         </term>
         <listitem>
           <para>Use GHC's native code generator rather than
-          compiling via C.  This will compile faster (up to twice as
-          fast), but may produce code that is slightly slower than
-          compiling via C.  <option>-fasm</option> is the default.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <option>-fvia-C</option>
-          <indexterm><primary><option>-fvia-C</option></primary></indexterm>
-        </term>
-        <listitem>
-          <para>Compile via C instead of using the native code
-          generator.  This is the default on architectures for which GHC
-          doesn't have a native code generator.</para>
+          compiling via LLVM.
+          <option>-fasm</option> is the default.</para>
         </listitem>
       </varlistentry>
 
@@ -620,8 +545,8 @@ $ cat foo.hspp</screen>
         <listitem>
           <para>Compile via LLVM instead of using the native code
           generator. This will generally take slightly longer than the
-          native code generator to compile but quicker than compiling
-          via C. Produced code is generally the same speed or faster
+          native code generator to compile.
+          Produced code is generally the same speed or faster
           than the other two code generators. Compiling via LLVM
           requires LLVM version 2.7 or later to be on the path.</para>
         </listitem>
@@ -930,11 +855,11 @@ $ cat foo.hspp</screen>
             However, if all the modules are otherwise up to date, you may need to force
             recompilation both of the module where the new "main" is, and of the
             module where the "main" function used to be;
-            <literal>ghc</literal> is not clever 
+            <literal>ghc</literal> is not clever
             enough to figure out that they both need recompiling.  You can
             force recompilation by removing the object file, or by using the
             <option>-fforce-recomp</option> flag.
-            </para> 
+            </para>
         </listitem>
       </varlistentry>
 
@@ -1003,7 +928,7 @@ $ cat foo.hspp</screen>
           <para>The threaded runtime system provides the following
           benefits:</para>
 
-          <itemizedlist> 
+          <itemizedlist>
             <listitem>
               <para>Parallelism<indexterm><primary>parallelism</primary></indexterm> on a multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm> or multicore<indexterm><primary>multicore</primary></indexterm>
               machine.  See <xref linkend="using-smp" />.</para>
@@ -1042,6 +967,86 @@ $ cat foo.hspp</screen>
 
       <varlistentry>
         <term>
+          <option>-rtsopts</option>
+          <indexterm><primary><option>-rtsopts</option></primary></indexterm>
+        </term>
+        <listitem>
+          <para>
+            This option affects the processing of RTS control options given either
+            on the command line or via the <envar>GHCRTS</envar> environment variable.
+            There are three possibilities:
+          </para>
+          <variablelist>
+            <varlistentry>
+              <term><option>-rtsopts=none</option></term>
+              <listitem>
+                <para>
+                  Disable all processing of RTS options.
+                  If <option>+RTS</option> appears anywhere on the command
+                  line, then the program will abort with an error message.
+                  If the <envar>GHCRTS</envar> environment variable is
+                  set, then the program will emit a warning message,
+                  <envar>GHCRTS</envar> will be ignored, and the program
+                  will run as normal.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term><option>-rtsopts=some</option></term>
+              <listitem>
+                <para>&lsqb;this is the default setting&rsqb; Enable
+                  only the "safe" RTS options: (Currently
+                  only <option>-?</option>
+                  and <option>--info</option>.)  Any other RTS options
+                  on the command line or in the <envar>GHCRTS</envar>
+                  environment variable causes the program with to abort
+                  with an error message.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term><option>-rtsopts=all</option>, or
+ just <option>-rtsopts</option></term>
+              <listitem>
+                <para>
+                  Enable <emphasis>all</emphasis> RTS option
+                  processing, both on the command line and through
+                  the <envar>GHCRTS</envar> environment variable.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+          <para>
+            In GHC 6.12.3 and earlier, the default was to process all
+            RTS options. However, since RTS options can be used to
+            write logging data to arbitrary files under the security
+            context of the running program, there is a potential
+            security problem.  For this reason, GHC 7.0.1 and later
+            default to <option>-rtsops=some</option>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>-with-rtsopts</option>
+          <indexterm><primary><option>-with-rtsopts</option></primary></indexterm>
+        </term>
+        <listitem>
+          <para>
+            This option allows you to set the default RTS options at link-time. For example,
+            <option>-with-rtsopts="-H128m"</option> sets the default heap size to 128MB.
+            This will always be the default heap size for this program, unless the user overrides it.
+            (Depending on the setting of the <option>-rtsopts</option> option, the user might
+            not have the ability to change RTS options at run-time, in which case
+            <option>-with-rtsopts</option> would be the <emphasis>only</emphasis> way to set
+            them.)
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
           <option>-fno-gen-manifest</option>
           <indexterm><primary><option>-fno-gen-manifest</option></primary>
           </indexterm>
@@ -1049,7 +1054,7 @@ $ cat foo.hspp</screen>
         <listitem>
           <para>On Windows, GHC normally generates a
             <firstterm>manifest</firstterm><indexterm><primary>manifest</primary>
-            </indexterm>file when linking a binary.  The
+            </indexterm> file when linking a binary.  The
             manifest is placed in the file
             <literal><replaceable>prog</replaceable>.exe.manifest</literal>
             where <replaceable>prog.exe</replaceable> is the name of the
@@ -1069,7 +1074,7 @@ $ cat foo.hspp</screen>
             system using the security control panel, but GHC by default
             generates binaries that don't depend on the user having disabled
             installer detection.</para>
-          
+
           <para>The <option>-fno-gen-manifest</option> disables generation of
             the manifest file.  One reason to do this would be if you had
             a manifest file of your own, for example.</para>
@@ -1081,7 +1086,7 @@ $ cat foo.hspp</screen>
             <option>-fno-embed-manifest</option>, see below.</para>
         </listitem>
       </varlistentry>
-          
+
       <varlistentry>
         <term>
           <option>-fno-embed-manifest</option>
@@ -1097,15 +1102,15 @@ $ cat foo.hspp</screen>
             </indexterm>; to see exactly what GHC does to embed the manifest,
             use the <option>-v</option> flag.  A GHC installation comes with
             its own copy of <literal>windres</literal> for this reason.</para>
-          
+
           <para>See also <option>-pgmwindres</option> (<xref
-              linkend="replacing-phases" />) and 
+              linkend="replacing-phases" />) and
             <option>-optwindres</option> (<xref
                                             linkend="forcing-options-through"
               />).</para>
         </listitem>
       </varlistentry>
-          
+
       <varlistentry>
         <term>
           <option>-fno-shared-implib</option>
@@ -1120,7 +1125,7 @@ $ cat foo.hspp</screen>
             disk-space cost of creating this import library, which can be substantial - it
             might require as much space as the code itself, as Haskell DLLs tend to export
             lots of symbols.</para>
-            
+
           <para>As long as you are happy to only be able to link to the DLL using
             <literal>GetProcAddress</literal> and friends, you can supply the
             <option>-fno-shared-implib</option> flag to disable the creation of the import