diff options
Diffstat (limited to 'docs/users_guide')
| -rw-r--r-- | docs/users_guide/codegens.xml | 150 | ||||
| -rw-r--r-- | docs/users_guide/debugging.xml | 28 | ||||
| -rw-r--r-- | docs/users_guide/ffi-chap.xml | 3 | ||||
| -rw-r--r-- | docs/users_guide/flags.xml | 8 | ||||
| -rw-r--r-- | docs/users_guide/phases.xml | 23 | ||||
| -rw-r--r-- | docs/users_guide/runtime_control.xml | 5 | ||||
| -rw-r--r-- | docs/users_guide/separate_compilation.xml | 13 | ||||
| -rw-r--r-- | docs/users_guide/sooner.xml | 20 | ||||
| -rw-r--r-- | docs/users_guide/using.xml | 22 |
9 files changed, 161 insertions, 111 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> diff --git a/docs/users_guide/debugging.xml b/docs/users_guide/debugging.xml index 2502d60249..003d2b5cd4 100644 --- a/docs/users_guide/debugging.xml +++ b/docs/users_guide/debugging.xml @@ -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: diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml index e6cf9edc92..678164136b 100644 --- a/docs/users_guide/ffi-chap.xml +++ b/docs/users_guide/ffi-chap.xml @@ -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 diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml index f4a8ba89d3..e554797740 100644 --- a/docs/users_guide/flags.xml +++ b/docs/users_guide/flags.xml @@ -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> diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml index 1f048f2612..f98fe90477 100644 --- a/docs/users_guide/phases.xml +++ b/docs/users_guide/phases.xml @@ -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> diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml index 57e89c7151..793ceec46b 100644 --- a/docs/users_guide/runtime_control.xml +++ b/docs/users_guide/runtime_control.xml @@ -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 “unregistered” + <para>Was this program compiled with an + <link linkend="unreg">“unregistered”</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 diff --git a/docs/users_guide/separate_compilation.xml b/docs/users_guide/separate_compilation.xml index 9d482e138a..d0acbfb39f 100644 --- a/docs/users_guide/separate_compilation.xml +++ b/docs/users_guide/separate_compilation.xml @@ -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> diff --git a/docs/users_guide/sooner.xml b/docs/users_guide/sooner.xml index 068908a3ae..c6445b9455 100644 --- a/docs/users_guide/sooner.xml +++ b/docs/users_guide/sooner.xml @@ -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> diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index 57057e86e2..47fec9ae1c 100644 --- a/docs/users_guide/using.xml +++ b/docs/users_guide/using.xml @@ -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. |