From: simonmar <unknown>
Date: Tue, 7 Aug 2001 09:58:39 +0000 (+0000)
Subject: [project @ 2001-08-07 09:58:39 by simonmar]
X-Git-Tag: Approximately_9120_patches~1345
X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=7c435dc127d3ca771ee02d03728c7b69a267a6b4;p=ghc-hetmet.git

[project @ 2001-08-07 09:58:39 by simonmar]
Document the GHCRTS env. var.
---

diff --git a/ghc/docs/users_guide/runtime_control.sgml b/ghc/docs/users_guide/runtime_control.sgml
index b7b6fab..e97a57d 100644
--- a/ghc/docs/users_guide/runtime_control.sgml
+++ b/ghc/docs/users_guide/runtime_control.sgml
@@ -60,10 +60,35 @@
   <literal>+RTS -M128m -RTS</literal>
   to the command line.</para>
 
+  <sect2 id="rts-optinos-environment">
+    <title>Setting global RTS options</title>
+
+    <indexterm><primary>RTS options</primary><secondary>from the environment</secondary></indexterm>
+    <indexterm><primary>environment variable</primary><secondary>for
+    setting RTS options</secondary></indexterm>
+
+    <para>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
+    <literal>sh</literal>-like shell):</para>
+
+<screen>
+   GHCRTS='-M128m'
+   export GHCRTS
+</screen>
+
+    <para>RTS options taken from the <envar>GHCRTS</envar> environment
+    variable can be overriden by options given on the command
+    line.</para>
+
+  </sect2>
+
   <sect2 id="rts-options-gc">
-    <title>RTS options to control the garbage-collector</title>
+    <title>RTS options to control the garbage collector</title>
 
-    <indexterm><primary>RTS options, garbage-collection</primary></indexterm>
+    <indexterm><primary>garbage collector</primary><secondary>options</secondary></indexterm>
+    <indexterm><primary>RTS options</primary><secondary>garbage collection</secondary></indexterm>
 
     <para>There are several options to give you precise control over
     garbage collection.  Hopefully, you won't need any of these in
@@ -96,6 +121,34 @@
       </varlistentry>
 
       <varlistentry>
+	<term><option>-c</option></term>
+	<indexterm><primary><option>-c</option></primary><secondary>RTS option</secondary>
+	</indexterm>
+	<indexterm><primary>garbage collection</primary><secondary>compacting</secondary>
+	</indexterm>
+	<indexterm><primary>compacting garbage collection</primary></indexterm>
+
+	<listitem>
+	  <para>Use a compacting algorithm for collecting the oldest
+	  generation.  By default, the oldest generation is collected
+	  using a copying algorithm; this option causes it to be
+	  compacted in-place instead.  The compaction algorithm is
+	  slower than the copying algorithm, but the savings in memory
+	  use can be considerable.</para>
+
+	  <para>For a given heap size (using the <option>-H</option>
+	  option), compaction can in fact reduce the GC cost by
+	  allowing fewer GCs to be performed.  This is more likely
+	  when the ratio of live data to heap size is high, say
+	  &gt;30&percnt;.</para>
+
+	  <para>NOTE: compaction doesn't currently work when a single
+	  generation is requested using the <option>-G1</option>
+	  option.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
 	<term><option>-F</option><replaceable>factor</replaceable></Term>
 	<listitem>
 	  <indexterm><primary><option>-F</option></primary><secondary>RTS option</secondary></indexterm>