Repository : ssh://darcs.haskell.org//srv/darcs/ghc On branch : master
http://hackage.haskell.org/trac/ghc/changeset/7ef48caa30777c634e0791189c5691f548ad3c3f >--------------------------------------------------------------- commit 7ef48caa30777c634e0791189c5691f548ad3c3f Author: David Terei <[email protected]> Date: Mon Nov 21 11:39:09 2011 -0800 Improve code generator documentation. >--------------------------------------------------------------- docs/users_guide/codegens.xml | 55 ++++++++++++++++++++++++++++++++++++++++ docs/users_guide/debugging.xml | 10 +++++++ docs/users_guide/phases.xml | 2 +- docs/users_guide/sooner.xml | 8 ++++- docs/users_guide/ug-ent.xml.in | 1 + docs/users_guide/using.xml | 2 + 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 0000000..b63c4d8 --- /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 fe98537..2502d60 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 2e23b95..1f048f2 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 ea3e306..068908a 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 b550035..0a90d03 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 2837842..57057e8 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; _______________________________________________ Cvs-ghc mailing list [email protected] http://www.haskell.org/mailman/listinfo/cvs-ghc
