various updates to the release notes

diff --git a/docs/users_guide/6.10.1-notes.xml b/docs/users_guide/6.10.1-notes.xml
index f005e4c..442618f 100644 (file)
--- a/docs/users_guide/6.10.1-notes.xml
+++ b/docs/users_guide/6.10.1-notes.xml
@@ -56,6 +56,47 @@
       </listitem>
       <listitem>
         <para>
+          FFI change: header files are now <emphasis>not
+            used</emphasis> when compiling via C.
+            The <option>-#include</option> flag,
+            the <literal>includes</literal> field
+            in <literal>.cabal</literal> files, and header files
+            specified in a <literal>foreign import</literal>
+            declaration all have no effect when compiling Haskell
+          source code.</para>
+
+        <para>This change has important ramifications if you are
+          calling FFI functions that are defined by macros (or renamed
+          by macros).  If you need to call one of these functions,
+          then write a C wrapper for the function and call the wrapper
+          using the FFI instead.  In this way, your code will work
+          with GHC 6.10.1, and will also work
+          with <option>-fasm</option> in older GHCs.</para>
+
+        <para>This change was made for several reasons.
+          Firstly, <option>-fvia-C</option> now behaves consistently
+          with <option>-fasm</option>, which is important because we
+          intend to stop compiling via C in the future.  Also, we
+          don't need to worry about the interactions between header
+          files, or CPP options necessary to expose certain functions
+          from the system header files (this was becoming quite a
+          headache).  We don't need to worry about needing header
+          files when inlining FFI calls across module or package
+          boundaries; calls can now be inlined freely.  One downside
+          is that you don't get a warning from the C compiler when you
+          call a function via the FFI at the wrong type.
+        </para>
+
+        <para>Another consequence of this change is that
+          calling <emphasis>varargs</emphasis> functions (such
+          as <literal>printf</literal>) via the FFI no longer works.
+          It has never been officially supported (the FFI spec outlaws
+          it), but in GHC 6.10.1 it may now really cause a crash on
+          certain platforms.  Again, to call one of these functions
+          use appropriate fixed-argument C wrappers.</para>
+      </listitem>
+      <listitem>
+        <para>
           There is a new languages extension PackageImports which allows
           imports to be qualified with the package they should come
           from, e.g.
@@ -64,7 +105,10 @@
 import "network" Network.Socket
 </programlisting>
         <para>
-          See <xref linkend="package-imports" /> for more details.
+          Note that this feature is not intended for general use, it
+          was added for constructing backwards-compatibility packages
+          such as the <literal>base-3.0.3.0</literal> package.  See
+          <xref linkend="package-imports" /> for more details.
         </para>
       </listitem>
       <listitem>
@@ -77,30 +121,6 @@ import "network" Network.Socket
       </listitem>
       <listitem>
         <para>
-          When compiling with <literal>-fvia-C</literal>, we no longer
-          use the C header files. Instead we rely on all the type
-          information being given as part of the FFI import declaration.
-          This makes it more consistent with <literal>-fasm</literal>.
-        </para>
-        <para>
-          This means that, unlike <literal>-fasm</literal>,
-          <literal>-fvia-C</literal> is no longer able to
-          call varargs functions.
-        </para>
-        <para>
-          Also, if you were using <literal>-fvia-C</literal> because
-          your program didn't work with <literal>-fasm</literal>, then
-          it probably won't work with <literal>-fvia-C</literal> either
-          now.
-        </para>
-        <para>
-          We recommend using <literal>-fasm</literal> (the default).
-          We expect to remove the <literal>-fvia-C</literal>
-          functionality in the 6.12 release.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
           GHC now treats the Unicode "Letter, Other" class as lowercase
           letters. This is an arbitrary choice, but better than not
           allowing them in identifiers at all. This may be revisited
@@ -576,8 +596,9 @@ Prelude&gt;
       </listitem>
       <listitem>
         <para>
-          GHCi can now use libffi to make FFI calls, which means that
-          it now works on all platforms that libffi supports.
+          GHCi now uses libffi to make FFI calls, which means that the
+          FFI now works in GHCi on a much wider range of platforms
+          (all those platforms that libffi supports).
         </para>
       </listitem>
     </itemizedlist>
@@ -585,27 +606,43 @@ Prelude&gt;
 
   <sect2>
     <title>Runtime system changes</title>
-
+    
     <itemizedlist>
       <listitem>
         <para>
-          If the user presses control-C while running a Haskell program
-          then the program gets an asynchronous UserInterrupt exception.
+          The garbage collector can now use multiple threads in parallel.
+          The new <literal>-g<replaceable>n</replaceable></literal> RTS
+          flag controls it, e.g. run your program with
+          <literal>+RTS -g2 -RTS</literal> to use 2 threads.
+          The <option>-g</option> option is implied by the
+          usual <option>-N</option> option, so normally there will be
+          no need to specify it separately, although occasionally it
+          is useful to turn it off with <option>-g1</option>.</para>
+        <para>Do let us know if you experience strange effects,
+          especially an increase in GC time when using the parallel GC
+          (use <option>+RTS -s -RTS</option> to measure GC time).
+          See <xref linkend="rts-options-gc" /> for more details.</para>
+      </listitem>
+      <listitem>
+        <para>
+          It is now possible to generate a heap profile without
+          recompiling your program for profiling.  Run the program
+          with <option>+RTS -hT</option> to generate a basic heap
+          profile, and use <command>hp2ps</command> as usual to
+          convert the heap profile into a <literal>.ps</literal> file
+          for viewing.  See <xref linkend="rts-profiling" /> for more
+          details.
         </para>
       </listitem>
       <listitem>
         <para>
-          We now ignore SIGPIPE by default.
+          If the user presses control-C while running a Haskell program
+          then the program gets an asynchronous UserInterrupt exception.
         </para>
       </listitem>
       <listitem>
         <para>
-          The garbage collector can now use multiple threads in parallel.
-          The new <literal>-g<replaceable>n</replaceable></literal> RTS
-          flag controls it, e.g. run your program with
-          <literal>+RTS -g2 -RTS</literal> to use 2 threads.
-          Don't use more threads than you have CPUs.
-          Only major GCs are parallelised; minor GCs are still sequential.
+          We now ignore SIGPIPE by default.
         </para>
       </listitem>
       <listitem>
@@ -663,6 +700,12 @@ Prelude&gt;
 
     <itemizedlist>
       <listitem>
+        <para>ghc-pkg will refuse to unregister a package on which
+          other packages depend, unless
+          the <option>&ndash;&ndash;force</option> option is also
+          supplied.</para>
+      </listitem>
+      <listitem>
         <para>
           ghc-pkg now has a <literal>-no-user-package-conf</literal>
           flag which instructs it to ignore the user's personal
@@ -768,6 +811,11 @@ Prelude&gt;
           </para>
         </listitem>
         <listitem>
+          <para>The <literal>Show</literal> instance
+            for <literal>Ratio</literal> now puts spaces around
+            the <literal>%</literal>, as required by Haskell 98.</para>
+        </listitem>
+        <listitem>
           <para>
             There is a new module <literal>Control.Category</literal>.
           </para>