</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>
<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#</literal>s
+ will store two unboxed <literal>Int#</literal>s
directly in the <function>T</function> constructor. The
unpacker can see through newtypes, too.</para>
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 ======================== -->
<literal>hi-boot</literal> files</primary></indexterm>
Here <filename>A</filename> imports <filename>B</filename>, but <filename>B</filename> imports
<filename>A</filename> with a <literal>{-# SOURCE #-}</literal> pragma, which breaks the
-circular dependency. For every module <filename>A.hs</filename> that is <literal>{-# SOURCE #-}</literal>-imported
+circular dependency. Every loop in the module import graph must be broken by a <literal>{-# SOURCE #-}</literal> import;
+or, equivalently, the module import graph must be acyclic if <literal>{-# SOURCE #-}</literal> imports are ignored.
+</para>
+<para>For every module <filename>A.hs</filename> that is <literal>{-# SOURCE #-}</literal>-imported
in this way there must exist a source file <literal>A.hs-boot</literal>. This file contains an abbreviated
version of <filename>A.hs</filename>, thus:
<programlisting>