Document the new RTS linker flags

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 1a26bee..7a52bdf 100644 (file)
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1819,6 +1819,21 @@ phase <replaceable>n</replaceable></entry>
              <entry>-</entry>
            </row>
            <row>
+             <entry><option>-rtsopts</option></entry>
+             <entry>Allow the RTS behaviour to be tweaked via command-line
+          flags and the <literal>GHCRTS</literal> environment
+          variable.</entry>
+             <entry>dynamic</entry>
+             <entry>-</entry>
+           </row>
+           <row>
+             <entry><option>-with-rtsopts=<replaceable>opts</replaceable></option></entry>
+             <entry>Set the default RTS options to
+          <replaceable>opts</replaceable>.</entry>
+             <entry>dynamic</entry>
+             <entry>-</entry>
+           </row>
+           <row>
              <entry><option>-no-link</option></entry>
              <entry>Omit linking</entry>
              <entry>dynamic</entry>

diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 9f06ba8..14732c5 100644 (file)
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -10,7 +10,8 @@
   code and then links it with a non-trivial runtime system (RTS),
   which handles storage management, profiling, etc.</para>
 
-  <para>You have some control over the behaviour of the RTS, by giving
+  <para>If you use the <literal>-rtsopts</literal> flag when linking,
+  you have some control over the behaviour of the RTS, by giving
   special command-line arguments to your program.</para>
 
   <para>When your Haskell program starts up, its RTS extracts
@@ -68,7 +69,8 @@
     <indexterm><primary>environment variable</primary><secondary>for
     setting RTS options</secondary></indexterm>
 
-    <para>RTS options are also taken from the environment variable
+    <para>When the <literal>-rtsopts</literal> flag is used when linking,
+    RTS options are also taken from the environment variable
     <envar>GHCRTS</envar><indexterm><primary><envar>GHCRTS</envar></primary>
       </indexterm>.  For example, to set the maximum heap size
     to 128M for all GHC-compiled programs (using an
@@ -1045,6 +1047,20 @@
 
   </sect2>
 
+  <sect2>
+    <title>Linker flags to change RTS behaviour</title>
+
+    <indexterm><primary>RTS behaviour, changing</primary></indexterm>
+
+    <para>
+      GHC lets you exercise rudimentary control over the RTS settings
+      for any given program, by using the <literal>-with-rtsopts</literal>
+      linker flag. For example, to set <literal>-H128m -K1m</literal>,
+      link with <literal>-with-rtsopts="-H128m -K1m"</literal>.
+    </para>
+
+  </sect2>
+
   <sect2 id="rts-hooks">
     <title>&ldquo;Hooks&rdquo; to change RTS behaviour</title>