Commit d6c2ffdc authored by dterei's avatar dterei
Browse files

Improve documentation on backends

parent 5d55dfe7
<?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>
......
......@@ -286,7 +286,8 @@
<indexterm><primary><option>-ddump-asm</option></primary></indexterm>
</term>
<listitem>
<para>assembly language from the native-code generator</para>
<para>assembly language from the
<link linkend="native-code-gen">native code generator</link></para>
</listitem>
</varlistentry>
......@@ -296,7 +297,8 @@
<indexterm><primary><option>-ddump-llvm</option></primary></indexterm>
</term>
<listitem>
<para>LLVM code from the LLVM code generator</para>
<para>LLVM code from the <link linkend="llvm-code-gen">LLVM code
generator</link></para>
</listitem>
</varlistentry>
......@@ -787,28 +789,6 @@ Main.skip2{-r1L6-} =
</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>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>
</sect2>
</sect1>
<!-- Emacs stuff:
......
......@@ -434,7 +434,8 @@ typedef enum {
<para>GHC no longer includes external header files when
compiling via C, so this checking is not performed. The
change was made for compatibility with the native code backend
change was made for compatibility with the
<ulink linkend="native-code-gen">native code generator</ulink>
(<literal>-fasm</literal>) and to comply strictly with the FFI
specification, which requires that FFI calls are not subject
to macro expansion and other CPP conversions that may be
......
......@@ -1859,13 +1859,15 @@ phase <replaceable>n</replaceable></entry>
<tbody>
<row>
<entry><option>-fasm</option></entry>
<entry>Use the native code generator</entry>
<entry>Use the <link linkend="native-code-gen">native code
generator</link></entry>
<entry>dynamic</entry>
<entry>-fllvm</entry>
</row>
<row>
<entry><option>-fllvm</option></entry>
<entry>Compile via LLVM</entry>
<entry>Compile using the <link linkend="llvm-code-gen">LLVM code
generator</link></entry>
<entry>dynamic</entry>
<entry>-fasm</entry>
</row>
......@@ -2771,7 +2773,7 @@ phase <replaceable>n</replaceable></entry>
</row>
<row>
<entry><option>-funregisterised</option></entry>
<entry>Unregisterised compilation (use <option>-unreg</option> instead)</entry>
<entry><link linkend="unreg">Unregisterised</link> compilation (use <option>-unreg</option> instead)</entry>
<entry>static</entry>
<entry>-</entry>
</row>
......
......@@ -531,8 +531,8 @@ $ cat foo.hspp</screen>
<indexterm><primary><option>-fasm</option></primary></indexterm>
</term>
<listitem>
<para>Use GHC's native code generator rather than
compiling via LLVM.
<para>Use GHC's <link linkend="native-code-gen">native code generator
</link>rather than compiling via LLVM.
<option>-fasm</option> is the default.</para>
</listitem>
</varlistentry>
......@@ -543,12 +543,12 @@ $ cat foo.hspp</screen>
<indexterm><primary><option>-fllvm</option></primary></indexterm>
</term>
<listitem>
<para>Compile via LLVM instead of using the native code
generator. This will generally take slightly longer than the
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.8 or later to be on the path.</para>
<para>Compile via <link linkend="llvm-code-gen">LLVM</link>instead
of using the native code generator. This will generally take slightly
longer than the 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 to be on the
path.</para>
</listitem>
</varlistentry>
......@@ -597,10 +597,9 @@ $ cat foo.hspp</screen>
</term>
<listitem>
<para>Generate position-independent code (code that can be put into
shared libraries). This currently works on Linux x86 and x86-64 when
using the native code generator (-fasm).
On Windows, position-independent code is never used
so the flag is a no-op on that platform.</para>
shared libraries). This currently works on Linux x86 and x86-64. On
Windows, position-independent code is never used so the flag is a
no-op on that platform.</para>
</listitem>
</varlistentry>
......
......@@ -1357,7 +1357,7 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
</sect2>
<sect2>
<sect2 id="ghc-info">
<title>Getting information about the RTS</title>
<indexterm><primary>RTS</primary></indexterm>
......@@ -1477,7 +1477,8 @@ $ ./a.out +RTS --info
<varlistentry>
<term><literal>Compiler unregistered</literal></term>
<listitem>
<para>Was this program compiled with an &ldquo;unregistered&rdquo;
<para>Was this program compiled with an
<link linkend="unreg">&ldquo;unregistered&rdquo;</link>
version of GHC? (I.e., a version of GHC that has no platform-specific
optimisations compiled in, usually because this is a currently
unsupported platform.) This value will usually be no, unless you're
......
......@@ -473,8 +473,9 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m`
<listitem>
<para>Keep intermediate <literal>.hc</literal> files when
doing <literal>.hs</literal>-to-<literal>.o</literal>
compilations via C (NOTE: <literal>.hc</literal> files
are only generated by unregisterised compilers).</para>
compilations via <link linkend="c-code-gen">C</link> (NOTE:
<literal>.hc</literal> files are only generated by
<link linkend="unreg">unregisterised</link> compilers).</para>
</listitem>
</varlistentry>
......@@ -488,10 +489,10 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m`
<listitem>
<para>Keep intermediate <literal>.ll</literal> files when
doing <literal>.hs</literal>-to-<literal>.o</literal>
compilations via LLVM (NOTE: <literal>.ll</literal> files
aren't generated when using the native code generator, you
may need to use <option>-fllvm</option> to force them
to be produced).</para>
compilations via <link linkend="llvm-code-gen">LLVM</link>
(NOTE: <literal>.ll</literal> files aren't generated when using the
native code generator, you may need to use <option>-fllvm</option> to
force them to be produced).</para>
</listitem>
</varlistentry>
......
......@@ -152,17 +152,17 @@ should go here!</para>
</varlistentry>
<varlistentry>
<term>Compile via LVM:</term>
<term>Compile via LLVM:</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. 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>
<para>The <link linkend="llvm-code-gen">LLVM code generator</link> can
sometimes do a far better job at producing fast code than the <link
linkend="native-code-gen">native code generator</link>. This is not
universal and depends on the code. Numeric heavy code seems to show
the best 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>
......
......@@ -731,11 +731,9 @@ ghc -c Foo.hs</screen>
<filename>Foo.hs</filename> to an object file
<filename>Foo.o</filename>.</para>
<para>Note: What the Haskell compiler proper produces depends on
whether a native-code generator<indexterm><primary>native-code
generator</primary></indexterm> is used (producing assembly
language) or not (producing C). See <xref
linkend="options-codegen"/> for more details.</para>
<para>Note: What the Haskell compiler proper produces depends on what
backend code generator is used. See <xref linkend="code-generators"/>
for more details.</para>
<para>Note: C pre-processing is optional, the
<option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
......@@ -2234,13 +2232,13 @@ f "2" = 2
<term><option>-msse2</option>:</term>
<listitem>
<para>
(x86 only, added in GHC 7.0.1) Use the SSE2 registers and
instruction set to implement floating point operations
when using the native code generator. This gives a
substantial performance improvement for floating point,
but the resulting compiled code will only run on
processors that support SSE2 (Intel Pentium 4 and later,
or AMD Athlon 64 and later).
(x86 only, added in GHC 7.0.1) Use the SSE2 registers and
instruction set to implement floating point operations when using
the <link linkend="native-code-gen">native code generator</link>.
This gives a substantial performance improvement for floating
point, but the resulting compiled code
will only run on processors that support SSE2 (Intel Pentium 4 and
later, or AMD Athlon 64 and later).
</para>
<para>
SSE2 is unconditionally used on x86-64 platforms.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment