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