[commit: ghc] master: Document -funbox-strict-primitive-fields (4f7027d)

Repository : ssh://darcs.haskell.org//srv/darcs/ghc

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/4f7027d6947af9c5cdecc0c18097268594c4592b

>---------------------------------------------------------------

commit 4f7027d6947af9c5cdecc0c18097268594c4592b
Author: Johan Tibell <[email protected]>
Date:   Fri Dec 7 09:00:04 2012 -0800

    Document -funbox-strict-primitive-fields

>---------------------------------------------------------------

 docs/users_guide/flags.xml |    8 ++++++++
 docs/users_guide/using.xml |   25 +++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 0 deletions(-)

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 0e7ed23..d433dcb 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1740,6 +1740,14 @@
           </row>
 
           <row>
+            <entry><option>-funbox-strict-primitive-fields</option></entry>
+            <entry>Flatten strict constructor fields with a
+              pointer-sized representation</entry>
+            <entry>dynamic</entry>
+            <entry><option>-fno-unbox-strict-primitive-fields</option></entry>
+          </row>
+
+          <row>
             <entry><option>-funfolding-creation-threshold</option></entry>
             <entry>Tweak unfolding settings</entry>
             <entry>dynamic</entry>
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index c3a1366..fb1a7cc 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -1862,6 +1862,31 @@ f "2"    = 2
 
         <varlistentry>
           <term>
+            <option>-funbox-strict-primitive-fields</option>:
+            <indexterm><primary><option>-funbox-strict-primitive-fields</option></primary></indexterm>
+            <indexterm><primary>strict constructor fields</primary></indexterm>
+            <indexterm><primary>constructor fields, strict</primary></indexterm>
+          </term>
+          <listitem>
+            <para>This option causes all constructor fields which are marked
+            strict (i.e. &ldquo;!&rdquo;) and which representation is smaller or
+            equal to the size of a pointer to be unpacked if possible. It is
+            equivalent to adding an <literal>UNPACK</literal> pragma to every
+            strict constructor field that fullfills the size restriction. (see
+            <xref linkend="unpack-pragma"/>).
+            </para>
+
+            <para>This option is less of a sledgehammer than
+            <option>-funbox-strict-fields</option>: it should rarely make things
+            worse. If you use <option>-funbox-strict-primitive-fields</option>
+            to turn on unboxing by default you can disable it for certain
+            constructor fields using the <literal>NOUNPACK</literal> pragma (see
+            <xref linkend="nounpack-pragma"/>).</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
             <option>-fspec-constr</option>
             <indexterm><primary><option>-fspec-constr</option></primary></indexterm>
           </term>