</sect1>
<sect1 id="static-dynamic-flags">
- <title>Static vs. Dynamic options</title>
+ <title>Static, Dynamic, and Mode options</title>
<indexterm><primary>static</primary><secondary>options</secondary>
</indexterm>
<indexterm><primary>dynamic</primary><secondary>options</secondary>
</indexterm>
+ <indexterm><primary>mode</primary><secondary>options</secondary>
+ </indexterm>
<para>Each of GHC's command line options is classified as either
- <firstterm>static</firstterm> or <firstterm>dynamic</firstterm>.
- A static flag may only be specified on the command line, whereas a
- dynamic flag may also be given in an <literal>OPTIONS_GHC</literal>
- pragma in a source file or set from the GHCi command-line with
- <literal>:set</literal>.</para>
-
- <para>As a rule of thumb, options which relate to filenames are
- static, and the rest are dynamic. The flag reference tables (<xref
+ <firstterm>static</firstterm> or <firstterm>dynamic</firstterm> or
+ <firstterm>mode</firstterm>:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Mode flags</term>
+ <listitem>
+ <para>For example, <option>--make</option> or <option>-E</option>.
+ There may be only a single mode flag on the command line. The
+ available modes are listed in <xref linkend="modes"/>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dynamic Flags</term>
+ <listitem>
+ <para>Most non-mode flags fall into this category. A dynamic flag
+ may be used on the command line, in a
+ <literal>GHC_OPTIONS</literal> pragma in a source file, or set
+ using <literal>:set</literal> in GHCi.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Static Flags</term>
+ <listitem>
+ <para>A few flags are "static", which means they can only be used on
+ the command-line, and remain in force over the entire GHC/GHCi
+ run.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The flag reference tables (<xref
linkend="flag-reference"/>) lists the status of each flag.</para>
</sect1>
<variablelist>
<varlistentry>
- <term>
- <filename>.lhs</filename>
- <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
- </term>
+ <term><filename>.hs</filename></term>
<listitem>
- <para>A “literate Haskell” module.</para>
+ <para>A Haskell module.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>.hs</filename></term>
+ <term>
+ <filename>.lhs</filename>
+ <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
+ </term>
<listitem>
- <para>A not-so-literate Haskell module.</para>
+ <para>A “literate Haskell” module.</para>
</listitem>
</varlistentry>
file.</para>
</listitem>
<listitem>
- <para>You don't have to write a<literal>Makefile</literal>.</para>
+ <para>You don't have to write a <literal>Makefile</literal>.</para>
<indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm>
</listitem>
<listitem>
<variablelist>
<varlistentry>
- <term><option>-x</option> <replaceable>suffix</replaceable></term>
- <indexterm><primary><option>-x</option></primary>
- </indexterm>
+ <term><option>-x</option> <replaceable>suffix</replaceable>
+ <indexterm><primary><option>-x</option></primary>
+ </indexterm></term>
<listitem>
<para>Causes all files following this option on the command
line to be processed as if they had the suffix
it).</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>-Rghc-timing</option>
+ <indexterm><primary><option>-Rghc-timing</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Prints a one-line summary of timing statistics for the
+ GHC run. This option is equivalent to
+ <literal>+RTS -tstderr</literal>, see <xref
+ linkend="rts-options-gc" />.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</sect1>
&phases;
<sect1 id="sec-using-concurrent">
-<title>Using Concurrent Haskell</title>
-
- <indexterm><primary>Concurrent Haskell—use</primary></indexterm>
-
-<para>
-GHC supports Concurrent Haskell by default, without requiring a
-special option or libraries compiled in a certain way. To get access
-to the support libraries for Concurrent Haskell, just import
-<literal>Control.Concurrent</literal> (details are in the accompanying
-library documentation).</para>
+ <title>Using Concurrent Haskell</title>
+ <indexterm><primary>Concurrent Haskell</primary><secondary>using</secondary></indexterm>
-<para>
-RTS options are provided for modifying the behaviour of the threaded
-runtime system. See <xref linkend="parallel-rts-opts"/>.
-</para>
+ <para>GHC supports Concurrent Haskell by default, without requiring a
+ special option or libraries compiled in a certain way. To get access to
+ the support libraries for Concurrent Haskell, just import
+ <ulink
+ url="../libraries/base/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>. More information on Concurrent Haskell is provided in the documentation for that module.</para>
-<para>
-Concurrent Haskell is described in more detail in the documentation
-for the <literal>Control.Concurrent</literal> module.
-</para>
+ <para>The following RTS option(s) affect the behaviour of Concurrent
+ Haskell programs:<indexterm><primary>RTS options, concurrent</primary></indexterm></para>
-</sect1>
+ <variablelist>
+ <varlistentry>
+ <term><option>-C<replaceable>s</replaceable></option></term>
+ <listitem>
+ <para><indexterm><primary><option>-C<replaceable>s</replaceable></option></primary><secondary>RTS option</secondary></indexterm>
+ Sets the context switch interval to <replaceable>s</replaceable>
+ seconds. A context switch will occur at the next heap block
+ allocation after the timer expires (a heap block allocation occurs
+ every 4k of allocation). With <option>-C0</option> or
+ <option>-C</option>, context switches will occur as often as
+ possible (at every heap block allocation). By default, context
+ switches occur every 20ms. Note that GHC's internal timer ticks
+ every 20ms, and the context switch timer is always a multiple of
+ this timer, so 20ms is the maximum granularity available for timed
+ context switches.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
<sect1 id="sec-using-parallel">
<title>Using parallel Haskell</title>
<para>
-<indexterm><primary>parallel Haskell—use</primary></indexterm>
-</para>
-
-<para>
-[You won't be able to execute parallel Haskell programs unless PVM3
+<indexterm><primary>Parallel Haskell</primary><secondary>using</secondary></indexterm>
+[NOTE: GHC does not support Parallel Haskell by default, you need to
+ obtain a special version of GHC from the <ulink
+ url="http://www.cee.hw.ac.uk/~dsg/gph/">GPH</ulink> site. Also,
+you won't be able to execute parallel Haskell programs unless PVM3
(parallel Virtual Machine, version 3) is installed at your site.]
</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.
+Control.Parallel</literal> into your Haskell modules.
</para>
<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
+<option>-qP</option><indexterm><primary>-qP RTS option</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,
which you can then display. For example, to run your program
</sect2>
<sect2 id="parallel-rts-opts">
-<title>RTS options for Concurrent/parallel Haskell
+<title>RTS options for 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>
</para>
<para>
Besides the usual runtime system (RTS) options
(<xref linkend="runtime-control"/>), there are a few options particularly
-for concurrent/parallel execution.
+for parallel execution.
</para>
<para>
</listitem>
</varlistentry>
<varlistentry>
-<term><option>-C[<us>]</option>:</term>
+<term><option>-C[<s>]</option>:</term>
<listitem>
<para>
-<indexterm><primary>-C<us> RTS option</primary></indexterm> Sets
+<indexterm><primary>-C<s> RTS option</primary></indexterm> Sets
the context switch interval to <literal><s></literal> seconds.
A context switch will occur at the next heap block allocation after
the timer expires (a heap block allocation occurs every 4k of
allocation). With <option>-C0</option> or <option>-C</option>,
context switches will occur as often as possible (at every heap block
-allocation). By default, context switches occur every 20ms
-milliseconds. Note that GHC's internal timer ticks every 20ms, and
+allocation). By default, context switches occur every 20ms. Note that GHC's internal timer ticks every 20ms, and
the context switch timer is always a multiple of this timer, so 20ms
is the maximum granularity available for timed context switches.
</para>
<listitem>
<para>
<indexterm><primary>-qt<num> RTS option</primary></indexterm>
-(paraLLEL ONLY) Limit the thread pool size, i.e. the number of concurrent
+(paraLLEL ONLY) Limit the thread pool size, i.e. the number of
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