Document the new RTS linker flags

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

diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 2b16234..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
@@ -850,15 +852,16 @@
     <variablelist>
       <varlistentry>
         <term>
-          <option>-l<optional><replaceable>type</replaceable></optional></option>
+          <option>-l<optional><replaceable>flags</replaceable></optional></option>
           <indexterm><primary><option>-l</option></primary><secondary>RTS option</secondary></indexterm>
         </term>
         <listitem>
           <para>
             Log events in binary format to the
             file <filename><replaceable>program</replaceable>.eventlog</filename>,
-            where <replaceable>type</replaceable> indicates the type
-            of events to log.  Currently there is only one type
+            where <replaceable>flags</replaceable> is a sequence of
+            zero or more characters indicating which kinds of events
+            to log.  Currently there is only one type
             supported: <literal>-ls</literal>, for scheduler events.
           </para>
 
@@ -878,13 +881,19 @@
 
       <varlistentry>
         <term>
-          <option>-v</option>
+          <option>-v</option><optional><replaceable>flags</replaceable></optional>
           <indexterm><primary><option>-v</option></primary><secondary>RTS option</secondary></indexterm>
         </term>
         <listitem>
           <para>
             Log events as text to standard output, instead of to
             the <literal>.eventlog</literal> file.
+            The <replaceable>flags</replaceable> are the same as
+            for <option>-l</option>, with the additional
+            option <literal>t</literal> which indicates that the
+            each event printed should be preceded by a timestamp value
+            (in the binary <literal>.eventlog</literal> file, all
+            events are automatically associated with a timestamp).
           </para>
         </listitem>
       </varlistentry>
@@ -973,20 +982,13 @@
         </term>
        <listitem>
          <para>Produce &ldquo;ticky-ticky&rdquo; statistics at the
-          end of the program run.  The <replaceable>file</replaceable>
-          business works just like on the <option>-S</option> RTS
-          option (above).</para>
-
-         <para>&ldquo;Ticky-ticky&rdquo; statistics are counts of
-          various program actions (updates, enters, etc.)  The program
-          must have been compiled using
-          <option>-ticky</option><indexterm><primary><option>-ticky</option></primary></indexterm>
-          (a.k.a. &ldquo;ticky-ticky profiling&rdquo;), and, for it to
-          be really useful, linked with suitable system libraries.
-          Not a trivial undertaking: consult the installation guide on
-          how to set things up for easy &ldquo;ticky-ticky&rdquo;
-          profiling.  For more information, see <xref
-          linkend="ticky-ticky"/>.</para>
+          end of the program run (only available if the program was
+          linked with <option>-debug</option>).
+          The <replaceable>file</replaceable> business works just like
+          on the <option>-S</option> RTS option, above.</para>
+
+          <para>For more information on ticky-ticky profiling, see
+          <xref linkend="ticky-ticky"/>.</para>
        </listitem>
       </varlistentry>
 
@@ -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>