<?xml version="1.0" encoding="iso-8859-1"?>
<sect1 id="code-generators">
  <title>GHC Backends</title>
  <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 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>only LLVM 3.5</emphasis>
      is 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.5 or greater then
      you also need the <ulink url="http://clang.llvm.org">Clang c
        compiler</ulink> compiler available on your PATH.
    </para>

    <para>To install LLVM and Clang:
      <itemizedlist>
        <listitem><emphasis>Linux</emphasis>: Use your package management tool.
        </listitem>
        <listitem><emphasis>Mac OS X</emphasis>: Clang is included by
        default on recent OS X machines when XCode is installed (from
        <literal>10.6</literal> and later). LLVM is not included. In
        order to use the LLVM based code generator, you should install
        the <ulink
        url="http://mxcl.github.com/homebrew/">Homebrew</ulink>
        package manager for OS X and then install LLVM 3.5. 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>

<!-- Emacs stuff:
     ;;; Local Variables: ***
     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
     ;;; End: ***
 -->
