Use runPhase_MoveBinary also for generating a dynamic library wrapper

[ghc-hetmet.git] / docs / users_guide / glasgow_exts.xml

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index de69b60..9b4dc58 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -2400,7 +2400,7 @@ may use different notation to that implemented in GHC.
 </para>
 <para>
 The rest of this section outlines the extensions to GHC that support GADTs.   The extension is enabled with 
-<option>-XGADTs</option>.
+<option>-XGADTs</option>.  The <option>-XGADTs</option> flag also sets <option>-XRelaxedPolyRec</option>.
 <itemizedlist>
 <listitem><para>
 A GADT can only be declared using GADT-style syntax (<xref linkend="gadt-style"/>); 
@@ -4501,7 +4501,9 @@ for rank-2 types.
 <sect2 id="impredicative-polymorphism">
 <title>Impredicative polymorphism
 </title>
-<para>GHC supports <emphasis>impredicative polymorphism</emphasis>.  This means
+<para>GHC supports <emphasis>impredicative polymorphism</emphasis>, 
+enabled with <option>-XImpredicativeTypes</option>.  
+This means
 that you can call a polymorphic function at a polymorphic type, and
 parameterise data structures over polymorphic types.  For example:
 <programlisting>
@@ -4542,7 +4544,7 @@ a type for <varname>ys</varname>; a major benefit of scoped type variables is th
 it becomes possible to do so.
 </para>
 <para>Lexically-scoped type variables are enabled by
-<option>-fglasgow-exts</option>.
+<option>-XScopedTypeVariables</option>.  This flag implies <option>-XRelaxedPolyRec</option>.
 </para>
 <para>Note: GHC 6.6 contains substantial changes to the way that scoped type
 variables work, compared to earlier releases.  Read this section
@@ -4600,7 +4602,7 @@ then
 <para>A declaration type signature that has <emphasis>explicit</emphasis>
 quantification (using <literal>forall</literal>) brings into scope the
 explicitly-quantified
-type variables, in the definition of the named function(s).  For example:
+type variables, in the definition of the named function.  For example:
 <programlisting>
   f :: forall a. [a] -> [a]
   f (x:xs) = xs ++ [ x :: a ]
@@ -4608,7 +4610,9 @@ type variables, in the definition of the named function(s).  For example:
 The "<literal>forall a</literal>" brings "<literal>a</literal>" into scope in
 the definition of "<literal>f</literal>".
 </para>
-<para>This only happens if the quantification in <literal>f</literal>'s type
+<para>This only happens if:
+<itemizedlist>
+<listitem><para> The quantification in <literal>f</literal>'s type
 signature is explicit.  For example:
 <programlisting>
   g :: [a] -> [a]
@@ -4618,6 +4622,26 @@ This program will be rejected, because "<literal>a</literal>" does not scope
 over the definition of "<literal>f</literal>", so "<literal>x::a</literal>"
 means "<literal>x::forall a. a</literal>" by Haskell's usual implicit
 quantification rules.
+</para></listitem>
+<listitem><para> The signature gives a type for a function binding or a bare variable binding, 
+not a pattern binding.
+For example:
+<programlisting>
+  f1 :: forall a. [a] -> [a]
+  f1 (x:xs) = xs ++ [ x :: a ]   -- OK
+
+  f2 :: forall a. [a] -> [a]
+  f2 = \(x:xs) -> xs ++ [ x :: a ]   -- OK
+
+  f3 :: forall a. [a] -> [a] 
+  Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ])   -- Not OK!
+</programlisting>
+The binding for <literal>f3</literal> is a pattern binding, and so its type signature
+does not bring <literal>a</literal> into scope.   However <literal>f1</literal> is a
+function binding, and <literal>f2</literal> binds a bare variable; in both cases
+the type signature brings <literal>a</literal> into scope.
+</para></listitem>
+</itemizedlist>
 </para>
 </sect3>
 
@@ -5000,9 +5024,13 @@ Type splices are not implemented, and neither are pattern splices or quotations.
    </para></listitem>
 
    <listitem><para>
-   Furthermore, you can only run a function at compile time if it is imported
+   You can only run a function at compile time if it is imported
    from another module <emphasis>that is not part of a mutually-recursive group of modules
-   that includes the module currently being compiled</emphasis>.  For example, when compiling module A,
+   that includes the module currently being compiled</emphasis>.  Furthermore, all of the modules of 
+   the mutually-recursive group must be reachable by non-SOURCE imports from the module where the
+   splice is to be run.</para>
+   <para>
+   For example, when compiling module A,
    you can only run Template Haskell functions imported from B if B does not import A (directly or indirectly).
    The reason should be clear: to run B we must compile and run A, but we are currently type-checking A.
    </para></listitem>
@@ -6374,14 +6402,14 @@ data T = T {-# UNPACK #-} !(Int,Int)
 
       <para>will store the two <literal>Int</literal>s directly in the
       <function>T</function> constructor, by flattening the pair.
-      Multi-level unpacking is also supported:</para>
+      Multi-level unpacking is also supported:
 
 <programlisting>
 data T = T {-# UNPACK #-} !S
 data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
 </programlisting>
 
-      <para>will store two unboxed <literal>Int&num;</literal>s
+      will store two unboxed <literal>Int&num;</literal>s
       directly in the <function>T</function> constructor.  The
       unpacker can see through newtypes, too.</para>
 
@@ -6395,6 +6423,15 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
       constructor field.</para>
     </sect2>
 
+    <sect2 id="source-pragma">
+      <title>SOURCE pragma</title>
+
+      <indexterm><primary>SOURCE</primary></indexterm>
+     <para>The <literal>{-# SOURCE #-}</literal> pragma is used only in <literal>import</literal> declarations,
+     to break a module loop.  It is described in detail in <xref linkend="mutual-recursion"/>.
+     </para>
+</sect2>
+
 </sect1>
 
 <!--  ======================= REWRITE RULES ======================== -->