Add release notes for the compiler

3 files changed, 745 insertions, 2 deletions

diff --git a/docs/users_guide/6.10.1-notes.xml b/docs/users_guide/6.10.1-notes.xml
new file mode 100644
index 0000000000..fd261b3a5e
--- /dev/null
+++ b/docs/users_guide/6.10.1-notes.xml
@@ -0,0 +1,743 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<sect1 id="release-6-10-1">
+  <title>Release notes for version 6.10.1</title>
+
+  <para>
+    The significant changes to the various parts of the compiler are
+    listed in the following sections.
+  </para>
+
+  <sect2>
+    <title>User-visible compiler changes</title>
+    <itemizedlist>
+      <listitem>
+        <para>
+          The new QuasiQuotes language extension adds
+          general quasi-quotation, as described in
+          "Nice to be Quoted: Quasiquoting for Haskell"
+          (Geoffrey Mainland, Haskell Workshop 2007).
+          See <xref linkend="th-quasiquotation" /> for more information.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The new ViewPatterns language extension allows
+          &quot;view patterns&quot;. The syntax for view patterns
+          is <literal>expression -> pattern</literal> in a pattern.
+          For more information, see <xref linkend="view-patterns" />.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GHC already supported (e op) postfix operators, but this
+          support was enabled by default. Now you need to use the
+          PostfixOperators language extension if you want it.
+          See <xref linkend="postfix-operators" /> for more information
+          on postfix operators.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The new TransformListComp language extension enables
+          implements generalised list comprehensions, as described in
+          the paper "Comprehensive comprehensions" (Peyton Jones &amp;
+          Wadler, Haskell Workshop 2007).
+          For more information see
+          <xref linkend="generalised-list-comprehensions" />.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          If you want to use impredicative types then you now need to
+          enable the ImpredicativeTypes language extension.
+          See <xref linkend="impredicative-polymorphism" /> for more
+          information.
+        </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.
+        </para>
+<programlisting>
+import "network" Network.Socket
+</programlisting>
+        <para>
+          See <xref linkend="package-imports" /> for more details.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          In earlier versions of GHC, the recompilation checker didn't
+          notice changes in other packages meant that recompilation is
+          needed. This is now handled properly, using MD5 checksums of
+          the interface ABIs.
+        </para>
+      </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
+          by Haskell'.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          In addition to the <literal>DEPRECATED</literal> pragma, you
+          can now attach arbitrary warnings to declarations with the new
+          <literal>WARNING</literal> pragma. See
+          <xref linkend="warning-deprecated-pragma" /> for more details.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          If GHC is failing due to <literal>-Werror</literal>, then it
+          now emits a message telling you so.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GHC now warns about unrecognised pragmas, as they are often
+          caused by a typo. The
+          <literal>-fwarn-unrecognised-pragmas</literal> controls
+          whether this warning is emitted.
+          The warning is enabled by default.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          There is a new flag
+          <literal>-fwarn-dodgy-foreign-imports</literal> which controls
+          a new warning about FFI delcarations of the form
+        </para>
+<programlisting>
+foreign import "f" f :: FunPtr t
+</programlisting>
+        <para>
+          on the grounds that it is probably meant to be
+        </para>
+<programlisting>
+foreign import "&amp;f" f :: FunPtr t
+</programlisting>
+        <para>
+          The warning is enabled by default.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          External core (output only) is working again.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          There is a new flag <literal>-dsuppress-uniques</literal> that
+          makes GHC's intermediate core easier to read. This flag cannot
+          be used when actually generating code.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          There is a new flag <literal>-dno-debug-output</literal> that
+          suppresses all of the debug information when running a
+          compiler built with the <literal>DEBUG</literal> option.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          A bug in earlier versions of GHC meant that sections didn't
+          always need to be parenthesised, e.g.
+          <literal>(+ 1, 2)</literal> was accepted. This has now been
+          fixed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>-fspec-threshold</literal> flag has been replaced
+          by <literal>-fspec-constr-threshold</literal> and
+          <literal>-fliberate-case-threshold</literal> flags.
+          The thresholds can be disabled by
+          <literal>-fno-spec-constr-threshold</literal> and
+          <literal>-fno-liberate-case-threshold</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The new flag <literal>-fsimplifier-phases</literal>
+          controls the number of simplifier phases run during
+          optimisation. These are numbered from n to 1 (by default, n=2).
+          Phase 0 is always run regardless of this flag.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Simplifier phases can have an arbitrary number of tags
+          assigned to them, and multiple phases can share the same tags.
+          The tags can be used as arguments to the new flag
+          <literal>-ddump-simpl-phases</literal>
+          to specify which phases are to be dumped.
+        </para>
+
+        <para>
+          For example,
+          <literal>-ddump-simpl-phases=main</literal> will dump the
+          output of phases 2, 1 and 0 of the initial simplifier run
+          (they all share the "main" tag) while
+          <literal>-ddump-simpl-phases=main:0</literal>
+          will dump only the output of phase 0 of that run.
+        </para>
+
+        <para>
+          At the moment, the supported tags are
+          main (the main, staged simplifier run (before strictness)),
+          post-worker-wrapper (after the w/w split),
+          post-liberate-case  (after LiberateCase), and
+          final (final clean-up run)
+        </para>
+
+        <para>
+          The names are somewhat arbitrary and will change in the future.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>-fno-method-sharing</literal> flag is now
+          dynamic (it used to be static).
+        </para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+  <sect2>
+    <title>Deprecated flags</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          The new flag <literal>-fwarn-deprecated-flags</literal>,
+          controls whether we warn about deprecated flags and language
+          extensions. The warning is on by default.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The following language extensions are now marked as
+          deprecated; expect them to be removed in a future release:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <literal>RecordPuns</literal>
+              (use <literal>NamedFieldPuns</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>PatternSignatures</literal>
+              (use <literal>ScopedTypeVariables</literal> instead)
+            </para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem>
+        <para>
+          The following flags are now marked as deprecated;
+          expect them to be removed in a future release:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <literal>-Onot</literal>
+              (use <literal>-O0</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-Wnot</literal>
+              (use <literal>-w</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-frewrite-rules</literal>
+              (use <literal>-fenable-rewrite-rules</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-no-link</literal>
+              (use <literal>-c</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-recomp</literal>
+              (use <literal>-fno-force-recomp</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-no-recomp</literal>
+              (use <literal>-fforce-recomp</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-syslib</literal>
+              (use <literal>-package</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fth</literal>
+              (use the <literal>TemplateHaskell</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-ffi</literal>, <literal>-fffi</literal>
+              (use the <literal>ForeignFunctionInterface</literal>
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-farrows</literal>
+              (use the <literal>Arrows</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fgenerics</literal>
+              (use the <literal>Generics</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fno-implicit-prelude</literal>
+              (use the <literal>NoImplicitPrelude</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fbang-patterns</literal>
+              (use the <literal>BangPatterns</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fno-monomorphism-restriction</literal>
+              (use the <literal>NoMonomorphismRestriction</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fmono-pat-binds</literal>
+              (use the <literal>MonoPatBinds</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fextended-default-rules</literal>
+              (use the <literal>ExtendedDefaultRules</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fimplicit-params</literal>
+              (use the <literal>ImplicitParams</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fscoped-type-variables</literal>
+              (use the <literal>ScopedTypeVariables</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fparr</literal>
+              (use the <literal>PArr</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fallow-overlapping-instances</literal>
+              (use the <literal>OverlappingInstances</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fallow-undecidable-instances</literal>
+              (use the <literal>UndecidableInstances</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fallow-incoherent-instances</literal>
+              (use the <literal>IncoherentInstances</literal> language
+              extension instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-optdep-s</literal>
+              (use <literal>-dep-suffix</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-optdep-f</literal>
+              (use <literal>-dep-makefile</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-optdep-w</literal>
+              (has no effect)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-optdep--include-prelude</literal>
+              (use <literal>-include-pkg-deps</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-optdep--include-pkg-deps</literal>
+              (use <literal>-include-pkg-deps</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-optdep--exclude-module</literal>
+              (use <literal>-exclude-module</literal> instead)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-optdep-x</literal>
+              (use <literal>-exclude-module</literal> instead)
+            </para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem>
+        <para>
+          The following flags have been removed:
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <literal>-no-link-chk</literal>
+              (has been a no-op since at least 6.0)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fruntime-types</literal>
+              (has not been used for years)
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>-fhardwire-lib-paths</literal>
+              (use <literal>-dynload sysdep</literal>)
+            </para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>-unreg</literal> flag, which was used to build
+          unregisterised code with a registerised compiler, has been
+          removed. Now you need to build an unregisterised compiler
+          if you want to build unregisterised code.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+  <sect2>
+    <title>GHC API changes</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          There is now a Ghc Monad used to carry around GHC's
+          Session data. This Monad also provides exception handling
+          functions.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          It is now possible to get the raw characters corresponding to
+          each token the lexer outputs, and thus to reconstruct the
+          original file.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GHCi implicitly brings all exposed modules into scope with
+          qualified module names. There is a new flag
+          <literal>-fimplicit-import-qualified</literal>
+          that controls this behaviour, so other GHC API clients can
+          specify whether or not they want it.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          There is now haddock documentation for much of the GHC API.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+  <sect2>
+    <title>GHCi changes</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          You can now force GHCi to interpret a module, rather than
+          loading its compiled code, by prepending a * character to its
+          name, e.g.
+        </para>
+<programlisting>
+Prelude> :load *A
+Compiling A                ( A.hs, interpreted )
+*A>
+</programlisting>
+      </listitem>
+      <listitem>
+        <para>
+          By default, GHCi will not print bind results, e.g.
+        </para>
+<programlisting>
+Prelude&gt; c &lt;- return 'c'
+Prelude&gt; 
+</programlisting>
+        <para>
+          does not print <literal>'c'</literal>. Use
+          <literal>-fprint-bind-result</literal> if you want the old
+          behaviour.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GHCi now uses editline, rather than readline, for input.
+          This shouldn't affect its behaviour.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The GHCi prompt history is now saved in
+          <literal>~/.ghc/ghci_history</literal>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GHCi can now use libffi to make FFI calls, which means that
+          it now works on all platforms that libffi supports.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+  <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.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          We now ignore SIGPIPE by default.
+        </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.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>-S</literal> and <literal>-s</literal> RTS flags
+          now send their output to stderr, rather than
+          <literal><replaceable>prog</replaceable>.stat</literal>,
+          by default.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The new <literal>-vg</literal> RTS flag provides some RTS trace
+          messages even in the non-debug RTS variants.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+  <sect2>
+    <title>runghc</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          runghc now uses the compiler that it came with to run the
+          code, rather than the first compiler that it finds on the
+          PATH.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          If the program to run does not have a <literal>.lhs</literal>
+          extension then runghc now treats it as a <literal>.hs</literal>
+          file. In particular, this means that programs without an
+          extension now work.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>runghc foo</literal> will now work if
+          <literal>foo.hs</literal> or <literal>foo.lhs</literal> exists.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          runghc can now take the code to run from stdin.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+  <sect2>
+    <title>ghc-pkg</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          ghc-pkg now has a <literal>-no-user-package-conf</literal>
+          flag which instructs it to ignore the user's personal
+          package.conf.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          ghc-pkg no longer allows you to register two packages that
+          differ in case only.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          ghc-pkg no longer allows you to register packages which have
+          unversioned dependencies.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          There is a new command <literal>dump</literal> which is
+          similar to <literal>describe '*'</literal>, but in a format
+          that is designed to be parsable by other tools.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+  <sect2>
+    <title>Haddock</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          Haddock 2 now comes with GHC.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+  <sect2>
+    <title>DPH changes</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          DPH is now an extralib.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          There is a new flag <literal>-Odph</literal> that sets the
+          flags recommended when using DPH. Currently it is equivalent
+          to
+          <literal>
+            -O2 -fno-method-sharing -fdicts-cheap
+            -fmax-simplifier-iterations20 -fno-spec-constr-threshold
+          </literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          There are now flags <literal>-fdph-seq</literal> and
+          <literal>-fdph-par</literal> for selecting which DPH backend
+          to use.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <literal>-fflatten</literal> flag has been removed. It
+          never worked and has now been superceded by vectorisation.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+</sect1>
+
diff --git a/docs/users_guide/intro.xml b/docs/users_guide/intro.xml
index 25ead9e894..dce6ec4626 100644
--- a/docs/users_guide/intro.xml
+++ b/docs/users_guide/intro.xml
@@ -295,7 +295,7 @@
   </sect1>
 
 
-&relnotes;
+&relnotes1;
 
 </chapter>
 
diff --git a/docs/users_guide/ug-ent.xml b/docs/users_guide/ug-ent.xml
index d5614e8524..d0903ffaeb 100644
--- a/docs/users_guide/ug-ent.xml
+++ b/docs/users_guide/ug-ent.xml
@@ -3,7 +3,7 @@
 <!ENTITY flags          SYSTEM "flags.xml">
 <!ENTITY license        SYSTEM "license.xml">
 <!ENTITY intro          SYSTEM "intro.xml" >
-<!ENTITY relnotes       SYSTEM "6.6-notes.xml" >
+<!ENTITY relnotes1      SYSTEM "6.10.1-notes.xml" >
 <!ENTITY installing     SYSTEM "installing.xml" >
 <!ENTITY using          SYSTEM "using.xml" >
 <!ENTITY runtime        SYSTEM "runtime_control.xml" >