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>
ghc [argument...]
</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
</sect2>
<sect2 id="source-file-options">
- <title>command line options in source files</title>
+ <title>Command line options in source files</title>
<indexterm><primary>source-file options</primary></indexterm>
<para>It is not recommended to move all the contents of your
Makefiles into your source files, but in some circumstances, the
<literal>OPTIONS_GHC</literal> pragma is the Right Thing. (If you
- use <option>-keep-hc-file-too</option> and have OPTION flags in
+ use <option>-keep-hc-file</option> and have OPTION flags in
your module, the OPTIONS_GHC will get put into the generated .hc
file).</para>
</sect2>
<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> or
+ <para>Each of GHC's command line options is classified as
+ <firstterm>static</firstterm>, <firstterm>dynamic</firstterm> or
<firstterm>mode</firstterm>:</para>
<variablelist>
<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
+ There may only be a single mode flag on the command line. The
available modes are listed in <xref linkend="modes"/>.</para>
</listitem>
</varlistentry>
<para>The flag reference tables (<xref
linkend="flag-reference"/>) lists the status of each flag.</para>
+
+ <para>There are a few flags that are static except that they can
+ also be used with GHCi's <literal>:set</literal> command; these
+ are listed as “static/<literal>:set</literal>” in the
+ table.</para>
</sect1>
<sect1 id="file-suffixes">
<variablelist>
<varlistentry>
<term>
- <cmdsynopsis><command>ghc</command>
- <arg choice='plain'>––interactive</arg>
+ <cmdsynopsis><command>ghc --interactive</command>
</cmdsynopsis>
<indexterm><primary>interactive mode</primary></indexterm>
<indexterm><primary>ghci</primary></indexterm>
<varlistentry>
<term>
- <cmdsynopsis><command>ghc</command>
- <arg choice='plain'>––make</arg>
+ <cmdsynopsis><command>ghc --make</command>
</cmdsynopsis>
<indexterm><primary>make mode</primary></indexterm>
<indexterm><primary><option>––make</option></primary></indexterm>
<varlistentry>
<term>
- <cmdsynopsis><command>ghc</command>
- <arg choice='plain'>–e</arg> <arg choice='plain'><replaceable>expr</replaceable></arg>
+ <cmdsynopsis><command>ghc -e</command>
+ <arg choice='plain'><replaceable>expr</replaceable></arg>
</cmdsynopsis>
<indexterm><primary>eval mode</primary></indexterm>
</term>
<varlistentry>
<term>
<cmdsynopsis>
- <command>ghc</command>
- <group>
- <arg>-E</arg>
- <arg>-C</arg>
- <arg>-S</arg>
- <arg>-c</arg>
- </group>
+ <command>ghc -E</command>
+ <command>ghc -c</command>
+ <command>ghc -S</command>
+ <command>ghc -c</command>
</cmdsynopsis>
<indexterm><primary><option>-E</option></primary></indexterm>
<indexterm><primary><option>-C</option></primary></indexterm>
<varlistentry>
<term>
<cmdsynopsis>
- <command>ghc</command>
- <arg choice='plain'>–M</arg>
+ <command>ghc -M</command>
</cmdsynopsis>
<indexterm><primary>dependency-generation mode</primary></indexterm>
</term>
<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="makefile-dependencies"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
- <command>ghc</command>
- <arg choice='plain'>––mk-dll</arg>
+ <command>ghc --mk-dll</command>
</cmdsynopsis>
- <indexterm><primary>dependency-generation mode</primary></indexterm>
+ <indexterm><primary>DLL-creation mode</primary></indexterm>
</term>
<listitem>
<para>DLL-creation mode (Windows only). See <xref
linkend="win32-dlls-create"/>.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc --help</command> <command>ghc -?</command>
+ </cmdsynopsis>
+ <indexterm><primary><option>––help</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Cause GHC to spew a long usage message to standard
+ output and then exit.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc --supported-languages</command>
+ </cmdsynopsis>
+ <indexterm><primary><option>––supported-languages</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Print the supported language extensions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc --info</command>
+ </cmdsynopsis>
+ <indexterm><primary><option>––info</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Print information about the compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc --version</command>
+ <command>ghc -V</command>
+ </cmdsynopsis>
+ <indexterm><primary><option>-V</option></primary></indexterm>
+ <indexterm><primary><option>––version</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Print a one-line string including GHC's version number.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc --numeric-version</command>
+ </cmdsynopsis>
+ <indexterm><primary><option>––numeric-version</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Print GHC's numeric version number only.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc --print-libdir</command>
+ </cmdsynopsis>
+ <indexterm><primary><option>––print-libdir</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Print the path to GHC's library directory. This is
+ the top of the directory tree containing GHC's libraries,
+ interfaces, and include files (usually something like
+ <literal>/usr/local/lib/ghc-5.04</literal> on Unix). This
+ is the value of
+ <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary></indexterm>
+ in the package configuration file
+ (see <xref linkend="packages"/>).</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
<sect2 id="make-mode">
<para>When given the <option>––make</option> option,
GHC will build a multi-module Haskell program by following
- dependencies from a single root module (usually
+ dependencies from one or more root modules (usually just
<literal>Main</literal>). For example, if your
<literal>Main</literal> module is in a file called
<filename>Main.hs</filename>, you could compile and link the
names or module names; GHC will figure out all the modules in
the program by following the imports from these initial modules.
It will then attempt to compile each module which is out of
- date, and finally if there is a <literal>Main</literal> module,
+ date, and finally, if there is a <literal>Main</literal> module,
the program will also be linked into an executable.</para>
<para>The main advantages to using <literal>ghc
<para>The first phase to run is determined by each input-file
suffix, and the last phase is determined by a flag. If no
- relevant flag is present, then go all the way through linking.
+ relevant flag is present, then go all the way through to linking.
This table summarises:</para>
<informaltable>
<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>
+ of the compiler, dumping the result in a file.</para>
<sect3 id="overriding-suffixes">
<title>Overriding the default behaviour for a file</title>
<indexterm><primary>help options</primary></indexterm>
<indexterm><primary>verbosity options</primary></indexterm>
+ <para>See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
+ and <option>--print-libdir</option> modes in <xref linkend="modes"/>.</para>
<variablelist>
<varlistentry>
<term>
- <option>––help</option>
- <indexterm><primary><option>––help</option></primary></indexterm>
- </term>
- <term>
- <option>-?</option>
- <indexterm><primary><option>-?</option></primary></indexterm>
+ <option>-n</option>
+ <indexterm><primary><option>-n</option></primary></indexterm>
</term>
<listitem>
- <para>Cause GHC to spew a long usage message to standard
- output and then exit.</para>
+ <para>Does a dry-run, i.e. GHC goes through all the motions
+ of compiling as normal, but does not actually run any
+ external commands.</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term>
- <option>-V</option>
- <indexterm><primary><option>-V</option></primary></indexterm>
- </term>
- <term>
- <option>––version</option>
- <indexterm><primary><option>––version</option></primary></indexterm>
- </term>
- <listitem>
- <para>Print a one-line string including GHC's version number.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>––numeric-version</option>
- <indexterm><primary><option>––numeric-version</option></primary></indexterm>
- </term>
- <listitem>
- <para>Print GHC's numeric version number only.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>––print-libdir</option>
- <indexterm><primary><option>––print-libdir</option></primary></indexterm>
- </term>
- <listitem>
- <para>Print the path to GHC's library directory. This is
- the top of the directory tree containing GHC's libraries,
- interfaces, and include files (usually something like
- <literal>/usr/local/lib/ghc-5.04</literal> on Unix). This
- is the value of
- <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
- </indexterm>in the package configuration file (see <xref
- linkend="packages"/>).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><option>-ferror-spans</option>
<indexterm><primary><option>-ferror-spans</option></primary>
</indexterm>
</varlistentry>
<varlistentry>
+ <term><option>-H</option><replaceable>size</replaceable>
+ <indexterm><primary><option>-H</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Set the minimum size of the heap to
+ <replaceable>size</replaceable>.
+ This option is equivalent to
+ <literal>+RTS -H<replaceable>size</replaceable></literal>,
+ see <xref linkend="rts-options-gc" />.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-Rghc-timing</option>
<indexterm><primary><option>-Rghc-timing</option></primary></indexterm>
</term>
<indexterm><primary>-W option</primary></indexterm>
<para>Provides the standard warnings plus
<option>-fwarn-incomplete-patterns</option>,
+ <option>-fwarn-dodgy-imports</option>,
<option>-fwarn-unused-matches</option>,
- <option>-fwarn-unused-imports</option>,
- <option>-fwarn-misc</option>, and
+ <option>-fwarn-unused-imports</option>, and
<option>-fwarn-unused-binds</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-w</option>:</term>
+ <term><option>-Wall</option>:</term>
<listitem>
- <indexterm><primary><option>-w</option></primary></indexterm>
- <para>Turns off all warnings, including the standard ones.</para>
+ <indexterm><primary><option>-Wall</option></primary></indexterm>
+ <para>Turns on all warning options that indicate potentially
+ suspicious code. The warnings that are
+ <emphasis>not</emphasis> enabled by <option>-Wall</option>
+ are
+ <option>-fwarn-simple-patterns</option>,
+ <option>-fwarn-tabs</option>,
+ <option>-fwarn-incomplete-record-updates</option>,
+ <option>-fwarn-monomorphism-restriction</option>, and
+ <option>-fwarn-implicit-prelude</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-Wall</option>:</term>
+ <term><option>-w</option>:</term>
<listitem>
- <indexterm><primary><option>-Wall</option></primary></indexterm>
- <para>Turns on all warning options.</para>
+ <indexterm><primary><option>-w</option></primary></indexterm>
+ <para>Turns off all warnings, including the standard ones and
+ those that <literal>-Wall</literal> doesn't enable.</para>
</listitem>
</varlistentry>
function or type is used. Entities can be marked as
deprecated using a pragma, see <xref
linkend="deprecated-pragma"/>.</para>
+
+ <para>This option is on by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-dodgy-imports</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-dodgy-imports</option></primary>
+ </indexterm>
+ <para>Causes a warning to be emitted when a a datatype
+ <literal>T</literal> is imported
+ with all constructors, i.e. <literal>T(..)</literal>, but has been
+ exported abstractly, i.e. <literal>T</literal>.</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
+ <term><option>-fwarn-implicit-prelude</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-implicit-prelude</option></primary></indexterm>
+ <indexterm><primary>implicit prelude, warning</primary></indexterm>
+ <para>Have the compiler warn if the Prelude is implicitly
+ imported. This happens unless either the Prelude module is
+ explicitly imported with an <literal>import ... Prelude ...</literal>
+ line, or this implicit import is disabled (either by
+ <option>-fno-implicit-prelude</option> or a
+ <literal>LANGUAGE NoImplicitPrelude</literal> pragma).</para>
+
+ <para>Note that no warning is given for syntax that implicitly
+ refers to the Prelude, even if <option>-fno-implicit-prelude</option>
+ would change whether it refers to the Prelude.
+ For example, no warning is given when
+ <literal>368</literal> means
+ <literal>Prelude.fromInteger (368::Prelude.Integer)</literal>
+ (where <literal>Prelude</literal> refers to the actual Prelude module,
+ regardless of the imports of the module being compiled).</para>
+
+ <para>This warning is off by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-fwarn-incomplete-patterns</option>:</term>
<listitem>
<indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
g [] = 2
</programlisting>
- <para>This option isn't enabled be default because it can be
+ <para>This option isn't enabled by default because it can be
a bit noisy, and it doesn't always indicate a bug in the
program. However, it's generally considered good practice
to cover all the cases in your functions.</para>
f foo = foo { x = 6 }
</programlisting>
- <para>This option isn't enabled be default because it can be
+ <para>This option isn't enabled by default because it can be
very noisy, and it often doesn't indicate a bug in the
program.</para>
</listitem>
<varlistentry>
<term>
- <option>-fwarn-misc</option>:
- <indexterm><primary><option>-fwarn-misc</option></primary></indexterm>
- </term>
- <listitem>
- <para>Turns on warnings for various harmless but untidy
- things. This currently includes: importing a type with
- <literal>(..)</literal> when the export is abstract, and
- listing duplicate class assertions in a qualified type.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
<option>-fwarn-missing-fields</option>:
<indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm>
<indexterm><primary>missing fields, warning</primary></indexterm>
<para>If you would like GHC to check that every top-level
function/value has a type signature, use the
- <option>-fwarn-missing-signatures</option> option. This
+ <option>-fwarn-missing-signatures</option> option. As part of
+ the warning GHC also reports the inferred type. The
option is off by default.</para>
</listitem>
</varlistentry>
inner-scope value has the same name as an outer-scope value,
i.e. the inner value shadows the outer one. This can catch
typographical errors that turn into hard-to-find bugs, e.g.,
- in the inadvertent cyclic definition <literal>let x = ... x
- ... in</literal>.</para>
-
- <para>Consequently, this option does
- <emphasis>will</emphasis> complain about cyclic recursive
- definitions.</para>
+ in the inadvertent capture of what would be a recursive call in
+ <literal>f = ... let f = id in ... f ...</literal>.</para>
</listitem>
</varlistentry>
</term>
<listitem>
<para>By default, the compiler will warn you if a set of
- patterns are overlapping, i.e.,</para>
+ patterns are overlapping, e.g.,</para>
<programlisting>
f :: String -> Int
patterns that can fail, eg. <literal>\(x:xs)->...</literal>.
Normally, these aren't treated as incomplete patterns by
<option>-fwarn-incomplete-patterns</option>.</para>
- <para>``Lambda-bound patterns'' includes all places where there is a single pattern,
+ <para>“Lambda-bound patterns” includes all places where there is a single pattern,
including list comprehensions and do-notation. In these cases, a pattern-match
failure is quite legitimate, and triggers filtering (list comprehensions) or
the monad <literal>fail</literal> operation (monads). For example:
</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>
- <para> The <literal>deriving( Read )</literal> mechanism produces monadic code with
- pattern matches, so you will also get misleading warnings about the compiler-generated
- code. (This is arguably a Bad Thing, but it's awkward to fix.)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-tabs</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-tabs</option></primary></indexterm>
+ <indexterm><primary>tabs, warning</primary></indexterm>
+ <para>Have the compiler warn if there are tabs in your source
+ file.</para>
+ <para>This warning is off by default.</para>
</listitem>
</varlistentry>
the Haskell defaulting mechanism for numeric types kicks
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
+ e.g., the ‘default default’ for Haskell 1.4 caused the
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
</varlistentry>
<varlistentry>
+ <term><option>-fwarn-monomorphism-restriction</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-monomorphism-restriction</option></primary></indexterm>
+ <indexterm><primary>monomorphism restriction, warning</primary></indexterm>
+ <para>Have the compiler warn/inform you where in your source
+ the Haskell Monomorphism Restriction is applied. If applied silently
+ the MR can give rise to unexpected behaviour, so it can be helpful
+ to have an explicit warning that it is being applied.</para>
+
+ <para>This warning is off by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-fwarn-unused-binds</option>:</term>
<listitem>
<indexterm><primary><option>-fwarn-unused-binds</option></primary></indexterm>
<para>Note that higher optimisation levels cause more
cross-module optimisation to be performed, which can have an
impact on how much of your program needs to be recompiled when
- you change something. This is one reaosn to stick to
+ you change something. This is one reason to stick to
no-optimisation when developing code.</para>
<variablelist>
<para>Means: “Generate good-quality code without
taking too long about it.” Thus, for example:
<command>ghc -c -O Main.lhs</command></para>
-
- <para><option>-O</option> currently also implies
- <option>-fvia-C</option>. This may change in the
- future.</para>
</listitem>
</varlistentry>
<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="assertions"/>). This flag is turned on by
<option>-O</option>.
</para>
</listitem>
<para>Turns off the full laziness optimisation (also known as
let-floating). Full laziness increases sharing, which can lead
to increased memory residency.</para>
+
+ <para>NOTE: GHC doesn't implement complete full-laziness.
+ When optimisation in on, and
+ <option>-fno-full-laziness</option> is not given, some
+ transformations that increase sharing are performed, such
+ as extracting repeated computations from a loop. These
+ are the same transformations that a fully lazy
+ implementation would do, the difference is that GHC
+ doesn't consistently apply full-laziness, so don't rely on
+ it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
+ <option>-fno-state-hack</option>
+ <indexterm><primary><option>-fno-state-hack</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Turn off the "state hack" whereby any lambda with a
+ <literal>State#</literal> token as argument is considered to be
+ single-entry, hence it is considered OK to inline things inside
+ it. This can improve performance of IO and ST monad code, but it
+ runs the risk of reducing sharing.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-fomit-interface-pragmas</option>
+ <indexterm><primary><option>-fomit-interface-pragmas</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Tells GHC to omit all inessential information from the interface file
+ generated for the module being compiled (say M). This means that a module
+ importing M will see only the <emphasis>types</emphasis> of the functions that M exports, but not
+ their unfoldings, strictness info, etc. Hence, for example,
+ no function exported by M will be inlined
+ into an importing module. The benefit is that modules that import M will
+ need to be recompiled less often (only when M's exports change their type,
+ not when they change their implementation).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-fignore-interface-pragmas</option>
+ <indexterm><primary><option>-fignore-interface-pragmas</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Tells GHC to ignore all inessential information when reading interface files.
+ That is, even if <filename>M.hi</filename> contains unfolding or strictness information
+ for a function, GHC will ignore that information.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<option>-funbox-strict-fields</option>:
<indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
<indexterm><primary>strict constructor fields</primary></indexterm>
<varlistentry>
<term>
- <option>-funfolding-update-in-place<n></option>
+ <option>-funfolding-update-in-place=<replaceable>n</replaceable></option>
<indexterm><primary><option>-funfolding-update-in-place</option></primary></indexterm>
</term>
<listitem>
<varlistentry>
<term>
- <option>-funfolding-creation-threshold<n></option>:
+ <option>-funfolding-creation-threshold=<replaceable>n</replaceable></option>:
<indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
<indexterm><primary>inlining, controlling</primary></indexterm>
<indexterm><primary>unfolding, controlling</primary></indexterm>
</varlistentry>
<varlistentry>
- <term><option>-funfolding-use-threshold<n></option>:</term>
+ <term><option>-funfolding-use-threshold=<replaceable>n</replaceable></option></term>
<listitem>
<indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
<indexterm><primary>inlining, controlling</primary></indexterm>
&phases;
- <sect1 id="sec-using-concurrent">
+ <sect1 id="using-concurrent">
<title>Using Concurrent Haskell</title>
<indexterm><primary>Concurrent Haskell</primary><secondary>using</secondary></indexterm>
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>
+ switches occur every 20ms.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
-<sect1 id="sec-using-parallel">
-<title>Using parallel Haskell</title>
-
-<para>
-<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>
-
-<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
-Control.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
-“processors” your program to run on. (For more details of
-all relevant RTS options, please see <xref
-linkend="parallel-rts-opts"/>.)
-</para>
-
-<para>
-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>
-
-<para>
-<indexterm><primary>PVM, how to 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>
-setenv PVM_ROOT /wherever/you/put/it
-setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
-setenv PVM_DPATH $PVM_ROOT/lib/pvmd
-</programlisting>
-
-</para>
-
-<para>
-Creating and/or controlling your “parallel machine” is a purely-PVM
-business; nothing specific to parallel Haskell. The following paragraphs
-describe how to configure your parallel machine interactively.
-</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>
-
-<programlisting>
-pvm $PVM_HOST_FILE
-</programlisting>
-
-<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>
-
-<row>
-<entry><keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo></entry>
-<entry>exit <command>pvm</command>, leaving it running</entry>
-</row>
-
-<row>
-<entry><command>halt</command></entry>
-<entry>kill off this “parallel machine” & exit</entry>
-</row>
-
-<row>
-<entry><command>add <host></command></entry>
-<entry>add <command><host></command> as a processor</entry>
-</row>
-
-<row>
-<entry><command>delete <host></command></entry>
-<entry>delete <command><host></command></entry>
-</row>
-
-<row>
-<entry><command>reset</command></entry>
-<entry>kill what's going, but leave PVM up</entry>
-</row>
-
-<row>
-<entry><command>conf</command></entry>
-<entry>list the current configuration</entry>
-</row>
-
-<row>
-<entry><command>ps</command></entry>
-<entry>report processes' status</entry>
-</row>
-
-<row>
-<entry><command>pstat <pid></command></entry>
-<entry>status of a particular process</entry>
-</row>
-
-</tbody>
-</tgroup>
-</informaltable>
-</para>
-
-<para>
-The PVM documentation can tell you much, much more about <command>pvm</command>!
-</para>
-
-</sect2>
-
-<sect2 id="par-profiles">
-<title>parallelism profiles</title>
-
-<para>
-<indexterm><primary>parallelism profiles</primary></indexterm>
-<indexterm><primary>profiles, parallelism</primary></indexterm>
-<indexterm><primary>visualisation tools</primary></indexterm>
-</para>
-
-<para>
-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</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
-<filename>a.out</filename> on 8 processors, then view the parallelism profile, do:
-</para>
-
-<para>
-
-<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>
+ <sect1 id="using-smp">
+ <title>Using SMP parallelism</title>
+ <indexterm><primary>parallelism</primary>
+ </indexterm>
+ <indexterm><primary>SMP</primary>
+ </indexterm>
-</para>
-
-<para>
-The scripts for processing the parallelism profiles are distributed
-in <filename>ghc/utils/parallel/</filename>.
-</para>
-
-</sect2>
-
-<sect2>
-<title>Other useful info about running parallel programs</title>
-
-<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
-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.
-</para>
-
-<para>
-Whether doing <option>+RTS -Sstderr</option> or not, a handy way to watch
-what's happening overall is: <command>tail -f /tmp/pvml.nnn</command>.
-</para>
-
-</sect2>
-
-<sect2 id="parallel-rts-opts">
-<title>RTS options for Parallel Haskell
-</title>
-
-<para>
-<indexterm><primary>RTS options, parallel</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 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;
-the default is 2.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-C[<s>]</option>:</term>
-<listitem>
-<para>
-<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. 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>
-<varlistentry>
-<term><option>-q[v]</option>:</term>
-<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
-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>).
--->
-</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
-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>
-<!-- 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>
-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>
--->
-<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
-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
-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
-<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
-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
-graph structure. Currently this is a binary option. With <num>=0 full globalisation is used
-(default). This means a global address is generated for every closure that
-is transmitted. With <num>=1 a thunk-only globalisation scheme is
-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>
-
-</sect2>
+ <para>GHC supports running Haskell programs in parallel on an SMP
+ (symmetric multiprocessor).</para>
+
+ <para>There's a fine distinction between
+ <emphasis>concurrency</emphasis> and <emphasis>parallelism</emphasis>:
+ parallelism is all about making your program run
+ <emphasis>faster</emphasis> by making use of multiple processors
+ simultaneously. Concurrency, on the other hand, is a means of
+ abstraction: it is a convenient way to structure a program that must
+ respond to multiple asynchronous events.</para>
+
+ <para>However, the two terms are certainly related. By making use of
+ multiple CPUs it is possible to run concurrent threads in parallel,
+ and this is exactly what GHC's SMP parallelism support does. But it
+ is also possible to obtain performance improvements with parallelism
+ on programs that do not use concurrency. This section describes how to
+ use GHC to compile and run parallel programs, in <xref
+ linkend="lang-parallel" /> we desribe the language features that affect
+ parallelism.</para>
+
+ <sect2 id="parallel-options">
+ <title>Options to enable SMP parallelism</title>
-</sect1>
+ <para>In order to make use of multiple CPUs, your program must be
+ linked with the <option>-threaded</option> option (see <xref
+ linkend="options-linker" />). Then, to run a program on multiple
+ CPUs, use the RTS <option>-N</option> option:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-N<replaceable>x</replaceable></option></term>
+ <listitem>
+ <para><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm>
+ Use <replaceable>x</replaceable> simultaneous threads when
+ running the program. Normally <replaceable>x</replaceable>
+ should be chosen to match the number of CPU cores on the machine.
+ There is no means (currently) by which this value may vary after
+ the program has started.</para>
+
+ <para>For example, on a dual-core machine we would probably use
+ <literal>+RTS -N2 -RTS</literal>.</para>
+
+ <para>Whether hyperthreading cores should be counted or not is an
+ open question; please feel free to experiment and let us know what
+ results you find.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Hints for using SMP parallelism</title>
+
+ <para>Add the <literal>-sstderr</literal> RTS option when
+ running the program to see timing stats, which will help to tell you
+ whether your program got faster by using more CPUs or not. If the user
+ time is greater than
+ the elapsed time, then the program used more than one CPU. You should
+ also run the program without <literal>-N</literal> for comparison.</para>
+
+ <para>GHC's parallelism support is new and experimental. It may make your
+ program go faster, or it might slow it down - either way, we'd be
+ interested to hear from you.</para>
+
+ <para>One significant limitation with the current implementation is that
+ the garbage collector is still single-threaded, and all execution must
+ stop when GC takes place. This can be a significant bottleneck in a
+ parallel program, especially if your program does a lot of GC. If this
+ happens to you, then try reducing the cost of GC by tweaking the GC
+ settings (<xref linkend="rts-options-gc" />): enlarging the heap or the
+ allocation area size is a good start.</para>
+ </sect2>
+ </sect1>
<sect1 id="options-platform">
<title>Platform-specific Flags</title>
<variablelist>
<varlistentry>
- <term><option>-mv8</option>:</term>
- <listitem>
- <para>(SPARC machines)<indexterm><primary>-mv8 option (SPARC
- only)</primary></indexterm> Means to pass the like-named
- option to GCC; it says to use the Version 8 SPARC
- instructions, notably integer multiply and divide. The
- similar <option>-m*</option> GCC options for SPARC also
- work, actually.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><option>-monly-[32]-regs</option>:</term>
<listitem>
<para>(iX86 machines)<indexterm><primary>-monly-N-regs
projects / ghc-hetmet.git / blobdiff