Improve code generator documentation.

6 files changed, 75 insertions, 3 deletions

diff --git a/docs/users_guide/codegens.xml b/docs/users_guide/codegens.xml
new file mode 100644
index 0000000000..b63c4d8b56
--- /dev/null
+++ b/docs/users_guide/codegens.xml
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<sect1 id="code-generators">
+  <title>GHC Backends</title>
+  <sect2 id="replacing-phases">
+  
+     <para>GHC supports multiple backend code-generators. This is the part
+        of the compiler responsible for taking the the last intermediate
+        representation that GHC uses and compiling it to executable code.
+        The supported backends are described below.
+     </para>
+
+     <sect3 id="native-code-gen">
+        <title>Native Code Generator (<option>-fasm</option>)</title>
+        This is the default backend used by GHC. It is a native code generator,
+        compiling all the way to assembly code. It is the fastest backend and
+        generally produces good performance code.  Select it with the
+        <option>-fasm</option> flag.
+     </sect3>
+
+     <sect3 id="llvm-code-gen">
+        <title>LLVM Code Generator (<option>-fllvm</option>)</title>
+        <para>This is an alternative backend that uses the
+           <ulink url="http://llvm.org">LLVM</ulink> compiler to produce
+           executable code.  It generally produces code as with performance as
+           good as the native code generator but for some cases can produce
+           much faster code. This is especially true for numeric, array heavy
+           code using packages like vector.
+        </para>
+          
+        <para>You must install and have LLVM available on your PATH for the
+           LLVM code generator to work. Specifically it needs to be able to
+           call the <literal>opt</literal>and <literal>llc</literal> tools.
+           Secondly, if you are running Mac OS X with LLVM 3.0 or greater then
+           you also need the
+           <ulink url="http://clang.llvm.org">Clang c compiler</ulink> compiler
+           available on your PATH. Clang and LLVM are both included with OS X
+           by default from 10.6 onwards.
+        </para>
+         
+     </sect3>
+
+     <sect3 id="c-code-gen">
+        <title>C Code Generator (<option>-fvia-C</option>)</title>
+
+     </sect3>
+
+  </sect2>
+
+</sect1>
+
+<!-- Emacs stuff:
+     ;;; Local Variables: ***
+     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
+     ;;; End: ***
+ -->
diff --git a/docs/users_guide/debugging.xml b/docs/users_guide/debugging.xml
index fe98537743..2502d60249 100644
--- a/docs/users_guide/debugging.xml
+++ b/docs/users_guide/debugging.xml
@@ -292,6 +292,16 @@
 
 	    <varlistentry>
 	      <term>
+	        <option>-ddump-llvm</option>:
+                <indexterm><primary><option>-ddump-llvm</option></primary></indexterm>
+	      </term>
+	      <listitem>
+		<para>LLVM code from the LLVM code generator</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term>
 	        <option>-ddump-bcos</option>:
                 <indexterm><primary><option>-ddump-bcos</option></primary></indexterm>
 	      </term>
diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml
index 2e23b95eaa..1f048f2612 100644
--- a/docs/users_guide/phases.xml
+++ b/docs/users_guide/phases.xml
@@ -548,7 +548,7 @@ $ cat foo.hspp</screen>
           native code generator to compile.
           Produced code is generally the same speed or faster
           than the other two code generators. Compiling via LLVM
-          requires LLVM version 2.7 or later to be on the path.</para>
+          requires LLVM version 2.8 or later to be on the path.</para>
         </listitem>
       </varlistentry>
 
diff --git a/docs/users_guide/sooner.xml b/docs/users_guide/sooner.xml
index ea3e30609d..068908a3ae 100644
--- a/docs/users_guide/sooner.xml
+++ b/docs/users_guide/sooner.xml
@@ -152,13 +152,17 @@ should go here!</para>
       </varlistentry>
 
       <varlistentry>
-	<term>Compile via LLVM:</term>
+	<term>Compile via LVM:</term>
 	<listitem>
 		<para>The LLVM code generator can sometimes do a far better job
 			    at producing fast code then either the native code generator
 					or the C code generator. This is not universal and depends
 					on the code. Numeric heavy code seems to show the best
-					improvement when compiled via LLVM.</para>
+					improvement when compiled via LLVM. You can also experiment
+					with passing specific flags to LLVM with the
+					<option>-optlo</option> and <option>-optlc</option> flags.
+				   Be careful though as setting these flags stops GHC from setting
+				   its usual flags for the LLVM optimiser and compiler.</para>
 	</listitem>
       </varlistentry>
 
diff --git a/docs/users_guide/ug-ent.xml.in b/docs/users_guide/ug-ent.xml.in
index b550035952..0a90d03ab7 100644
--- a/docs/users_guide/ug-ent.xml.in
+++ b/docs/users_guide/ug-ent.xml.in
@@ -5,6 +5,7 @@
 <!ENTITY intro          SYSTEM "intro.xml" >
 <!-- <!ENTITY relnotes1      SYSTEM "7.0.1-notes.xml" > -->
 <!ENTITY using          SYSTEM "using.xml" >
+<!ENTITY code-gens      SYSTEM "codegens.xml" >
 <!ENTITY runtime        SYSTEM "runtime_control.xml" >
 <!ENTITY prof           SYSTEM "profiling.xml" >
 <!ENTITY debug          SYSTEM "debugging.xml" >
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 2837842a0e..57057e86e2 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -2003,6 +2003,8 @@ f "2"    = 2
 
   </sect1>
 
+  &code-gens;
+
   &phases;
 
   &shared_libs;