--- /dev/null
+<?xml version="1.0" encoding="iso-8859-1"?>
+<chapter id="using-ghc">
+ <title>Using GHC</title>
+
+ <indexterm><primary>GHC, using</primary></indexterm>
+ <indexterm><primary>using GHC</primary></indexterm>
+
+ <sect1>
+ <title>Options overview</title>
+
+ <para>GHC's behaviour is controlled by
+ <firstterm>options</firstterm>, which for historical reasons are
+ also sometimes referred to as command-line flags or arguments.
+ Options can be specified in three ways:</para>
+
+ <sect2>
+ <title>command-line arguments</title>
+
+ <indexterm><primary>structure, command-line</primary></indexterm>
+ <indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm>
+ <indexterm><primary>arguments</primary><secondary>command-line</secondary></indexterm>
+
+ <para>An invocation of GHC takes the following form:</para>
+
+<screen>
+ghc [argument...]
+</screen>
+
+ <para>command-line arguments are either options or file names.</para>
+
+ <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
+ foo</literal>. All options are processed and then applied to
+ all files; you cannot, for example, invoke <literal>ghc -c -O1
+ Foo.hs -O2 Bar.hs</literal> to apply different optimisation
+ levels to the files <filename>Foo.hs</filename> and
+ <filename>Bar.hs</filename>.</para>
+ </sect2>
+
+ <sect2 id="source-file-options">
+ <title>command line options in source files</title>
+
+ <indexterm><primary>source-file options</primary></indexterm>
+
+ <para>Sometimes it is useful to make the connection between a
+ source file and the command-line options it requires quite
+ tight. For instance, if a Haskell source file uses GHC
+ extensions, it will always need to be compiled with the
+ <option>-fglasgow-exts</option> option. Rather than maintaining
+ the list of per-file options in a <filename>Makefile</filename>,
+ it is possible to do this directly in the source file using the
+ <literal>OPTIONS</literal> pragma <indexterm><primary>OPTIONS
+ pragma</primary></indexterm>:</para>
+
+<programlisting>
+{-# OPTIONS -fglasgow-exts #-}
+module X where
+...
+</programlisting>
+
+ <para><literal>OPTIONS</literal> pragmas are only looked for at
+ the top of your source files, upto the first
+ (non-literate,non-empty) line not containing
+ <literal>OPTIONS</literal>. Multiple <literal>OPTIONS</literal>
+ pragmas are recognised. Note that your command shell does not
+ get to the source file options, they are just included literally
+ in the array of command-line arguments the compiler driver
+ maintains internally, so you'll be desperately disappointed if
+ you try to glob etc. inside <literal>OPTIONS</literal>.</para>
+
+ <para>NOTE: the contents of OPTIONS are prepended to the
+ command-line options, so you <emphasis>do</emphasis> have the
+ ability to override OPTIONS settings via the command
+ line.</para>
+
+ <para>It is not recommended to move all the contents of your
+ Makefiles into your source files, but in some circumstances, the
+ <literal>OPTIONS</literal> pragma is the Right Thing. (If you
+ use <option>-keep-hc-file-too</option> and have OPTION flags in
+ your module, the OPTIONS will get put into the generated .hc
+ file).</para>
+ </sect2>
+
+ <sect2>
+ <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"/>
+ for more details.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="static-dynamic-flags">
+ <title>Static vs. Dynamic options</title>
+ <indexterm><primary>static</primary><secondary>options</secondary>
+ </indexterm>
+ <indexterm><primary>dynamic</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</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
+ linkend="flag-reference"/>) lists the status of each flag.</para>
+ </sect1>
+
+ <sect1 id="file-suffixes">
+ <title>Meaningful file suffixes</title>
+
+ <indexterm><primary>suffixes, file</primary></indexterm>
+ <indexterm><primary>file suffixes for GHC</primary></indexterm>
+
+ <para>File names with “meaningful” suffixes (e.g.,
+ <filename>.lhs</filename> or <filename>.o</filename>) cause the
+ “right thing” to happen to those files.</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ <filename>.lhs</filename>
+ <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm>
+ </term>
+ <listitem>
+ <para>A “literate Haskell” module.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.hs</filename></term>
+ <listitem>
+ <para>A not-so-literate Haskell module.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.hi</filename></term>
+ <listitem>
+ <para>A Haskell interface file, probably
+ compiler-generated.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.hc</filename></term>
+ <listitem>
+ <para>Intermediate C file produced by the Haskell
+ compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.c</filename></term>
+ <listitem>
+ <para>A C file not produced by the Haskell
+ compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.s</filename></term>
+ <listitem>
+ <para>An assembly-language source file, usually produced by
+ the compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>.o</filename></term>
+ <listitem>
+ <para>An object file, produced by an assembler.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Files with other suffixes (or without suffixes) are passed
+ straight to the linker.</para>
+
+ </sect1>
+
+ <sect1 id="modes">
+ <title>Modes of operation</title>
+
+ <para>GHC's behaviour is firstly controlled by a mode flag. Only
+ one of these flags may be given, but it does not necessarily need
+ to be the first option on the command-line. The available modes
+ are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <cmdsynopsis><command>ghc</command>
+ <arg choice='plain'>––interactive</arg>
+ </cmdsynopsis>
+ <indexterm><primary>interactive mode</primary></indexterm>
+ <indexterm><primary>ghci</primary></indexterm>
+ </term>
+ <listitem>
+ <para>Interactive mode, which is also available as
+ <command>ghci</command>. Interactive mode is described in
+ more detail in <xref linkend="ghci"/>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis><command>ghc</command>
+ <arg choice='plain'>––make</arg>
+ </cmdsynopsis>
+ <indexterm><primary>make mode</primary></indexterm>
+ <indexterm><primary><option>––make</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>In this mode, GHC will build a multi-module Haskell
+ program automatically, figuring out dependencies for itself.
+ 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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis><command>ghc</command>
+ <arg choice='plain'>–e</arg> <arg choice='plain'><replaceable>expr</replaceable></arg>
+ </cmdsynopsis>
+ <indexterm><primary>eval mode</primary></indexterm>
+ </term>
+ <listitem>
+ <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
+ more details.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc</command>
+ <group>
+ <arg>-E</arg>
+ <arg>-C</arg>
+ <arg>-S</arg>
+ <arg>-c</arg>
+ </group>
+ </cmdsynopsis>
+ <indexterm><primary><option>-E</option></primary></indexterm>
+ <indexterm><primary><option>-C</option></primary></indexterm>
+ <indexterm><primary><option>-S</option></primary></indexterm>
+ <indexterm><primary><option>-c</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>This is the traditional batch-compiler mode, in which
+ GHC can compile source files one at a time, or link objects
+ together into an executable. This mode also applies if
+ 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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc</command>
+ <arg choice='plain'>–M</arg>
+ </cmdsynopsis>
+ <indexterm><primary>dependency-generation mode</primary></indexterm>
+ </term>
+ <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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc</command>
+ <arg choice='plain'>––mk-dll</arg>
+ </cmdsynopsis>
+ <indexterm><primary>dependency-generation mode</primary></indexterm>
+ </term>
+ <listitem>
+ <para>DLL-creation mode (Windows only). See <xref
+ linkend="win32-dlls-create"/>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <sect2 id="make-mode">
+ <title>Using <command>ghc</command> <option>––make</option></title>
+ <indexterm><primary><option>––make</option></primary></indexterm>
+ <indexterm><primary>separate compilation</primary></indexterm>
+
+ <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
+ <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
+ program like this:</para>
+
+<screen>
+ghc ––make Main.hs
+</screen>
+
+ <para>The command line may contain any number of source file
+ 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,
+ the program will also be linked into an executable.</para>
+
+ <para>The main advantages to using <literal>ghc
+ ––make</literal> over traditional
+ <literal>Makefile</literal>s are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>GHC doesn't have to be restarted for each compilation,
+ which means it can cache information between compilations.
+ Compiling a muli-module program with <literal>ghc
+ ––make</literal> can be up to twice as fast as
+ running <literal>ghc</literal> individually on each source
+ file.</para>
+ </listitem>
+ <listitem>
+ <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>
+ <para>GHC re-calculates the dependencies each time it is
+ invoked, so the dependencies never get out of sync with the
+ source.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Any of the command-line options described in the rest of
+ this chapter can be used with
+ <option>––make</option>, but note that any options
+ 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>
+
+ <para>If the program needs to be linked with additional objects
+ (say, some auxilliary C code), then the object files can be
+ given on the command line and GHC will include them when linking
+ the executable.</para>
+
+ <para>Note that GHC can only follow dependencies if it has the
+ source file available, so if your program includes a module for
+ which there is no source file, even if you have an object and an
+ interface file for the module, then GHC will complain. The
+ exception to this rule is for package modules, which may or may
+ not have source files.</para>
+
+ <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>
+ </sect2>
+
+ <sect2 id="eval-mode">
+ <title>Expression evaluation mode</title>
+
+ <para>This mode is very similar to interactive mode, except that
+ there is a single expression to evaluate which is specified on
+ the command line as an argument to the <option>-e</option>
+ option:</para>
+
+<screen>
+ghc -e <replaceable>expr</replaceable>
+</screen>
+
+ <para>Haskell source files may be named on the command line, and
+ they will be loaded exactly as in interactive mode. The
+ expression is evaluated in the context of the loaded
+ modules.</para>
+
+ <para>For example, to load and run a Haskell program containing
+ a module <literal>Main</literal>, we might say</para>
+
+<screen>
+ghc -e Main.main Main.hs
+</screen>
+
+ <para>or we can just use this mode to evaluate expressions in
+ the context of the <literal>Prelude</literal>:</para>
+
+<screen>
+$ ghc -e "interact (unlines.map reverse.lines)"
+hello
+olleh
+</screen>
+ </sect2>
+
+ <sect2 id="options-order">
+ <title>Batch compiler mode</title>
+
+ <para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files
+ given on the command line.</para>
+
+ <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.
+ This table summarises:</para>
+
+ <informaltable>
+ <tgroup cols="4">
+ <colspec align="left"/>
+ <colspec align="left"/>
+ <colspec align="left"/>
+ <colspec align="left"/>
+
+ <thead>
+ <row>
+ <entry>Phase of the compilation system</entry>
+ <entry>Suffix saying “start here”</entry>
+ <entry>Flag saying “stop after”</entry>
+ <entry>(suffix of) output file</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>literate pre-processor</entry>
+ <entry><literal>.lhs</literal></entry>
+ <entry>-</entry>
+ <entry><literal>.hs</literal></entry>
+ </row>
+
+ <row>
+ <entry>C pre-processor (opt.) </entry>
+ <entry><literal>.hs</literal> (with
+ <option>-cpp</option>)</entry>
+ <entry><option>-E</option></entry>
+ <entry><literal>.hspp</literal></entry>
+ </row>
+
+ <row>
+ <entry>Haskell compiler</entry>
+ <entry><literal>.hs</literal></entry>
+ <entry><option>-C</option>, <option>-S</option></entry>
+ <entry><literal>.hc</literal>, <literal>.s</literal></entry>
+ </row>
+
+ <row>
+ <entry>C compiler (opt.)</entry>
+ <entry><literal>.hc</literal> or <literal>.c</literal></entry>
+ <entry><option>-S</option></entry>
+ <entry><literal>.s</literal></entry>
+ </row>
+
+ <row>
+ <entry>assembler</entry>
+ <entry><literal>.s</literal></entry>
+ <entry><option>-c</option></entry>
+ <entry><literal>.o</literal></entry>
+ </row>
+
+ <row>
+ <entry>linker</entry>
+ <entry><replaceable>other</replaceable></entry>
+ <entry>-</entry>
+ <entry><filename>a.out</filename></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <indexterm><primary><option>-C</option></primary></indexterm>
+ <indexterm><primary><option>-E</option></primary></indexterm>
+ <indexterm><primary><option>-S</option></primary></indexterm>
+ <indexterm><primary><option>-c</option></primary></indexterm>
+
+ <para>Thus, a common invocation would be: </para>
+
+<screen>
+ghc -c Foo.hs</screen>
+
+ <para>to compile the Haskell source file
+ <filename>Foo.hs</filename> to an object file
+ <filename>Foo.o</filename>.</para>
+
+ <para>Note: What the Haskell compiler proper produces depends on
+ 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>
+
+ <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
+ details.</para>
+
+ <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>
+ </sect2>
+ </sect1>
+
+ <sect1 id="options-help">
+ <title>Help and verbosity options</title>
+
+ <indexterm><primary>help options</primary></indexterm>
+ <indexterm><primary>verbosity options</primary></indexterm>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>––help</option>
+ <indexterm><primary><option>––help</option></primary></indexterm>
+ </term>
+ <term>
+ <option>-?</option>
+ <indexterm><primary><option>-?</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>
+ <option>-v</option>
+ <indexterm><primary><option>-v</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>The <option>-v</option> option makes GHC
+ <emphasis>verbose</emphasis>: it reports its version number
+ and shows (on stderr) exactly how it invokes each phase of
+ the compilation system. Moreover, it passes the
+ <option>-v</option> flag to most phases; each reports its
+ version number (and possibly some other information).</para>
+
+ <para>Please, oh please, use the <option>-v</option> option
+ when reporting bugs! Knowing that you ran the right bits in
+ the right order is always the first thing we want to
+ verify.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-v</option><replaceable>n</replaceable>
+ <indexterm><primary><option>-v</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>To provide more control over the compiler's verbosity,
+ the <option>-v</option> flag takes an optional numeric
+ argument. Specifying <option>-v</option> on its own is
+ equivalent to <option>-v3</option>, and the other levels
+ have the following meanings:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-v0</option></term>
+ <listitem>
+ <para>Disable all non-essential messages (this is the
+ default).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-v1</option></term>
+ <listitem>
+ <para>Minimal verbosity: print one line per
+ compilation (this is the default when
+ <option>––make</option> or
+ <option>––interactive</option> is on).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-v2</option></term>
+ <listitem>
+ <para>Print the name of each compilation phase as it
+ is executed. (equivalent to
+ <option>-dshow-passes</option>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-v3</option></term>
+ <listitem>
+ <para>The same as <option>-v2</option>, except that in
+ addition the full command line (if appropriate) for
+ each compilation phase is also printed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-v4</option></term>
+ <listitem>
+ <para>The same as <option>-v3</option> except that the
+ intermediate program representation after each
+ compilation phase is also printed (excluding
+ preprocessed and C/assembly files).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </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>
+
+ </variablelist>
+ </sect1>
+
+ &separate;
+
+ <sect1 id="options-sanity">
+ <title>Warnings and sanity-checking</title>
+
+ <indexterm><primary>sanity-checking options</primary></indexterm>
+ <indexterm><primary>warnings</primary></indexterm>
+
+
+ <para>GHC has a number of options that select which types of
+ non-fatal error messages, otherwise known as warnings, can be
+ generated during compilation. By default, you get a standard set
+ of warnings which are generally likely to indicate bugs in your
+ program. These are:
+ <option>-fwarn-overlapping-patterns</option>,
+ <option>-fwarn-deprecations</option>,
+ <option>-fwarn-duplicate-exports</option>,
+ <option>-fwarn-missing-fields</option>, and
+ <option>-fwarn-missing-methods</option>. The following flags are
+ simple ways to select standard “packages” of warnings:
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-W</option>:</term>
+ <listitem>
+ <indexterm><primary>-W option</primary></indexterm>
+ <para>Provides the standard warnings plus
+ <option>-fwarn-incomplete-patterns</option>,
+ <option>-fwarn-unused-matches</option>,
+ <option>-fwarn-unused-imports</option>,
+ <option>-fwarn-misc</option>, and
+ <option>-fwarn-unused-binds</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-w</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-w</option></primary></indexterm>
+ <para>Turns off all warnings, including the standard ones.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Wall</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-Wall</option></primary></indexterm>
+ <para>Turns on all warning options.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Werror</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-Werror</option></primary></indexterm>
+ <para>Makes any warning into a fatal error. Useful so that you don't
+ miss warnings when doing batch compilation. </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>The full set of warning options is described below. To turn
+ off any warning, simply give the corresponding
+ <option>-fno-warn-...</option> option on the command line.</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-fwarn-deprecations</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-deprecations</option></primary>
+ </indexterm>
+ <indexterm><primary>deprecations</primary></indexterm>
+ <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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-duplicate-exports</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
+ <indexterm><primary>duplicate exports, warning</primary></indexterm>
+ <indexterm><primary>export lists, duplicates</primary></indexterm>
+
+ <para>Have the compiler warn about duplicate entries in
+ export lists. This is useful information if you maintain
+ large export lists, and want to avoid the continued export
+ of a definition after you've deleted (one) mention of it in
+ the export list.</para>
+
+ <para>This option is on by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-hi-shadowing</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
+ <indexterm><primary>shadowing</primary>
+ <secondary>interface files</secondary></indexterm>
+
+ <para>Causes the compiler to emit a warning when a module or
+ interface file in the current directory is shadowing one
+ with the same module name in a library or other
+ directory.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-incomplete-patterns</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
+ <indexterm><primary>incomplete patterns, warning</primary></indexterm>
+ <indexterm><primary>patterns, incomplete</primary></indexterm>
+
+ <para>Similarly for incomplete patterns, the function
+ <function>g</function> below will fail when applied to
+ non-empty lists, so the compiler will emit a warning about
+ this when <option>-fwarn-incomplete-patterns</option> is
+ enabled.</para>
+
+<programlisting>
+g [] = 2
+</programlisting>
+
+ <para>This option isn't enabled be 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>
+ </listitem>
+ </varlistentry>
+
+ <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>
+ <indexterm><primary>fields, missing</primary></indexterm>
+ </term>
+ <listitem>
+
+ <para>This option is on by default, and warns you whenever
+ the construction of a labelled field constructor isn't
+ complete, missing initializers for one or more fields. While
+ not an error (the missing fields are initialised with
+ bottoms), it is often an indication of a programmer error.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-missing-methods</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm>
+ <indexterm><primary>missing methods, warning</primary></indexterm>
+ <indexterm><primary>methods, missing</primary></indexterm>
+
+ <para>This option is on by default, and warns you whenever
+ an instance declaration is missing one or more methods, and
+ the corresponding class declaration has no default
+ declaration for them.</para>
+ <para>The warning is suppressed if the method name
+ begins with an underscore. Here's an example where this is useful:
+ <programlisting>
+ class C a where
+ _simpleFn :: a -> String
+ complexFn :: a -> a -> String
+ complexFn x y = ... _simpleFn ...
+ </programlisting>
+ The idea is that: (a) users of the class will only call <literal>complexFn</literal>;
+ never <literal>_simpleFn</literal>; and (b)
+ instance declarations can define either <literal>complexFn</literal> or <literal>_simpleFn</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-missing-signatures</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm>
+ <indexterm><primary>type signatures, missing</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 is off by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-name-shadowing</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm>
+ <indexterm><primary>shadowing, warning</primary></indexterm>
+
+ <para>This option causes a warning to be emitted whenever an
+ 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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-fwarn-overlapping-patterns</option>:
+ <indexterm><primary><option>-fwarn-overlapping-patterns</option></primary></indexterm>
+ <indexterm><primary>overlapping patterns, warning</primary></indexterm>
+ <indexterm><primary>patterns, overlapping</primary></indexterm>
+ </term>
+ <listitem>
+ <para>By default, the compiler will warn you if a set of
+ patterns are overlapping, i.e.,</para>
+
+<programlisting>
+f :: String -> Int
+f [] = 0
+f (_:xs) = 1
+f "2" = 2
+</programlisting>
+
+ <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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-simple-patterns</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-simple-patterns</option></primary>
+ </indexterm>
+ <para>Causes the compiler to warn about lambda-bound
+ 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,
+ 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>
+ f :: [Maybe a] -> [a]
+ 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>
+ <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-type-defaults</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-type-defaults</option></primary></indexterm>
+ <indexterm><primary>defaulting mechanism, warning</primary></indexterm>
+ <para>Have the compiler warn/inform you where in your source
+ 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
+ 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
+ usefulness of being non-silent about this.</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>
+ <indexterm><primary>unused binds, warning</primary></indexterm>
+ <indexterm><primary>binds, unused</primary></indexterm>
+ <para>Report any function definitions (and local bindings)
+ which are unused. For top-level functions, the warning is
+ only given if the binding is not exported.</para>
+ <para>A definition is regarded as "used" if (a) it is exported, or (b) it is
+ mentioned in the right hand side of another definition that is used, or (c) the
+ function it defines begins with an underscore. The last case provides a
+ way to suppress unused-binding warnings selectively. </para>
+ <para> Notice that a variable
+ is reported as unused even if it appears in the right-hand side of another
+ unused binding. </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-unused-imports</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-unused-imports</option></primary></indexterm>
+ <indexterm><primary>unused imports, warning</primary></indexterm>
+ <indexterm><primary>imports, unused</primary></indexterm>
+
+ <para>Report any modules that are explicitly imported but
+ never used. However, the form <literal>import M()</literal> is
+ never reported as an unused import, because it is a useful idiom
+ for importing instance declarations, which are anonymous in Haskell.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-unused-matches</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-unused-matches</option></primary></indexterm>
+ <indexterm><primary>unused matches, warning</primary></indexterm>
+ <indexterm><primary>matches, unused</primary></indexterm>
+
+ <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
+ warning is suppressed if the variable name begins with an underscore, thus:
+ <programlisting>
+ f _x = True
+ </programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>If you're feeling really paranoid, the
+ <option>-dcore-lint</option>
+ option<indexterm><primary><option>-dcore-lint</option></primary></indexterm>
+ is a good choice. It turns on heavyweight intra-pass
+ sanity-checking within GHC. (It checks GHC's sanity, not
+ yours.)</para>
+
+ </sect1>
+
+ &packages;
+
+ <sect1 id="options-optimise">
+ <title>Optimisation (code improvement)</title>
+
+ <indexterm><primary>optimisation</primary></indexterm>
+ <indexterm><primary>improvement, code</primary></indexterm>
+
+ <para>The <option>-O*</option> options specify convenient
+ “packages” of optimisation flags; the
+ <option>-f*</option> options described later on specify
+ <emphasis>individual</emphasis> optimisations to be turned on/off;
+ the <option>-m*</option> options specify
+ <emphasis>machine-specific</emphasis> optimisations to be turned
+ on/off.</para>
+
+ <sect2 id="optimise-pkgs">
+ <title><option>-O*</option>: convenient “packages” of optimisation flags.</title>
+
+ <para>There are <emphasis>many</emphasis> options that affect
+ the quality of code produced by GHC. Most people only have a
+ general goal, something like “Compile quickly” or
+ “Make my program run like greased lightning.” The
+ following “packages” of optimisations (or lack
+ thereof) should suffice.</para>
+
+ <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
+ no-optimisation when developing code.</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>No <option>-O*</option>-type option specified:</term>
+ <indexterm><primary>-O* not specified</primary></indexterm>
+ <listitem>
+ <para>This is taken to mean: “Please compile
+ quickly; I'm not over-bothered about compiled-code
+ quality.” So, for example: <command>ghc -c
+ Foo.hs</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-O0</option>:</term>
+ <indexterm><primary><option>-O0</option></primary></indexterm>
+ <listitem>
+ <para>Means “turn off all optimisation”,
+ reverting to the same settings as if no
+ <option>-O</option> options had been specified. Saying
+ <option>-O0</option> can be useful if
+ eg. <command>make</command> has inserted a
+ <option>-O</option> on the command line already.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-O</option> or <option>-O1</option>:</term>
+ <indexterm><primary>-O option</primary></indexterm>
+ <indexterm><primary>-O1 option</primary></indexterm>
+ <indexterm><primary>optimise</primary><secondary>normally</secondary></indexterm>
+ <listitem>
+ <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>
+
+ <varlistentry>
+ <term><option>-O2</option>:</term>
+ <indexterm><primary>-O2 option</primary></indexterm>
+ <indexterm><primary>optimise</primary><secondary>aggressively</secondary></indexterm>
+ <listitem>
+ <para>Means: “Apply every non-dangerous
+ optimisation, even if it means significantly longer
+ compile times.”</para>
+
+ <para>The avoided “dangerous” optimisations
+ are those that can make runtime or space
+ <emphasis>worse</emphasis> if you're unlucky. They are
+ normally turned on or off individually.</para>
+
+ <para>At the moment, <option>-O2</option> is
+ <emphasis>unlikely</emphasis> to produce better code than
+ <option>-O</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-Ofile <file></option>:</term>
+ <indexterm><primary>-Ofile <file> option</primary></indexterm>
+ <indexterm><primary>optimising, customised</primary></indexterm>
+ <listitem>
+ <para>(NOTE: not supported since GHC 4.x. Please ask if
+ you're interested in this.)</para>
+
+ <para>For those who need <emphasis>absolute</emphasis>
+ control over <emphasis>exactly</emphasis> what options are
+ used (e.g., compiler writers, sometimes :-), a list of
+ options can be put in a file and then slurped in with
+ <option>-Ofile</option>.</para>
+
+ <para>In that file, comments are of the
+ <literal>#</literal>-to-end-of-line variety; blank
+ lines and most whitespace is ignored.</para>
+
+ <para>Please ask if you are baffled and would like an
+ example of <option>-Ofile</option>!</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>We don't use a <option>-O*</option> flag for day-to-day
+ work. We use <option>-O</option> to get respectable speed;
+ e.g., when we want to measure something. When we want to go for
+ broke, we tend to use <option>-O2 -fvia-C</option> (and we go for
+ lots of coffee breaks).</para>
+
+ <para>The easiest way to see what <option>-O</option> (etc.)
+ “really mean” is to run with <option>-v</option>,
+ then stand back in amazement.</para>
+ </sect2>
+
+ <sect2 id="options-f">
+ <title><option>-f*</option>: platform-independent flags</title>
+
+ <indexterm><primary>-f* options (GHC)</primary></indexterm>
+ <indexterm><primary>-fno-* options (GHC)</primary></indexterm>
+
+ <para>These flags turn on and off individual optimisations.
+ They are normally set via the <option>-O</option> options
+ described above, and as such, you shouldn't need to set any of
+ them explicitly (indeed, doing so could lead to unexpected
+ results). However, there are one or two that may be of
+ interest:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-fexcess-precision</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fexcess-precision</option></primary></indexterm>
+ <para>When this option is given, intermediate floating
+ point values can have a <emphasis>greater</emphasis>
+ precision/range than the final type. Generally this is a
+ good thing, but some programs may rely on the exact
+ precision/range of
+ <literal>Float</literal>/<literal>Double</literal> values
+ and should not use this option for their compilation.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fignore-asserts</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fignore-asserts</option></primary></indexterm>
+ <para>Causes GHC to ignore uses of the function
+ <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
+ <option>-O</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fno-strictness</option></term>
+ <indexterm><primary><option>-fno-strictness</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Turns off the strictness analyser; sometimes it eats
+ too many cycles.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fno-cpr-analyse</option></term>
+ <indexterm><primary><option>-fno-cpr-analyse</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Turns off the CPR (constructed product result)
+ analysis; it is somewhat experimental.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-funbox-strict-fields</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
+ <indexterm><primary>strict constructor fields</primary></indexterm>
+ <indexterm><primary>constructor fields, strict</primary></indexterm>
+
+ <para>This option causes all constructor fields which are
+ marked strict (i.e. “!”) to be unboxed or
+ unpacked if possible. It is equivalent to adding an
+ <literal>UNPACK</literal> pragma to every strict
+ constructor field (see <xref
+ linkend="unpack-pragma"/>).</para>
+
+ <para>This option is a bit of a sledgehammer: it might
+ sometimes make things worse. Selectively unboxing fields
+ by using <literal>UNPACK</literal> pragmas might be
+ better.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-funfolding-update-in-place<n></option></term>
+ <indexterm><primary><option>-funfolding-update-in-place</option></primary></indexterm>
+ <listitem>
+ <para>Switches on an experimental "optimisation".
+ 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>
+ x = plusInt a b
+</programlisting>
+ If we inlined plusInt we might get an opportunity to use
+ update-in-place for the thunk 'x'.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-funfolding-creation-threshold<n></option>:</term>
+ <listitem>
+ <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
+ <indexterm><primary>inlining, controlling</primary></indexterm>
+ <indexterm><primary>unfolding, controlling</primary></indexterm>
+
+ <para>(Default: 45) Governs the maximum size that GHC will
+ allow a function unfolding to be. (An unfolding has a
+ “size” that reflects the cost in terms of
+ “code bloat” of expanding that unfolding at
+ at a call site. A bigger function would be assigned a
+ bigger cost.) </para>
+
+ <para> Consequences: (a) nothing larger than this will be
+ inlined (unless it has an INLINE pragma); (b) nothing
+ larger than this will be spewed into an interface
+ file. </para>
+
+
+ <para> Increasing this figure is more likely to result in longer
+ compile times than faster code. The next option is more
+ useful:</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-funfolding-use-threshold<n></option>:</term>
+ <listitem>
+ <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
+ <indexterm><primary>inlining, controlling</primary></indexterm>
+ <indexterm><primary>unfolding, controlling</primary></indexterm>
+
+ <para>(Default: 8) This is the magic cut-off figure for
+ unfolding: below this size, a function definition will be
+ unfolded at the call-site, any bigger and it won't. The
+ size computed for a function depends on two things: the
+ actual size of the expression minus any discounts that
+ apply (see <option>-funfolding-con-discount</option>).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ </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>
+
+<para>
+RTS options are provided for modifying the behaviour of the threaded
+runtime system. See <xref linkend="parallel-rts-opts"/>.
+</para>
+
+<para>
+Concurrent Haskell is described in more detail in the documentation
+for the <literal>Control.Concurrent</literal> module.
+</para>
+
+</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
+(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>
+
+<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 (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,
+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>
+
+</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 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>
+</para>
+
+<para>
+Besides the usual runtime system (RTS) options
+(<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;
+the default is 2.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><option>-C[<us>]</option>:</term>
+<listitem>
+<para>
+<indexterm><primary>-C<us> 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
+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 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>
+<!-- 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>
+
+</sect1>
+
+ <sect1 id="options-platform">
+ <title>Platform-specific Flags</title>
+
+ <indexterm><primary>-m* options</primary></indexterm>
+ <indexterm><primary>platform-specific options</primary></indexterm>
+ <indexterm><primary>machine-specific options</primary></indexterm>
+
+ <para>Some flags only make sense for particular target
+ platforms.</para>
+
+ <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
+ similiar <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
+ option (iX86 only)</primary></indexterm> GHC tries to
+ “steal” four registers from GCC, for performance
+ reasons; it almost always works. However, when GCC is
+ compiling some modules with four stolen registers, it will
+ crash, probably saying:
+
+<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>
+
+ Just give some registers back with
+ <option>-monly-N-regs</option>. Try `3' first, then `2'.
+ If `2' doesn't work, please report the bug to us.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect1>
+
+&runtime;
+
+<sect1 id="ext-core">
+ <title>Generating and compiling External Core Files</title>
+
+ <indexterm><primary>intermediate code generation</primary></indexterm>
+
+ <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">
+ <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>
+
+ <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>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-fext-core</option></term>
+ <indexterm>
+ <primary><option>-fext-core</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Generate <literal>.hcr</literal> files.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+<para>GHC can also read in External Core files as source; just give the <literal>.hcr</literal> file on
+the command line, instead of the <literal>.hs</literal> or <literal>.lhs</literal> Haskell source.
+A current infelicity is that you need to give teh <literal>-fglasgow-exts</literal> flag too, because
+ordinary Haskell 98, when translated to External Core, uses things like rank-2 types.</para>
+</sect1>
+
+&debug;
+&flags;
+
+</chapter>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: xml ***
+ ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff