From d4f8ccee287199f4ac34321f0fad64316950fc25 Mon Sep 17 00:00:00 2001
From: Simon Marlow <simonmar@microsoft.com>
Date: Wed, 21 Jun 2006 11:25:23 +0000
Subject: [PATCH] documentation for TH w/ profiling

---
 docs/users_guide/glasgow_exts.xml |   39 +++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 8a21368..319104e 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -4236,7 +4236,46 @@ Hello
 </programlisting>
 
 </sect2>
+
+<sect2>
+<title>Using Template Haskell with Profiling</title>
+<indexterm><primary>profiling</primary><secondary>with Template Haskell</secondary></indexterm>
  
+<para>Template Haskell relies on GHC's built-in bytecode compiler and
+interpreter to run the splice expressions.  The bytecode interpreter
+runs the compiled expression on top of the same runtime on which GHC
+itself is running; this means that the compiled code referred to by
+the interpreted expression must be compatible with this runtime, and
+in particular this means that object code that is compiled for
+profiling <emphasis>cannot</emphasis> be loaded and used by a splice
+expression, because profiled object code is only compatible with the
+profiling version of the runtime.</para>
+
+<para>This causes difficulties if you have a multi-module program
+containing Template Haskell code and you need to compile it for
+profiling, because GHC cannot load the profiled object code and use it
+when executing the splices.  Fortunately GHC provides a workaround.
+The basic idea is to compile the program twice:</para>
+
+<orderedlist>
+<listitem>
+  <para>Compile the program or library first the normal way, without
+  <option>-prof</option><indexterm><primary><option>-prof</option></primary></indexterm>.</para>
+</listitem>
+<listitem>
+  <para>Then compile it again with <option>-prof</option>, and
+  additionally use <option>-osuf
+  p_o</option><indexterm><primary><option>-osuf</option></primary></indexterm>
+  to name the object files differentliy (you can choose any suffix
+  that isn't the normal object suffix here).  GHC will automatically
+  load the object files built in the first step when executing splice
+  expressions.  If you omit the <option>-osuf</option> flag when
+  building with <option>-prof</option> and Template Haskell is used,
+  GHC will emit an error message. </para>
+</listitem>
+</orderedlist>
+</sect2>
+
 </sect1>
 
 <!-- ===================== Arrow notation ===================  -->
-- 
1.7.10.4