diff options
Diffstat (limited to 'docs/users_guide/codegens.xml')
| -rw-r--r-- | docs/users_guide/codegens.xml | 150 |
1 files changed, 109 insertions, 41 deletions
diff --git a/docs/users_guide/codegens.xml b/docs/users_guide/codegens.xml index b63c4d8b56..f854e1137e 100644 --- a/docs/users_guide/codegens.xml +++ b/docs/users_guide/codegens.xml @@ -1,49 +1,117 @@ <?xml version="1.0" encoding="iso-8859-1"?> <sect1 id="code-generators"> <title>GHC Backends</title> - <sect2 id="replacing-phases"> + <indexterm><primary>ghc backends</primary></indexterm> + <indexterm><primary>ghc code generators</primary></indexterm> - <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> + <para>GHC supports multiple backend code generators. This is the part + of the compiler responsible for taking the last intermediate + representation that GHC uses (a form called Cmm that is a simple, C like + language) and compiling it to executable code. The backends that GHC + support are described below. + </para> + <sect2 id="native-code-gen"> + <title>Native code Generator (<option>-fasm</option>)</title> + <indexterm><primary>native code generator</primary></indexterm> + + The default backend for GHC. It is a native code generator, compiling Cmm + all the way to assembly code. It is the fastest backend and generally + produces good performance code. It has the best support for compiling + shared libraries. Select it with the <option>-fasm</option> flag. + </sect2> + + <sect2 id="llvm-code-gen"> + <title>LLVM Code Generator (<option>-fllvm</option>)</title> + <indexterm><primary>LLVM code generator</primary></indexterm> + + <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. The penalty is a significant increase in + compilation times. Select the LLVM backend with the + <option>-fllvm</option> flag. Currently <emphasis>LLVM 2.8</emphasis> and + later are supported. + </para> + + <para>You must install and have LLVM available on your PATH for the LLVM + code generator to work. Specifically GHC needs to be able to call the + <command>opt</command>and <command>llc</command> 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> + + <para>To install LLVM and Clang: + <itemizedlist> + <listitem><emphasis>Linux</emphasis>: Use your package management tool. + </listitem> + <listitem><emphasis>Mac OS X</emphasis>: LLVM and Clang are included by + default from <literal>10.6</literal> and later. For + <literal>10.5</literal> you should install the + <ulink url="http://mxcl.github.com/homebrew/">Homebrew</ulink> package + manager for OS X. Alternatively you can download binaries for LLVM + and Clang from + <ulink url="http://llvm.org/releases/download.html">here</ulink>. + </listitem> + <listitem><emphasis>Windows</emphasis>: You should download binaries for + LLVM and clang from + <ulink url="http://llvm.org/releases/download.html">here</ulink>. + </listitem> + </itemizedlist> + </para> + </sect2> + + <sect2 id="c-code-gen"> + <title>C Code Generator (<option>-fvia-C</option>)</title> + <indexterm><primary>C code generator</primary></indexterm> + <indexterm><primary>-fvia-C</primary></indexterm> + + <para>This is the oldest code generator in GHC and is generally not included + any more having been deprecated around GHC 7.0. Select it with the + <option>-fvia-C</option> flag. + </para> + + <para>The C code generator is only supported when GHC is built in + unregisterised mode, a mode where GHC produces 'portable' C code as + output to facilitate porting GHC itself to a new platform. This mode + produces much slower code though so it's unlikely your version of + GHC was built this way. If it has then the native code generator + probably won't be available. You can check this information by calling + <link linkend="ghc-info"><literal>ghc --info</literal></link>. + </para> + </sect2> + + <sect2 id="unreg"> + <title>Unregisterised compilation</title> + <indexterm><primary>unregisterised compilation</primary></indexterm> + + <para>The term "unregisterised" really means "compile via vanilla C", + disabling some of the platform-specific tricks that GHC normally uses to + make programs go faster. When compiling unregisterised, GHC simply + generates a C file which is compiled via gcc.</para> + + <para>When GHC is build in unregisterised mode only the LLVM and C code + generators will be available. The native code generator won't be. LLVM + usually offers a substantial performance benefit over the C backend in + unregisterised mode.</para> + + <para>Unregisterised compilation can be useful when porting GHC to a new + machine, since it reduces the prerequisite tools to + <command>gcc</command>, <command>as</command>, and <command>ld</command> + and nothing more, and furthermore the amount of platform-specific code + that needs to be written in order to get + unregisterised compilation going is usually fairly small.</para> + + <para>Unregisterised compilation cannot be selected at compile-time; you + have to build GHC with the appropriate options set. Consult the GHC + Building Guide for details.</para> + + <para>You can check if your GHC is unregisterised by calling + <link linkend="ghc-info"><literal>ghc --info</literal></link>.</para> </sect2> </sect1> |