Commit a3783a32 authored by dterei's avatar dterei

Update release notes and docs with LLVM info.

parent 7c086ecd
......@@ -71,7 +71,8 @@ As a rule of thumb, all the language options are dynamic, as are the
warning options and the debugging options.
The rest are static, with the notable exceptions of
.BR \-v ", " \-cpp ", " \-fasm ", " \-fvia\-C ", and " \-#include .
.BR \-v ", " \-cpp ", " \-fasm ", " \-fvia\-C ", " \-fllvm ", and
" \-#include .
The OPTIONS sections lists the status of each flag.
.PP
......
......@@ -49,6 +49,14 @@ $ ghci -package haskell2010 -hide-package base -hide-package array
</para>
</listitem>
<listitem>
<para>
GHC now includes an LLVM code generator. For certain code,
particularly arithmetic heavy code, using the LLVM code
generator can bring some nice performance improvements.
</para>
</listitem>
<listitem>
<para>
The inliner has been overhauled, which should in general
......@@ -351,14 +359,14 @@ import SpecConstr
flags to keep the LLVM intermediate files,
<literal>-keep-llvm-file</literal> and
<literal>-keep-llvm-files</literal>;
flags to set the location and options for the LLVM assembler,
optimiser and compiler,
<literal>-pgmla</literal>,
flags to set the location and options for the LLVM optimiser
and compiler,
<literal>-pgmlo</literal>,
<literal>-pgmlc</literal>,
<literal>-optla</literal>,
<literal>-optlo</literal> and
<literal>-optlc</literal>.
The LLVM code generator requires LLVM version 2.7 or later on
your path.
</para>
</listitem>
......
......@@ -310,6 +310,13 @@
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-keep-llvm-file</option> or
<option>-keep-llvm-files</option></entry>
<entry>retain intermediate LLVM <literal>.ll</literal> files</entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-keep-s-file</option> or
<option>-keep-s-files</option></entry>
......@@ -1721,6 +1728,12 @@ phase <replaceable>n</replaceable></entry>
<entry>dynamic</entry>
<entry>-fasm</entry>
</row>
<row>
<entry><option>-fllvm</option></entry>
<entry>Compile via LLVM</entry>
<entry>dynamic</entry>
<entry>-fasm</entry>
</row>
<row>
<entry><option>-fno-code</option></entry>
<entry>Omit code generation</entry>
......@@ -1948,6 +1961,18 @@ phase <replaceable>n</replaceable></entry>
<entry>Use <replaceable>cmd</replaceable> as the C compiler</entry>
<entry>dynamic</entry>
<entry>-</entry>
<row>
<entry><option>-pgmlo</option> <replaceable>cmd</replaceable></entry>
<entry>Use <replaceable>cmd</replaceable> as the LLVM optimiser</entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-pgmlc</option> <replaceable>cmd</replaceable></entry>
<entry>Use <replaceable>cmd</replaceable> as the LLVM compiler</entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
</row>
<row>
<entry><option>-pgmm</option> <replaceable>cmd</replaceable></entry>
......@@ -1999,6 +2024,8 @@ phase <replaceable>n</replaceable></entry>
<indexterm><primary><option>-pgmL</option></primary></indexterm>
<indexterm><primary><option>-pgmP</option></primary></indexterm>
<indexterm><primary><option>-pgmc</option></primary></indexterm>
<indexterm><primary><option>-pgmlo</option></primary></indexterm>
<indexterm><primary><option>-pgmlc</option></primary></indexterm>
<indexterm><primary><option>-pgma</option></primary></indexterm>
<indexterm><primary><option>-pgml</option></primary></indexterm>
<indexterm><primary><option>-pgmdll</option></primary></indexterm>
......@@ -2048,6 +2075,18 @@ phase <replaceable>n</replaceable></entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-optlo</option> <replaceable>option</replaceable></entry>
<entry>pass <replaceable>option</replaceable> to the LLVM optimiser</entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-optlc</option> <replaceable>option</replaceable></entry>
<entry>pass <replaceable>option</replaceable> to the LLVM compiler</entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-optm</option> <replaceable>option</replaceable></entry>
<entry>pass <replaceable>option</replaceable> to the mangler</entry>
......@@ -2235,6 +2274,12 @@ phase <replaceable>n</replaceable></entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-ddump-llvm</option></entry>
<entry>Dump LLVM intermediate code</entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-ddump-occur-anal</option></entry>
<entry>Dump occurrence analysis output</entry>
......
......@@ -47,6 +47,28 @@
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-pgmlo</option> <replaceable>cmd</replaceable>
<indexterm><primary><option>-pgmlo</option></primary></indexterm>
</term>
<listitem>
<para>Use <replaceable>cmd</replaceable> as the LLVM
optimiser.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-pgmlc</option> <replaceable>cmd</replaceable>
<indexterm><primary><option>-pgmlc</option></primary></indexterm>
</term>
<listitem>
<para>Use <replaceable>cmd</replaceable> as the LLVM
compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-pgmm</option> <replaceable>cmd</replaceable>
......@@ -176,6 +198,24 @@
<para>Pass <replaceable>option</replaceable> to the C compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-optlo</option> <replaceable>option</replaceable>
<indexterm><primary><option>-optlo</option></primary></indexterm>
</term>
<listitem>
<para>Pass <replaceable>option</replaceable> to the LLVM optimiser.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-optlc</option> <replaceable>option</replaceable>
<indexterm><primary><option>-optlc</option></primary></indexterm>
</term>
<listitem>
<para>Pass <replaceable>option</replaceable> to the LLVM compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-optm</option> <replaceable>option</replaceable>
......@@ -408,42 +448,42 @@ $ cat foo.hspp</screen>
</varlistentry>
<varlistentry>
<term>
<term>
<constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant>
<indexterm><primary><constant>&lowbar;&lowbar;PARALLEL&lowbar;HASKELL&lowbar;&lowbar;</constant></primary></indexterm>
</term>
<listitem>
<para>Only defined when <option>-parallel</option> is in
<listitem>
<para>Only defined when <option>-parallel</option> is in
use! This symbol is defined when pre-processing Haskell
(input) and pre-processing C (GHC output).</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>
<term>
<constant><replaceable>os</replaceable>_HOST_OS=1</constant>
</term>
<listitem>
<para>This define allows conditional compilation based on
<listitem>
<para>This define allows conditional compilation based on
the Operating System, where<replaceable>os</replaceable> is
the name of the current Operating System
(eg. <literal>linux</literal>, <literal>mingw32</literal>
for Windows, <literal>solaris</literal>, etc.).</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
<term>
<term>
<constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant>
</term>
<listitem>
<para>This define allows conditional compilation based on
<listitem>
<para>This define allows conditional compilation based on
the host architecture, where<replaceable>arch</replaceable>
is the name of the current architecture
(eg. <literal>i386</literal>, <literal>x86_64</literal>,
<literal>powerpc</literal>, <literal>sparc</literal>,
etc.).</para>
</listitem>
</listitem>
</varlistentry>
</variablelist>
......@@ -572,6 +612,21 @@ $ cat foo.hspp</screen>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-fllvm</option>
<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 but quicker than compiling
via C. 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>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-fno-code</option>
......@@ -633,7 +688,7 @@ $ cat foo.hspp</screen>
different package will reside in a different shared library or
binary.</para>
<para>Note that using this option when linking causes GHC to link
against shared libraries.</para>
against shared libraries.</para>
</listitem>
</varlistentry>
</variablelist>
......@@ -699,10 +754,10 @@ $ cat foo.hspp</screen>
</term>
<listitem>
<para>Omits the link step. This option can be used with
<option>&ndash;&ndash;make</option> to avoid the automatic linking
that takes place if the program contains a <literal>Main</literal>
module.</para>
</listitem>
<option>&ndash;&ndash;make</option> to avoid the automatic linking
that takes place if the program contains a <literal>Main</literal>
module.</para>
</listitem>
</varlistentry>
<varlistentry>
......@@ -799,9 +854,9 @@ $ cat foo.hspp</screen>
</term>
<listitem>
<para>This flag tells GHC to link against shared Haskell libraries.
This flag only affects the selection of dependent libraries, not
the form of the current target (see -shared).
See <xref linkend="using-shared-libs" /> on how to
This flag only affects the selection of dependent libraries, not
the form of the current target (see -shared).
See <xref linkend="using-shared-libs" /> on how to
create them.</para>
<para>Note that this option also has an effect on
......@@ -821,20 +876,20 @@ $ cat foo.hspp</screen>
DLL, or a Mac OS dylib. GHC hides the operating system
details beneath this uniform flag.</para>
<para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
resulting shared object links statically or dynamically to
Haskell package libraries given as <option>-package</option> option. Non-Haskell
libraries are linked as gcc would regularly link it on your
system, e.g. on most ELF system the linker uses the dynamic
libraries when found.</para>
<para>The flags <option>-dynamic</option>/<option>-static</option> control whether the
resulting shared object links statically or dynamically to
Haskell package libraries given as <option>-package</option> option. Non-Haskell
libraries are linked as gcc would regularly link it on your
system, e.g. on most ELF system the linker uses the dynamic
libraries when found.</para>
<para>Object files linked into shared objects must be
compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
<para>Object files linked into shared objects must be
compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para>
<para>When creating shared objects for Haskell packages, the
shared object must be named properly, so that GHC recognizes
the shared object when linked against this package. See
shared object name mangling.</para>
<para>When creating shared objects for Haskell packages, the
shared object must be named properly, so that GHC recognizes
the shared object when linked against this package. See
shared object name mangling.</para>
</listitem>
</varlistentry>
......@@ -845,9 +900,9 @@ $ cat foo.hspp</screen>
</term>
<listitem>
<para>
This flag selects one of a number of modes for finding shared
libraries at runtime. See <xref linkend="finding-shared-libs"/> for
a description of each mode.
This flag selects one of a number of modes for finding shared
libraries at runtime. See <xref linkend="finding-shared-libs"/> for
a description of each mode.
</para>
</listitem>
</varlistentry>
......@@ -864,21 +919,21 @@ $ cat foo.hspp</screen>
to change which function is the "main" one, and the <option>-main-is</option> flag
allows you to do so. The <replaceable>thing</replaceable> can be one of:
<itemizedlist>
<listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
<listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
<listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
</itemizedlist>
<listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
<listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
<listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
</itemizedlist>
Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
in the latter two items above). It has no effect for other modules,
and hence can safely be given to <literal>ghc --make</literal>.
However, if all the modules are otherwise up to date, you may need to force
recompilation both of the module where the new "main" is, and of the
module where the "main" function used to be;
<literal>ghc</literal> is not clever
enough to figure out that they both need recompiling. You can
force recompilation by removing the object file, or by using the
<option>-fforce-recomp</option> flag.
However, if all the modules are otherwise up to date, you may need to force
recompilation both of the module where the new "main" is, and of the
module where the "main" function used to be;
<literal>ghc</literal> is not clever
enough to figure out that they both need recompiling. You can
force recompilation by removing the object file, or by using the
<option>-fforce-recomp</option> flag.
</para>
</listitem>
</varlistentry>
......
......@@ -440,6 +440,8 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m`
</indexterm>
<indexterm><primary><literal>.hc</literal> files, saving</primary>
</indexterm>
<indexterm><primary><literal>.ll</literal> files, saving</primary>
</indexterm>
<indexterm><primary><literal>.s</literal> files, saving</primary>
</indexterm>
......@@ -465,6 +467,23 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m`
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-keep-llvm-file</option>,
<option>-keep-llvm-files</option>
<indexterm><primary><option>-keep-llvm-file</option></primary></indexterm>
<indexterm><primary><option>-keep-llvm-files</option></primary></indexterm>
</term>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-keep-s-file</option>,
......
......@@ -151,6 +151,17 @@ should go here!</para>
</listitem>
</varlistentry>
<varlistentry>
<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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Compile via C and crank up GCC:</term>
<listitem>
......
......@@ -267,6 +267,22 @@ module X where
</listitem>
</varlistentry>
<varlistentry>
<term><filename>.ll</filename></term>
<listitem>
<para>An llvm-intermediate-language source file, usually
produced by the compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>.bc</filename></term>
<listitem>
<para>An llvm-intermediate-language bitcode file, usually
produced by the compiler.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>.s</filename></term>
<listitem>
......
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