New syntax for GADT-style record declarations, and associated refactoring
[ghc-hetmet.git] / docs / users_guide / 6.6-notes.xml
index 2260690..a04b99e 100644 (file)
           when you compile with <option>-threaded</option>, you now get
           an RTS flag <option>-N</option> that allows you to specify the
           number of OS threads that GHC should use. Defaults to 1.
-          See <xref linkend="sec-using-smp" /> and <xref
+          See <xref linkend="using-smp" /> and <xref
           linkend="lang-parallel" />.
         </para>
       </listitem>
       <listitem>
         <para>
-          GHC's modules are now also bundled into a
-          <literal>ghc</literal> package, allowing programs to make use
-          of GHC as a library. The interface has not yet been properly
-          designed, so is subject to change.
+          GHC now handles impredicative polymorphism; see <xref linkend="impredicative-polymorphism" />.
         </para>
       </listitem>
       <listitem>
         <para>
-          GHC now handles impredicative polymorphism and there are
-          changes to the way scoped type variables work; see
-          <ulink url="http://www.haskell.org/pipermail/glasgow-haskell-users/2006-January/009565.html"> Simon's e-mail</ulink>
-          for more details.
+         There are significant changes to the way scoped type variables work,
+         and some programs that used to compile may no longer do so.
+         The new story is documented in  <xref linkend="scoped-type-variables" />.
+          (<ulink url="http://www.haskell.org/pipermail/glasgow-haskell-users/2006-January/009565.html"> Simon's e-mail</ulink>
+          gives some background, but the user manual should be complete (tell
+          us if not), and
+          certainly takes precedence if there is any conflict.)
         </para>
       </listitem>
       <listitem>
@@ -41,6 +41,7 @@
           <programlisting>
     f (x, y) | x `seq` False = undefined
              | otherwise = [x,y]</programlisting>
+          See <xref linkend="bang-patterns" /> for more details.
         </para>
       </listitem>
       <listitem>
           ignored in comments, so ASCII code with comments in, for
           example, Latin-1 will also work.
         </para>
+
+        <para>
+          A way to have Latin-1 source files pre-processed by GHC is
+          described in <xref linkend="pre-processor" />.
+        </para>
       </listitem>
       <listitem>
         <para>
           performance when a lot of memory is taken up by
           <literal>STArray</literal>s, <literal>IOArray</literal>s,
           <literal>STRef</literal>s or <literal>IORef</literal>s.
+          For more details see
+          <ulink url="http://hackage.haskell.org/trac/ghc/ticket/650">trac bug #650</ulink>.
         </para>
       </listitem>
       <listitem>
             The following flags (and, where appropriate, their inverses)
             used to be static (can only be given on
             the command line) but are now dynamic (can also be given in
-            a <literal>GHC_OPTIONS</literal> pragma or with
+            an <literal>OPTIONS_GHC</literal> pragma or with
             <literal>:set</literal> in GHCi):
             <option>-c</option>,
             <option>-hcsuf</option>,
             <option>-pgma</option>,
             <option>-pgml</option>,
             <option>-pgmdll</option>,
-            <option>-pgmdep</option>,
             <option>-pgmF</option>,
             <option>-optl</option>,
             <option>-optdll</option>,
       </listitem>
       <listitem>
         <para>
+          The
+          <option>-no-recomp</option><indexterm><primary><option>-no-recomp</option></primary></indexterm>
+          option is now called
+          <option>-fforce-recomp</option><indexterm><primary><option>-fforce-recomp</option></primary></indexterm>.
+          (the old name is still accepted for backwards compatibility,
+          but will be removed in the future).
+        </para>
+      </listitem>
+      <listitem>
+        <para>
           The <option>-fglobalise-toplev-names</option>
           flag has been removed.
         </para>
           <literal>MyIO <replaceable>t</replaceable></literal>
           rather than just
           <literal>IO <replaceable>t</replaceable></literal>.
+         See <xref linkend="ffi-newtype-io"/>
         </para>
       </listitem>
+      <listitem> <para> GHC's mechansim for deriving user-defined classes
+         for newtypes has been further generalised, to multi-parameter type
+         classes and higher-kinded types.  See <xref
+         linkend="newtype-deriving"/>.
+         </para></listitem>
       <listitem>
         <para>
           By default, pattern bindings in GHC are now monomorphic.
       </listitem>
       <listitem>
         <para>
-          It is now possible, with the <literal>-I</literal> RTS flag,
-          to control the amount of idle time that happens before a major
-          GC is performed.
+          Linear implicit parameters have been scheduled for removal for some
+          time.  In 6.6 we've removed them from the user manual, and they may
+         well disappear from the compiler itself in 6.6.1.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          If the program is idle for a certain amount of time then GHC
+          will now take the opportunity to do a major garbage collection.
+          The amount of idle time that is required before that happens
+          is controlled by the new <literal>-I</literal> RTS flag.
+          There is more detail in <xref linkend="rts-options-gc" />.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          It is now possible to control the frequency that the RTS clock
+          ticks at with the new <literal>-V</literal> RTS flag. This is
+          normally handled automatically by other flags, but this flag
+          is needed if you want to increase the resolution of the time
+          profiler.
+          For more details see <xref linkend="rts-options-misc" />.
         </para>
       </listitem>
       <listitem>
       </listitem>
       <listitem>
         <para>
-          The <option>-split-objs</option> flag can now be used with
-          <option>--make</option>, and hence can be used by cabal.
+          The <option>-split-objs</option> flag, which when used to compile
+          libraries means executables using the library will be smaller,
+          can now be used with <option>--make</option> and hence
+          can be used by cabal.
+          See <xref linkend="options-linker" /> for more information.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Template Haskell used to have limited support for type signatures in 
+         patterns, but since that design is in flux for Haskell (let alone
+         Template Haskell), we've removed type signatures in patterns from
+         Template Haskell.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GHC now supports postfix operators, as a simple generalisation of
+          left sections (<xref linkend="postfix-operators"/>).
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Parallel arrays, as enabled by <literal>-fparr</literal>, no
+          longer work.  They'll be coming back shortly, in full glory.
         </para>
       </listitem>
     </itemizedlist>
           See <xref linkend="ghci-commands" /> for more information.
         </para>
       </listitem>
+      <listitem>
+        <para>
+          GHCi now has an <literal>:edit</literal> command which pops
+          up an editor on the most recently loaded file, or a
+          specified file.  See <xref linkend="ghci-commands" /> for
+          more information.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GHCi now invokes <literal>print</literal> by default on the
+          result of IO actions and bindings at the prompt.  This is
+          occasionally not what you want, so it can be disabled (at
+          least for bindings) with 
+          <literal>:set -fno-print-bind-result</literal>.  See <xref
+          linkend="ghci-stmts" />.</para>
+      </listitem>
     </itemizedlist>
   </sect2>
 
       <itemizedlist>
         <listitem>
           <para>
-            Version number 2.0 (was 1.0).
+            Version number 2.1 (was 1.0).
           </para>
         </listitem>
         <listitem>
             <literal>inline</literal> which, provided the RHS is visible
             to the compiler, forcibly inlines its argument.
             Otherwise, it acts like <literal>id</literal>.
+            For more details, see <xref linkend="special-ids" />.
           </para>
         </listitem>
         <listitem>
           <para>
             <literal>GHC.Exts</literal> now provides a function
-            <literal>lazy</literal> which forces GHC to think that its
-            argument is lazy in its first argument.
+            <literal>lazy</literal>, where <literal>lazy f</literal>
+            behaves like <literal>f</literal>, except GHC is forced
+            to believe that it is lazy in its first argument.
+            For more details, see <xref linkend="special-ids" />.
           </para>
         </listitem>
         <listitem>
       <itemizedlist>
         <listitem>
           <para>
-            Version number 1.1.5 (was 1.1.4).
+            Version number 1.1.6 (was 1.1.4).
           </para>
         </listitem>
         <listitem>
         </listitem>
         <listitem>
           <para>
-            Added <filename>cabal-setup</filename>, a user interface to
-            building and installing Cabal packages.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            Added <filename>cabal-install</filename>, an automated
-            installer for cabal packages.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            There is now a <literal>Network.Hackage</literal> hierarchy
-            for code needed by hackage, the package server.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
             There are now modules
             <literal>Distribution.Simple.<replaceable>compiler</replaceable></literal>
             for each of <literal>GHC</literal>, <literal>NHC</literal>,
       <itemizedlist>
         <listitem>
           <para>
-            Version number 2.0 (was 1.0).
+            Version number 2.1 (was 1.0).
           </para>
         </listitem>
         <listitem>
         </listitem>
         <listitem>
           <para>
-            There is a new module
-            <literal>Control.Sequential.STM</literal> for non-concurrent
-            transactions which nevertheless need to be atomic in the
-            face of exceptions.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
             A new module
             <literal>Control.Concurrent.STM.TArray</literal> defines
             <literal>TArray</literal>, a transactional array, and makes
       <itemizedlist>
         <listitem>
           <para>
-            Version number 2.0 (was 1.0).
+            Version number 2.1 (was 1.0).
           </para>
         </listitem>
         <listitem>
             and <literal>System.Win32.Console</literal>.
           </para>
         </listitem>
-        <listitem>
-          <para>
-            <literal>System.Win32</literal> no longer exports
-            <literal>LCID</literal>,
-            <literal>LANGID</literal>,
-            <literal>SortID</literal>,
-            <literal>SubLANGID</literal>,
-            <literal>PrimaryLANGID</literal>,
-            <literal>mAKELCID</literal>,
-            <literal>lANGIDFROMLCID</literal>,
-            <literal>sORTIDFROMLCID</literal>,
-            <literal>mAKELANGID</literal>,
-            <literal>pRIMARYLANGID</literal> or
-            <literal>sUBLANGID</literal> from
-            <literal>System.Win32.NLS</literal>.
-          </para>
-        </listitem>
       </itemizedlist>
     </sect3>
   </sect2>
       <itemizedlist>
         <listitem>
           <para>
-            Version number remains 0.1.
+            Version number 0.2 (was 0.1).
           </para>
         </listitem>
         <listitem>
             <literal>network</literal> package.
           </para>
         </listitem>
+        <listitem>
+          <para>
+            The <literal>Network.CGI.Compat</literal> module provides
+            a similar interface to the old <literal>Network.CGI</literal>
+            module, but it uses <literal>Text.XHtml</literal> rather than
+            <literal>Text.Html</literal>.
+          </para>
+        </listitem>
       </itemizedlist>
     </sect3>
 
     </sect3>
 
     <sect3>
-      <title>HaXml</title>
-      <itemizedlist>
-        <listitem>
-          <para>
-            Version number 1.16 (was 1.12.1).
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            There are now lazy versions of the parsing modules
-            <literal>Text.XML.HaXml.ParseLazy</literal>
-            (a lazy non-validating XML parser) and
-            <literal>Text.XML.HaXml.Html.ParseLazy</literal>
-            (a lazy HTML parser).
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            There are lazy versions of two of the example tools,
-            <literal>CanonicaliseLazy</literal> and
-            <literal>XtractLazy</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            <literal>Text.XML.HaXml.Haskell2Xml</literal> and
-            <literal>Text.XML.HaXml.Xml2Haskell</literal> have been
-            removed, with <literal>Text.XML.HaXml.XmlContent</literal>
-            replacing them.
-            You must now use <literal>{-! derive : XmlContent !-}</literal>
-            rather than <literal>{-! derive :Haskell2Xml !-}</literal>
-            to have instances derived for your classes.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            Now also provides the
-            <literal>Text.ParserCombinators.HuttonMeijer</literal>
-            monadic parser combinator library.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            Provides another new set of parser combinators, as well as a lazy
-            variant, a variant that carries around state, and a
-            variant that does both. The modules are
-            <literal>Text.ParserCombinators.Poly</literal>,
-            <literal>Text.ParserCombinators.PolyLazy</literal>,
-            <literal>Text.ParserCombinators.PolyState</literal> and
-            <literal>Text.ParserCombinators.PolyStateLazy</literal>
-            respectively.
-            It also provides
-            <literal>Text.ParserCombinators.TextParser</literal>, which
-            is the <literal>Poly</literal> parser combinators
-            specialised for strings.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            Now provides a SAX-like parser in
-            <literal>Text.XML.HaXml.SAX</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            Now provides a module
-            <literal>Text.XML.HaXml.TypeMapping</literal>, which
-            defines an explicit representation for Haskell types.
-            This allows generation of a DTD from a Haskell value.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            The <literal>Posn</literal> type has been pulled out from
-            <literal>Text.XML.HaXml.Lex</literal> into its own module
-            <literal>Text.XML.HaXml.Posn</literal>. Some helper
-            functions are also exported.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            The APIs to the pre-existing modules have also substantially
-            changed.
-          </para>
-        </listitem>
-      </itemizedlist>
-    </sect3>
-
-    <sect3>
       <title>HGL</title>
       <itemizedlist>
         <listitem>
     </sect3>
 
     <sect3>
-      <title>Japi</title>
-      <itemizedlist>
-        <listitem>
-          <para>
-            No change.
-          </para>
-        </listitem>
-      </itemizedlist>
-    </sect3>
-
-    <sect3>
-      <title>monads</title>
-      <itemizedlist>
-        <listitem>
-          <para>
-            Version number 2.0.1 (was 1.1).
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            In <literal>Monad.Id</literal>, <literal>run</literal> has
-            been renamed <literal>runId</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            The <literal>Monad.BackT</literal> module has been removed;
-            use the new <literal>Monad.SearchT</literal> module instead.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            There is a new module <literal>Monad.ForEach</literal>
-            containing a class <literal>ForEach</literal>, for
-            applying a monadic function to each element in a container.
-            It provides instances for <literal>[]</literal> and
-            <literal>Maybe</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            The following combinators have been moved from
-            <literal>Monad.Prelude</literal> to a new module
-            <literal>Monad.Combinators</literal>:
-            <literal>(@@)</literal>,
-            <literal>(#)</literal>,
-            <literal>(&lt;#)</literal>,
-            <literal>(&lt;##)</literal>,
-            <literal>concatMap</literal> and
-            <literal>partitionM</literal>.
-            <literal>Monad.Combinators</literal> also defines the
-            following new combinators:
-            <literal>ifM</literal>,
-            <literal>whenM</literal>,
-            <literal>andM</literal>,
-            <literal>orM</literal>,
-            <literal>allM</literal>,
-            <literal>anyM</literal>,
-            <literal>forEach2</literal>,
-            <literal>forEach2_</literal>,
-            <literal>forEach3</literal> and
-            <literal>forEach3_</literal>, and re-exports
-            <literal>Control.Monad</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            The modules
-            <literal>Monad.Cont</literal>,
-            <literal>Monad.Except</literal>,
-            <literal>Monad.Reader</literal>,
-            <literal>Monad.State</literal> and
-            <literal>Monad.Writer</literal> have been removed, but their
-            monad transformer counterparts remain. If you want the
-            monads then just transform the identity monad instead.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            The <literal>Monad.ExceptT</literal> module now also exports
-            runExceptWith and unsafeRunExcept. It also now defines an
-            instance <literal>ContM (ExceptT x m)</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            In <literal>Monad.Prelude</literal>, the
-            <literal>get</literal> method of the
-            <literal>ReaderM</literal> module has been renamed
-            <literal>getR</literal>. The <literal>local</literal> method
-            has been removed with a new class
-            <literal>ReadUpdM</literal>, with methods
-            <literal>updateR</literal> 
-            and <literal>setR</literal>, taking its place.
-            The <literal>letLocal</literal> function has also been removed.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            In <literal>Monad.Prelude</literal>,
-            <literal>update</literal> has been made a method of
-            <literal>StateM</literal>.
-            The
-            <literal>peek</literal> and <literal>poke</literal> methods
-            have been renamed <literal>get</literal> and
-            <literal>set</literal> respectively, and both have a default
-            definition in terms of <literal>update</literal>.
-            The <literal>poke_</literal> function has also been renamed
-            <literal>set_</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            In <literal>Monad.Prelude</literal>,
-            <literal>handle</literal> has been taken out of the
-            <literal>ExceptM</literal> class and put into a new
-            class <literal>HandlerM</literal> along with a new method
-            <literal>checkExcept</literal>.
-            There are also new functions <literal>withHandler</literal>
-            and <literal>handle_</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            The <literal>TakeWriterM</literal> class has been renamed
-            <literal>CollectorM</literal>, and rather than a single
-            method <literal>takeFrom</literal> it has methods
-            <literal>censor</literal> and <literal>collect</literal>
-            with default definitions in terms of each other.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            <literal>Monad.Prelude</literal> defines a type
-            <literal>Cont</literal> and functions
-            <literal>returnCC</literal> and <literal>cJump</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            <literal>Monad.Prelude</literal> exports functions
-            <literal>inReader</literal>,
-            <literal>inWriter</literal>,
-            <literal>inState</literal> and
-            <literal>inExcept</literal>.
-            These make it easy to turn a pure representation of an
-            effectful computation into an actual computation.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            The <literal>zipWith3M</literal> and
-            <literal>zipWith3M_</literal> functions have been removed
-            from <literal>Monad.Prelude</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            <literal>Monad.Prelude</literal> now re-exports
-            <literal>Monad.Combinators</literal> and
-            <literal>Monad.ForEach</literal>, but no longer re-exports
-            <literal>Monad</literal>.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-            There is a new module <literal>Monad.Transformers</literal>
-            which re-exports
-            <literal>Monad.Id</literal>,
-            <literal>Monad.ReaderT</literal>,
-            <literal>Monad.WriterT</literal>,
-            <literal>Monad.StateT</literal>,
-            <literal>Monad.ExceptT</literal>,
-            <literal>Monad.SearchT</literal> and
-            <literal>Monad.ContT</literal>.
-          </para>
-        </listitem>
-      </itemizedlist>
-    </sect3>
-
-    <sect3>
       <title>mtl</title>
       <itemizedlist>
         <listitem>
       <itemizedlist>
         <listitem>
           <para>
-            Version number remains 1.1.
+            Version number 1.2 (was 1.1).
           </para>
         </listitem>
         <listitem>
   </sect2>
 
   <sect2>
+    <title>GHC As A Library</title>
+      <para>
+        Version number 6.6.
+      </para>
+      <para>
+        The internal modules of GHC are now available as a library, package
+        name <literal>ghc</literal>.
+        The interface has not been designed with use by other programs
+        in mind, so expect the API to vary radically in future
+        releases.
+      </para>
+      <para>
+        An introduction to using the library can be found
+        <ulink url="http://www.haskell.org/haskellwiki/GHC/As_a_library">on the wiki</ulink>.
+      </para>
+  </sect2>
+
+  <sect2>
     <title>Internal changes</title>
     <itemizedlist>
       <listitem>