Doc changes following changes to the way -rtsopts works

Mainly, -rtsopts doesn't work with -no-hs-main, and you have to do
something in your main() to get the effect of -rtsopts (and
-with-rtsopts).

3 files changed, 111 insertions, 64 deletions

diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml
index 340d07d64c..e6cf9edc92 100644
--- a/docs/users_guide/ffi-chap.xml
+++ b/docs/users_guide/ffi-chap.xml
@@ -278,40 +278,7 @@ int main(int argc, char *argv[])
 	(i.e. those arguments between
 	<literal>+RTS...-RTS</literal>).</para>
 
-      <informaltable>
-	<tgroup cols="2" align="left" colsep="1" rowsep="1">
-	  <thead>
-	    <row>
-	      <entry>Character</entry>
-	      <entry>Replacement</entry>
-	    </row>
-	  </thead>
-	  <tbody>
-	    <row>
-	      <entry><literal>.</literal></entry>
-	      <entry><literal>zd</literal></entry>
-	    </row>
-	    <row>
-	      <entry><literal>_</literal></entry>
-	      <entry><literal>zu</literal></entry>
-	    </row>
-	    <row>
-	      <entry><literal>`</literal></entry>
-	      <entry><literal>zq</literal></entry>
-	    </row>
-	    <row>
-	      <entry><literal>Z</literal></entry>
-	      <entry><literal>ZZ</literal></entry>
-	    </row>
-	    <row>
-	      <entry><literal>z</literal></entry>
-	      <entry><literal>zz</literal></entry>
-	    </row>
-          </tbody>
-        </tgroup>
-      </informaltable>
-
-	<para>After we've finished invoking our Haskell functions, we
+        <para>After we've finished invoking our Haskell functions, we
 	can call <literal>hs_exit()</literal>, which terminates the
 	RTS.</para>
 
@@ -331,6 +298,85 @@ int main(int argc, char *argv[])
 	<option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
 	  </indexterm>, otherwise GHC will try to link
 	to the <literal>Main</literal> Haskell module.</para>
+
+        <para>To use <literal>+RTS</literal> flags
+          with <literal>hs_init()</literal>, we have to modify the
+          example slightly.  By default, GHC's RTS will only accept
+          "safe"
+          <literal>+RTS</literal> flags (see
+          <xref linkend="options-linker" />), and
+          the <option>-rtsopts</option><indexterm><primary><option>-rtsopts</option></primary></indexterm> link-time flag overrides this.
+          However, <option>-rtsopts</option> has no effect
+          when <option>-no-hs-main</option> is in use (and the same
+          goes for <option>-with-rtsopts</option>).  To set these
+          options we have to call a GHC-specific API instead
+          of <option>hs_init()</option>:</para>
+
+<programlisting>
+#include &lt;stdio.h&gt;
+#include "HsFFI.h"
+
+#ifdef __GLASGOW_HASKELL__
+#include "foo_stub.h"
+#include "Rts.h"
+#endif
+
+int main(int argc, char *argv[])
+{
+  int i;
+
+#if __GLASGOW_HASKELL__ >= 703
+  {
+      RtsConfig conf = defaultRtsConfig;
+      conf.rts_opts_enabled = RtsOptsAll;
+      hs_init_ghc(&amp;argc, &amp;argv, conf);
+  }
+#else
+  hs_init(&amp;argc, &amp;argv);
+#endif
+
+  for (i = 0; i &lt; 5; i++) {
+    printf("%d\n", foo(2500));
+  }
+
+  hs_exit();
+  return 0;
+}</programlisting>
+
+      <para>Note two changes: we included <literal>Rts.h</literal>,
+        which defines the GHC-specific external RTS interface, and we
+        called <literal>hs_init_ghc()</literal> instead
+        of <literal>hs_init()</literal>, passing an argument of
+        type <literal>RtsConfig</literal>.
+        <literal>RtsConfig</literal> is a struct with various fields
+        that affect the behaviour of the runtime system.  Its
+        definition is:</para>
+
+<programlisting>
+typedef struct {
+    RtsOptsEnabledEnum rts_opts_enabled;
+    const char *rts_opts;
+} RtsConfig;
+
+extern const RtsConfig defaultRtsConfig;
+
+typedef enum {
+    RtsOptsNone,         // +RTS causes an error
+    RtsOptsSafeOnly,     // safe RTS options allowed; others cause an error
+    RtsOptsAll           // all RTS options allowed
+  } RtsOptsEnabledEnum;
+</programlisting>
+
+      <para>There is a default
+        value <literal>defaultRtsConfig</literal> that should be used
+        to initialise variables of type <literal>RtsConfig</literal>.
+        More fields will undoubtedly be added
+        to <literal>RtsConfig</literal> in the future, so in order to
+        keep your code forwards-compatible it is best to initialise
+        with <literal>defaultRtsConfig</literal> and then modify the
+        required fields, as in the code sample above.</para>
+
+
       </sect3>
 
       <sect3 id="ffi-library">
diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml
index 7158c14af4..2e23b95eaa 100644
--- a/docs/users_guide/phases.xml
+++ b/docs/users_guide/phases.xml
@@ -891,6 +891,18 @@ $ cat foo.hspp</screen>
           <literal>Main</literal> module present (normally the
           compiler will not attempt linking when there is no
           <literal>Main</literal>).</para>
+
+          <para>The flags <option>-rtsopts</option>
+            and <option>-with-rtsopts</option> have no effect when
+            used with <option>-no-hs-main</option>, because they are
+            implemented by changing the definition
+            of <literal>main</literal> that GHC generates.  See
+            <xref linkend="using-own-main" /> for how to get the
+            effect of <option>-rtsopts</option>
+            and <option>-with-rtsopts</option> when using your
+            own <literal>main</literal>.
+          </para>
+
         </listitem>
       </varlistentry>
 
@@ -1024,6 +1036,12 @@ $ cat foo.hspp</screen>
             security problem.  For this reason, GHC 7.0.1 and later
             default to <option>-rtsops=some</option>.
           </para>
+
+          <para>
+            Note that <option>-rtsopts</option> has no effect when
+            used with <option>-no-hs-main</option>; see
+            <xref linkend="using-own-main" /> for details.
+          </para>
         </listitem>
       </varlistentry>
 
@@ -1042,6 +1060,12 @@ $ cat foo.hspp</screen>
             <option>-with-rtsopts</option> would be the <emphasis>only</emphasis> way to set
             them.)
           </para>
+
+          <para>
+            Note that <option>-with-rtsopts</option> has no effect when
+            used with <option>-no-hs-main</option>; see
+            <xref linkend="using-own-main" /> for details.
+          </para>
         </listitem>
       </varlistentry>
 
diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 20aca07cd3..57e89c7151 100644
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -135,8 +135,10 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
         <para>
           GHC lets you change the default RTS options for a program at
           compile time, using the <literal>-with-rtsopts</literal>
-          flag (<xref linkend="options-linker" />). For example, to
-          set <literal>-H128m -K64m</literal>, link
+          flag (<xref linkend="options-linker" />).  A common use for this is
+          to give your program a default heap and/or stack size that is
+          greater than the default.  For example, to set <literal>-H128m
+            -K64m</literal>, link
           with <literal>-with-rtsopts="-H128m -K64m"</literal>.
         </para>
       </sect3>
@@ -187,37 +189,17 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
     <indexterm><primary>RTS hooks</primary></indexterm>
     <indexterm><primary>RTS behaviour, changing</primary></indexterm>
 
-    <para>GHC lets you exercise rudimentary control over the RTS
+    <para>GHC lets you exercise rudimentary control over certain RTS
     settings for any given program, by compiling in a
     &ldquo;hook&rdquo; that is called by the run-time system.  The RTS
-    contains stub definitions for all these hooks, but by writing your
+    contains stub definitions for these hooks, but by writing your
     own version and linking it on the GHC command line, you can
     override the defaults.</para>
 
     <para>Owing to the vagaries of DLL linking, these hooks don't work
     under Windows when the program is built dynamically.</para>
 
-    <para>The hook <literal>ghc_rts_opts</literal><indexterm><primary><literal>ghc_rts_opts</literal></primary>
-      </indexterm>lets you set RTS
-    options permanently for a given program, in the same way as the
-    newer <option>-with-rtsopts</option> linker option does.  A common use for this is
-    to give your program a default heap and/or stack size that is
-    greater than the default.  For example, to set <literal>-H128m
-    -K1m</literal>, place the following definition in a C source
-    file:</para>
-
-<programlisting>
-char *ghc_rts_opts = "-H128m -K1m";
-</programlisting>
-
-    <para>Compile the C file, and include the object file on the
-    command line when you link your Haskell program.</para>
-
-    <para>These flags are interpreted first, before any RTS flags from
-    the <literal>GHCRTS</literal> environment variable and any flags
-    on the command line.</para>
-
-    <para>You can also change the messages printed when the runtime
+    <para>You can change the messages printed when the runtime
     system &ldquo;blows up,&rdquo; e.g., on stack overflow.  The hooks
     for these are as follows:</para>
 
@@ -254,11 +236,6 @@ char *ghc_rts_opts = "-H128m -K1m";
 	</listitem>
       </varlistentry>
     </variablelist>
-
-    <para>For examples of the use of these hooks, see GHC's own
-    versions in the file
-    <filename>ghc/compiler/parser/hschooks.c</filename> in a GHC
-    source tree.</para>
   </sect3>
 
     </sect2>