refactor and tidy up the section on RTS options

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

diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml
index 81be0a5..b48ebe8 100644 (file)
--- a/docs/users_guide/phases.xml
+++ b/docs/users_guide/phases.xml
@@ -359,44 +359,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 +397,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>
@@ -1042,6 +991,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>