<listitem>
<para>Template Haskell, a new feature for compile-time
metaprogramming has been introduced. See <xref
- linkend="template-haskell">.</para>
+ linkend="template-haskell"/>.</para>
</listitem>
<listitem>
<para>INLINE pragmas on methods in class or instance
</listitem>
<listitem>
<para>Recursive do-notation (aka <literal>mdo</literal>) is
- now supported. See <xref linkend="mdo-notation">.</para>
+ now supported. See <xref linkend="mdo-notation"/>.</para>
</listitem>
<listitem>
<para>There is now a native code generator for PowerPC
<listitem>
<para>Profiling: the <option>-xt</option> RTS option enables
inclusion of thread stacks in a heap profile. See <xref
- linkend="rts-options-heap-prof">.</para>
+ linkend="rts-options-heap-prof"/>.</para>
</listitem>
<listitem>
<para>Non-blocking I/O is now supported on Windows.</para>
<para>Hierarchical libraries are now available without needing
to specify an explicit <option>-package</option> flag. There
are some exceptions to this rule (see <xref
- linkend="using-packages">), but if you stick to GHCi and
+ linkend="using-packages"/>), but if you stick to GHCi and
<option>--make</option> mode then there will normally be no
need to specify <option>-package</option> options at
all.</para>
-<Chapter id="bugs-and-infelicities">
+<chapter id="bugs-and-infelicities">
<title>Known bugs and infelicities</title>
<sect1 id="vs-Haskell-defn">
<para>This section lists Glasgow Haskell infelicities in its
implementation of Haskell 98. See also the “when things
- go wrong” section (<XRef LinkEnd="wrong">) for information
+ go wrong” section (<xref linkend="wrong"/>) for information
about crashes, space leaks, and other undesirable phenomena.</para>
<para>The limitations here are listed in Haskell Report order
(let x = 42 in x == 42 == True)</programlisting>
The Haskell report is arguably wrong here, but nevertheless
- it's a difference between GHC & Haskell 98.</para>
+ it's a difference between GHC & Haskell 98.</para>
</listitem>
</itemizedlist>
</sect3>
<itemizedlist>
<listitem>
<para> GHC can warn about non-exhaustive or overlapping
- patterns (see <xref linkend="options-sanity">), and usually
+ patterns (see <xref linkend="options-sanity"/>), and usually
does so correctly. But not always. It gets confused by
string patterns, and by guards, and can then emit bogus
warnings. The entire overlap-check code needs an overhaul
<para>HACKER TERRITORY. HACKER TERRITORY. (You were warned.)</para>
- <Sect2 id="dumping-output">
+ <sect2 id="dumping-output">
<title>Dumping out compiler intermediate structures</title>
<indexterm><primary>dumping GHC intermediates</primary></indexterm>
STG-to-STG passes, respectively. (<emphasis>Lots</emphasis>
of output!) So: when we're really desperate:</para>
- <Screen>
+ <screen>
% ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs
-</Screen>
+</screen>
</listitem>
</varlistentry>
<para>Let's do this by commenting an example. It's from doing
<option>-ddump-ds</option> on this code:
-<ProgramListing>
+<programlisting>
skip2 m = m : skip2 (m+2)
-</ProgramListing>
+</programlisting>
Before we jump in, a word about names of things. Within GHC,
variables, type constructors, etc., are identified by their
usually printed out when debugging, in some form or another. So
here we go…</para>
-<ProgramListing>
+<programlisting>
Desugared:
Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4]
{- end CoRec -}
} in skip2.t3Ja
-</ProgramListing>
+</programlisting>
<para>(“It's just a simple functional language” is an
unregisterised trademark of Peyton Jones Enterprises, plc.)</para>
</variablelist>
</sect2>
-</Sect1>
+</sect1>
<!-- Emacs stuff:
;;; Local Variables: ***
<listitem>
<para>If you're also using CPP, beware of the known pitfall
with string gaps mentioned in <xref
- linkend="cpp-string-gaps">.</para>
+ linkend="cpp-string-gaps"/>.</para>
</listitem>
</varlistentry>
<listitem>
<para>You should use the <option>-#include</option> option to
bring the correct prototype into scope (see <xref
- linkend="options-C-compiler">).</para>
+ linkend="options-C-compiler"/>).</para>
</listitem>
</varlistentry>
-auto-all</literal> (make sure you have the profiling libraries
installed), and run it with <literal>+RTS -xc -RTS</literal> to get a
“stack trace” at the point at which the exception was
-raised. See <xref linkend="rts-options-debugging"> for more
+raised. See <xref linkend="rts-options-debugging"/> for more
details.</para>
</listitem>
</varlistentry>
<term>How do I increase the heap size permanently for a given
binary?</term>
<listitem>
- <para>See <xref linkend="rts-hooks">.</para>
+ <para>See <xref linkend="rts-hooks"/>.</para>
</listitem>
</varlistentry>
main = do
putStr "how are you today? "
hFlush stdout
- input <- hGetLine
+ input &- hGetLine
...</programlisting>
<para>You'll probably find that the behaviour differs when
Include files named by <option>-#include</option> options
or in <literal>foreign import</literal> declarations are only
used in via-C compilation mode. See <xref
- linkend="finding-header-files"> for more details.</para>
+ linkend="finding-header-files"/> for more details.</para>
</listitem>
</varlistentry>
<screen>ghc --make -prof -o foo-prof -osuf p.o -hisuf p.hi Main</screen>
- <para>See <xref linkend="options-output"> for more details on
+ <para>See <xref linkend="options-output"/> for more details on
the <option>-osuf</option> and <option>-hisuf</option>
options.</para>
</listitem>
<!-- FFI docs as a chapter -->
-<Chapter id="ffi">
-<Title>Foreign function interface (FFI)</Title>
+<chapter id="ffi">
+<title>Foreign function interface (FFI)</title>
<para>GHC (mostly) conforms to the Haskell 98 Foreign Function Interface
- Addendum 1.0, whose definition is available from <ULink
- URL="http://haskell.org/"><literal>http://haskell.org/</literal></ULink >.
+ Addendum 1.0, whose definition is available from <ulink
+ URL="http://haskell.org/"><literal>http://haskell.org/</literal></ulink >.
The FFI support in GHC diverges from the Addendum in the following ways:
</para>
<listitem>
<para>GHC implements a number of GHC-specific extensions to the FFI
Addendum. These extensions are described in <xref
- linkend="sec-ffi-ghcexts">, but please note that programs using
+ linkend="sec-ffi-ghcexts"/>, but please note that programs using
these features are not portable. Hence, these features should be
avoided where possible.</para>
</listitem>
use of the foreign function interface in GHC.</para>
<sect2 id="foreign-export-ghc">
- <title>Using <literal>foreign export</literal> and <literal>foreign
- import ccall "wrapper"</literal> with GHC</title>
+ <title>Using <literal>foreign export</literal> and <literal>foreign import ccall "wrapper"</literal> with GHC</title>
<indexterm><primary><literal>foreign export
</literal></primary><secondary>with GHC</secondary>
</indexterm>
<para>When GHC compiles a module (say <filename>M.hs</filename>)
- which uses <literal>foreign export</literal> or <literal>foreign
- import "wrapper"</literal>, it generates two
+ which uses <literal>foreign export</literal> or
+ <literal>foreign import "wrapper"</literal>, it generates two
additional files, <filename>M_stub.c</filename> and
<filename>M_stub.h</filename>. GHC will automatically compile
<filename>M_stub.c</filename> to generate
hs_add_root(__stginit_Foo);
#endif
- for (i = 0; i < 5; i++) {
+ for (i = 0; i < 5; i++) {
printf("%d\n", foo(2500));
}
</sect3>
<sect3 id="foreign-export-dynamic-ghc">
- <title>Using <literal>foreign import ccall "wrapper"</literal> with
- GHC</title>
+ <title>Using <literal>foreign import ccall "wrapper"</literal> with GHC</title>
<indexterm><primary><literal>foreign import
ccall "wrapper"</literal></primary><secondary>with GHC</secondary>
<para>When generating C (using the <option>-fvia-C</option>
directive), one can assist the C compiler in detecting type
errors by using the <option>-#include</option> directive
- (<xref linkend="options-C-compiler">) to provide
+ (<xref linkend="options-C-compiler"/>) to provide
<filename>.h</filename> files containing function
headers.</para>
<option>-#include</option> options are; but they should be in the package
configuration, which GHC knows about. So if you are building a package, remember
to put all those <option>-#include</option> options into the package configuration.
-See the <literal>c_includes</literal> field in <xref linkend="package-management">.
+See the <literal>c_includes</literal> field in <xref linkend="package-management"/>.
</para>
<para>
are searched for using the C compiler's usual search path.
You can add directories to this search path using the
<option>-I</option> option (see <xref
- linkend="c-pre-processor">).</para>
+ linkend="c-pre-processor"/>).</para>
<para>Note: header files are ignored unless compiling via C.
If you had been compiling your code using the native code
</variablelist>
</sect2>
</sect1>
-</Chapter>
+</chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
<para>This section is a quick-reference for GHC's command-line
flags. For each flag, we also list its static/dynamic status (see
- <xref linkend="static-dynamic-flags">), and the flag's opposite
+ <xref linkend="static-dynamic-flags"/>), and the flag's opposite
(if available).</para>
<sect2>
- <title>Help and verbosity options (<xref linkend="options-help">)</title>
+ <title>Help and verbosity options (<xref linkend="options-help"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Which phases to run (<xref linkend="options-order">)</title>
+ <title>Which phases to run (<xref linkend="options-order"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Redirecting output (<xref linkend="options-output">)</title>
+ <title>Redirecting output (<xref linkend="options-output"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Keeping intermediate files (<xref linkend="keeping-intermediates">)</title>
+ <title>Keeping intermediate files (<xref linkend="keeping-intermediates"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Temporary files (<xref linkend="temp-files">)</title>
+ <title>Temporary files (<xref linkend="temp-files"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Finding imports (<xref linkend="search-path">)</title>
+ <title>Finding imports (<xref linkend="search-path"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Interface file options (<xref linkend="hi-options">)</title>
+ <title>Interface file options (<xref linkend="hi-options"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Recompilation checking (<xref linkend="recomp">)</title>
+ <title>Recompilation checking (<xref linkend="recomp"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Interactive-mode options (<xref linkend="ghci-dot-files">)</title>
+ <title>Interactive-mode options (<xref linkend="ghci-dot-files"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Packages (<xref linkend="packages">)</title>
+ <title>Packages (<xref linkend="packages"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Language options (<xref linkend="options-language">)</title>
+ <title>Language options (<xref linkend="options-language"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Warnings (<xref linkend="options-sanity">)</title>
+ <title>Warnings (<xref linkend="options-sanity"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
<row>
<entry><option>-fwarn-deprecations</option></entry>
- <entry>warn about uses of functions & types that are deprecated</entry>
+ <entry>warn about uses of functions & types that are deprecated</entry>
<entry>dynamic</entry>
<entry><option>-fno-warn-deprecations</option></entry>
</row>
</sect2>
<sect2>
- <title>Optimisation levels (<xref linkend="options-optimise">)</title>
+ <title>Optimisation levels (<xref linkend="options-optimise"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Individual optimisations (<xref linkend="options-f">)</title>
+ <title>Individual optimisations (<xref linkend="options-f"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Profiling options (<xref linkend="profiling">)</title>
+ <title>Profiling options (<xref linkend="profiling"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Parallelism options (<xref linkend="sec-using-parallel">)</title>
+ <title>Parallelism options (<xref linkend="sec-using-parallel"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>C pre-processor options (<xref linkend="c-pre-processor">)</title>
+ <title>C pre-processor options (<xref linkend="c-pre-processor"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>C compiler options (<xref linkend="options-C-compiler">)</title>
+ <title>C compiler options (<xref linkend="options-C-compiler"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Code generation options (<xref linkend="options-codegen">)</title>
+ <title>Code generation options (<xref linkend="options-codegen"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Linking options (<xref linkend="options-linker">)</title>
+ <title>Linking options (<xref linkend="options-linker"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Replacing phases (<xref linkend="replacing-phases">)</title>
+ <title>Replacing phases (<xref linkend="replacing-phases"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Forcing options to particular phases (<xref linkend="forcing-options-through">)</title>
+ <title>Forcing options to particular phases (<xref linkend="forcing-options-through"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
</sect2>
<sect2>
- <title>Platform-specific options (<xref linkend="options-platform">)</title>
+ <title>Platform-specific options (<xref linkend="options-platform"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
<sect2>
- <title>External core file options (<xref linkend="ext-core">)</title>
+ <title>External core file options (<xref linkend="ext-core"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
<sect2>
- <title>Compiler debugging options (<xref linkend="options-debugging">)</title>
+ <title>Compiler debugging options (<xref linkend="options-debugging"/>)</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
<title>Misc compiler options</title>
<informaltable>
- <tgroup cols=3 align=left colsep=1 rowsep=1>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>Flag</entry>
indicate that the current context for expressions typed at the
prompt is the <literal>Main</literal> module we just loaded (we'll
explain what the <literal>*</literal> means later in <xref
- linkend="ghci-scope">). So we can now type expressions involving
+ linkend="ghci-scope"/>). So we can now type expressions involving
the functions from <filename>Main.hs</filename>:</para>
<screen>
<para>or it can be set using the <literal>:set</literal> command
from within GHCi (see <xref
- linkend="ghci-cmd-line-options">)<footnote><para>Note that in
+ linkend="ghci-cmd-line-options"/>)<footnote><para>Note that in
GHCi, and <option>––make</option> mode, the <option>-i</option>
option is used to specify the search path for
<emphasis>source</emphasis> files, whereas in standard
batch-compilation mode the <option>-i</option> option is used to
specify the search path for interface files, see <xref
- linkend="search-path">.</para> </footnote></para>
+ linkend="search-path"/>.</para> </footnote></para>
<para>One consequence of the way that GHCi follows dependencies
to find modules to load is that every module must have a source
doing its best to avoid actually recompiling modules if their
external dependencies haven't changed. This is the same
mechanism we use to avoid re-compiling modules in the batch
- compilation setting (see <xref linkend="recomp">).</para>
+ compilation setting (see <xref linkend="recomp"/>).</para>
</sect2>
</sect1>
use one in preference to interpreting the source if possible. For
example, suppose we have a 4-module program consisting of modules
A, B, C, and D. Modules B and C both import D only,
- and A imports both B & C:</para>
+ and A imports both B & C:</para>
<screen>
A
/ \
<para>Here's an example:</para>
<screen>
-Prelude> x <- return 42
+Prelude> x <- return 42
Prelude> print x
42
Prelude>
</screen>
- <para>The statement <literal>x <- return 42</literal> means
+ <para>The statement <literal>x <- return 42</literal> means
“execute <literal>return 42</literal> in the
<literal>IO</literal> monad, and bind the result to
<literal>x</literal>”. We can then use
Prelude>
</screen>
<para>An important difference between the two types of binding
- is that the monadic bind (<literal>p <- e</literal>) is
+ is that the monadic bind (<literal>p <- e</literal>) is
<emphasis>strict</emphasis> (it evaluates <literal>e</literal>),
whereas with the <literal>let</literal> form, the expression
isn't evaluated immediately:</para>
<para>The corresponding translation for an IO-typed
<replaceable>e</replaceable> is
<screen>
- it <- <replaceable>e</replaceable>
+ it <- <replaceable>e</replaceable>
</screen>
</para>
instructs GHCi to load the specified modules or filenames (and all
the modules they depend on), just as if you had said
<literal>:load <replaceable>modules</replaceable></literal> at the
- GHCi prompt (see <xref linkend="ghci-commands">). For example, to
+ GHCi prompt (see <xref linkend="ghci-commands"/>). For example, to
start GHCi and load the program whose topmost module is in the
file <literal>Main.hs</literal>, we could say:</para>
</screen>
<para>Most of the command-line options accepted by GHC (see <xref
- linkend="using-ghc">) also make sense in interactive mode. The ones
+ linkend="using-ghc"/>) also make sense in interactive mode. The ones
that don't make sense are mostly obvious; for example, GHCi
doesn't generate interface files, so options related to interface
file generation won't have any effect.</para>
<title>Packages</title>
<indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
- <para>Most packages (see <xref linkend="using-packages">) are
+ <para>Most packages (see <xref linkend="using-packages"/>) are
available without needing to specify any extra flags at all:
they will be automatically loaded the first time they are
needed.</para>
the normal <literal>-l<replaceable>lib</replaceable></literal>
option. (The term <emphasis>library</emphasis> here refers to
libraries of foreign object code; for using libraries of Haskell
- source code, see <xref linkend="ghci-modules-filenames">.) For
+ source code, see <xref linkend="ghci-modules-filenames"/>.) For
example, to load the “m” library:</para>
<screen>
<para>Ordering of <option>-l</option> options matters: a library
should be mentioned <emphasis>before</emphasis> the libraries it
- depends on (see <xref linkend="options-linker">).</para>
+ depends on (see <xref linkend="options-linker"/>).</para>
</sect2>
</sect1>
<para>That's all a little confusing, so here's a few
examples. To start with, here's a new GHCi command which
doesn't take any arguments or produce any results, it just
- outputs the current date & time:</para>
+ outputs the current date & time:</para>
<screen>
Prelude> let date _ = Time.getClockTime >>= print >> return ""
<indexterm><primary><literal>:module</literal></primary></indexterm>
<listitem>
<para>Sets or modifies the current context for statements
- typed at the prompt. See <xref linkend="ghci-scope"> for
+ typed at the prompt. See <xref linkend="ghci-scope"/> for
more details.</para>
</listitem>
</varlistentry>
<term><literal>:set</literal> <optional><replaceable>option</replaceable>...</optional></term>
<indexterm><primary><literal>:set</literal></primary></indexterm>
<listitem>
- <para>Sets various options. See <xref linkend="ghci-set">
+ <para>Sets various options. See <xref linkend="ghci-set"/>
for a list of available options. The
<literal>:set</literal> command by itself shows which
options are currently set.</para>
<term><literal>:unset</literal> <replaceable>option</replaceable>...</term>
<indexterm><primary><literal>:unset</literal></primary></indexterm>
<listitem>
- <para>Unsets certain options. See <xref linkend="ghci-set">
+ <para>Unsets certain options. See <xref linkend="ghci-set"/>
for a list of available options.</para>
</listitem>
</varlistentry>
<para>Any GHC command-line option that is designated as
<firstterm>dynamic</firstterm> (see the table in <xref
- linkend="flag-reference">), may be set using
+ linkend="flag-reference"/>), may be set using
<literal>:set</literal>. To unset an option, you can set the
reverse option:</para>
<indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm>
Prelude> :set -fno-glasgow-exts
</screen>
- <para><xref linkend="flag-reference"> lists the reverse for each
+ <para><xref linkend="flag-reference"/> lists the reverse for each
option where applicable.</para>
<para>Certain static options (<option>-package</option>,
<listitem>
<para>This simultaneously enables all of the extensions to
Haskell 98 described in <xref
- linkend="ghc-language-features">, except where otherwise
+ linkend="ghc-language-features"/>, except where otherwise
noted. </para>
<para>New reserved words: <literal>forall</literal> (only in
<indexterm><primary><option>-fallow-undecidable-instances</option></primary></indexterm>
<indexterm><primary><option>-fcontext-stack</option></primary></indexterm>
<listitem>
- <para> See <xref LinkEnd="instance-decls">. Only relevant
+ <para> See <xref linkend="instance-decls"/>. Only relevant
if you also use <option>-fglasgow-exts</option>.</para>
</listitem>
</varlistentry>
<term><option>-finline-phase</option></term>
<indexterm><primary><option>-finline-phase</option></primary></indexterm>
<listitem>
- <para>See <xref LinkEnd="rewrite-rules">. Only relevant if
+ <para>See <xref linkend="rewrite-rules"/>. Only relevant if
you also use <option>-fglasgow-exts</option>.</para>
</listitem>
</varlistentry>
<term><option>-farrows</option></term>
<indexterm><primary><option>-farrows</option></primary></indexterm>
<listitem>
- <para>See <xref LinkEnd="arrow-notation">. Independent of
+ <para>See <xref linkend="arrow-notation"/>. Independent of
<option>-fglasgow-exts</option>.</para>
<para>New reserved words/symbols: <literal>rec</literal>,
<term><option>-fgenerics</option></term>
<indexterm><primary><option>-fgenerics</option></primary></indexterm>
<listitem>
- <para>See <xref LinkEnd="generic-classes">. Independent of
+ <para>See <xref linkend="generic-classes"/>. Independent of
<option>-fglasgow-exts</option>.</para>
</listitem>
</varlistentry>
<para>However, <option>-fno-implicit-prelude</option> does
change the handling of certain built-in syntax: see <xref
- LinkEnd="rebindable-syntax">.</para>
+ linkend="rebindable-syntax"/>.</para>
</listitem>
</varlistentry>
<term><option>-fth</option></term>
<listitem>
<para>Enables Template Haskell (see <xref
- linkend="template-haskell">). Currently also implied by
+ linkend="template-haskell"/>). Currently also implied by
<option>-fglasgow-exts</option>.</para>
<para>Syntax stolen: <literal>[|</literal>,
<term><option>-fimplicit-params</option></term>
<listitem>
<para>Enables implicit parameters (see <xref
- linkend="implicit-parameters">). Currently also implied by
+ linkend="implicit-parameters"/>). Currently also implied by
<option>-fglasgow-exts</option>.</para>
<para>Syntax stolen:
<para>For details on how GHC searches for source and interface
files in the presence of hierarchical modules, see <xref
- linkend="search-path">.</para>
+ linkend="search-path"/>.</para>
<para>GHC comes with a large collection of libraries arranged
hierarchically; see the accompanying library documentation.
<para>
<indexterm><primary>Pattern guards (Glasgow extension)</primary></indexterm>
-The discussion that follows is an abbreviated version of Simon Peyton Jones's original <ULink URL="http://research.microsoft.com/~simonpj/Haskell/guards.html">proposal</ULink>. (Note that the proposal was written before pattern guards were implemented, so refers to them as unimplemented.)
+The discussion that follows is an abbreviated version of Simon Peyton Jones's original <ulink URL="http://research.microsoft.com/~simonpj/Haskell/guards.html">proposal</ulink>. (Note that the proposal was written before pattern guards were implemented, so refers to them as unimplemented.)
</para>
<para>
</programlisting>
The lookup returns <function>Nothing</function> if the supplied key is not in the domain of the mapping, and <function>(Just v)</function> otherwise,
-where <VarName>v</VarName> is the value that the key maps to. Now consider the following definition:
+where <varname>v</varname> is the value that the key maps to. Now consider the following definition:
</para>
<programlisting>
-clunky env var1 var2 | ok1 && ok2 = val1 + val2
+clunky env var1 var2 | ok1 && ok2 = val1 + val2
| otherwise = var1 + var2
where
m1 = lookup env var1
</programlisting>
<para>
-What is <function>clunky</function> doing? The guard <literal>ok1 &&
+What is <function>clunky</function> doing? The guard <literal>ok1 &&
ok2</literal> checks that both lookups succeed, using
<function>maybeToBool</function> to convert the <function>Maybe</function>
types to booleans. The (lazily evaluated) <function>expectJust</function>
calls extract the values from the results of the lookups, and binds the
-returned values to <VarName>val1</VarName> and <VarName>val2</VarName>
+returned values to <varname>val1</varname> and <varname>val2</varname>
respectively. If either lookup fails, then clunky takes the
<literal>otherwise</literal> case and returns the sum of its arguments.
</para>
</para>
<programlisting>
-f x | [y] <- x
+f x | [y] <- x
, y > 3
- , Just z <- h y
+ , Just z <- h y
= ...
</programlisting>
<programlisting>
import Control.Monad.Fix
-justOnes = mdo xs <- Just (1:xs)
+justOnes = mdo xs <- Just (1:xs)
return xs
</programlisting>
<para>
example, the following zips together two lists:</para>
<programlisting>
- [ (x, y) | x <- xs | y <- ys ]
+ [ (x, y) | x <- xs | y <- ys ]
</programlisting>
<para>The behavior of parallel list comprehensions follows that of
<para>Given a parallel comprehension of the form: </para>
<programlisting>
- [ e | p1 <- e11, p2 <- e12, ...
- | q1 <- e21, q2 <- e22, ...
+ [ e | p1 <- e11, p2 <- e12, ...
+ | q1 <- e21, q2 <- e22, ...
...
]
</programlisting>
<para>This will be translated to: </para>
<programlisting>
- [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...]
- [(q1,q2) | q1 <- e21, q2 <- e22, ...]
+ [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...]
+ [(q1,q2) | q1 <- e21, q2 <- e22, ...]
...
]
</programlisting>
<para>Syntactically, the declaration lacks the "= constrs" part. The
type can be parameterised over types of any kind, but if the kind is
not <literal>*</literal> then an explicit kind annotation must be used
-(see <xref linkend="sec-kinding">).</para>
+(see <xref linkend="sec-kinding"/>).</para>
<para>Such data types have only one value, namely bottom.
Nevertheless, they can be useful when defining "phantom types".</para>
The idea of using existential quantification in data type declarations
was suggested by Laufer (I believe, thought doubtless someone will
correct me), and implemented in Hope+. It's been in Lennart
-Augustsson's <Command>hbc</Command> Haskell compiler for several years, and
+Augustsson's <command>hbc</command> Haskell compiler for several years, and
proved very useful. Here's the idea. Consider the declaration:
</para>
<title>Type classes</title>
<para>
-An easy extension (implemented in <Command>hbc</Command>) is to allow
+An easy extension (implemented in <command>hbc</command>) is to allow
arbitrary contexts before the constructor. For example:
</para>
(MkT a) == (MkT b) = ???
</programlisting>
-But <VarName>a</VarName> and <VarName>b</VarName> have distinct types, and so can't be compared.
+But <varname>a</varname> and <varname>b</varname> have distinct types, and so can't be compared.
It's just about possible to imagine examples in which the derived instance
would make sense, but it seems altogether simpler simply to prohibit such
declarations. Define your own instances!
<para>
This section documents GHC's implementation of multi-parameter type
-classes. There's lots of background in the paper <ULink
+classes. There's lots of background in the paper <ulink
URL="http://research.microsoft.com/~simonpj/multi.ps.gz" >Type
-classes: exploring the design space</ULink > (Simon Peyton Jones, Mark
+classes: exploring the design space</ulink > (Simon Peyton Jones, Mark
Jones, Erik Meijer).
</para>
<para>
There are the following constraints on class declarations:
-<OrderedList>
+<orderedlist>
<listitem>
<para>
<para>
<emphasis>All of the class type variables must be reachable (in the sense
-mentioned in <xref linkend="type-restrictions">)
+mentioned in <xref linkend="type-restrictions"/>)
from the free varibles of each method type
</emphasis>. For example:
</para>
</listitem>
-</OrderedList>
+</orderedlist>
</para>
<sect3 id="class-method-types">
language omits them; in Haskell 98, all the free type variables of an
explicit source-language type signature are universally quantified,
except for the class type variables in a class declaration. However,
-in GHC, you can give the foralls if you want. See <xref LinkEnd="universal-quantification">).
+in GHC, you can give the foralls if you want. See <xref linkend="universal-quantification"/>).
</para>
<para>
-<OrderedList>
+<orderedlist>
<listitem>
<para>
that the reachability condition is weaker than saying that <literal>a</literal> is
functionally dependendent on a type variable free in
<literal>type</literal> (see <xref
-linkend="functional-dependencies">). The reason for this is there
+linkend="functional-dependencies"/>). The reason for this is there
might be a "hidden" dependency, in a superclass perhaps. So
"reachable" is a conservative approximation to "functionally dependent".
For example, consider:
</para>
</listitem>
-</OrderedList>
+</orderedlist>
</para>
</sect3>
<sect3 id="hoist">
<title>For-all hoisting</title>
<para>
-It is often convenient to use generalised type synonyms (see <xref linkend="type-synonyms">) at the right hand
+It is often convenient to use generalised type synonyms (see <xref linkend="type-synonyms"/>) at the right hand
end of an arrow, thus:
<programlisting>
type Discard a = forall b. a -> b -> a
is not OK.
</para>
</listitem>
-</OrderedList>
+</orderedlist>
These restrictions ensure that
context reduction terminates: each reduction step removes one type
constructor. For example, the following would make the type checker
<literal>cmp</literal>.
<programlisting>
min :: [a] -> a
- min = let ?cmp = (<=) in least
+ min = let ?cmp = (<=) in least
</programlisting>
</para>
<para>
just as it is nice to give a type signature for a function. On some occasions,
it is essential to do so. For example, in his paper "Restricted Data Types in Haskell" (Haskell Workshop 1999)
John Hughes had to define the data type:
-<Screen>
+<screen>
data Set cxt a = Set [a]
| Unused (cxt a -> ())
-</Screen>
+</screen>
The only use for the <literal>Unused</literal> constructor was to force the correct
kind for the type variable <literal>cxt</literal>.
</para>
a type variable is explicitly bound. Namely:
<itemizedlist>
<listitem><para><literal>data</literal> declarations:
-<Screen>
+<screen>
data Set (cxt :: * -> *) a = Set [a]
-</Screen></para></listitem>
+</screen></para></listitem>
<listitem><para><literal>type</literal> declarations:
-<Screen>
+<screen>
type T (f :: * -> *) = f Int
-</Screen></para></listitem>
+</screen></para></listitem>
<listitem><para><literal>class</literal> declarations:
-<Screen>
+<screen>
class (Eq a) => C (f :: * -> *) a where ...
-</Screen></para></listitem>
+</screen></para></listitem>
<listitem><para><literal>forall</literal>'s in type signatures:
-<Screen>
+<screen>
f :: forall (cxt :: * -> *). Set cxt Int
-</Screen></para></listitem>
+</screen></para></listitem>
</itemizedlist>
</para>
<para>
As part of the same extension, you can put kind annotations in types
as well. Thus:
-<Screen>
+<screen>
f :: (Int :: *) -> Int
g :: forall a. a -> (a :: *)
-</Screen>
+</screen>
The syntax is
-<Screen>
+<screen>
atype ::= '(' ctype '::' kind ')
-</Screen>
+</screen>
The parentheses are required.
</para>
</sect2>
including an operational type class context, is legal:
<itemizedlist>
<listitem> <para> On the left of a function arrow </para> </listitem>
-<listitem> <para> On the right of a function arrow (see <xref linkend="hoist">) </para> </listitem>
+<listitem> <para> On the right of a function arrow (see <xref linkend="hoist"/>) </para> </listitem>
<listitem> <para> As the argument of a constructor, or type of a field, in a data type declaration. For
example, any of the <literal>f1,f2,f3,g1,g2</literal> above would be valid
field type signatures.</para> </listitem>
<listitem> <para> As the type of an implicit parameter </para> </listitem>
-<listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables">) </para> </listitem>
+<listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables"/>) </para> </listitem>
</itemizedlist>
There is one place you cannot put a <literal>forall</literal>:
you cannot instantiate a type variable with a forall-type. So you cannot
<para>
What does it mean to "provide" an explicit type for x? You can do that by
giving a type signature for x directly, using a pattern type signature
-(<xref linkend="scoped-type-variables">), thus:
+(<xref linkend="scoped-type-variables"/>), thus:
<programlisting>
\ f :: (forall a. a->a) -> (f True, f 'c')
</programlisting>
</para>
<para>
-The pattern <literal>(xs::[a])</literal> includes a type signature for <VarName>xs</VarName>.
+The pattern <literal>(xs::[a])</literal> includes a type signature for <varname>xs</varname>.
This brings the type variable <literal>a</literal> into scope; it scopes over
all the patterns and right hand sides for this equation for <function>f</function>.
-In particular, it is in scope at the type signature for <VarName>y</VarName>.
+In particular, it is in scope at the type signature for <varname>y</varname>.
</para>
<para>
Pattern type signatures are completely orthogonal to ordinary, separate
type signatures. The two can be used independently or together.
-At ordinary type signatures, such as that for <VarName>ys</VarName>, any type variables
+At ordinary type signatures, such as that for <varname>ys</varname>, any type variables
mentioned in the type signature <emphasis>that are not in scope</emphasis> are
implicitly universally quantified. (If there are no type variables in
scope, all type variables mentioned in the signature are universally
-quantified, which is just as in Haskell 98.) In this case, since <VarName>a</VarName>
-is in scope, it is not universally quantified, so the type of <VarName>ys</VarName> is
-the same as that of <VarName>xs</VarName>. In Haskell 98 it is not possible to declare
-a type for <VarName>ys</VarName>; a major benefit of scoped type variables is that
+quantified, which is just as in Haskell 98.) In this case, since <varname>a</varname>
+is in scope, it is not universally quantified, so the type of <varname>ys</varname> is
+the same as that of <varname>xs</varname>. In Haskell 98 it is not possible to declare
+a type for <varname>ys</varname>; a major benefit of scoped type variables is that
it becomes possible to do so.
</para>
as the term variable(s) bound by the pattern. For example:
<programlisting>
let
- f (x::a) = <...rhs of f...>
+ f (x::a) = <...rhs of f...>
(p::b, q::b) = (1,2)
- in <...body of let...>
+ in <...body of let...>
</programlisting>
Here, the type variable <literal>a</literal> scopes over the right hand side of <literal>f</literal>,
just like <literal>x</literal> does; while the type variable <literal>b</literal> scopes over the
f x = x::a
</programlisting>
-It's illegal because <VarName>a</VarName> is not in scope in the body of <function>f</function>,
+It's illegal because <varname>a</varname> is not in scope in the body of <function>f</function>,
so the ordinary signature <literal>x::a</literal> is equivalent to <literal>x::forall a.a</literal>;
and that is an incorrect typing.
returnA
</screen>
Note that variables not used later in the composition are projected out.
-After simplification using rewrite rules (see <xref linkEnd="rewrite-rules">)
+After simplification using rewrite rules (see <xref linkend="rewrite-rules"/>)
defined in the
<ulink url="../base/Control.Arrow.html"><literal>Control.Arrow</literal></ulink>
module, this reduces to
For example, we could simulate <literal>do</literal>-notation by defining
<programlisting>
bind :: Arrow a => a e b -> a (e,b) c -> a e c
-u `bind` f = returnA &&& u >>> f
+u `bind` f = returnA &&& u >>> f
bind_ :: Arrow a => a e b -> a e c -> a e c
u `bind_` f = u `bind` (arr fst >>> f)
</programlisting>
<para>See also the <literal>NOINLINE</literal> pragma (<xref
- linkend="noinline-pragma">).</para>
+ linkend="noinline-pragma"/>).</para>
</sect3>
<sect3 id="noinline-pragma">
</itemizedlist>
<para>The same phase-numbering control is available for RULES
- (<xref LinkEnd="rewrite-rules">).</para>
+ (<xref linkend="rewrite-rules"/>).</para>
</sect3>
</sect2>
<para>The <literal>OPTIONS</literal> pragma is used to specify
additional options that are given to the compiler when compiling
- this source file. See <xref linkend="source-file-options"> for
+ this source file. See <xref linkend="source-file-options"/> for
details.</para>
</sect2>
<title>RULES pragma</title>
<para>The RULES pragma lets you specify rewrite rules. It is
- described in <xref LinkEnd="rewrite-rules">.</para>
+ described in <xref linkend="rewrite-rules"/>.</para>
</sect2>
<sect2 id="specialize-pragma">
<para>A <literal>SPECIALIZE</literal> has the effect of generating
(a) a specialised version of the function and (b) a rewrite rule
- (see <xref linkend="rewrite-rules">) that rewrites a call to the
+ (see <xref linkend="rewrite-rules"/>) that rewrites a call to the
un-specialised function into a call to the specialised one.</para>
<para>In earlier versions of GHC, it was possible to provide your own
</programlisting>
This feature has been removed, as it is now subsumed by the
- <literal>RULES</literal> pragma (see <xref linkend="rule-spec">).</para>
+ <literal>RULES</literal> pragma (see <xref linkend="rule-spec"/>).</para>
</sect2>
the constructor itself, removing a level of indirection. For
example:</para>
-<ProgramListing>
+<programlisting>
data T = T {-# UNPACK #-} !Float
{-# UNPACK #-} !Float
-</ProgramListing>
+</programlisting>
<para>will create a constructor <literal>T</literal> containing
two unboxed floats. This may not always be an optimisation: if
- the <Function>T</Function> constructor is scrutinised and the
+ the <function>T</function> constructor is scrutinised and the
floats passed to a non-strict function for example, they will
have to be reboxed (this is done automatically by the
compiler).</para>
unfoldings to the compiler so the reboxing can be removed as
often as possible. For example:</para>
-<ProgramListing>
+<programlisting>
f :: T -> Float
f (T f1 f2) = f1 + f2
-</ProgramListing>
+</programlisting>
- <para>The compiler will avoid reboxing <Function>f1</Function>
- and <Function>f2</Function> by inlining <Function>+</Function>
+ <para>The compiler will avoid reboxing <function>f1</function>
+ and <function>f2</function> by inlining <function>+</function>
on floats, but only when <option>-O</option> is on.</para>
<para>Any single-constructor data is eligible for unpacking; for
example</para>
-<ProgramListing>
+<programlisting>
data T = T {-# UNPACK #-} !(Int,Int)
-</ProgramListing>
+</programlisting>
<para>will store the two <literal>Int</literal>s directly in the
- <Function>T</Function> constructor, by flattening the pair.
+ <function>T</function> constructor, by flattening the pair.
Multi-level unpacking is also supported:</para>
-<ProgramListing>
+<programlisting>
data T = T {-# UNPACK #-} !S
data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
-</ProgramListing>
+</programlisting>
<para>will store two unboxed <literal>Int#</literal>s
- directly in the <Function>T</Function> constructor. The
+ directly in the <function>T</function> constructor. The
unpacker can see through newtypes, too.</para>
<para>If a field cannot be unpacked, you will not get a warning,
<para>
The programmer can specify rewrite rules as part of the source program
(in a pragma). GHC applies these rewrite rules wherever it can, provided (a)
-the <option>-O</option> flag (<xref LinkEnd="options-optimise">) is on,
+the <option>-O</option> flag (<xref linkend="options-optimise"/>) is on,
and (b) the <option>-frules-off</option> flag
-(<xref LinkEnd="options-f">) is not specified.
+(<xref linkend="options-f"/>) is not specified.
</para>
<para>
<listitem>
<para>
-A rule may optionally have a phase-control number (see <xref LinkEnd="phase-control">),
+A rule may optionally have a phase-control number (see <xref linkend="phase-control"/>),
immediately after the name of the rule. Thus:
<programlisting>
{-# RULES
<para>
Matching is carried out on GHC's intermediate language, which includes
type abstractions and applications. So a rule only matches if the
-types match too. See <xref LinkEnd="rule-spec"> below.
+types match too. See <xref linkend="rule-spec"/> below.
</para>
</listitem>
<listitem>
</programlisting>
The expression <literal>s (t xs)</literal> does not match the rule <literal>"map/map"</literal>, but GHC
-will substitute for <VarName>s</VarName> and <VarName>t</VarName>, giving an expression which does match.
-If <VarName>s</VarName> or <VarName>t</VarName> was (a) used more than once, and (b) large or a redex, then it would
+will substitute for <varname>s</varname> and <varname>t</varname>, giving an expression which does match.
+If <varname>s</varname> or <varname>t</varname> was (a) used more than once, and (b) large or a redex, then it would
not be substituted, and the rule would not fire.
</para>
<listitem>
<para>
- The defintion of (say) <function>build</function> in <FileName>GHC/Base.lhs</FileName> looks llike this:
+ The defintion of (say) <function>build</function> in <filename>GHC/Base.lhs</filename> looks llike this:
<programlisting>
build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
<para>
However, when external for is generated (via
<option>-fext-core</option>), there will be Notes attached to the
- expressions <function>show</function> and <VarName>x</VarName>.
+ expressions <function>show</function> and <varname>x</varname>.
The core function declaration for <function>f</function> is:
</para>
Here, we can see that the function <function>show</function> (which
has been expanded out to a case expression over the Show dictionary)
has a <literal>%note</literal> attached to it, as does the
- expression <VarName>eta</VarName> (which used to be called
- <VarName>x</VarName>).
+ expression <varname>eta</varname> (which used to be called
+ <varname>x</varname>).
</para>
</sect2>
<chapter id="wrong">
<title>What to do when something goes wrong</title>
- <Indexterm><Primary>problems</Primary></Indexterm>
+ <indexterm><primary>problems</primary></indexterm>
<para>If you still have a problem after consulting this section,
- then you may have found a <Emphasis>bug</Emphasis>—please
- report it! See <XRef LinkEnd="bug-reporting"> for details on how to
+ then you may have found a <emphasis>bug</emphasis>—please
+ report it! See <xref linkend="bug-reporting"/> for details on how to
report a bug and a list of things we'd like to know about your bug.
If in doubt, send a report—we love mail from irate users
:-!</para>
- <para>(<XRef LinkEnd="vs-Haskell-defn">, which describes Glasgow
+ <para>(<xref linkend="vs-Haskell-defn"/>, which describes Glasgow
Haskell's shortcomings vs. the Haskell language definition, may
also be of interest.)</para>
<sect1 id="wrong-compiler">
<title>When the compiler “does the wrong thing”</title>
- <Indexterm><Primary>compiler problems</Primary></Indexterm>
- <Indexterm><Primary>problems with the compiler</Primary></Indexterm>
+ <indexterm><primary>compiler problems</primary></indexterm>
+ <indexterm><primary>problems with the compiler</primary></indexterm>
<variablelist>
<varlistentry>
<term>“Help! The compiler crashed (or `panic'd)!”</term>
<listitem>
- <para>These events are <Emphasis>always</Emphasis> bugs in
+ <para>These events are <emphasis>always</emphasis> bugs in
the GHC system—please report them.</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term>Sensitivity to <Filename>.hi</Filename> interface files:</term>
+ <term>Sensitivity to <filename>.hi</filename> interface files:</term>
<listitem>
<para>GHC is very sensitive about interface files. For
example, if it picks up a non-standard
<sect1 id="wrong-compilee">
<title>When your program “does the wrong thing”</title>
- <Indexterm><Primary>problems running your program</Primary></Indexterm>
+ <indexterm><primary>problems running your program</primary></indexterm>
<para>(For advice about overly slow or memory-hungry Haskell
- programs, please see <XRef
- LinkEnd="sooner-faster-quicker">).</para>
+ programs, please see <xref
+ linkend="sooner-faster-quicker"/>).</para>
<variablelist>
<para>For example, if an interface is lying about the type
of an imported value then GHC may well generate duff code
- for the importing module. <Emphasis>This applies to pragmas
- inside interfaces too!</Emphasis> If the pragma is lying
+ for the importing module. <emphasis>This applies to pragmas
+ inside interfaces too!</emphasis> If the pragma is lying
(e.g., about the “arity” of a value), then duff
code may result. Furthermore, arities may change even if
types do not.</para>
automatically generate the dependencies required in order to
make sure that every module <emphasis>is</emphasis>
up-to-date with respect to its imported interfaces. Please
- see <xref linkend="sec-makefile-dependencies">.</para>
+ see <xref linkend="sec-makefile-dependencies"/>.</para>
<para>If you are down to your
last-compile-before-a-bug-report, we would recommend that
<para>So, before you report a bug because of a core dump,
you should probably:</para>
-<Screen>
+<screen>
% rm *.o # scrub your object files
% make my_prog # re-make your program; use -hi-diffs to highlight changes;
# as mentioned above, use -dcore-lint to be more paranoid
% ./my_prog ... # retry...
-</Screen>
+</screen>
<para>Of course, if you have foreign calls in your program
then all bets are off, because you can trash the heap, the
<term>“My program entered an `absent' argument.”</term>
<listitem>
<para>This is definitely caused by a bug in GHC. Please
- report it (see <xref linkend="bug-reporting">).</para>
+ report it (see <xref linkend="bug-reporting"/>).</para>
</listitem>
</varlistentry>
-<Chapter id="sec-installing-bin-distrib">
- <Title>Installing GHC</Title>
-<IndexTerm><Primary>binary installations</Primary></IndexTerm>
-<IndexTerm><Primary>installation, of binaries</Primary></IndexTerm>
+<chapter id="sec-installing-bin-distrib">
+ <title>Installing GHC</title>
+<indexterm><primary>binary installations</primary></indexterm>
+<indexterm><primary>installation, of binaries</primary></indexterm>
-<Para>
+<para>
Installing from binary distributions is easiest, and recommended!
(Why binaries? Because GHC is a Haskell compiler written in Haskell,
so you've got to bootstrap it somehow. We provide machine-generated
C-files-from-Haskell for this purpose, but it's really quite a pain to
use them. If you must build GHC from its sources, using a
binary-distributed GHC to do so is a sensible way to proceed. For the
-other <Literal>fptools</Literal> programs, many are written in
+other <literal>fptools</literal> programs, many are written in
Haskell, so binary distributions allow you to install them without
having a Haskell compiler.)
-</Para>
+</para>
-<Para>This guide is in several parts:</para>
+<para>This guide is in several parts:</para>
<itemizedlist>
<listitem>
- <para> Installing on Unix-a-likes (<Xref
- LinkEnd="sec-unix-a-likes">). </para>
+ <para> Installing on Unix-a-likes (<xref
+ linkend="sec-unix-a-likes"/>). </para>
</listitem>
<listitem>
- <para> Installing on Windows (<Xref
- LinkEnd="sec-install-windows">). </para>
+ <para> Installing on Windows (<xref
+ linkend="sec-install-windows"/>). </para>
</listitem>
<listitem>
- <para> The layout of installed files (<Xref
- LinkEnd="sec-install-files">). You don't need to know this to
+ <para> The layout of installed files (<xref
+ linkend="sec-install-files"/>). You don't need to know this to
install GHC, but it's useful if you are changing the
implementation.</para>
</listitem>
</itemizedlist>
- <Sect1 id="sec-unix-a-likes"><Title>Installing on Unix-a-likes</Title>
+ <sect1 id="sec-unix-a-likes"><title>Installing on Unix-a-likes</title>
<sect2>
<title>When a platform-specific package is available</title>
<varlistentry>
<term>RedHat or SuSE Linux/x86</term>
<listitem>
- <para>RPM source & binary packages for RedHat and SuSE
+ <para>RPM source & binary packages for RedHat and SuSE
Linux (x86 only) are available for most major
releases.</para>
</listitem>
<term>FreeBSD/x86</term>
<listitem>
<para>On FreeBSD/x86, GHC can be installed using either
- the ports tree (<literal>cd /usr/ports/lang/ghc && make
+ the ports tree (<literal>cd /usr/ports/lang/ghc && make
install</literal>) or from a pre-compiled package
available from your local FreeBSD mirror.</para>
</listitem>
the GHC download page for details.</para>
</sect2>
-<Sect2>
-<Title>GHC binary distributions</Title>
+<sect2>
+<title>GHC binary distributions</title>
-<Para>
-<IndexTerm><Primary>bundles of binary stuff</Primary></IndexTerm>
-</Para>
+<para>
+<indexterm><primary>bundles of binary stuff</primary></indexterm>
+</para>
-<Para>
+<para>
Binary distributions come in “bundles,” one bundle per file called
-<literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>. (See the building guide for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus:
-</Para>
+<literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</literal>. (See the building guide for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus:
+</para>
-<Para>
+<para>
-<Screen>
+<screen>
% cd /your/scratch/space
-% gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -</Screen>
+% gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -</screen>
-</Para>
+</para>
-<Para>
+<para>
Then you should find a single directory,
-<Literal>ghc-<replaceable>version</replaceable></Literal>, with the
+<literal>ghc-<replaceable>version</replaceable></literal>, with the
following structure:
-</Para>
-
-<Para>
-<IndexTerm><Primary>binary distribution, layout</Primary></IndexTerm>
-<IndexTerm><Primary>directory layout (binary distributions)</Primary></IndexTerm>
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>Makefile.in</Literal></Term>
-<ListItem>
-<Para>
-the raw material from which the <Literal>Makefile</Literal>
-will be made (<Xref LinkEnd="sec-install">).
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>configure</Literal></Term>
-<ListItem>
-<Para>
-the configuration script (<Xref LinkEnd="sec-install">).
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>README</Literal></Term>
-<ListItem>
-<Para>
+</para>
+
+<para>
+<indexterm><primary>binary distribution, layout</primary></indexterm>
+<indexterm><primary>directory layout (binary distributions)</primary></indexterm>
+<variablelist>
+
+<varlistentry>
+<term><literal>Makefile.in</literal></term>
+<listitem>
+<para>
+the raw material from which the <literal>Makefile</literal>
+will be made (<xref linkend="sec-install"/>).
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>configure</literal></term>
+<listitem>
+<para>
+the configuration script (<xref linkend="sec-install"/>).
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>README</literal></term>
+<listitem>
+<para>
Contains this file summary.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>INSTALL</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>INSTALL</literal></term>
+<listitem>
+<para>
Contains this description of how to install
the bundle.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>ANNOUNCE</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>ANNOUNCE</literal></term>
+<listitem>
+<para>
The announcement message for the bundle.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>NEWS</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>NEWS</literal></term>
+<listitem>
+<para>
release notes for the bundle—a longer version
-of <Literal>ANNOUNCE</Literal>. For GHC, the release notes are contained in the User
+of <literal>ANNOUNCE</literal>. For GHC, the release notes are contained in the User
Guide and this file isn't present.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
- <Term><Literal>bin/<replaceable>platform</replaceable></Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+ <term><literal>bin/<replaceable>platform</replaceable></literal></term>
+<listitem>
+<para>
contains platform-specific executable
files to be invoked directly by the user. These are the files that
must end up in your path.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>lib/<replaceable>platform</replaceable>/</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>lib/<replaceable>platform</replaceable>/</literal></term>
+<listitem>
+<para>
contains platform-specific support
files for the installation. Typically there is a subdirectory for
-each <Literal>fptools</Literal> project, whose name is the name of the project with its
+each <literal>fptools</literal> project, whose name is the name of the project with its
version number. For example, for GHC there would be a sub-directory
-<Literal>ghc-x.xx</Literal>/ where <Literal>x.xx</Literal> is the version number of GHC in the bundle.
-</Para>
+<literal>ghc-x.xx</literal>/ where <literal>x.xx</literal> is the version number of GHC in the bundle.
+</para>
-<Para>
+<para>
These sub-directories have the following general structure:
-</Para>
+</para>
-<Para>
-<VariableList>
+<para>
+<variablelist>
-<VarListEntry>
-<Term><Literal>libHSstd.a</Literal> etc:</Term>
-<ListItem>
-<Para>
+<varlistentry>
+<term><literal>libHSstd.a</literal> etc:</term>
+<listitem>
+<para>
supporting library archives.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>ghc-iface.prl</Literal> etc:</Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>ghc-iface.prl</literal> etc:</term>
+<listitem>
+<para>
support scripts.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>import/</Literal></Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>Interface files</Primary></IndexTerm> (<Literal>.hi</Literal>) for the prelude.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>include/</Literal></Term>
-<ListItem>
-<Para>
-A few C <Literal>#include</Literal> files.
-</Para>
-</ListItem></VarListEntry>
-</VariableList>
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>share/</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>import/</literal></term>
+<listitem>
+<para>
+<indexterm><primary>Interface files</primary></indexterm> (<literal>.hi</literal>) for the prelude.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>include/</literal></term>
+<listitem>
+<para>
+A few C <literal>#include</literal> files.
+</para>
+</listitem></varlistentry>
+</variablelist>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>share/</literal></term>
+<listitem>
+<para>
contains platform-independent support files
for the installation. Again, there is a sub-directory for each
-<Literal>fptools</Literal> project.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>html/</Literal></Term>
-<ListItem>
-<Para>
+<literal>fptools</literal> project.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>html/</literal></term>
+<listitem>
+<para>
contains HTML documentation files (one
sub-directory per project).
-</Para>
-</ListItem></VarListEntry>
-</VariableList>
-</Para>
+</para>
+</listitem></varlistentry>
+</variablelist>
+</para>
-<Sect3 id="sec-install">
-<Title>Installing</Title>
+<sect3 id="sec-install">
+<title>Installing</title>
-<Para>
+<para>
OK, so let's assume that you have unpacked your chosen bundles. What
next? Well, you will at least need to run the
-<Literal>configure</Literal><IndexTerm><Primary>configure</Primary></IndexTerm>
+<literal>configure</literal><indexterm><primary>configure</primary></indexterm>
script by changing directory into the top-level directory for the
-bundle and typing <Literal>./configure</Literal>. That should convert
-<Literal>Makefile.in</Literal> to <Literal>Makefile</Literal>.
-</Para>
-
-<Para>
-<IndexTerm><Primary>installing in-place</Primary></IndexTerm>
-<IndexTerm><Primary>in-place installation</Primary></IndexTerm>
-You can now either start using the tools <Emphasis>in-situ</Emphasis> without going
-through any installation process, just type <Literal>make in-place</Literal> to set the
-tools up for this. You'll also want to add the path which <Literal>make</Literal> will
-now echo to your <Literal>PATH</Literal> environment variable. This option is useful if
+bundle and typing <literal>./configure</literal>. That should convert
+<literal>Makefile.in</literal> to <literal>Makefile</literal>.
+</para>
+
+<para>
+<indexterm><primary>installing in-place</primary></indexterm>
+<indexterm><primary>in-place installation</primary></indexterm>
+You can now either start using the tools <emphasis>in-situ</emphasis> without going
+through any installation process, just type <literal>make in-place</literal> to set the
+tools up for this. You'll also want to add the path which <literal>make</literal> will
+now echo to your <literal>PATH</literal> environment variable. This option is useful if
you simply want to try out the package and/or you don't have the
necessary privileges (or inclination) to properly install the tools
locally. Note that if you do decide to install the package `properly'
at a later date, you have to go through the installation steps that
follow.
-</Para>
+</para>
-<Para>
+<para>
To install a package, you'll have to do the following:
-</Para>
+</para>
-<Para>
+<para>
-<OrderedList>
-<ListItem>
+<orderedlist>
+<listitem>
-<Para>
- Edit the <Literal>Makefile</Literal> and check the settings of the following variables:
+<para>
+ Edit the <literal>Makefile</literal> and check the settings of the following variables:
-<IndexTerm><Primary>directories, installation</Primary></IndexTerm>
-<IndexTerm><Primary>installation directories</Primary></IndexTerm>
+<indexterm><primary>directories, installation</primary></indexterm>
+<indexterm><primary>installation directories</primary></indexterm>
-<VariableList>
+<variablelist>
-<VarListEntry>
-<Term><Literal>platform</Literal></Term>
-<ListItem>
-<Para>
+<varlistentry>
+<term><literal>platform</literal></term>
+<listitem>
+<para>
the platform you are going to install for.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>bindir</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>bindir</literal></term>
+<listitem>
+<para>
the directory in which to install user-invokable
binaries.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>libdir</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>libdir</literal></term>
+<listitem>
+<para>
the directory in which to install
platform-dependent support files.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>datadir</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>datadir</literal></term>
+<listitem>
+<para>
the directory in which to install
platform-independent support files.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>infodir</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>infodir</literal></term>
+<listitem>
+<para>
the directory in which to install Emacs info
files.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>htmldir</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>htmldir</literal></term>
+<listitem>
+<para>
the directory in which to install HTML
documentation.
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>dvidir</Literal></Term>
-<ListItem>
-<Para>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>dvidir</literal></term>
+<listitem>
+<para>
the directory in which to install DVI
documentation.
-</Para>
-</ListItem></VarListEntry>
-</VariableList>
+</para>
+</listitem></varlistentry>
+</variablelist>
The values for these variables can be set through invocation of the
-<Command>configure</Command><IndexTerm><Primary>configure</Primary></IndexTerm>
+<command>configure</command><indexterm><primary>configure</primary></indexterm>
script that comes with the distribution, but doing an optical diff to
see if the values match your expectations is always a Good Idea.
</para>
<para>
-<Emphasis>Instead of running <Command>configure</Command>, it is
-perfectly OK to copy <Filename>Makefile.in</Filename> to
-<Filename>Makefile</Filename> and set all these variables directly
-yourself. But do it right!</Emphasis>
-</Para>
+<emphasis>Instead of running <command>configure</command>, it is
+perfectly OK to copy <filename>Makefile.in</filename> to
+<filename>Makefile</filename> and set all these variables directly
+yourself. But do it right!</emphasis>
+</para>
-</ListItem>
-<ListItem>
+</listitem>
+<listitem>
-<Para>
-Run <Literal>make install</Literal>. This <Emphasis>
-should</Emphasis> work with ordinary Unix
-<Literal>make</Literal>—no need for fancy stuff like GNU
-<Literal>make</Literal>.
+<para>
+Run <literal>make install</literal>. This <emphasis>
+should</emphasis> work with ordinary Unix
+<literal>make</literal>—no need for fancy stuff like GNU
+<literal>make</literal>.
-</Para>
-</ListItem>
-<ListItem>
+</para>
+</listitem>
+<listitem>
-<Para>
-<Literal>rehash</Literal> (t?csh or zsh users), so your shell will see the new
+<para>
+<literal>rehash</literal> (t?csh or zsh users), so your shell will see the new
stuff in your bin directory.
-</Para>
-</ListItem>
-<ListItem>
+</para>
+</listitem>
+<listitem>
-<Para>
+<para>
Once done, test your “installation” as suggested in
-<XRef LinkEnd="sec-GHC-test">. Be sure to use a <Literal>-v</Literal>
+<xref linkend="sec-GHC-test"/>. Be sure to use a <literal>-v</literal>
option, so you can see exactly what pathnames it's using.
If things don't work as expected, check the list of known pitfalls in
the building guide.
-</Para>
-</ListItem>
+</para>
+</listitem>
-</OrderedList>
+</orderedlist>
-</Para>
+</para>
-<Para>
-<IndexTerm><Primary>link, installed as ghc</Primary></IndexTerm>
+<para>
+<indexterm><primary>link, installed as ghc</primary></indexterm>
When installing the user-invokable binaries, this installation
-procedure will install GHC as <Literal>ghc-x.xx</Literal> where <Literal>x.xx</Literal> is the version
+procedure will install GHC as <literal>ghc-x.xx</literal> where <literal>x.xx</literal> is the version
number of GHC. It will also make a link (in the binary installation
-directory) from <Literal>ghc</Literal> to <Literal>ghc-x.xx</Literal>. If you install multiple versions
-of GHC then the last one “wins”, and “<Literal>ghc</Literal>” will invoke the last
+directory) from <literal>ghc</literal> to <literal>ghc-x.xx</literal>. If you install multiple versions
+of GHC then the last one “wins”, and “<literal>ghc</literal>” will invoke the last
one installed. You can change this manually if you want. But
-regardless, <Literal>ghc-x.xx</Literal> should always invoke GHC version <Literal>x.xx</Literal>.
-</Para>
+regardless, <literal>ghc-x.xx</literal> should always invoke GHC version <literal>x.xx</literal>.
+</para>
-</Sect3>
+</sect3>
-<Sect3>
-<Title>What bundles there are</Title>
+<sect3>
+<title>What bundles there are</title>
-<Para>
-<IndexTerm><Primary>bundles, binary</Primary></IndexTerm> There are
+<para>
+<indexterm><primary>bundles, binary</primary></indexterm> There are
plenty of “non-basic” GHC bundles. The files for them are
called
-<Literal>ghc-x.xx-<replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>,
+<literal>ghc-x.xx-<replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</literal>,
where the <replaceable>platform</replaceable> is as above, and
<replaceable>bundle</replaceable> is one of these:
-</Para>
+</para>
-<Para>
-<VariableList>
+<para>
+<variablelist>
-<VarListEntry>
-<Term><Literal>prof</Literal>:</Term>
-<ListItem>
-<Para>
+<varlistentry>
+<term><literal>prof</literal>:</term>
+<listitem>
+<para>
Profiling with cost-centres. You probably want this.
-<IndexTerm><Primary>profiling bundles</Primary></IndexTerm>
-<IndexTerm><Primary>bundles, profiling</Primary></IndexTerm>
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>par</Literal>:</Term>
-<ListItem>
-<Para>
+<indexterm><primary>profiling bundles</primary></indexterm>
+<indexterm><primary>bundles, profiling</primary></indexterm>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>par</literal>:</term>
+<listitem>
+<para>
Parallel Haskell features (sits on top of PVM).
You'll want this if you're into that kind of thing.
-<IndexTerm><Primary>parallel bundles</Primary></IndexTerm>
-<IndexTerm><Primary>bundles, parallel</Primary></IndexTerm>
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>gran</Literal>:</Term>
-<ListItem>
-<Para>
+<indexterm><primary>parallel bundles</primary></indexterm>
+<indexterm><primary>bundles, parallel</primary></indexterm>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>gran</literal>:</term>
+<listitem>
+<para>
The “GranSim” parallel-Haskell simulator
(hmm… mainly for implementors).
-<IndexTerm><Primary>bundles, gransim</Primary></IndexTerm>
-<IndexTerm><Primary>gransim bundles</Primary></IndexTerm>
-</Para>
-</ListItem></VarListEntry>
-<VarListEntry>
-<Term><Literal>ticky</Literal>:</Term>
-<ListItem>
-<Para>
+<indexterm><primary>bundles, gransim</primary></indexterm>
+<indexterm><primary>gransim bundles</primary></indexterm>
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><literal>ticky</literal>:</term>
+<listitem>
+<para>
“Ticky-ticky” profiling; very detailed
information about “what happened when I ran this program”—really
for implementors.
-<IndexTerm><Primary>bundles, ticky-ticky</Primary></IndexTerm>
-<IndexTerm><Primary>ticky-ticky bundles</Primary></IndexTerm>
-</Para>
-</ListItem></VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-One likely scenario is that you will grab <Emphasis>two</Emphasis>
+<indexterm><primary>bundles, ticky-ticky</primary></indexterm>
+<indexterm><primary>ticky-ticky bundles</primary></indexterm>
+</para>
+</listitem></varlistentry>
+</variablelist>
+</para>
+
+<para>
+One likely scenario is that you will grab <emphasis>two</emphasis>
binary bundles—basic, and profiling. We don't usually make the
rest, although you can build them yourself from a source distribution.
-</Para>
+</para>
<para>The various GHC bundles are designed to be unpacked into the
same directory; then installing as per the directions above will
at least have the basic GHC binary distribution bundle, these extra
bundles won't install on their own.</para>
-</Sect3>
+</sect3>
-<Sect3 id="sec-GHC-test">
-<Title>Testing that GHC seems to be working
-</Title>
+<sect3 id="sec-GHC-test">
+<title>Testing that GHC seems to be working
+</title>
-<Para>
-<IndexTerm><Primary>testing a new GHC</Primary></IndexTerm>
-</Para>
+<para>
+<indexterm><primary>testing a new GHC</primary></indexterm>
+</para>
-<Para>
-The way to do this is, of course, to compile and run <Emphasis>this</Emphasis> program
-(in a file <Literal>Main.hs</Literal>):
-</Para>
+<para>
+The way to do this is, of course, to compile and run <emphasis>this</emphasis> program
+(in a file <literal>Main.hs</literal>):
+</para>
-<Para>
+<para>
-<ProgramListing>
+<programlisting>
main = putStr "Hello, world!\n"
-</ProgramListing>
+</programlisting>
-</Para>
+</para>
-<Para>
-Compile the program, using the <Literal>-v</Literal> (verbose) flag to verify that
+<para>
+Compile the program, using the <literal>-v</literal> (verbose) flag to verify that
libraries, etc., are being found properly:
-<Screen>
-% ghc -v -o hello Main.hs</Screen>
+<screen>
+% ghc -v -o hello Main.hs</screen>
-</Para>
+</para>
-<Para>
+<para>
Now run it:
-<Screen>
+<screen>
% ./hello
-Hello, world!</Screen>
+Hello, world!</screen>
-</Para>
+</para>
-<Para>
+<para>
Some simple-but-profitable tests are to compile and run the notorious
-<Literal>nfib</Literal><IndexTerm><Primary>nfib</Primary></IndexTerm> program, using different numeric types. Start with
-<Literal>nfib :: Int -> Int</Literal>, and then try <Literal>Integer</Literal>, <Literal>Float</Literal>, <Literal>Double</Literal>,
-<Literal>Rational</Literal> and perhaps the overloaded version. Code for this is
-distributed in <Literal>ghc/misc/examples/nfib/</Literal> in a source distribution.
-</Para>
+<literal>nfib</literal><indexterm><primary>nfib</primary></indexterm> program, using different numeric types. Start with
+<literal>nfib :: Int -> Int</literal>, and then try <literal>Integer</literal>, <literal>Float</literal>, <literal>Double</literal>,
+<literal>Rational</literal> and perhaps the overloaded version. Code for this is
+distributed in <literal>ghc/misc/examples/nfib/</literal> in a source distribution.
+</para>
<para>For more information on how to “drive” GHC, read
on...</para>
-</Sect3>
+</sect3>
-</Sect2>
+</sect2>
-</Sect1>
+</sect1>
-<Sect1 id="sec-install-windows"><Title>Installing on Windows</Title>
+<sect1 id="sec-install-windows"><title>Installing on Windows</title>
<para>
Getting the Glasgow Haskell Compiler (post 5.02) to run on Windows platforms is
a snap: the Installshield does everything you need.
</para>
-<Sect2><Title>Installing GHC on Windows</Title>
+<sect2><title>Installing GHC on Windows</title>
<para>
To install GHC, use the following steps:
</para>
<itemizedlist>
-<listitem><para>Download the Installshield <Filename>setup.exe</Filename>
+<listitem><para>Download the Installshield <filename>setup.exe</filename>
from the GHC download page
-<ULink
-URL="http://www.haskell.org/ghc">haskell.org</ULink>.
+<ulink
+URL="http://www.haskell.org/ghc">haskell.org</ulink>.
</para></listitem>
-<listitem><para>Run <Filename>setup.exe</Filename>.
+<listitem><para>Run <filename>setup.exe</filename>.
On Windows, all of GHC's files are installed in a single directory.
If you choose ``Custom'' from the list of install options, you will be given a
choice about where this directory is; otherwise it will be installed
of the installation directory you choose.
</para>
<para>(If you have already installed the same version of GHC, Installshield will offer to "modify",
-or "remove" GHC. Choose "remove"; then run <Filename>setup.exe</Filename> a
+or "remove" GHC. Choose "remove"; then run <filename>setup.exe</filename> a
second time. This time it should offer to install.)
</para>
<para>
<listitem><para>Otherwise, there is a per-user default which varies
between versions of Windows. On NT and XP-ish versions, it might
be:
-<Filename>c:\Documents and Settings\<username>\Local Settings\Temp</filename>
+<filename>c:\Documents and Settings\<username>\Local Settings\Temp</filename>
</para></listitem>
</itemizedlist>
The main point is that if you don't do anything GHC will work fine;
</para></listitem>
<listitem>
-<Para>
+<para>
To test the fruits of your labour, try now to compile a simple
Haskell program:
-</Para>
+</para>
-<Screen>
+<screen>
bash$ cat main.hs
module Main(main) where
..
bash$ ./main
Hello, world!
-bash$ </Screen>
+bash$ </screen>
</listitem>
</itemizedlist>
You do <emphasis>not</emphasis> need the Cygwin toolchain, or anything
else, to install and run GHC.
</para>
-<Para>
+<para>
An installation of GHC requires about 140M of disk space.
To run GHC comfortably, your machine should have at least
64M of memory.
-</Para>
+</para>
</sect2>
-<Sect2><title>Moving GHC around</title>
-<Para>
-At the moment, GHC installs in a fixed place (<Filename>c:/ghc/ghc-x.yy</Filename>,
+<sect2><title>Moving GHC around</title>
+<para>
+At the moment, GHC installs in a fixed place (<filename>c:/ghc/ghc-x.yy</filename>,
but once it is installed, you can freely move the entire GHC tree just by copying
-the <Filename>ghc-x.yy</Filename> directory. (You may need to fix up
+the <filename>ghc-x.yy</filename> directory. (You may need to fix up
the links in "Start/Programs/Glasgow Haskell Compiler" if you do this.)
</para>
<para>
We havn't quite got to the bottom of this, but so far as we know it's not
a problem with GHC itself. Nevertheless, just to keep life simple we usually
put GHC in a place with a space-free path.
-</Para>
+</para>
</sect2>
-<Sect2 id="winfaq"><title>Installing ghc-win32 FAQ</title>
+<sect2 id="winfaq">
+<title>Installing ghc-win32 FAQ</title>
-<QandASet>
+<qandaset>
-<QandAEntry>
+<qandaentry>
-<Question>
-<Para>
+<question>
+<para>
I'm having trouble with symlinks.
-</Para>
-</Question>
+</para>
+</question>
-<Answer>
-<Para>
-Symlinks only work under Cygwin (<Xref LinkEnd="sec-install">), so binaries
+<answer>
+<para>
+Symlinks only work under Cygwin (<xref linkend="sec-install"/>), so binaries
not linked to the Cygwin DLL, in particular those built for Mingwin, will not
work with symlinks.
-</Para>
-</Answer>
+</para>
+</answer>
-</QandAEntry>
+</qandaentry>
-<QandAEntry>
+<qandaentry>
-<Question>
-<Para>
-I'm getting “permission denied” messages from the <Command>rm</Command> or
-<Command>mv</Command>.
-</Para>
-</Question>
+<question>
+<para>
+I'm getting “permission denied” messages from the <command>rm</command> or
+<command>mv</command>.
+</para>
+</question>
-<Answer>
-<Para>
+<answer>
+<para>
This can have various causes: trying to rename a directory when an Explorer
window is open on it tends to fail. Closing the window generally cures the
problem, but sometimes its cause is more mysterious, and logging off and back
on or rebooting may be the quickest cure.
-</Para>
-</Answer>
+</para>
+</answer>
-</QandAEntry>
+</qandaentry>
-</QandASet>
+</qandaset>
<!-- doesn't add much value any longer; leave out [sof 7/2002].
-<Para>
-Further information on using GHC under Windows can be found in <ULink
+<para>
+Further information on using GHC under Windows can be found in <ulink
URL="http://www.dcs.gla.ac.uk/~sof/ghc-win32.html">Sigbjørn Finne's
-pages</ULink>. Note: ignore the installation instructions, which are rather
-out of date; the <Emphasis>Miscellaneous</Emphasis> section at the bottom of
+pages</ulink>. Note: ignore the installation instructions, which are rather
+out of date; the <emphasis>Miscellaneous</emphasis> section at the bottom of
the page is of most interest, covering topics beyond the scope of this
manual.
-</Para>
+</para>
-->
-</Sect2>
+</sect2>
-</Sect1>
+</sect1>
-<Sect1 id="sec-install-files"><Title>The layout of installed files</Title>
+<sect1 id="sec-install-files"><title>The layout of installed files</title>
<para>
This section describes what files get installed where. You don't need to know it
<variablelist>
<varlistentry>
<term>Library directory,</term>
-<listitem> <para> known as <Filename>$(libdir)</Filename>, holds all the
+<listitem> <para> known as <filename>$(libdir)</filename>, holds all the
support files needed to run GHC. On Unix, this
-directory is usually something like <Filename>/usr/lib/ghc/ghc-5.02</Filename>. </para>
+directory is usually something like <filename>/usr/lib/ghc/ghc-5.02</filename>. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Binary directory</term>
-<listitem> <para> known as <Filename>$(bindir)</Filename>, holds executables that
+<listitem> <para> known as <filename>$(bindir)</filename>, holds executables that
the user is expected to invoke.
Notably, it contains
-<Filename>ghc</Filename> and <Filename>ghci</FileName>. On Unix, this directory
-can be anywhere, but is typically something like <Filename>/usr/local/bin</Filename>. On Windows,
-however, this directory <emphasis>must be</emphasis> <Filename>$(libdir)/bin</Filename>.
+<filename>ghc</filename> and <filename>ghci</filename>. On Unix, this directory
+can be anywhere, but is typically something like <filename>/usr/local/bin</filename>. On Windows,
+however, this directory <emphasis>must be</emphasis> <filename>$(libdir)/bin</filename>.
</para>
</listitem>
</varlistentry>
<itemizedlist>
<listitem>
<para>
-<Filename>$(libdir)</Filename> is passed to GHC using the <option>-B</option> flag.
+<filename>$(libdir)</filename> is passed to GHC using the <option>-B</option> flag.
On Unix (but not Windows), the installed <filename>ghc</filename> is just a one-line
shell script that invokes the real GHC, passing a suitable <option>-B</option> flag.
[All the user-supplied flags
<listitem>
<para> On Windows (but not Unix), if no <option>-B</option> flag is given, GHC uses a system
call to find the directory in which the running GHC executable lives, and derives
-<Filename>$(libdir)</Filename> from that. [Unix lacks such a system call.]
-That is why <Filename>$(bindir)</Filename> must be <Filename>$(libdir)/bin</Filename>.
+<filename>$(libdir)</filename> from that. [Unix lacks such a system call.]
+That is why <filename>$(bindir)</filename> must be <filename>$(libdir)/bin</filename>.
</para>
</listitem>
</itemizedlist>
<sect2> <title>The binary directory</title>
-<para>The binary directory, <Filename>$(bindir)</Filename> contains user-visible
+<para>The binary directory, <filename>$(bindir)</filename> contains user-visible
executables, notably <filename>ghc</filename> and <filename>ghci</filename>.
You should add it to your <literal>$PATH</literal>
</para>
<para>On Unix, the user-invokable <filename>ghc</filename> invokes <filename>$(libdir)/ghc-<replaceable>version</replaceable></filename>,
passing a suitable <option>-B</option> flag to tell <filename>ghc-<replaceable>version</replaceable></filename> where
-<Filename>$(libdir)</Filename> is.
+<filename>$(libdir)</filename> is.
Similarly <filename>ghci</filename>, except the extra flag <literal>--interactive</literal> is passed.
</para>
</sect1>
-</Chapter>
+</chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
<para>GHC has two main components: an interactive Haskell
interpreter (also known as GHCi), described in <xref
- linkend="ghci">, and a batch compiler, described throughout <xref
- linkend="using-ghc">. In fact, GHC consists of a single program
+ linkend="ghci"/>, and a batch compiler, described throughout <xref
+ linkend="using-ghc"/>. In fact, GHC consists of a single program
which is just run with different options to provide either the
interactive or the batch system.</para>
extensions such as multi-parameter type classes, local universal and
existential quantification, functional dependencies, scoped type
variables and explicit unboxed types. These are all described in
- <xref linkend="ghc-language-features">.</para>
+ <xref linkend="ghc-language-features"/>.</para>
<para>GHC has a comprehensive optimiser, so when you want to Really
Go For It (and you've got time to spare) GHC can produce pretty fast
<para>GHC's profiling system supports “cost centre
stacks”: a way of seeing the profile of a Haskell program in a
- call-graph like structure. See <xref linkend="profiling"> for more
+ call-graph like structure. See <xref linkend="profiling"/> for more
details.</para>
<para>GHC comes with a large collection of libraries, with
everything from parser combinators to networking. The libraries are
described in separate documentation.</para>
- <Sect1 id="mailing-lists-GHC">
- <Title>Meta-information: Web sites, mailing lists, etc.</Title>
+ <sect1 id="mailing-lists-GHC">
+ <title>Meta-information: Web sites, mailing lists, etc.</title>
- <IndexTerm><Primary>mailing lists, Glasgow Haskell</Primary></IndexTerm>
- <IndexTerm><Primary>Glasgow Haskell mailing lists</Primary></IndexTerm>
+ <indexterm><primary>mailing lists, Glasgow Haskell</primary></indexterm>
+ <indexterm><primary>Glasgow Haskell mailing lists</primary></indexterm>
<para>On the World-Wide Web, there are several URLs of likely
interest:</para>
<listitem>
<para>This list is for GHC users to chat among themselves.
If you have a specific question about GHC, please check the
- FAQ first (<xref linkend="faq">).</para>
+ FAQ first (<xref linkend="faq"/>).</para>
<variablelist>
<varlistentry>
</listitem>
<listitem>
<para>Email your bug report to
- <Email>glasgow-haskell-bugs@haskell.org</Email>. </para>
+ <email>glasgow-haskell-bugs@haskell.org</email>. </para>
</listitem>
</itemizedlist>
<sect2>
<title>How do I tell if I should report my bug?</title>
- <para>Take a look at the FAQ (<xref linkend="faq">) and <xref
- linkend="wrong">, which will give you some guidance as to
+ <para>Take a look at the FAQ (<xref linkend="faq"/>) and <xref
+ linkend="wrong"/>, which will give you some guidance as to
whether the behaviour you're seeing is really a bug or
not.</para>
<listitem>
<para>What kind of machine are you running on, and exactly
what version of the operating system are you using?
- (on a Unix system, <Command>uname -a</Command> or <Command>cat
- /etc/motd</Command> will show the desired information.)</para>
+ (on a Unix system, <command>uname -a</command> or <command>cat
+ /etc/motd</command> will show the desired information.)</para>
</listitem>
<listitem>
- <para> What version of GCC are you using? <Command>gcc
- -v</Command> will tell you.</para>
+ <para> What version of GCC are you using? <command>gcc
+ -v</command> will tell you.</para>
</listitem>
<listitem>
<listitem>
<para> Be sure any Haskell compilations are run with a
- <Option>-v</Option> (verbose) flag, so we can see exactly
+ <option>-v</option> (verbose) flag, so we can see exactly
what was run, what versions of things you have, etc.</para>
</listitem>
old libraries.</para>
<para>The value of <literal>__GLASGOW_HASKELL__</literal>
- (see <xref linkend="c-pre-processor">) for a major release
+ (see <xref linkend="c-pre-processor"/>) for a major release
<literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>
is the integer <replaceable>xyy</replaceable> (if
<replaceable>y</replaceable> is a single digit, then a leading zero
<para>The version number of your copy of GHC can be found by
invoking <literal>ghc</literal> with the
<literal>––version</literal> flag (see <xref
- linkend="options-help">).</para>
+ linkend="options-help"/>).</para>
</sect1>
&relnotes;
-</Chapter>
+</chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
-<Chapter id="ghc-language-features">
-<Title>GHC Language Features</Title>
+<chapter id="ghc-language-features">
+<title>GHC Language Features</title>
-&glasgowexts
-¶llel
+&glasgowexts;
+∥
-</Chapter>
+</chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
-<Preface id="License">
-<Title>The Glasgow Haskell Compiler License</Title>
+<preface id="License">
+<title>The Glasgow Haskell Compiler License</title>
-<Para>
+<para>
Copyright 2002, The University Court of the University of Glasgow.
All rights reserved.
-</Para>
+</para>
-<Para>
+<para>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
-</Para>
+</para>
-<Para>
-<ItemizedList>
+<para>
+<itemizedlist>
-<ListItem>
-<Para>
+<listitem>
+<para>
Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
-</Para>
-</ListItem>
+</para>
+</listitem>
-<ListItem>
-<Para>
+<listitem>
+<para>
Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
-</Para>
-</ListItem>
+</para>
+</listitem>
-<ListItem>
-<Para>
+<listitem>
+<para>
Neither name of the University nor the names of its contributors may be
used to endorse or promote products derived from this software without
specific prior written permission.
-</Para>
-</ListItem>
+</para>
+</listitem>
-</ItemizedList>
-</Para>
+</itemizedlist>
+</para>
-<Para>
+<para>
THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY COURT OF THE UNIVERSITY OF
GLASGOW AND THE CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
-</Para>
+</para>
-</Preface>
+</preface>
from an existing GHC installation, using the supplied
<literal>ghc-pkg</literal><indexterm><primary><literal>ghc-pkg</literal></primary>
</indexterm> tool, described in <xref
- linkend="package-management">.</para>
+ linkend="package-management"/>.</para>
<sect2 id="using-packages">
<title>Using a package</title>
<para>There's one case where you need to use the
<option>-package</option> option even for auto packages: when
- linking a program in batch mode mode (<xref linkend="options-order">)
+ linking a program in batch mode mode (<xref linkend="options-order"/>)
<footnote><para>This is because
GHC can't figure out from the object files which packages are
required; in <option>––make</option> mode and in
The same flag is necessary even if we compiled the modules from source, because GHC still
reckons it's in batch mode:
<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
-In <literal>--make</literal> and <literal>--interactive</literal> modes (<xref linkend="modes">), however, GHC figures out
+In <literal>--make</literal> and <literal>--interactive</literal> modes (<xref linkend="modes"/>), however, GHC figures out
the auto packages required for linking without further assistance.
</para>
<quote><literal>[]</literal></quote> in it. Packages can be
added to the new configuration file using the
<literal>ghc-pkg</literal> tool, described in <xref
- linkend="package-management">.</para>
+ linkend="package-management"/>.</para>
</sect2>
<sect2 id="building-packages">
make an inter-DLL call rather than an intra-DLL call
(inter-DLL calls require an extra
indirection). <emphasis>Building packages as DLLs doesn't
- work at the moment; see <XRef LinkEnd="win32-dlls-create">
+ work at the moment; see <xref linkend="win32-dlls-create"/>
for the gory details.</emphasis>
</para>
called <filename>HSfoo.o</filename> and load that. On some
systems, the <literal>ghc-pkg</literal> tool can
automatically build the GHCi version of each library, see
- <xref linkend="package-management">. To build these
+ <xref linkend="package-management"/>. To build these
libraries by hand from the <literal>.a</literal> archive, it
is possible to use GNU <command>ld</command> as
follows:</para>
<listitem>
<para>Set to <literal>True</literal> if the package should
be automatically available (see <xref
- linkend="using-packages">). This is normally set to
+ linkend="using-packages"/>). This is normally set to
<literal>True</literal> for packages which contain
hierarchical libraries, because in that case there is no
danger of polluting the module namespace.</para>
database as follows:
</para>
<screen>
- $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
+ $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg
</screen>
<para>
-<Sect1 id="concurrent-and-parallel">
-<Title>Concurrent and Parallel Haskell
-</Title>
+<sect1 id="concurrent-and-parallel">
+<title>Concurrent and Parallel Haskell</title>
-<Para>
-<IndexTerm><Primary>Concurrent Haskell</Primary></IndexTerm>
-<IndexTerm><Primary>Parallel Haskell</Primary></IndexTerm>
+<para>
+<indexterm><primary>Concurrent Haskell</primary></indexterm>
+<indexterm><primary>Parallel Haskell</primary></indexterm>
Concurrent and Parallel Haskell are Glasgow extensions to Haskell
which let you structure your program as a group of independent
`threads'.
-</Para>
+</para>
-<Para>
+<para>
Concurrent and Parallel Haskell have very different purposes.
-</Para>
+</para>
-<Para>
+<para>
Concurrent Haskell is for applications which have an inherent
structure of interacting, concurrent tasks (i.e. `threads'). Threads
-in such programs may be <Emphasis>required</Emphasis>. For example, if a concurrent thread has been spawned to handle a mouse click, it isn't
+in such programs may be <emphasis>required</emphasis>. For example, if a concurrent thread has been spawned to handle a mouse click, it isn't
optional—the user wants something done!
-</Para>
+</para>
-<Para>
+<para>
A Concurrent Haskell program implies multiple `threads' running within
a single Unix process on a single processor.
-</Para>
+</para>
-<Para>
+<para>
You will find at least one paper about Concurrent Haskell hanging off
-of <ULink URL="http://research.microsoft.com/~simonpj/">Simon Peyton
-Jones's Web page</ULink>.
-</Para>
+of <ulink URL="http://research.microsoft.com/~simonpj/">Simon Peyton
+Jones's Web page</ulink>.
+</para>
-<Para>
-Parallel Haskell is about <Emphasis>speed</Emphasis>—spawning
+<para>
+Parallel Haskell is about <emphasis>speed</emphasis>—spawning
threads onto multiple processors so that your program will run faster.
-The `threads' are always <Emphasis>advisory</Emphasis>—if the
+The `threads' are always <emphasis>advisory</emphasis>—if the
runtime system thinks it can get the job done more quickly by
sequential execution, then fine.
-</Para>
+</para>
-<Para>
+<para>
A Parallel Haskell program implies multiple processes running on
multiple processors, under a PVM (Parallel Virtual Machine) framework.
An MPI interface is under development but not fully functional, yet.
-</Para>
+</para>
-<Para>
+<para>
Parallel Haskell is still relatively new; it is more about “research
fun” than about “speed.” That will change.
-</Para>
+</para>
-<Para>
-Check the <ULink URL="http://www.cee.hw.ac.uk/~dsg/gph/">GPH Page</Ulink>
+<para>
+Check the <ulink url="http://www.cee.hw.ac.uk/~dsg/gph/">GPH Page</ulink>
for more information on “GPH” (Haskell98 with extensions for
parallel execution), the latest version of “GUM” (the runtime
system to enable parallel executions) and papers on research issues. A
list of publications about GPH and about GUM is also available from Simon's
Web Page.
-</Para>
+</para>
-<Para>
+<para>
Some details about Parallel Haskell follow. For more information
about concurrent Haskell, see the module
<literal>Control.Concurrent</literal> in the library documentation.
-</Para>
+</para>
-<Sect2>
-<Title>Features specific to Parallel Haskell
-<IndexTerm><Primary>Parallel Haskell—features</Primary></IndexTerm></Title>
+<sect2>
+<title>Features specific to Parallel Haskell
+<indexterm><primary>Parallel Haskell—features</primary></indexterm></title>
-<Sect3>
-<Title>The <Literal>Parallel</Literal> interface (recommended)
-<IndexTerm><Primary>Parallel interface</Primary></IndexTerm></Title>
+<sect3>
+<title>The <literal>Parallel</literal> interface (recommended)
+<indexterm><primary>Parallel interface</primary></indexterm></title>
-<Para>
+<para>
GHC provides two functions for controlling parallel execution, through
-the <Literal>Parallel</Literal> interface:
-</Para>
+the <literal>Parallel</literal> interface:
+</para>
-<Para>
+<para>
-<ProgramListing>
+<programlisting>
interface Parallel where
infixr 0 `par`
infixr 1 `seq`
par :: a -> b -> b
seq :: a -> b -> b
-</ProgramListing>
+</programlisting>
-</Para>
+</para>
-<Para>
-The expression <Literal>(x `par` y)</Literal> <Emphasis>sparks</Emphasis> the evaluation of <Literal>x</Literal>
-(to weak head normal form) and returns <Literal>y</Literal>. Sparks are queued for
+<para>
+The expression <literal>(x `par` y)</literal> <emphasis>sparks</emphasis> the evaluation of <literal>x</literal>
+(to weak head normal form) and returns <literal>y</literal>. Sparks are queued for
execution in FIFO order, but are not executed immediately. At the
next heap allocation, the currently executing thread will yield
control to the scheduler, and the scheduler will start a new thread
(until reaching the active thread limit) for each spark which has not
already been evaluated to WHNF.
-</Para>
+</para>
-<Para>
-The expression <Literal>(x `seq` y)</Literal> evaluates <Literal>x</Literal> to weak head normal
-form and then returns <Literal>y</Literal>. The <Function>seq</Function> primitive can be used to
+<para>
+The expression <literal>(x `seq` y)</literal> evaluates <literal>x</literal> to weak head normal
+form and then returns <literal>y</literal>. The <function>seq</function> primitive can be used to
force evaluation of an expression beyond WHNF, or to impose a desired
execution sequence for the evaluation of an expression.
-</Para>
+</para>
-<Para>
+<para>
For example, consider the following parallel version of our old
-nemesis, <Function>nfib</Function>:
-</Para>
+nemesis, <function>nfib</function>:
+</para>
-<Para>
+<para>
-<ProgramListing>
+<programlisting>
import Parallel
nfib :: Int -> Int
| otherwise = par n1 (seq n2 (n1 + n2 + 1))
where n1 = nfib (n-1)
n2 = nfib (n-2)
-</ProgramListing>
+</programlisting>
-</Para>
+</para>
-<Para>
-For values of <VarName>n</VarName> greater than 1, we use <Function>par</Function> to spark a thread
-to evaluate <Literal>nfib (n-1)</Literal>, and then we use <Function>seq</Function> to force the
-parent thread to evaluate <Literal>nfib (n-2)</Literal> before going on to add
+<para>
+For values of <varname>n</varname> greater than 1, we use <function>par</function> to spark a thread
+to evaluate <literal>nfib (n-1)</literal>, and then we use <function>seq</function> to force the
+parent thread to evaluate <literal>nfib (n-2)</literal> before going on to add
together these two subexpressions. In this divide-and-conquer
approach, we only spark a new thread for one branch of the computation
(leaving the parent to evaluate the other branch). Also, we must use
-<Function>seq</Function> to ensure that the parent will evaluate <VarName>n2</VarName> <Emphasis>before</Emphasis>
-<VarName>n1</VarName> in the expression <Literal>(n1 + n2 + 1)</Literal>. It is not sufficient to
-reorder the expression as <Literal>(n2 + n1 + 1)</Literal>, because the compiler may
+<function>seq</function> to ensure that the parent will evaluate <varname>n2</varname> <emphasis>before</emphasis>
+<varname>n1</varname> in the expression <literal>(n1 + n2 + 1)</literal>. It is not sufficient to
+reorder the expression as <literal>(n2 + n1 + 1)</literal>, because the compiler may
not generate code to evaluate the addends from left to right.
-</Para>
+</para>
-</Sect3>
+</sect3>
-<Sect3>
-<Title>Underlying functions and primitives
-<IndexTerm><Primary>parallelism primitives</Primary></IndexTerm>
-<IndexTerm><Primary>primitives for parallelism</Primary></IndexTerm></Title>
+<sect3>
+<title>Underlying functions and primitives
+<indexterm><primary>parallelism primitives</primary></indexterm>
+<indexterm><primary>primitives for parallelism</primary></indexterm></title>
-<Para>
-The functions <Function>par</Function> and <Function>seq</Function> are wired into GHC, and unfold
-into uses of the <Function>par#</Function> and <Function>seq#</Function> primitives, respectively. If
+<para>
+The functions <function>par</function> and <function>seq</function> are wired into GHC, and unfold
+into uses of the <function>par#</function> and <function>seq#</function> primitives, respectively. If
you'd like to see this with your very own eyes, just run GHC with the
-<Option>-ddump-simpl</Option> option. (Anything for a good time…)
-</Para>
+<option>-ddump-simpl</option> option. (Anything for a good time…)
+</para>
-</Sect3>
+</sect3>
-<Sect3>
-<Title>Scheduling policy for concurrent threads
-<IndexTerm><Primary>Scheduling—concurrent</Primary></IndexTerm>
-<IndexTerm><Primary>Concurrent scheduling</Primary></IndexTerm></Title>
+<sect3>
+<title>Scheduling policy for concurrent threads
+<indexterm><primary>Scheduling—concurrent</primary></indexterm>
+<indexterm><primary>Concurrent scheduling</primary></indexterm></title>
-<Para>
+<para>
Runnable threads are scheduled in round-robin fashion. Context
switches are signalled by the generation of new sparks or by the
expiry of a virtual timer (the timer interval is configurable with the
-<Option>-C[<num>]</Option><IndexTerm><Primary>-C<num> RTS option (concurrent,
-parallel)</Primary></IndexTerm> RTS option). However, a context switch doesn't
+<option>-C[<num>]</option><indexterm><primary>-C<num> RTS option (concurrent,
+parallel)</primary></indexterm> RTS option). However, a context switch doesn't
really happen until the current heap block is full. You can't get any
faster context switching than this.
-</Para>
+</para>
-<Para>
+<para>
When a context switch occurs, pending sparks which have not already
been reduced to weak head normal form are turned into new threads.
However, there is a limit to the number of active threads (runnable or
blocked) which are allowed at any given time. This limit can be
-adjusted with the <Option>-t<num></Option><IndexTerm><Primary>-t <num> RTS option (concurrent, parallel)</Primary></IndexTerm>
+adjusted with the <option>-t<num></option><indexterm><primary>-t <num> RTS option (concurrent, parallel)</primary></indexterm>
RTS option (the default is 32). Once the
thread limit is reached, any remaining sparks are deferred until some
of the currently active threads are completed.
-</Para>
+</para>
-</Sect3>
+</sect3>
-<Sect3>
-<Title>Scheduling policy for parallel threads
-<IndexTerm><Primary>Scheduling—parallel</Primary></IndexTerm>
-<IndexTerm><Primary>Parallel scheduling</Primary></IndexTerm></Title>
+<sect3>
+<title>Scheduling policy for parallel threads
+<indexterm><primary>Scheduling—parallel</primary></indexterm>
+<indexterm><primary>Parallel scheduling</primary></indexterm></title>
-<Para>
+<para>
In GUM we use an unfair scheduler, which means that a thread continues to
perform graph reduction until it blocks on a closure under evaluation, on a
remote closure or until the thread finishes.
-</Para>
+</para>
-</Sect3>
+</sect3>
-</Sect2>
+</sect2>
-</Sect1>
+</sect1>
<!-- Emacs stuff:
;;; Local Variables: ***
<para>You may specify that a different program be used for one
of the phases of the compilation system, in place of whatever
- the <Command>ghc</Command> has wired into it. For example, you
+ the <command>ghc</command> has wired into it. For example, you
might want to try a different assembler. The following options
allow you to change the external program used for a given
compilation phase:</para>
</indexterm>
<listitem>
<para>Pass <replaceable>option</replaceable> to the
- custom pre-processor (see <xref linkend="pre-processor">).</para>
+ custom pre-processor (see <xref linkend="pre-processor"/>).</para>
</listitem>
</varlistentry>
<varlistentry>
<para>GHC is itself a Haskell program, so if you need to pass
options directly to GHC's runtime system you can enclose them in
<literal>+RTS ... -RTS</literal> (see <xref
- linkend="runtime-control">).</para>
+ linkend="runtime-control"/>).</para>
</sect2>
<option>-D</option> macros passed to the C compiler
when compiling via C! For those, use the
<option>-optc-Dfoo</option> hack… (see <xref
- linkend="forcing-options-through">).</para>
+ linkend="forcing-options-through"/>).</para>
</listitem>
</varlistentry>
gaps vs -cpp</primary></indexterm>. In other words, strings
such as the following:</para>
-<ProgramListing>
+<programlisting>
strmod = "\
\ p \
\ "
-</ProgramListing>
+</programlisting>
<para>don't work with <option>-cpp</option>;
<filename>/usr/bin/cpp</filename> elides the backslash-newline
way to do this, but you can use this hack from the
command-line:</para>
-<Screen>
+<screen>
% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
-</Screen>
+</screen>
</sect2>
fast), but may produce code that is slightly slower than
compiling via C. <option>-fasm</option> is the default
when optimisation is off (see <xref
- linkend="options-optimise">).</para>
+ linkend="options-optimise"/>).</para>
</listitem>
</varlistentry>
<indexterm><primary><option>-package</option></primary></indexterm>
<listitem>
<para>If you are using a Haskell “package”
- (see <xref linkend="packages">), don't forget to add the
+ (see <xref linkend="packages"/>), don't forget to add the
relevant <option>-package</option> option when linking the
program too: it will cause the appropriate libraries to be
linked in with the program. Forgetting the
be supplying its definition of <function>main()</function>
at link-time, you will have to. To signal that to the
compiler when linking, use
- <option>-no-hs-main</option>. See also <xref linkend="using-own-main">.</para>
+ <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
<para>Notice that since the command-line passed to the
linker is rather involved, you probably want to use
<para>
We use the terms “reading” and “writing” to refer to accessing
-<emphasis>mutable</emphasis> arrays (see <xref LinkEnd="sect-mutable">), and
+<emphasis>mutable</emphasis> arrays (see <xref linkend="sect-mutable">), and
“indexing” to refer to reading a value from an <emphasis>immutable</emphasis>
array.
</para>
it should be entered—we never usually return an unevaluated
object! This is a pain: primitive ops aren't supposed to do
complicated things like enter objects. The current solution is to
-return a single element unboxed tuple (see <xref LinkEnd="unboxed-tuples">).
+return a single element unboxed tuple (see <xref linkend="unboxed-tuples">).
</para>
<para>
<chapter id="profiling">
- <title>Profiling</Title>
+ <title>Profiling</title>
<indexterm><primary>profiling</primary>
</indexterm>
<indexterm><primary>cost-centre profiling</primary></indexterm>
<literal>-prof</literal> option, and probably one of the
<literal>-auto</literal> or <literal>-auto-all</literal>
options. These options are described in more detail in <xref
- linkend="prof-compiler-options"> </para>
+ linkend="prof-compiler-options"/> </para>
<indexterm><primary><literal>-prof</literal></primary>
</indexterm>
<indexterm><primary><literal>-auto</literal></primary>
<programlisting>
main = print (nfib 25)
-nfib n = if n < 2 then 1 else nfib (n-1) + nfib (n-2)
+nfib n = if n < 2 then 1 else nfib (n-1) + nfib (n-2)
</programlisting>
<para>Compile and run this program as follows:</para>
main = print (f 25 + g 25)
f n = nfib n
g n = nfib (n `div` 2)
-nfib n = if n < 2 then 1 else nfib (n-1) + nfib (n-2)
+nfib n = if n < 2 then 1 else nfib (n-1) + nfib (n-2)
</programlisting>
<para>Compile and run this program as before, and take a look at
</varlistentry>
</variablelist>
- <para>In addition you can use the <Option>-P</Option> RTS option
+ <para>In addition you can use the <option>-P</option> RTS option
<indexterm><primary><option>-P</option></primary></indexterm> to
get the following additional information:</para>
<varlistentry>
<term><literal>bytes</literal></term>
- <listItem>
+ <listitem>
<para>Number of bytes allocated in the heap while in this
cost-centre; again, this is the raw number from which we get
the <literal>%alloc</literal> figure mentioned
above.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
</variablelist>
<para>What about recursive functions, and mutually recursive
called each other recursively, this information isn't displayed in
the basic time and allocation profile, instead the call-graph is
flattened into a tree. The XML profiling tool (described in <xref
- linkend="prof-xml-tool">) will be able to display real loops in
+ linkend="prof-xml-tool"/>) will be able to display real loops in
the call-graph.</para>
<sect2><title>Inserting cost centres by hand</title>
</listitem>
<listitem>
- <para>Time spent in foreign code (see <xref linkend="ffi">)
+ <para>Time spent in foreign code (see <xref linkend="ffi"/>)
is always attributed to the cost centre in force at the
Haskell call-site of the foreign function.</para>
</listitem>
<indexterm><primary>profiling</primary><secondary>options</secondary></indexterm>
<indexterm><primary>options</primary><secondary>for profiling</secondary></indexterm>
- <variableList>
- <varListEntry>
- <term><Option>-prof</Option>:</Term>
+ <variablelist>
+ <varlistentry>
+ <term><option>-prof</option>:</term>
<indexterm><primary><option>-prof</option></primary></indexterm>
- <listItem>
+ <listitem>
<para> To make use of the profiling system
<emphasis>all</emphasis> modules must be compiled and linked
with the <option>-prof</option> option. Any
<literal>SCC</literal>s are ignored; so you can compile
<literal>SCC</literal>-laden code without changing
it.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
</variablelist>
<para>There are a few other profiling-related compilation options.
<variablelist>
<varlistentry>
- <term><option>-auto</option>:</Term>
+ <term><option>-auto</option>:</term>
<indexterm><primary><option>-auto</option></primary></indexterm>
<indexterm><primary>cost centres</primary><secondary>automatically inserting</secondary></indexterm>
- <listItem>
+ <listitem>
<para> GHC will automatically add
- <Function>_scc_</Function> constructs for all
+ <function>_scc_</function> constructs for all
top-level, exported functions.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><option>-auto-all</option>:</Term>
+ <varlistentry>
+ <term><option>-auto-all</option>:</term>
<indexterm><primary><option>-auto-all</option></primary></indexterm>
- <listItem>
- <para> <Emphasis>All</Emphasis> top-level functions,
+ <listitem>
+ <para> <emphasis>All</emphasis> top-level functions,
exported or not, will be automatically
- <Function>_scc_</Function>'d.</para>
- </listItem>
- </varListEntry>
+ <function>_scc_</function>'d.</para>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><option>-caf-all</option>:</Term>
+ <varlistentry>
+ <term><option>-caf-all</option>:</term>
<indexterm><primary><option>-caf-all</option></primary></indexterm>
- <listItem>
+ <listitem>
<para> The costs of all CAFs in a module are usually
attributed to one “big” CAF cost-centre. With
this option, all CAFs get their own cost-centre. An
“if all else fails” option…</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><option>-ignore-scc</option>:</Term>
+ <varlistentry>
+ <term><option>-ignore-scc</option>:</term>
<indexterm><primary><option>-ignore-scc</option></primary></indexterm>
- <listItem>
- <para>Ignore any <Function>_scc_</Function>
+ <listitem>
+ <para>Ignore any <function>_scc_</function>
constructs, so a module which already has
- <Function>_scc_</Function>s can be compiled
+ <function>_scc_</function>s can be compiled
for profiling with the annotations ignored.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- </variableList>
+ </variablelist>
</sect1>
<sect1 id="prof-time-options">
- <title>Time and allocation profiling</Title>
+ <title>Time and allocation profiling</title>
<para>To generate a time and allocation profile, give one of the
following RTS options to the compiled program when you run it (RTS
options should be enclosed between <literal>+RTS...-RTS</literal>
as usual):</para>
- <variableList>
- <varListEntry>
- <term><Option>-p</Option> or <Option>-P</Option>:</Term>
+ <variablelist>
+ <varlistentry>
+ <term><option>-p</option> or <option>-P</option>:</term>
<indexterm><primary><option>-p</option></primary></indexterm>
<indexterm><primary><option>-P</option></primary></indexterm>
<indexterm><primary>time profile</primary></indexterm>
- <listItem>
- <para>The <Option>-p</Option> option produces a standard
- <Emphasis>time profile</Emphasis> report. It is written
+ <listitem>
+ <para>The <option>-p</option> option produces a standard
+ <emphasis>time profile</emphasis> report. It is written
into the file
- <Filename><replaceable>program</replaceable>.prof</Filename>.</para>
+ <filename><replaceable>program</replaceable>.prof</filename>.</para>
- <para>The <Option>-P</Option> option produces a more
+ <para>The <option>-P</option> option produces a more
detailed report containing the actual time and allocation
data as well. (Not used much.)</para>
</listitem>
<listitem>
<para>The <option>-px</option> option generates profiling
information in the XML format understood by our new
- profiling tool, see <xref linkend="prof-xml-tool">.</para>
+ profiling tool, see <xref linkend="prof-xml-tool"/>.</para>
</listitem>
</varlistentry>
<para>This option makes use of the extra information
maintained by the cost-centre-stack profiler to provide
useful information about the location of runtime errors.
- See <xref linkend="rts-options-debugging">.</para>
+ See <xref linkend="rts-options-debugging"/>.</para>
</listitem>
</varlistentry>
- </variableList>
+ </variablelist>
</sect1>
<orderedlist>
<listitem>
<para>Compile the program for profiling (<xref
- linkend="prof-compiler-options">).</para>
+ linkend="prof-compiler-options"/>).</para>
</listitem>
<listitem>
<para>Run it with one of the heap profiling options described
file,
<filename><replaceable>prog</replaceable>.ps</filename>. The
<command>hp2ps</command> utility is described in detail in
- <xref linkend="hp2ps">.</para>
+ <xref linkend="hp2ps"/>.</para>
</listitem>
<listitem>
<para>Display the heap profile using a postscript viewer such
<listitem>
<para>Break down the graph by <firstterm>retainer
set</firstterm>. Retainer profiling is described in more
- detail below (<xref linkend="retainer-prof">).</para>
+ detail below (<xref linkend="retainer-prof"/>).</para>
</listitem>
</varlistentry>
<para>Break down the graph by
<firstterm>biography</firstterm>. Biographical profiling
is described in more detail below (<xref
- linkend="biography-prof">).</para>
+ linkend="biography-prof"/>).</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
- <term><Option>-i<replaceable>secs</replaceable></Option>:</Term>
+ <term><option>-i<replaceable>secs</replaceable></option>:</term>
<indexterm><primary><option>-i</option></primary></indexterm>
- <listItem>
+ <listitem>
<para>Set the profiling (sampling) interval to
<replaceable>secs</replaceable> seconds (the default is
0.1 second). Fractions are allowed: for example
- <Option>-i0.2</Option> will get 5 samples per second.
+ <option>-i0.2</option> will get 5 samples per second.
This only affects heap profiling; time profiles are always
sampled on a 1/50 second frequency.</para>
- </listItem>
+ </listitem>
</varlistentry>
<varlistentry>
<para>The program
<command>hp2ps</command><indexterm><primary>hp2ps
program</primary></indexterm> converts a heap profile as produced
- by the <Option>-h<break-down></Option> runtime option into a
+ by the <option>-h<break-down></option> runtime option into a
PostScript graph of the heap profile. By convention, the file to
be processed by <command>hp2ps</command> has a
<filename>.hp</filename> extension. The PostScript output is
<para>The flags are:</para>
- <variableList>
+ <variablelist>
- <varListEntry>
- <term><Option>-d</Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-d</option></term>
+ <listitem>
<para>In order to make graphs more readable,
<command>hp2ps</command> sorts the shaded bands for each
identifier. The default sort ordering is for the bands with
the largest area to be stacked on top of the smaller ones.
- The <Option>-d</Option> option causes rougher bands (those
+ The <option>-d</option> option causes rougher bands (those
representing series of values with the largest standard
deviations) to be stacked on top of smoother ones.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-b</Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-b</option></term>
+ <listitem>
<para>Normally, <command>hp2ps</command> puts the title of
the graph in a small box at the top of the page. However, if
the JOB string is too long to fit in a small box (more than
35 characters), then <command>hp2ps</command> will choose to
- use a big box instead. The <Option>-b</Option> option
+ use a big box instead. The <option>-b</option> option
forces <command>hp2ps</command> to use a big box.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-e<float>[in|mm|pt]</Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-e<float>[in|mm|pt]</option></term>
+ <listitem>
<para>Generate encapsulated PostScript suitable for
inclusion in LaTeX documents. Usually, the PostScript graph
is drawn in landscape mode in an area 9 inches wide by 6
area to be approximately centred on a sheet of a4 paper.
This format is convenient of studying the graph in detail,
but it is unsuitable for inclusion in LaTeX documents. The
- <Option>-e</Option> option causes the graph to be drawn in
+ <option>-e</option> option causes the graph to be drawn in
portrait mode, with float specifying the width in inches,
millimetres or points (the default). The resulting
PostScript file conforms to the Encapsulated PostScript
(EPS) convention, and it can be included in a LaTeX document
using Rokicki's dvi-to-PostScript converter
<command>dvips</command>.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-g</Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-g</option></term>
+ <listitem>
<para>Create output suitable for the <command>gs</command>
PostScript previewer (or similar). In this case the graph is
printed in portrait mode without scaling. The output is
unsuitable for a laser printer.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-l</Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-l</option></term>
+ <listitem>
<para>Normally a profile is limited to 20 bands with
additional identifiers being grouped into an
- <literal>OTHER</literal> band. The <Option>-l</Option> flag
+ <literal>OTHER</literal> band. The <option>-l</option> flag
removes this 20 band and limit, producing as many bands as
necessary. No key is produced as it won't fit!. It is useful
for creation time profiles with many bands.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-m<int></Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-m<int></option></term>
+ <listitem>
<para>Normally a profile is limited to 20 bands with
additional identifiers being grouped into an
- <literal>OTHER</literal> band. The <Option>-m</Option> flag
+ <literal>OTHER</literal> band. The <option>-m</option> flag
specifies an alternative band limit (the maximum is
20).</para>
- <para><Option>-m0</Option> requests the band limit to be
+ <para><option>-m0</option> requests the band limit to be
removed. As many bands as necessary are produced. However no
key is produced as it won't fit! It is useful for displaying
creation time profiles with many bands.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-p</Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-p</option></term>
+ <listitem>
<para>Use previous parameters. By default, the PostScript
graph is automatically scaled both horizontally and
vertically so that it fills the page. However, when
preparing a series of graphs for use in a presentation, it
is often useful to draw a new graph using the same scale,
shading and ordering as a previous one. The
- <Option>-p</Option> flag causes the graph to be drawn using
+ <option>-p</option> flag causes the graph to be drawn using
the parameters determined by a previous run of
<command>hp2ps</command> on <filename>file</filename>. These
are extracted from <filename>file@.aux</filename>.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-s</Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-s</option></term>
+ <listitem>
<para>Use a small box for the title.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-t<float></Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-t<float></option></term>
+ <listitem>
<para>Normally trace elements which sum to a total of less
than 1% of the profile are removed from the
profile. The <option>-t</option> option allows this
percentage to be modified (maximum 5%).</para>
- <para><Option>-t0</Option> requests no trace elements to be
+ <para><option>-t0</option> requests no trace elements to be
removed from the profile, ensuring that all the data will be
displayed.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-c</Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-c</option></term>
+ <listitem>
<para>Generate colour output.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-y</Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-y</option></term>
+ <listitem>
<para>Ignore marks.</para>
- </listItem>
- </varListEntry>
+ </listitem>
+ </varlistentry>
- <varListEntry>
- <term><Option>-?</Option></Term>
- <listItem>
+ <varlistentry>
+ <term><option>-?</option></term>
+ <listitem>
<para>Print out usage information.</para>
- </listItem>
- </varListEntry>
- </variableList>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<sect2 id="manipulating-hp">
#!/bin/sh
head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
| hp2ps > FOO.ps
- gv -watch -seascape FOO.ps &
+ gv -watch -seascape FOO.ps &
while [ 1 ] ; do
sleep 10 # We generate a new profile every 10 seconds.
head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
#!/bin/sh
head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \
| hp2ps > FOO.ps
- gv FOO.ps &
+ gv FOO.ps &
gvpsnum=$!
while [ 1 ] ; do
sleep 10
</sect1>
<sect1 id="ticky-ticky">
- <title>Using “ticky-ticky” profiling (for implementors)</Title>
+ <title>Using “ticky-ticky” profiling (for implementors)</title>
<indexterm><primary>ticky-ticky profiling</primary></indexterm>
<para>(ToDo: document properly.)</para>
profiling</primary></indexterm> <indexterm><primary>profiling,
ticky-ticky</primary></indexterm> because that's the sound a Sun4
makes when it is running up all those counters
- (<Emphasis>slowly</Emphasis>).</para>
+ (<emphasis>slowly</emphasis>).</para>
<para>Ticky-ticky profiling is mainly intended for implementors;
it is quite separate from the main “cost-centre”
the installation guide.</para>
<para>To get your compiled program to spit out the ticky-ticky
- numbers, use a <Option>-r</Option> RTS
+ numbers, use a <option>-r</option> RTS
option<indexterm><primary>-r RTS option</primary></indexterm>.
- See <XRef LinkEnd="runtime-control">.</para>
+ See <xref linkend="runtime-control"/>.</para>
- <para>Compiling your program with the <Option>-ticky</Option>
+ <para>Compiling your program with the <option>-ticky</option>
switch yields an executable that performs these counts. Here is a
sample ticky-ticky statistics file, generated by the invocation
<command>foo +RTS -rfoo.ticky</command>.</para>
<para>The formatting of the information above the row of asterisks
is subject to change, but hopefully provides a useful
- human-readable summary. Below the asterisks <Emphasis>all
- counters</Emphasis> maintained by the ticky-ticky system are
+ human-readable summary. Below the asterisks <emphasis>all
+ counters</emphasis> maintained by the ticky-ticky system are
dumped, in a format intended to be machine-readable: zero or more
spaces, an integer, a space, the counter name, and a newline.</para>
- <para>In fact, not <Emphasis>all</Emphasis> counters are
+ <para>In fact, not <emphasis>all</emphasis> counters are
necessarily dumped; compile- or run-time flags can render certain
counters invalid. In this case, either the counter will simply
not appear, or it will appear with a modified counter name,
with an inserted <literal>!</literal> above). Software analysing
this output should always check that it has the counters it
expects. Also, beware: some of the counters can have
- <Emphasis>large</Emphasis> values!</para>
+ <emphasis>large</emphasis> values!</para>
</sect1>
<variablelist>
<varlistentry>
- <term><option>-A</option><replaceable>size</replaceable></Term>
+ <term><option>-A</option><replaceable>size</replaceable></term>
<indexterm><primary><option>-A</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary>allocation area, size</primary></indexterm>
<listitem>
</varlistentry>
<varlistentry>
- <term><option>-F</option><replaceable>factor</replaceable></Term>
+ <term><option>-F</option><replaceable>factor</replaceable></term>
<listitem>
<indexterm><primary><option>-F</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary>heap size, factor</primary></indexterm>
</varlistentry>
<varlistentry>
- <term><option>-G</option><replaceable>generations</replaceable></Term>
+ <term><option>-G</option><replaceable>generations</replaceable></term>
<indexterm><primary><option>-G</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary>generations, number
of</primary></indexterm>
<para>Specifying 1 generation with <option>+RTS -G1</option>
gives you a simple 2-space collector, as you would expect.
In a 2-space collector, the <option>-A</option> option (see
- above) specifies the <Emphasis>minimum</Emphasis> allocation
+ above) specifies the <emphasis>minimum</emphasis> allocation
area size, since the allocation area will grow with the
amount of live data in the heap. In a multi-generational
collector the allocation area is a fixed size (unless you
</listitem>
</varlistentry>
- <VarListEntry>
+ <varlistentry>
<term><option>-H</option><replaceable>size</replaceable></term>
<indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary>heap size, suggested</primary></indexterm>
<varlistentry>
<term><option>-s</option><replaceable>file</replaceable></term>
- <term><option>-S</option><replaceable>file</replaceable></Term>
+ <term><option>-S</option><replaceable>file</replaceable></term>
<indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
<indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm>
<listitem>
(<option>-S</option>) garbage-collector statistics into file
<replaceable>file</replaceable>. The default
<replaceable>file</replaceable> is
- <Filename><replaceable>program</replaceable>.stat</Filename>. The
+ <filename><replaceable>program</replaceable>.stat</filename>. The
<replaceable>file</replaceable> <constant>stderr</constant>
is treated specially, with the output really being sent to
<constant>stderr</constant>.</para>
</sect2>
-<!-- ---------------------------------------------------------------------- -->
<sect2>
<title>RTS options for profiling and Concurrent/Parallel Haskell</title>
- <para>The RTS options related to profiling are described in <XRef
- LinkEnd="prof-rts-options">; and those for concurrent/parallel
- stuff, in <XRef LinkEnd="parallel-rts-opts">.</para>
+ <para>The RTS options related to profiling are described in <xref
+ linkend="rts-options-heap-prof"/>; and those for concurrent/parallel
+ stuff, in <xref linkend="parallel-rts-opts"/>.</para>
</sect2>
-<!-- ---------------------------------------------------------------------- -->
<sect2 id="rts-options-debugging">
<title>RTS options for hackers, debuggers, and over-interested
souls</title>
be really useful, linked with suitable system libraries.
Not a trivial undertaking: consult the installation guide on
how to set things up for easy “ticky-ticky”
- profiling. For more information, see <XRef
- LinkEnd="ticky-ticky">.</para>
+ profiling. For more information, see <xref
+ linkend="ticky-ticky"/>.</para>
</listitem>
</varlistentry>
</screen>
<para>each <literal>cc</literal><subscript>i</subscript> is
a cost centre in the program (see <xref
- linkend="cost-centres">), and the sequence represents the
+ linkend="cost-centres"/>), and the sequence represents the
“call stack” at the point the exception was
raised. The leftmost item is the innermost function in the
call stack, and the rightmost item is the outermost
<varlistentry>
<term><function>void OutOfHeapHook (unsigned long, unsigned long)</function></term>
<indexterm><primary><function>OutOfHeapHook</function></primary></indexterm>
- <ListItem>
+ <listitem>
<para>The heap-overflow message.</para>
</listitem>
</varlistentry>
<term><function>void MallocFailHook (long int)</function></term>
<indexterm><primary><function>MallocFailHook</function></primary></indexterm>
<listitem>
- <para>The message printed if <Function>malloc</Function>
+ <para>The message printed if <function>malloc</function>
fails.</para>
</listitem>
</varlistentry>
<para>Note that this section is written with
<firstterm>hierarchical modules</firstterm> in mind (see <xref
- linkend="hierarchical-modules">); hierarchical modules are an
+ linkend="hierarchical-modules"/>); hierarchical modules are an
extension to Haskell 98 which extends the lexical syntax of
module names to include a dot ‘.’. Non-hierarchical
modules are thus a special case in which none of the module names
should be placed in the file <literal>A/B/C.hs</literal>,
relative to some base directory. GHC's behaviour if this rule
is not followed is fully defined by the following section (<xref
- linkend="output-files">).</para>
+ linkend="output-files"/>).</para>
</sect2>
<sect2 id="output-files">
types of exported functions, definitions of data types, and so
on. It is stored in a binary format, so don't try to read one;
use the <option>--show-iface</option> option instead (see <xref
- linkend="hi-options">).</para>
+ linkend="hi-options"/>).</para>
<para>You should think of the object file and the interface file as a
pair, since the interface file is in a sense a compiler-readable
<para>For any module that is imported, GHC requires that the
name of the module in the import statement exactly matches the
name of the module in the interface file (or source file) found
- using the strategy specified in <xref linkend="search-path">.
+ using the strategy specified in <xref linkend="search-path"/>.
This means that for most modules, the source file name should
match the module name.</para>
<para>This isn't the whole story: GHC also looks for modules in
pre-compiled libraries, known as packages. See the section on
- packages (<xref linkend="packages">), for details.</para>
+ packages (<xref linkend="packages"/>), for details.</para>
</sect2>
<sect2 id="options-output">
<para>Redirects object files to directory
<replaceable>dir</replaceable>. For example:</para>
-<Screen>
+<screen>
$ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
-</Screen>
+</screen>
<para>The object files, <filename>Foo.o</filename>,
<filename>Bar.o</filename>, and
<para>Similarly, the <option>-hisuf</option>
<replaceable>suffix</replaceable> will change the
<literal>.hi</literal> file suffix for non-system
- interface files (see <XRef LinkEnd="hi-options">).</para>
+ interface files (see <xref linkend="hi-options"/>).</para>
<para>Finally, the option <option>-hcsuf</option>
<replaceable>suffix</replaceable> will change the
game is particularly useful if you want to compile a
program both with and without profiling, in the same
directory. You can say:
- <Screen>
- ghc ...</Screen>
+ <screen>
+ ghc ...</screen>
to get the ordinary version, and
- <Screen>
- ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</Screen>
+ <screen>
+ ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</screen>
to get the profiled version.</para>
</listitem>
</varlistentry>
<para>Instructs the GHC driver not to delete any of its
temporary files, which it normally keeps in
<literal>/tmp</literal> (or possibly elsewhere; see <xref
- linkend="temp-files">). Running GHC with
+ linkend="temp-files"/>). Running GHC with
<option>-v</option> will show you what temporary files
were generated along the way.</para>
</listitem>
in <filename>/tmp</filename> (or wherever your
installation thinks temporary files should go), you may
use the <option>-tmpdir
- <dir></option><IndexTerm><Primary>-tmpdir
- <dir> option</Primary></IndexTerm> option to specify
+ <dir></option><indexterm><primary>-tmpdir
+ <dir> option</primary></indexterm> option to specify
an alternate directory. For example, <option>-tmpdir
.</option> says to put temporary files in the current
working directory.</para>
- <para>Alternatively, use your <Constant>TMPDIR</Constant>
- environment variable.<IndexTerm><Primary>TMPDIR
- environment variable</Primary></IndexTerm> Set it to the
+ <para>Alternatively, use your <constant>TMPDIR</constant>
+ environment variable.<indexterm><primary>TMPDIR
+ environment variable</primary></indexterm> Set it to the
name of the directory where temporary files should be put.
GCC and other programs will honour the
- <Constant>TMPDIR</Constant> variable as well.</para>
+ <constant>TMPDIR</constant> variable as well.</para>
<para>Even better idea: Set the
- <Constant>DEFAULT_TMPDIR</Constant> make variable when
+ <constant>DEFAULT_TMPDIR</constant> make variable when
building GHC, and never worry about
- <Constant>TMPDIR</Constant> again. (see the build
+ <constant>TMPDIR</constant> again. (see the build
documentation).</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
- <Sect2 id="hi-options">
+ <sect2 id="hi-options">
<title>Other options related to interface files</title>
<indexterm><primary>interface files, options</primary></indexterm>
required”. What a beautiful sight!</para>
<para>Patrick Sansom had a workshop paper about how all this is
- done (though the details have changed quite a bit). <ULink
- URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a
+ done (though the details have changed quite a bit). <ulink
+ URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ulink> if you want a
copy.</para>
</sect2>
<filename>Makefile</filename> to use with GHC, assuming you name
your source files the same as your modules. Thus:</para>
-<ProgramListing>
+<programlisting>
HC = ghc
HC_OPTS = -cpp $(EXTRA_HC_OPTS)
# Inter-module dependencies
Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz
-</ProgramListing>
+</programlisting>
<para>(Sophisticated <command>make</command> variants may
achieve some of the above more elegantly. Notably,
<command>gmake</command>'s pattern rules let you write the more
comprehensible:</para>
-<ProgramListing>
+<programlisting>
%.o : %.lhs
$(HC) -c $< $(HC_OPTS)
-</ProgramListing>
+</programlisting>
<para>What we've shown should work with any
<command>make</command>.)</para>
<para>Note the inter-module dependencies at the end of the
Makefile, which take the form</para>
-<ProgramListing>
+<programlisting>
Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz
-</ProgramListing>
+</programlisting>
<para>They tell <command>make</command> that if any of
<literal>Foo.o</literal>, <literal>Foo.hc</literal> or
automatically generating the required dependencies. Add the
following to your <filename>Makefile</filename>:</para>
-<ProgramListing>
+<programlisting>
depend :
ghc -M $(HC_OPTS) $(SRCS)
-</ProgramListing>
+</programlisting>
<para>Now, before you start compiling, and any time you change
the <literal>imports</literal> in your program, do
A.o : B.hi-boot
</programlisting>
- (See <xref linkend="mutual-recursion"> for details of
+ (See <xref linkend="mutual-recursion"/> for details of
<literal>hi-boot</literal> style interface files.) If
<literal>A</literal> imports multiple modules, then there will
be multiple lines with <filename>A.o</filename> as the
<para>Currently, the compiler does not have proper support for
dealing with mutually recursive modules:</para>
-<ProgramListing>
+<programlisting>
module A where
import B
g :: TA -> TB
g (MkTA x) = MkTB x
-</ProgramListing>
+</programlisting>
<para>When compiling either module A and B, the compiler will
try (in vain) to look for the interface file of the other. So,
files</primary></indexterm> <indexterm><primary>importing,
<literal>hi-boot</literal> files</primary></indexterm></para>
-<ProgramListing>
+<programlisting>
import {-# SOURCE #-} A
-</ProgramListing>
+</programlisting>
<para>The hand-written interface need only contain the bare
minimum of information needed to get the bootstrapping process
<para>For the example at hand, the boot interface file for A
would look like the following:</para>
-<ProgramListing>
+<programlisting>
module A where
newtype TA = MkTA GHC.Base.Int
-</ProgramListing>
+</programlisting>
<para>The syntax is similar to a normal Haskell source file, but
with some important differences:</para>
<listitem> <para>For <literal>data</literal> or <literal>newtype</literal> declaration, you may omit all
the constructors, by omitting the '=' and everything that follows it:
-<ProgramListing>
+<programlisting>
module A where
data TA
-</ProgramListing>
+</programlisting>
In a <emphasis>source</emphasis> program
- this would declare TA to have no constructors (a GHC extension: see <xref linkend="nullary-types">),
+ this would declare TA to have no constructors (a GHC extension: see <xref linkend="nullary-types"/>),
but in an hi-boot file it means "I don't know or care what the construtors are".
This is the most common form of data type declaration, because it's easy to get right.</para>
<para>
<para>
Regardless of whether you write the constructors, you must write all the type parameters,
<emphasis>including their kinds</emphasis>
- if they are not '*'. (You can give explicit kinds in source files too (<xref linkend="sec-kinding">),
+ if they are not '*'. (You can give explicit kinds in source files too (<xref linkend="sec-kinding"/>),
but you <emphasis>must</emphasis> do so in hi-boot files.)</para>
</listitem>
<para>Notice that we only put the declaration for the newtype
<literal>TA</literal> in the <literal>hi-boot</literal> file,
- not the signature for <Function>f</Function>, since
- <Function>f</Function> isn't used by <literal>B</literal>.</para>
+ not the signature for <function>f</function>, since
+ <function>f</function> isn't used by <literal>B</literal>.</para>
</sect2>
<para>In particular, if an instance declaration is in the same module as the definition
of any type or class mentioned in the head of the instance declaration, then
GHC has to visit that interface file anyway. Example:</para>
-<ProgramListing>
+<programlisting>
module A where
instance C a => D (T a) where ...
data T a = ...
-</ProgramListing>
+</programlisting>
<para> The instance declaration is only relevant if the type T is in use, and if
so, GHC will have visited A's interface file to find T's definition. </para>
<para> The only problem comes when a module contains an instance declaration
and GHC has no other reason for visiting the module. Example:
-<ProgramListing>
+<programlisting>
module Orphan where
instance C a => D (T a) where ...
class C a where ...
-</ProgramListing>
+</programlisting>
Here, neither D nor T is declared in module Orphan.
We call such modules ``orphan modules'',
defined thus:</para>
default), and you have lots of memory, try increasing the
maximum with the
<option>-M<size></option><indexterm><primary>-M<size>
- option</primary></indexterm> option, e.g.: <Command>ghc -c
- -O -M1024m Foo.hs</Command>.</para>
+ option</primary></indexterm> option, e.g.: <command>ghc -c
+ -O -M1024m Foo.hs</command>.</para>
<para>Increasing the default allocation area size used by
the compiler's RTS might also help: use the
<listitem>
<para>As soon as GHC plus its “fellow citizens”
(other processes on your machine) start using more than the
- <Emphasis>real memory</Emphasis> on your machine, and the
- machine starts “thrashing,” <Emphasis>the party
- is over</Emphasis>. Compile times will be worse than
+ <emphasis>real memory</emphasis> on your machine, and the
+ machine starts “thrashing,” <emphasis>the party
+ is over</emphasis>. Compile times will be worse than
terrible! Use something like the csh-builtin
- <Command>time</Command> command to get a report on how many
+ <command>time</command> command to get a report on how many
page faults you're getting.</para>
<para>If you don't know what virtual memory, thrashing, and
page faults are, or you don't know the memory configuration
- of your machine, <Emphasis>don't</Emphasis> try to be clever
+ of your machine, <emphasis>don't</emphasis> try to be clever
about memory use: you'll just make your life a misery (and
for other people, too, probably).</para>
</listitem>
to/from a remote filesystem.</para>
<para>It would be quite sensible to
- <Emphasis>compile</Emphasis> on a fast machine using
- remotely-mounted disks; then <Emphasis>link</Emphasis> on a
+ <emphasis>compile</emphasis> on a fast machine using
+ remotely-mounted disks; then <emphasis>link</emphasis> on a
slow machine that had your disks directly mounted.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Don't derive/use <Function>Read</Function> unnecessarily:</term>
+ <term>Don't derive/use <function>Read</function> unnecessarily:</term>
<listitem>
<para>It's ugly and slow.</para>
</listitem>
<literal>import Foo (...stuff I want...)</literal> You can
get GHC to tell you the minimal set of required imports by
using the <option>-ddump-minimal-imports</option> option
- (see <xref linkend="hi-options">).</para>
+ (see <xref linkend="hi-options"/>).</para>
<para>Truthfully, the reduction on compilation time will be
very small. However, judicious use of
<para>The key tool to use in making your Haskell program run
faster are GHC's profiling facilities, described separately in
- <XRef LinkEnd="profiling">. There is <Emphasis>no
- substitute</Emphasis> for finding where your program's time/space
- is <Emphasis>really</Emphasis> going, as opposed to where you
+ <xref linkend="profiling"/>. There is <emphasis>no
+ substitute</emphasis> for finding where your program's time/space
+ is <emphasis>really</emphasis> going, as opposed to where you
imagine it is going.</para>
<para>Another point to bear in mind: By far the best way to
- improve a program's performance <Emphasis>dramatically</Emphasis>
+ improve a program's performance <emphasis>dramatically</emphasis>
is to use better algorithms. Once profiling has thrown the
spotlight on the guilty time-consumer(s), it may be better to
re-think your program than to try all the tweaks listed below.</para>
<para>Another extremely efficient way to make your program snappy
is to use library code that has been Seriously Tuned By Someone
- Else. You <Emphasis>might</Emphasis> be able to write a better
+ Else. You <emphasis>might</emphasis> be able to write a better
quicksort than the one in <literal>Data.List</literal>, but it
will take you much longer than typing <literal>import
Data.List</literal>.</para>
<indexterm><primary>overloading, death to</primary></indexterm>
<para>Specialize the overloading on key functions in
- your program. See <XRef LinkEnd="specialize-pragma">
- and <XRef LinkEnd="specialize-instance-pragma">.</para>
+ your program. See <xref linkend="specialize-pragma"/>
+ and <xref linkend="specialize-instance-pragma"/>.</para>
</listitem>
</varlistentry>
files for overloaded type signatures. You can view
interface files using the
<option>--show-iface</option> option (see <xref
- linkend="hi-options">).
+ linkend="hi-options"/>).
<programlisting>
% ghc --show-iface Foo.hi | egrep '^[a-z].*::.*=>'
the third field in the pragma; it should say
<literal>__S <string></literal>. The
<literal><string></literal> gives the strictness of
- the function's arguments. <Function>L</Function> is lazy
- (bad), <Function>S</Function> and <Function>E</Function> are
- strict (good), <Function>P</Function> is
- “primitive” (good), <Function>U(...)</Function>
+ the function's arguments. <function>L</function> is lazy
+ (bad), <function>S</function> and <function>E</function> are
+ strict (good), <function>P</function> is
+ “primitive” (good), <function>U(...)</function>
is strict and “unpackable” (very good), and
- <Function>A</Function> is absent (very good).</para>
+ <function>A</function> is absent (very good).</para>
<para>For an “unpackable”
- <Function>U(...)</Function> argument, the info inside tells
+ <function>U(...)</function> argument, the info inside tells
the strictness of its components. So, if the argument is a
- pair, and it says <Function>U(AU(LSS))</Function>, that
+ pair, and it says <function>U(AU(LSS))</function>, that
means “the first component of the pair isn't used; the
second component is itself unpackable, with three components
(lazy in the first, strict in the second \&
<listitem>
<para>Placing <literal>INLINE</literal> pragmas on certain
functions that are used a lot can have a dramatic effect.
- See <XRef LinkEnd="inline-pragma">.</para>
+ See <xref linkend="inline-pragma"/>.</para>
</listitem>
</varlistentry>
module, GHC must assume that everything in that module will
be exported. This has various pessimising effects. For
example, if a bit of code is actually
- <Emphasis>unused</Emphasis> (perhaps because of unfolding
+ <emphasis>unused</emphasis> (perhaps because of unfolding
effects), GHC will not be able to throw it away, because it
is exported and some other module may be relying on its
existence.</para>
<para>It can also help in a third way: when used with
<option>-funbox-strict-fields</option> (see <xref
- linkend="options-f">), a strict field can be unpacked or
+ linkend="options-f"/>), a strict field can be unpacked or
unboxed in the constructor, and one or more levels of
indirection may be removed. Unpacking only happens for
single-constructor datatypes (<literal>Int</literal> is a
<varlistentry>
<term>Use unboxed types (a GHC extension):</term>
<listitem>
- <para>When you are <Emphasis>really</Emphasis> desperate for
+ <para>When you are <emphasis>really</emphasis> desperate for
speed, and you want to get right down to the “raw
- bits.” Please see <XRef LinkEnd="glasgow-unboxed"> for
+ bits.” Please see <xref linkend="glasgow-unboxed"/> for
some information about using unboxed types.</para>
<para>Before resorting to explicit unboxed types, try using
of massively-tuned library code, and the best thing is not
to compete with it, but link with it.</para>
- <para><XRef LinkEnd="ffi"> describes the foreign function
+ <para><xref linkend="ffi"/> describes the foreign function
interface.</para>
</listitem>
</varlistentry>
yourself with numerical errors.</para>
<para>One time when <literal>Float</literal> might be a good
- idea is if you have a <Emphasis>lot</Emphasis> of them, say
+ idea is if you have a <emphasis>lot</emphasis> of them, say
a giant array of <literal>Float</literal>s. They take up
half the space in the heap compared to
<literal>Doubles</literal>. However, this isn't true on a
<option>-M<size></option><indexterm><primary>-M<size>
RTS option</primary></indexterm> or
<option>-A<size></option><indexterm><primary>-A<size>
- RTS option</primary></indexterm> RTS options (see <XRef
- LinkEnd="rts-options-gc">).</para>
+ RTS option</primary></indexterm> RTS options (see <xref
+ linkend="rts-options-gc"/>).</para>
<para>This is especially important if your program uses a
lot of mutable arrays of pointers or mutable variables
</varlistentry>
</variablelist>
-</Sect1>
+</sect1>
<sect1 id="smaller">
<title>Smaller: producing a program that is smaller
option</primary></indexterm> option for the extreme case. (“Only unfoldings with
zero cost should proceed.”) Warning: except in certain specialised
cases (like Happy parsers) this is likely to actually
-<Emphasis>increase</Emphasis> the size of your program, because unfolding
+<emphasis>increase</emphasis> the size of your program, because unfolding
generally enables extra simplifying optimisations to be performed.
</para>
<para>
-Avoid <Function>Read</Function>.
+Avoid <function>Read</function>.
</para>
<para>
Use <literal>strip</literal> on your executables.
</para>
-</Sect1>
+</sect1>
<sect1 id="thriftier">
<title>Thriftier: producing a program that gobbles less heap space
with <option>+RTS -Sstderr</option>, and remove all doubt! (You'll
see the heap usage get bigger and bigger…)
[Hmmm…this might be even easier with the
-<option>-G1</option> RTS option; so… <Command>./a.out +RTS
--Sstderr -G1</Command>...]
+<option>-G1</option> RTS option; so… <command>./a.out +RTS
+-Sstderr -G1</command>...]
<indexterm><primary>-G RTS option</primary></indexterm>
<indexterm><primary>-Sstderr RTS option</primary></indexterm>
</para>
<para>
-Once again, the profiling facilities (<XRef LinkEnd="profiling">) are
+Once again, the profiling facilities (<xref linkend="profiling"/>) are
the basic tool for demystifying the space behaviour of your program.
</para>
be required).
</para>
-</Sect1>
+</sect1>
-</Chapter>
+</chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
-<BookInfo>
-<Title>The Glasgow Haskell Compiler User's Guide, Version 6.0</Title>
-<Author><OtherName>The GHC Team</OtherName></Author>
-<Address>
-<Email>glasgow-haskell-{bugs,users}-request@haskell.org</Email>
-</Address>
-</BookInfo>
+<bookinfo>
+<title>The Glasgow Haskell Compiler User's Guide, Version 6.0</title>
+<author><othername>The GHC Team</othername></author>
+<address>
+<email>glasgow-haskell-{bugs,users}-request@haskell.org</email>
+</address>
+</bookinfo>
&license;
&intro;
%ug-ent;
<!ENTITY ug-book SYSTEM "ug-book.sgml">
]>
-
+
<Book id="users-guide">
&ug-book;
</Book>
Options can be specified in three ways:</para>
<sect2>
- <title>Command-line arguments</title>
+ <title>command-line arguments</title>
<indexterm><primary>structure, command-line</primary></indexterm>
<indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm>
<para>An invocation of GHC takes the following form:</para>
-<Screen>
+<screen>
ghc [argument...]
-</Screen>
+</screen>
- <para>Command-line arguments are either options or file names.</para>
+ <para>command-line arguments are either options or file names.</para>
- <para>Command-line options begin with <literal>-</literal>.
+ <para>command-line options begin with <literal>-</literal>.
They may <emphasis>not</emphasis> be grouped:
<option>-vO</option> is different from <option>-v -O</option>.
Options need not precede filenames: e.g., <literal>ghc *.o -o
<filename>Bar.hs</filename>.</para>
</sect2>
- <Sect2 id="source-file-options">
- <title>Command line options in source files</title>
+ <sect2 id="source-file-options">
+ <title>command line options in source files</title>
<indexterm><primary>source-file options</primary></indexterm>
<literal>OPTIONS</literal> pragma <indexterm><primary>OPTIONS
pragma</primary></indexterm>:</para>
-<ProgramListing>
+<programlisting>
{-# OPTIONS -fglasgow-exts #-}
module X where
...
-</ProgramListing>
+</programlisting>
<para><literal>OPTIONS</literal> pragmas are only looked for at
the top of your source files, upto the first
<title>Setting options in GHCi</title>
<para>Options may also be modified from within GHCi, using the
- <literal>:set</literal> command. See <xref linkend="ghci-set">
+ <literal>:set</literal> command. See <xref linkend="ghci-set"/>
for more details.</para>
</sect2>
</sect1>
<para>As a rule of thumb, options which relate to filenames are
static, and the rest are dynamic. The flag reference tables (<xref
- linkend="flag-reference">) lists the status of each flag.</para>
+ linkend="flag-reference"/>) lists the status of each flag.</para>
</sect1>
<sect1 id="file-suffixes">
<variablelist>
<varlistentry>
<term><cmdsynopsis><command>ghc</command>
- <arg choice=plain>––interactive</arg>
+ <arg choice='plain'>––interactive</arg>
</cmdsynopsis></term>
<indexterm><primary>interactive mode</primary>
</indexterm>
<listitem>
<para>Interactive mode, which is also available as
<command>ghci</command>. Interactive mode is described in
- more detail in <xref linkend="ghci">.</para>
+ more detail in <xref linkend="ghci"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><cmdsynopsis><command>ghc</command>
- <arg choice=plain>––make</arg>
+ <arg choice='plain'>––make</arg>
</cmdsynopsis></term>
<indexterm><primary>make mode</primary>
</indexterm>
If you have a straightforward Haskell program, this is
likely to be much easier, and faster, than using
<command>make</command>. Make mode is described in <xref
- linkend="make-mode">.</para>
+ linkend="make-mode"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><cmdsynopsis><command>ghc</command>
- <arg choice=plain>–e</arg> <arg choice=plain><replaceable>expr</replaceable></arg>
+ <arg choice='plain'>–e</arg> <arg choice='plain'><replaceable>expr</replaceable></arg>
</cmdsynopsis></term>
<indexterm><primary>eval mode</primary>
</indexterm>
<para>Expression-evaluation mode. This is very similar to
interactive mode, except that there is a single expression
to evaluate (<replaceable>expr</replaceable>) which is given
- on the command line. See <xref linkend="eval-mode"> for
+ on the command line. See <xref linkend="eval-mode"/> for
more details.</para>
</listitem>
</varlistentry>
there is no other mode flag specified on the command line,
in which case it means that the specified files should be
compiled and then linked to form a program. See <xref
- linkend="options-order">.</para>
+ linkend="options-order"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><cmdsynopsis><command>ghc</command>
- <arg choice=plain>–M</arg></cmdsynopsis></term>
+ <arg choice='plain'>–M</arg></cmdsynopsis></term>
<indexterm><primary>dependency-generation mode</primary>
</indexterm>
<listitem>
<para>Dependency-generation mode. In this mode, GHC can be
used to generate dependency information suitable for use in
a <literal>Makefile</literal>. See <xref
- linkend="sec-makefile-dependencies">.</para>
+ linkend="sec-makefile-dependencies"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><cmdsynopsis><command>ghc</command>
- <arg choice=plain>––mk-dll</arg></cmdsynopsis></term>
+ <arg choice='plain'>––mk-dll</arg></cmdsynopsis></term>
<indexterm><primary>dependency-generation mode</primary>
</indexterm>
<listitem>
<para>DLL-creation mode (Windows only). See <xref
- linkend="win32-dlls-create">.</para>
+ linkend="win32-dlls-create"/>.</para>
</listitem>
</varlistentry>
</variablelist>
you give on the command line will apply to all the source files
compiled, so if you want any options to apply to a single source
file only, you'll need to use an <literal>OPTIONS</literal>
- pragma (see <xref linkend="source-file-options">).</para>
+ pragma (see <xref linkend="source-file-options"/>).</para>
<para>If the program needs to be linked with additional objects
(say, some auxilliary C code), then the object files can be
<para>The source files for the program don't all need to be in
the same directory; the <option>-i</option> option can be used
to add directories to the search path (see <xref
- linkend="search-path">).</para>
+ linkend="search-path"/>).</para>
</sect2>
<sect2 id="eval-mode">
<informaltable>
<tgroup cols="4">
- <colspec align="left">
- <colspec align="left">
- <colspec align="left">
- <colspec align="left">
+ <colspec align="left"/>
+ <colspec align="left"/>
+ <colspec align="left"/>
+ <colspec align="left"/>
<thead>
<row>
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>
+ linkend="options-codegen"/> for more details.</para>
<para>Note: C pre-processing is optional, the
<option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
- flag turns it on. See <xref linkend="c-pre-processor"> for more
+ flag turns it on. See <xref linkend="c-pre-processor"/> for more
details.</para>
- <para>Note: The option <option>-E</option><IndexTerm><Primary>-E
- option</Primary></IndexTerm> runs just the pre-processing passes
+ <para>Note: The option <option>-E</option><indexterm><primary>-E
+ option</primary></indexterm> runs just the pre-processing passes
of the compiler, dumping the result in a file. Note that this
differs from the previous behaviour of dumping the file to
standard output.</para>
<sect1 id="options-help">
<title>Help and verbosity options</title>
- <IndexTerm><Primary>help options</Primary></IndexTerm>
- <IndexTerm><Primary>verbosity options</Primary></IndexTerm>
+ <indexterm><primary>help options</primary></indexterm>
+ <indexterm><primary>verbosity options</primary></indexterm>
<variablelist>
<varlistentry>
is the value of
<literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
</indexterm>in the package configuration file (see <xref
- linkend="packages">).</para>
+ linkend="packages"/>).</para>
</listitem>
</varlistentry>
simple ways to select standard “packages” of warnings:
</para>
- <VariableList>
+ <variablelist>
<varlistentry>
<term><option>-W</option>:</term>
<listitem>
- <IndexTerm><Primary>-W option</Primary></IndexTerm>
+ <indexterm><primary>-W option</primary></indexterm>
<para>Provides the standard warnings plus
<option>-fwarn-incomplete-patterns</option>,
<option>-fwarn-unused-matches</option>,
<varlistentry>
<term><option>-w</option>:</term>
<listitem>
- <IndexTerm><Primary><option>-w</option></Primary></IndexTerm>
+ <indexterm><primary><option>-w</option></primary></indexterm>
<para>Turns off all warnings, including the standard ones.</para>
</listitem>
</varlistentry>
<para>Causes a warning to be emitted when a deprecated
function or type is used. Entities can be marked as
deprecated using a pragma, see <xref
- linkend="deprecated-pragma">.</para>
+ linkend="deprecated-pragma"/>.</para>
</listitem>
</varlistentry>
f "2" = 2
</programlisting>
- <para>where the last pattern match in <Function>f</Function>
+ <para>where the last pattern match in <function>f</function>
won't ever be reached, as the second pattern overlaps
it. More often than not, redundant patterns is a programmer
mistake/error, so this option is enabled by default.</para>
the monad <literal>fail</literal> operation (monads). For example:
<programlisting>
f :: [Maybe a] -> [a]
- f xs = [y | Just y <- xs]
+ f xs = [y | Just y <- xs]
</programlisting>
Switching on <option>-fwarn-simple-patterns</option> will elicit warnings about
these probably-innocent cases, which is why the flag is off by default. </para>
in. This is useful information when converting code from a
context that assumed one default into one with another,
e.g., the `default default' for Haskell 1.4 caused the
- otherwise unconstrained value <Constant>1</Constant> to be
+ otherwise unconstrained value <constant>1</constant> to be
given the type <literal>Int</literal>, whereas Haskell 98
defaults it to <literal>Integer</literal>. This may lead to
differences in performance and behaviour, hence the
<para>Report all unused variables which arise from pattern
matches, including patterns consisting of a single variable.
For instance <literal>f x y = []</literal> would report
- <VarName>x</VarName> and <VarName>y</VarName> as unused. The
+ <varname>x</varname> and <varname>y</varname> as unused. The
warning is suppressed if the variable name begins with an underscore, thus:
<programlisting>
f _x = True
</listitem>
</varlistentry>
- </VariableList>
+ </variablelist>
<para>If you're feeling really paranoid, the
<option>-dcore-lint</option>
<literal>Exception.assert</literal> in source code (in
other words, rewriting <literal>Exception.assert p
e</literal> to <literal>e</literal> (see <xref
- linkend="sec-assertions">). This flag is turned on by
+ linkend="sec-assertions"/>). This flag is turned on by
<option>-O</option>.
</para>
</listitem>
unpacked if possible. It is equivalent to adding an
<literal>UNPACK</literal> pragma to every strict
constructor field (see <xref
- linkend="unpack-pragma">).</para>
+ linkend="unpack-pragma"/>).</para>
<para>This option is a bit of a sledgehammer: it might
sometimes make things worse. Selectively unboxing fields
Switching it on makes the compiler a little keener to
inline a function that returns a constructor, if the
context is that of a thunk.
-<ProgramListing>
+<programlisting>
x = plusInt a b
-</ProgramListing>
+</programlisting>
If we inlined plusInt we might get an opportunity to use
update-in-place for the thunk 'x'.</para>
</listitem>
<para>
RTS options are provided for modifying the behaviour of the threaded
-runtime system. See <XRef LinkEnd="parallel-rts-opts">.
+runtime system. See <xref linkend="parallel-rts-opts"/>.
</para>
<para>
for the <literal>Control.Concurrent</literal> module.
</para>
-</Sect1>
+</sect1>
-<Sect1 id="sec-using-parallel">
-<title>Using Parallel Haskell</title>
+<sect1 id="sec-using-parallel">
+<title>Using parallel Haskell</title>
<para>
-<indexterm><primary>Parallel Haskell—use</primary></indexterm>
+<indexterm><primary>parallel Haskell—use</primary></indexterm>
</para>
<para>
[You won't be able to execute parallel Haskell programs unless PVM3
-(Parallel Virtual Machine, version 3) is installed at your site.]
-</Para>
+(parallel Virtual Machine, version 3) is installed at your site.]
+</para>
<para>
To compile a Haskell program for parallel execution under PVM, use the
-<Option>-parallel</Option> option,<IndexTerm><Primary>-parallel
-option</Primary></IndexTerm> both when compiling <Emphasis>and
-linking</Emphasis>. You will probably want to <Literal>import
-Parallel</Literal> into your Haskell modules.
-</Para>
+<option>-parallel</option> option,<indexterm><primary>-parallel
+option</primary></indexterm> both when compiling <emphasis>and
+linking</emphasis>. You will probably want to <literal>import
+parallel</literal> into your Haskell modules.
+</para>
<para>
To run your parallel program, once PVM is going, just invoke it
“as normal”. The main extra RTS option is
-<Option>-qp<n></Option>, to say how many PVM
+<option>-qp<n></option>, to say how many PVM
“processors” your program to run on. (For more details of
-all relevant RTS options, please see <XRef
-LinkEnd="parallel-rts-opts">.)
+all relevant RTS options, please see <xref
+linkend="parallel-rts-opts"/>.)
</para>
<para>
-In truth, running Parallel Haskell programs and getting information
+In truth, running parallel Haskell programs and getting information
out of them (e.g., parallelism profiles) is a battle with the vagaries of
PVM, detailed in the following sections.
</para>
-<Sect2 id="pvm-dummies">
-<Title>Dummy's guide to using PVM</Title>
+<sect2 id="pvm-dummies">
+<title>Dummy's guide to using PVM</title>
<para>
<indexterm><primary>PVM, how to use</primary></indexterm>
-<indexterm><primary>Parallel Haskell—PVM use</primary></indexterm>
+<indexterm><primary>parallel Haskell—PVM use</primary></indexterm>
Before you can run a parallel program under PVM, you must set the
required environment variables (PVM's idea, not ours); something like,
probably in your <filename>.cshrc</filename> or equivalent:
-<ProgramListing>
+<programlisting>
setenv PVM_ROOT /wherever/you/put/it
setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
setenv PVM_DPATH $PVM_ROOT/lib/pvmd
-</ProgramListing>
+</programlisting>
</para>
<para>
Creating and/or controlling your “parallel machine” is a purely-PVM
-business; nothing specific to Parallel Haskell. The following paragraphs
+business; nothing specific to parallel Haskell. The following paragraphs
describe how to configure your parallel machine interactively.
-</Para>
+</para>
-<Para>
+<para>
If you use parallel Haskell regularly on the same machine configuration it
is a good idea to maintain a file with all machine names and to make the
environment variable PVM_HOST_FILE point to this file. Then you can avoid
the interactive operations described below by just saying
-</Para>
+</para>
-<ProgramListing>
+<programlisting>
pvm $PVM_HOST_FILE
-</ProgramListing>
+</programlisting>
-<Para>
-You use the <Command>pvm</Command><IndexTerm><Primary>pvm command</Primary></IndexTerm> command to start PVM on your
+<para>
+You use the <command>pvm</command><indexterm><primary>pvm command</primary></indexterm> command to start PVM on your
machine. You can then do various things to control/monitor your
“parallel machine;” the most useful being:
</para>
<para>
-<InformalTable>
-<TGroup Cols=2>
-<ColSpec Align="Left">
-<TBody>
+<informaltable>
+<tgroup cols="2">
+<colspec align="left"/>
+<tbody>
<row>
-<entry><KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo></entry>
+<entry><keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo></entry>
<entry>exit <command>pvm</command>, leaving it running</entry>
</row>
<entry>status of a particular process</entry>
</row>
-</TBody>
-</TGroup>
-</InformalTable>
+</tbody>
+</tgroup>
+</informaltable>
</para>
<para>
</sect2>
-<Sect2 id="par-profiles">
-<Title>Parallelism profiles</Title>
+<sect2 id="par-profiles">
+<title>parallelism profiles</title>
<para>
<indexterm><primary>parallelism profiles</primary></indexterm>
</para>
<para>
-With Parallel Haskell programs, we usually don't care about the
+With parallel Haskell programs, we usually don't care about the
results—only with “how parallel” it was! We want pretty pictures.
</para>
-<Para>
-Parallelism profiles (à la <Command>hbcpp</Command>) can be generated with the
-<Option>-qP</Option><IndexTerm><Primary>-qP RTS option (concurrent, parallel)</Primary></IndexTerm> RTS option. The
+<para>
+parallelism profiles (à la <command>hbcpp</command>) can be generated with the
+<option>-qP</option><indexterm><primary>-qP RTS option (concurrent, parallel)</primary></indexterm> RTS option. The
per-processor profiling info is dumped into files named
-<Filename><full-path><program>.gr</Filename>. These are then munged into a PostScript picture,
+<filename><full-path><program>.gr</filename>. These are then munged into a PostScript picture,
which you can then display. For example, to run your program
-<Filename>a.out</Filename> on 8 processors, then view the parallelism profile, do:
-</Para>
+<filename>a.out</filename> on 8 processors, then view the parallelism profile, do:
+</para>
-<Para>
+<para>
-<Screen>
+<screen>
<prompt>$</prompt> ./a.out +RTS -qP -qp8
<prompt>$</prompt> grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one
<prompt>$</prompt> gr2ps -O temp.gr # cvt to .ps; output in temp.ps
<prompt>$</prompt> ghostview -seascape temp.ps # look at it!
-</Screen>
+</screen>
-</Para>
+</para>
<para>
The scripts for processing the parallelism profiles are distributed
</sect2>
-<Sect2>
-<Title>Other useful info about running parallel programs</Title>
+<sect2>
+<title>Other useful info about running parallel programs</title>
-<Para>
+<para>
The “garbage-collection statistics” RTS options can be useful for
seeing what parallel programs are doing. If you do either
-<Option>+RTS -Sstderr</Option><IndexTerm><Primary>-Sstderr RTS option</Primary></IndexTerm> or <Option>+RTS -sstderr</Option>, then
+<option>+RTS -Sstderr</option><indexterm><primary>-Sstderr RTS option</primary></indexterm> or <option>+RTS -sstderr</option>, then
you'll get mutator, garbage-collection, etc., times on standard
error. The standard error of all PE's other than the `main thread'
appears in <filename>/tmp/pvml.nnn</filename>, courtesy of PVM.
</sect2>
-<Sect2 id="parallel-rts-opts">
-<title>RTS options for Concurrent/Parallel Haskell
+<sect2 id="parallel-rts-opts">
+<title>RTS options for Concurrent/parallel Haskell
</title>
<para>
<indexterm><primary>RTS options, concurrent</primary></indexterm>
<indexterm><primary>RTS options, parallel</primary></indexterm>
<indexterm><primary>Concurrent Haskell—RTS options</primary></indexterm>
-<indexterm><primary>Parallel Haskell—RTS options</primary></indexterm>
+<indexterm><primary>parallel Haskell—RTS options</primary></indexterm>
</para>
<para>
Besides the usual runtime system (RTS) options
-(<XRef LinkEnd="runtime-control">), there are a few options particularly
+(<xref linkend="runtime-control"/>), there are a few options particularly
for concurrent/parallel execution.
</para>
<para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-qp<N></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qp<N> RTS option</Primary></IndexTerm>
-(PARALLEL ONLY) Use <Literal><N></Literal> PVM processors to run this program;
+<variablelist>
+
+<varlistentry>
+<Term><option>-qp<N></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qp<N> RTS option</primary></indexterm>
+(paraLLEL ONLY) Use <literal><N></literal> PVM processors to run this program;
the default is 2.
</para>
</listitem>
<listitem>
<para>
<indexterm><primary>-q RTS option</primary></indexterm>
-(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
-in the file <FIlename><program>.qp</FIlename>. In the style of <command>hbcpp</command>, this profile
+(paraLLEL ONLY) Produce a quasi-parallel profile of thread activity,
+in the file <filename><program>.qp</filename>. In the style of <command>hbcpp</command>, this profile
records the movement of threads between the green (runnable) and red
(blocked) queues. If you specify the verbose suboption (<option>-qv</option>), the
green queue is split into green (for the currently running thread
only) and amber (for other runnable threads). We do not recommend
that you use the verbose suboption if you are planning to use the
-<Command>hbcpp</Command> profiling tools or if you are context switching at every heap
-check (with <Option>-C</Option>).
+<command>hbcpp</command> profiling tools or if you are context switching at every heap
+check (with <option>-C</option>).
-->
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-qt<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qt<num> RTS option</Primary></IndexTerm>
-(PARALLEL ONLY) Limit the thread pool size, i.e. the number of concurrent
-threads per processor to <Literal><num></Literal>. The default is
-32. Each thread requires slightly over 1K <Emphasis>words</Emphasis> in
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<Term><option>-qt<num></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qt<num> RTS option</primary></indexterm>
+(paraLLEL ONLY) Limit the thread pool size, i.e. the number of concurrent
+threads per processor to <literal><num></literal>. The default is
+32. Each thread requires slightly over 1K <emphasis>words</emphasis> in
the heap for thread state and stack objects. (For 32-bit machines, this
translates to 4K bytes, and for 64-bit machines, 8K bytes.)
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
<!-- no more -HWL
-<VarListEntry>
-<Term><Option>-d</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-d RTS option (parallel)</Primary></IndexTerm>
-(PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
-something…) per PVM processor. We use the standard <Command>debugger</Command>
+<varlistentry>
+<Term><option>-d</option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-d RTS option (parallel)</primary></indexterm>
+(paraLLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
+something…) per PVM processor. We use the standard <command>debugger</command>
script that comes with PVM3, but we sometimes meddle with the
-<Command>debugger2</Command> script. We include ours in the GHC distribution,
-in <Filename>ghc/utils/pvm/</Filename>.
-</Para>
-</ListItem>
-</VarListEntry>
+<command>debugger2</command> script. We include ours in the GHC distribution,
+in <filename>ghc/utils/pvm/</filename>.
+</para>
+</listitem>
+</varlistentry>
-->
-<VarListEntry>
-<Term><Option>-qe<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qe<num> RTS option
-(parallel)</Primary></IndexTerm> (PARALLEL ONLY) Limit the spark pool size
+<varlistentry>
+<Term><option>-qe<num></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qe<num> RTS option
+(parallel)</primary></indexterm> (paraLLEL ONLY) Limit the spark pool size
i.e. the number of pending sparks per processor to
-<Literal><num></Literal>. The default is 100. A larger number may be
+<literal><num></literal>. The default is 100. A larger number may be
appropriate if your program generates large amounts of parallelism
initially.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-qQ<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qQ<num> RTS option (parallel)</Primary></IndexTerm>
-(PARALLEL ONLY) Set the size of packets transmitted between processors
-to <Literal><num></Literal>. The default is 1024 words. A larger number may be
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<Term><option>-qQ<num></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qQ<num> RTS option (parallel)</primary></indexterm>
+(paraLLEL ONLY) Set the size of packets transmitted between processors
+to <literal><num></literal>. The default is 1024 words. A larger number may be
appropriate if your machine has a high communication cost relative to
computation speed.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-qh<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qh<num> RTS option (parallel)</Primary></IndexTerm>
-(PARALLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<Term><option>-qh<num></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qh<num> RTS option (parallel)</primary></indexterm>
+(paraLLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to
<num>-1 (0 means infinity). By default GUM uses full-subgraph
packing, i.e. the entire subgraph with the requested closure as root is
transmitted (provided it fits into one packet). Choosing a smaller value
reduces the amount of pre-fetching of work done in GUM. This can be
advantageous for improving data locality but it can also worsen the balance
of the load in the system.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-qg<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qg<num> RTS option
-(parallel)</Primary></IndexTerm> (PARALLEL ONLY) Select a globalisation
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<Term><option>-qg<num></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qg<num> RTS option
+(parallel)</primary></indexterm> (paraLLEL ONLY) Select a globalisation
scheme. This option affects the
generation of global addresses when transferring data. Global addresses are
globally unique identifiers required to maintain sharing in the distributed
used, which generated global address only for thunks. The latter case may
lose sharing of data but has a reduced overhead in packing graph structures
and maintaining internal tables of global addresses.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
</para>
</sect2>
-</Sect1>
+</sect1>
<sect1 id="options-platform">
<title>Platform-specific Flags</title>
compiling some modules with four stolen registers, it will
crash, probably saying:
-<Screen>
+<screen>
Foo.hc:533: fixed or forbidden register was spilled.
This may be due to a compiler bug or to impossible asm
statements or clauses.
-</Screen>
+</screen>
Just give some registers back with
<option>-monly-N-regs</option>. Try `3' first, then `2'.
<para>GHC can dump its optimized intermediate code (said to be in “Core” format)
to a file as a side-effect of compilation. Core files, which are given the suffix
<filename>.hcr</filename>, can be read and processed by non-GHC back-end
- tools. The Core format is formally described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz"
+ tools. The Core format is formally described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">
<citetitle>An External Representation for the GHC Core Language</citetitle></ulink>,
and sample tools (in Haskell)
for manipulating Core files are available in the GHC source distribution
directory <literal>/fptools/ghc/utils/ext-core</literal>.
Note that the format of <literal>.hcr</literal>
files is <emphasis>different</emphasis> (though similar) to the Core output format generated
- for debugging purposes (<xref linkend="options-debugging">).</para>
+ for debugging purposes (<xref linkend="options-debugging"/>).</para>
<para>The Core format natively supports notes which you can add to
your source code using the <literal>CORE</literal> pragma (see <xref
- linkend="pragmas">).</para>
+ linkend="pragmas"/>).</para>
<variablelist>
&debug;
&flags;
-</Chapter>
+</chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
corresponding type constructor instead.</para>
<para>Actually, GHC also comes with <command>etags</command>
- [for C], and <Command>perltags</Command> [for You
+ [for C], and <command>perltags</command> [for You
Know What]. And—I cannot tell a lie—there is
- Denis Howe's <Command>fptags</Command> [for Haskell,
+ Denis Howe's <command>fptags</command> [for Haskell,
etc.] in the <Filename>ghc/CONTRIB</Filename>
section…)</para>
<para>Andy Gill and Simon Marlow have written a parser-generator
for Haskell, called
- <Command>happy</Command>.<IndexTerm><Primary>happy parser
- generator</Primary></IndexTerm> <command>Happy</command> is to
+ <command>happy</command>.<indexterm><primary>happy parser
+ generator</primary></indexterm> <command>Happy</command> is to
Haskell what <command>Yacc</command> is to C.</para>
- <para>You can get <Command>happy</Command> from <ulink
+ <para>You can get <command>happy</command> from <ulink
url="http://www.haskell.org/happy/">the Happy
Homepage</ulink>.</para>
<!-- we don't distribute this anymore
<sect1 id="pphs">
- <title>Pretty-printing Haskell: <Command>pphs</Command></title>
+ <title>Pretty-printing Haskell: <command>pphs</command></title>
<indexterm><primary>pphs</primary></indexterm>
<indexterm><primary>pretty-printing Haskell code</primary></indexterm>
<para>Andrew Preece has written
- <Command>pphs</Command>,<IndexTerm><Primary>pphs</Primary></IndexTerm><IndexTerm><Primary>pretty-printing
- Haskell</Primary></IndexTerm> a utility to pretty-print Haskell
+ <command>pphs</command>,<indexterm><primary>pphs</primary></indexterm><indexterm><primary>pretty-printing
+ Haskell</primary></indexterm> a utility to pretty-print Haskell
code in LaTeX documents. Keywords in bolds, variables in
italics—that sort of thing. It is good at lining up program
clauses and equals signs, things that are very tiresome to do by
header file.</para>
<sect2>
- <title>Command line syntax</title>
+ <title>command line syntax</title>
<para><command>hsc2hs</command> takes input files as arguments,
and flags that modify its behavior:</para>
<literal>.hsc</literal> suffix replaced:</para>
<informaltable>
- <tgroup cols=2>
+ <tgroup cols="2">
<tbody>
<row>
<entry><literal>.hs</literal></entry>
in which case you must arrange for the importing
module to <literal>#include</literal> the C header
file generated by <command>hsc2hs</command> (see
- <xref linkend="glasgow-foreign-headers">).
+ <xref linkend="glasgow-foreign-headers"/>).
For this reason we avoid using <literal>#def</literal>
in the libraries.</para></note>
</listitem>
<sect2><title>Things to do</title>
<itemizedlist>
<listitem>
-<para> Don't use absolute paths in make, configure & co if there is any chance
+<para> Don't use absolute paths in make, configure & co if there is any chance
that those might be passed to GHC (or to GHC-compiled programs). Relative
paths are fine because cygwin tools are happy with them and GHC accepts
'/' as path-separator. And relative paths don't depend on where cygwin's
<sect1 id="win32-dlls">
-<Title>Building and using Win32 DLLs
-</Title>
+<title>Building and using Win32 DLLs
+</title>
-<Para>
-<IndexTerm><Primary>Dynamic link libraries, Win32</Primary></IndexTerm>
-<IndexTerm><Primary>DLLs, Win32</Primary></IndexTerm>
+<para>
+<indexterm><primary>Dynamic link libraries, Win32</primary></indexterm>
+<indexterm><primary>DLLs, Win32</primary></indexterm>
On Win32 platforms, the compiler is capable of both producing and using
dynamic link libraries (DLLs) containing ghc-compiled code. This
section shows you how to make use of this facility.
-</Para>
+</para>
-<Para>
-Until recently, <Command>strip</Command> didn't work reliably on DLLs, so you
+<para>
+Until recently, <command>strip</command> didn't work reliably on DLLs, so you
should test your version with care, or make sure you have the latest
binutils. Unfortunately, we don't know exactly which version of binutils
cured the problem (it was supposedly fixed some years ago).
-</Para>
+</para>
-<Sect2 id="win32-dlls-link">
-<Title>Linking with DLLs
-</Title>
+<sect2 id="win32-dlls-link">
+<title>Linking with DLLs</title>
-<Para>
+<para>
The default on Win32 platforms is to link applications in such a way
that the executables will use the Prelude and system libraries DLLs,
rather than contain (large chunks of) them. This is transparent at the
command-line, so
-</Para>
+</para>
-<Para>
-<Screen>
+<para>
+<screen>
sh$ cat main.hs
module Main where
main = putStrLn "hello, world!"
sh$ ./main
hello, world!
sh$
-</Screen>
-</Para>
+</screen>
+</para>
-<Para>
-will give you a binary as before, but the <Filename>main.exe</Filename>
+<para>
+will give you a binary as before, but the <filename>main.exe</filename>
generated will use the Prelude and RTS DLLs instead of linking them in
statically.
-</Para>
+</para>
-<Para>
-4K for a <Literal>"hello, world"</Literal> application—not bad, huh? :-)
-</Para>
+<para>
+4K for a <literal>"hello, world"</literal> application—not bad, huh? :-)
+</para>
-</Sect2>
+</sect2>
-<Sect2 id="win32-dlls-linking-static">
-<Title>Not linking with DLLs
-<IndexTerm><Primary>-static option (Win32)</Primary></IndexTerm></Title>
+<sect2 id="win32-dlls-linking-static">
+<title>Not linking with DLLs
+<indexterm><primary>-static option (Win32)</primary></indexterm></title>
-<Para>
+<para>
If you want to build an executable that doesn't depend on any
-ghc-compiled DLLs, use the <Option>-static</Option> option to link in
+ghc-compiled DLLs, use the <option>-static</option> option to link in
the code statically.
-</Para>
+</para>
-<Para>
+<para>
Notice that you cannot mix code that has been compiled with
-<Option>-static</Option> and not, so you have to use the <Option>-static</Option>
+<option>-static</option> and not, so you have to use the <option>-static</option>
option on all the Haskell modules that make up your application.
-</Para>
+</para>
-</Sect2>
+</sect2>
-<Sect2 id="win32-dlls-create">
-<Title>Creating a DLL
-</Title>
+<sect2 id="win32-dlls-create">
+<title>Creating a DLL</title>
-<Para>
+<para>
<emphasis>Making libraries into DLLs doesn't work on Windows at the
moment (and is no longer supported); however, all the machinery is
still there. If you're interested, contact the GHC team. Note that
building an entire Haskell application as a DLL is still supported
(it's just inter-DLL Haskell calls that don't work).</emphasis>
-<IndexTerm><Primary>Creating a Win32 DLL</Primary></IndexTerm>
-<IndexTerm><Primary>––mk-dll</Primary></IndexTerm>
+<indexterm><primary>Creating a Win32 DLL</primary></indexterm>
+<indexterm><primary>––mk-dll</primary></indexterm>
Sealing up your Haskell library inside a DLL is straightforward;
compile up the object files that make up the library, and then build
the DLL by issuing a command of the form:
-</Para>
+</para>
-<Para>
-<Screen>
+<para>
+<screen>
ghc ––mk-dll -o foo.dll bar.o baz.o wibble.a -lfooble
-</Screen>
-</Para>
+</screen>
+</para>
-<Para>
-By feeding the ghc compiler driver the option <Option>––mk-dll</Option>, it
+<para>
+By feeding the ghc compiler driver the option <option>––mk-dll</option>, it
will build a DLL rather than produce an executable. The DLL will
consist of all the object files and archives given on the command
line.
-</Para>
+</para>
-<Para>
+<para>
To create a `static' DLL, i.e. one that does not depend on the GHC DLLs,
-use the <Option>-static</Option> when compiling up your Haskell code and
+use the <option>-static</option> when compiling up your Haskell code and
building the DLL.
-</Para>
+</para>
-<Para>
+<para>
A couple of things to notice:
-</Para>
+</para>
-<Para>
+<para>
-<ItemizedList>
-<ListItem>
-<Para>
-Since DLLs correspond to packages (see <XRef LinkEnd="packages">) you need
-to use <Option>-package-name dll-name</Option> when compiling modules that
+<itemizedlist>
+<listitem>
+<para>
+Since DLLs correspond to packages (see <xref linkend="packages"/>) you need
+to use <option>-package-name dll-name</option> when compiling modules that
belong to a DLL if you're going to call them from Haskell. Otherwise, Haskell
code that calls entry points in that DLL will do so incorrectly, and crash.
For similar reasons, you can only compile a single module tree into a DLL,
-as <Function>startupHaskell</Function> needs to be able to call its
-initialisation function, and only takes one such argument (see <XRef
-LinkEnd="win32-dlls-foreign">). Hence the modules
+as <function>startupHaskell</function> needs to be able to call its
+initialisation function, and only takes one such argument (see <xref
+linkend="win32-dlls-foreign"/>). Hence the modules
you compile into a DLL must have a common root.
-</Para>
-</ListItem>
+</para>
+</listitem>
-<ListItem>
-<Para>
+<listitem>
+<para>
By default, the entry points of all the object files will be exported from
-the DLL when using <Option>––mk-dll</Option>. Should you want to constrain
-this, you can specify the <Emphasis>module definition file</Emphasis> to use
+the DLL when using <option>––mk-dll</option>. Should you want to constrain
+this, you can specify the <emphasis>module definition file</emphasis> to use
on the command line as follows:
-<Screen>
+<screen>
ghc ––mk-dll -o .... -optdll--def -optdllMyDef.def
-</Screen>
+</screen>
See Microsoft documentation for details, but a module definition file
simply lists what entry points you want to export. Here's one that's
suitable when building a Haskell COM server DLL:
-<ProgramListing>
+<programlisting>
EXPORTS
DllCanUnloadNow = DllCanUnloadNow@0
DllGetClassObject = DllGetClassObject@12
DllRegisterServer = DllRegisterServer@0
DllUnregisterServer = DllUnregisterServer@0
-</ProgramListing>
-</Para>
-</ListItem>
+</programlisting>
+</para>
+</listitem>
-<ListItem>
-<Para>
-In addition to creating a DLL, the <Option>––mk-dll</Option> option also
+<listitem>
+<para>
+In addition to creating a DLL, the <option>––mk-dll</option> option also
creates an import library. The import library name is derived from the
name of the DLL, as follows:
-<ProgramListing>
+<programlisting>
DLL: HScool.dll ==> import lib: libHScool_imp.a
-</ProgramListing>
+</programlisting>
The naming scheme may look a bit weird, but it has the purpose of allowing
the co-existence of import libraries with ordinary static libraries (e.g.,
-<Filename>libHSfoo.a</Filename> and
-<Filename>libHSfoo_imp.a</Filename>.
+<filename>libHSfoo.a</filename> and
+<filename>libHSfoo_imp.a</filename>.
Additionally, when the compiler driver is linking in non-static mode, it
-will rewrite occurrence of <Option>-lHSfoo</Option> on the command line to
-<Option>-lHSfoo_imp</Option>. By doing this for you, switching from
+will rewrite occurrence of <option>-lHSfoo</option> on the command line to
+<option>-lHSfoo_imp</option>. By doing this for you, switching from
non-static to static linking is simply a question of adding
-<Option>-static</Option> to your command line.
+<option>-static</option> to your command line.
-</Para>
-</ListItem>
-</ItemizedList>
-</Para>
+</para>
+</listitem>
+</itemizedlist>
+</para>
-</Sect2>
+</sect2>
-<Sect2 id="win32-dlls-foreign">
-<Title>Making DLLs to be called from other languages</Title>
+<sect2 id="win32-dlls-foreign">
+<title>Making DLLs to be called from other languages</title>
-<Para>
+<para>
If you want to package up Haskell code to be called from other languages,
such as Visual Basic or C++, there are some extra things it is useful to
-know. The dirty details are in the <Emphasis>Foreign Function
-Interface</Emphasis> definition, but it can be tricky to work out how to
+know. The dirty details are in the <emphasis>Foreign Function
+Interface</emphasis> definition, but it can be tricky to work out how to
combine this with DLL building, so here's an example:
-</Para>
+</para>
-<ItemizedList>
+<itemizedlist>
-<ListItem>
-<Para>
-Use <Literal>foreign export</Literal> declarations to export the Haskell
+<listitem>
+<para>
+Use <literal>foreign export</literal> declarations to export the Haskell
functions you want to call from the outside. For example,
-<ProgramListing>
+<programlisting>
module Adder where
adder :: Int -> Int -> IO Int -- gratuitous use of IO
adder x y = return (x+y)
foreign export stdcall adder :: Int -> Int -> IO Int
-</ProgramListing>
-</Para>
-</ListItem>
+</programlisting>
+</para>
+</listitem>
-<ListItem>
-<Para>
+<listitem>
+<para>
Compile it up:
-<Screen>
+<screen>
ghc -c adder.hs -fglasgow-exts
-</Screen>
+</screen>
This will produce two files, adder.o and adder_stub.o
-</Para>
-</ListItem>
+</para>
+</listitem>
-<ListItem>
-<Para>
-compile up a <Function>DllMain()</Function> that starts up the Haskell
+<listitem>
+<para>
+compile up a <function>DllMain()</function> that starts up the Haskell
RTS-––a possible implementation is:
-<ProgramListing>
+<programlisting>
#include <windows.h>
#include <Rts.h>
}
return TRUE;
}
-</ProgramListing>
+</programlisting>
-Here, <Literal>Adder</Literal> is the name of the root module in the module
+Here, <literal>Adder</literal> is the name of the root module in the module
tree (as mentioned above, there must be a single root module, and hence a
single module tree in the DLL).
Compile this up:
-<Screen>
+<screen>
ghc -c dllMain.c
-</Screen>
-</Para>
-</ListItem>
+</screen>
+</para>
+</listitem>
-<ListItem>
-<Para>
+<listitem>
+<para>
Construct the DLL:
-<Screen>
+<screen>
ghc ––mk-dll -o adder.dll adder.o adder_stub.o dllMain.o
-</Screen>
+</screen>
-</Para>
-</ListItem>
+</para>
+</listitem>
-<ListItem>
-<Para>
-Start using <Function>adder</Function> from VBA-––here's how I would
-<Constant>Declare</Constant> it:
+<listitem>
+<para>
+Start using <function>adder</function> from VBA-––here's how I would
+<constant>Declare</constant> it:
-<ProgramListing>
+<programlisting>
Private Declare Function adder Lib "adder.dll" Alias "adder@8"
(ByVal x As Long, ByVal y As Long) As Long
-</ProgramListing>
+</programlisting>
Since this Haskell DLL depends on a couple of the DLLs that come with GHC,
make sure that they are in scope/visible.
-</Para>
+</para>
-<Para>
+<para>
Building statically linked DLLs is the same as in the previous section: it
-suffices to add <Option>-static</Option> to the commands used to compile up
+suffices to add <option>-static</option> to the commands used to compile up
the Haskell source and build the DLL.
-</Para>
+</para>
-</ListItem>
+</listitem>
-</ItemizedList>
+</itemizedlist>
-</Sect2>
+</sect2>
</sect1>
-</Chapter>
+</chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
projects / ghc-hetmet.git / commitdiff