<indexterm><primary>GHC, using</primary></indexterm>
<indexterm><primary>using GHC</primary></indexterm>
- <para>GHC can work in one of three “modes”:</para>
-
- <variablelist>
- <varlistentry>
- <term><cmdsynopsis><command>ghc</command>
- <arg choice=plain>––interactive</arg>
- </cmdsynopsis></term>
- <indexterm><primary>interactive mode</primary>
- </indexterm>
- <indexterm><primary>ghci</primary>
- </indexterm>
- <listitem>
- <para>Interactive mode, which is also available as
- <command>ghci</command>. Interactive mode is described in
- more detail in <xref linkend="ghci">.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><cmdsynopsis><command>ghc</command>
- <arg choice=plain>––make</arg>
- </cmdsynopsis></term>
- <indexterm><primary>make mode</primary>
- </indexterm>
- <indexterm><primary><option>––make</option></primary>
- </indexterm>
- <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>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><cmdsynopsis>
- <command>ghc</command>
- <group>
- <arg>-E</arg>
- <arg>-C</arg>
- <arg>-S</arg>
- <arg>-c</arg>
- </group>
- </cmdsynopsis></term>
- <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>
- <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.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
<sect1>
<title>Options overview</title>
Options can be specified in three ways:</para>
<sect2>
- <title>Command-line arguments</title>
+ <title>command-line arguments</title>
<indexterm><primary>structure, command-line</primary></indexterm>
<indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm>
<para>An invocation of GHC takes the following form:</para>
-<Screen>
+<screen>
ghc [argument...]
-</Screen>
+</screen>
- <para>Command-line arguments are either options or file names.</para>
+ <para>command-line arguments are either options or file names.</para>
- <para>Command-line options begin with <literal>-</literal>.
+ <para>command-line options begin with <literal>-</literal>.
They may <emphasis>not</emphasis> be grouped:
<option>-vO</option> is different from <option>-v -O</option>.
Options need not precede filenames: e.g., <literal>ghc *.o -o
<filename>Bar.hs</filename>.</para>
</sect2>
- <Sect2 id="source-file-options">
- <title>Command line options in source files</title>
+ <sect2 id="source-file-options">
+ <title>command line options in source files</title>
<indexterm><primary>source-file options</primary></indexterm>
<literal>OPTIONS</literal> pragma <indexterm><primary>OPTIONS
pragma</primary></indexterm>:</para>
-<ProgramListing>
+<programlisting>
{-# OPTIONS -fglasgow-exts #-}
module X where
...
-</ProgramListing>
+</programlisting>
<para><literal>OPTIONS</literal> pragmas are only looked for at
the top of your source files, upto the first
<title>Setting options in GHCi</title>
<para>Options may also be modified from within GHCi, using the
- <literal>:set</literal> command. See <xref linkend="ghci-set">
+ <literal>:set</literal> command. See <xref linkend="ghci-set"/>
for more details.</para>
</sect2>
</sect1>
pragma in a source file or set from the GHCi command-line with
<literal>:set</literal>.</para>
- <para>As a rule of thumb, all the language options are dynamic, as
- are the warning options and the debugging options. The rest are
- static, with the notable exceptions of <option>-v</option>,
- <option>-cpp</option>, <option>-fasm</option>,
- <option>-fvia-C</option>, and <option>-#include</option>.
-
- The flag reference tables (<xref linkend="flag-reference">) lists
- the status of each flag.</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">
</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></term>
+ <indexterm><primary>interactive mode</primary>
+ </indexterm>
+ <indexterm><primary>ghci</primary>
+ </indexterm>
+ <listitem>
+ <para>Interactive mode, which is also available as
+ <command>ghci</command>. Interactive mode is described in
+ more detail in <xref linkend="ghci"/>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><cmdsynopsis><command>ghc</command>
+ <arg choice='plain'>––make</arg>
+ </cmdsynopsis></term>
+ <indexterm><primary>make mode</primary>
+ </indexterm>
+ <indexterm><primary><option>––make</option></primary>
+ </indexterm>
+ <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></term>
+ <indexterm><primary>eval mode</primary>
+ </indexterm>
+ <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></term>
+ <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>
+ <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></term>
+ <indexterm><primary>dependency-generation mode</primary>
+ </indexterm>
+ <listitem>
+ <para>Dependency-generation mode. In this mode, GHC can be
+ used to generate dependency information suitable for use in
+ a <literal>Makefile</literal>. See <xref
+ linkend="sec-makefile-dependencies"/>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><cmdsynopsis><command>ghc</command>
+ <arg choice='plain'>––mk-dll</arg></cmdsynopsis></term>
+ <indexterm><primary>dependency-generation mode</primary>
+ </indexterm>
+ <listitem>
+ <para>DLL-creation mode (Windows only). See <xref
+ linkend="win32-dlls-create"/>.</para>
+ </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>
+ </listitem>
+ <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary>
+ </indexterm>
+ <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>
+ <indexterm><primary>help options</primary></indexterm>
+ <indexterm><primary>verbosity options</primary></indexterm>
<variablelist>
<varlistentry>
</varlistentry>
<varlistentry>
+ <term><option>-V</option></term>
<term><option>––version</option></term>
+ <indexterm><primary><option>-V</option></primary></indexterm>
<indexterm><primary><option>––version</option></primary></indexterm>
<listitem>
<para>Print a one-line string including GHC's version number.</para>
is the value of
<literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
</indexterm>in the package configuration file (see <xref
- linkend="packages">).</para>
+ linkend="packages"/>).</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
- <sect1 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 must contain one source file or module
- name; GHC will figure out all the modules in the program by
- following the imports from this initial module. It will then
- attempt to compile each module which is out of date, and finally
- if the top module is <literal>Main</literal>, 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>
- </listitem>
- <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary>
- </indexterm>
- <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), these can be specified on the
- command line as usual.</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="options-finding-imports">).</para>
-
- </sect1>
-
- <Sect1 id="options-order">
- <title>GHC without <option>––make</option></title>
-
- <para>Without <option>––make</option>, 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: <literal>ghc -c
- Foo.hs</literal></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>-ccp</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>
- </sect1>
-
- <sect1 id="options-output">
- <title>Re-directing the compilation output(s)</title>
-
- <indexterm><primary>output-directing options</primary></indexterm>
- <indexterm><primary>redirecting compilation output</primary></indexterm>
-
-
- <variablelist>
- <varlistentry>
- <term><option>-o</option></term>
- <indexterm><primary><option>-o</option></primary></indexterm>
- <listitem>
- <para>GHC's compiled output normally goes into a
- <filename>.hc</filename>, <filename>.o</filename>, etc.,
- file, depending on the last-run compilation phase. The
- option <option>-o foo</option><IndexTerm><Primary>-o
- option</Primary></IndexTerm> re-directs the output of that
- last-run phase to file <filename>foo</filename>.</para>
-
- <para>Note: this “feature” can be
- counterintuitive: <command>ghc -C -o foo.o foo.hs</command>
- will put the intermediate C code in the file
- <filename>foo.o</filename>, name notwithstanding!</para>
-
- <para>Note: on Windows, if the result is an executable file, the
- extension "<filename>.exe</filename>" is added if the specified filename
- does not already have an extension. Thus
- <programlisting>
- ghc -o foo Main.hs
- </programlisting>
- will compile and link the module <filename>Main.hs</filename>, and put the
- resulting executable in <filename>foo.exe</filename> (not <filename>foo</filename>).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-odir</option></term>
- <indexterm><primary><option>-odir</option></primary></indexterm>
- <listitem>
- <para>The <option>-o</option> option isn't of much use if
- you have <emphasis>several</emphasis> input files…
- Non-interface output files are normally put in the same
- directory as their corresponding input file came from. You
- may specify that they be put in another directory using the
- <option>-odir <dir></option><IndexTerm><Primary>-odir
- <dir> option</Primary></IndexTerm> (the “Oh,
- dear” option). For example:</para>
-
-<Screen>
-% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
-</Screen>
-
- <para>The output files, <filename>Foo.o</filename>,
- <filename>Bar.o</filename>, and
- <filename>Bumble.o</filename> would be put into a
- subdirectory named after the architecture of the executing
- machine (<filename>sun4</filename>,
- <filename>mips</filename>, etc). The directory must already
- exist; it won't be created.</para>
-
- <para>Note that the <option>-odir</option> option does
- <emphasis>not</emphasis> affect where the interface files
- are put. In the above example, they would still be put in
- <filename>parse/Foo.hi</filename>,
- <filename>parse/Bar.hi</filename>, and
- <filename>gurgle/Bumble.hi</filename>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-ohi</option> <replaceable>file</replaceable></term>
- <indexterm><primary><option>-ohi</option></primary>
- </indexterm>
- <listitem>
- <para>The interface output may be directed to another file
- <filename>bar2/Wurble.iface</filename> with the option
- <option>-ohi bar2/Wurble.iface</option> (not
- recommended).</para>
-
- <para>WARNING: if you redirect the interface file somewhere
- that GHC can't find it, then the recompilation checker may
- get confused (at the least, you won't get any recompilation
- avoidance). We recommend using a combination of
- <option>-hidir</option> and <option>-hisuf</option> options
- instead, if possible.</para>
-
- <para>To avoid generating an interface at all, you could use
- this option to redirect the interface into the bit bucket:
- <literal>-ohi /dev/null</literal>, for example.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-hidir</option> <replaceable>directory</replaceable></term>
- <indexterm><primary><option>-hidir</option></primary>
- </indexterm>
- <listitem>
- <para>Redirects all generated interface files into
- <replaceable>directory</replaceable>, instead of the default
- which is to place the interface file in the same directory
- as the source file.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-osuf</option> <replaceable>suffix</replaceable></term>
- <term><option>-hisuf</option> <replaceable>suffix</replaceable></term>
- <term><option>-hcsuf</option> <replaceable>suffix</replaceable></term>
- <indexterm><primary><option>-osuf</option></primary></indexterm>
- <indexterm><primary><option>-hisuf</option></primary></indexterm>
- <indexterm><primary><option>-hcsuf</option></primary></indexterm>
- <listitem>
- <para>EXOTICA: The <option>-osuf</option>
- <replaceable>suffix</replaceable> will change the
- <literal>.o</literal> file suffix for object files to
- whatever you specify. We use this when compiling libraries,
- so that objects for the profiling versions of the libraries
- don't clobber the normal ones.</para>
-
- <para>Similarly, the <option>-hisuf</option>
- <replaceable>suffix</replaceable> will change the
- <literal>.hi</literal> file suffix for non-system interface
- files (see <XRef LinkEnd="hi-options">).</para>
-
- <para>Finally, the option <option>-hcsuf</option>
- <replaceable>suffix</replaceable> will change the
- <literal>.hc</literal> file suffix for compiler-generated
- intermediate C files.</para>
-
- <para>The <option>-hisuf</option>/<option>-osuf</option>
- game is particularly useful if you want to compile a program both with and without
- profiling, in the same directory. You can say:
- <Screen>
- ghc ...
- </Screen>
- to get the ordinary version, and
- <Screen>
- ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all
- </Screen>
- to get the profiled version.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <sect2 id="keeping-intermediates">
- <title>Keeping Intermediate Files</title>
- <indexterm><primary>intermediate files, saving</primary>
- </indexterm>
- <indexterm><primary><literal>.hc</literal> files, saving</primary>
- </indexterm>
- <indexterm><primary><literal>.s</literal> files, saving</primary>
- </indexterm>
-
-
- <para>The following options are useful for keeping certain
- intermediate files around, when normally GHC would throw these
- away after compilation:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-keep-hc-files</option></term>
- <indexterm>
- <primary><option>-keep-hc-files</option></primary>
- </indexterm>
- <listitem>
- <para>Keep intermediate <literal>.hc</literal> files when
- doing <literal>.hs</literal>-to-<literal>.o</literal>
- compilations via C (NOTE: <literal>.hc</literal> files
- aren't generated when using the native code generator, you
- may need to use <option>-fvia-C</option> to force them
- to be produced).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-keep-s-files</option></term>
- <indexterm>
- <primary><option>-keep-s-files</option></primary>
- </indexterm>
- <listitem>
- <para>Keep intermediate <literal>.s</literal> files.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-keep-raw-s-files</option></term>
- <indexterm>
- <primary><option>-keep-raw-s-files</option></primary>
- </indexterm>
- <listitem>
- <para>Keep intermediate <literal>.raw-s</literal> files.
- These are the direct output from the C compiler, before
- GHC does “assembly mangling” to produce the
- <literal>.s</literal> file. Again, these are not produced
- when using the native code generator.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-keep-tmp-files</option></term>
- <indexterm>
- <primary><option>-keep-tmp-files</option></primary>
- </indexterm>
- <indexterm>
- <primary>temporary files</primary>
- <secondary>keeping</secondary>
- </indexterm>
- <listitem>
- <para>Instructs the GHC driver not to delete any of its
- temporary files, which it normally keeps in
- <literal>/tmp</literal> (or possibly elsewhere; see <xref
- linkend="temp-files">). Running GHC with
- <option>-v</option> will show you what temporary files
- were generated along the way.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="temp-files">
- <title>Redirecting temporary files</title>
-
- <indexterm>
- <primary>temporary files</primary>
- <secondary>redirecting</secondary>
- </indexterm>
-
- <variablelist>
- <varlistentry>
- <term><option>-tmpdir</option></term>
- <indexterm><primary><option>-tmpdir</option></primary></indexterm>
- <listitem>
- <para>If you have trouble because of running out of space
- in <filename>/tmp</filename> (or wherever your
- installation thinks temporary files should go), you may
- use the <option>-tmpdir
- <dir></option><IndexTerm><Primary>-tmpdir
- <dir> option</Primary></IndexTerm> option to specify
- an alternate directory. For example, <option>-tmpdir
- .</option> says to put temporary files in the current
- working directory.</para>
-
- <para>Alternatively, use your <Constant>TMPDIR</Constant>
- environment variable.<IndexTerm><Primary>TMPDIR
- environment variable</Primary></IndexTerm> Set it to the
- name of the directory where temporary files should be put.
- GCC and other programs will honour the
- <Constant>TMPDIR</Constant> variable as well.</para>
-
- <para>Even better idea: Set the
- <Constant>DEFAULT_TMPDIR</Constant> make variable when
- building GHC, and never worry about
- <Constant>TMPDIR</Constant> again. (see the build
- documentation).</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- </sect1>
+ &separate;
<sect1 id="options-sanity">
<title>Warnings and sanity-checking</title>
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-overlpapping-patterns</option>,
+ <option>-fwarn-overlapping-patterns</option>,
<option>-fwarn-deprecations</option>,
<option>-fwarn-duplicate-exports</option>,
<option>-fwarn-missing-fields</option>, and
simple ways to select standard “packages” of warnings:
</para>
- <VariableList>
+ <variablelist>
<varlistentry>
<term><option>-W</option>:</term>
<listitem>
- <IndexTerm><Primary>-W option</Primary></IndexTerm>
+ <indexterm><primary>-W option</primary></indexterm>
<para>Provides the standard warnings plus
<option>-fwarn-incomplete-patterns</option>,
<option>-fwarn-unused-matches</option>,
<varlistentry>
<term><option>-w</option>:</term>
<listitem>
- <IndexTerm><Primary><option>-w</option></Primary></IndexTerm>
+ <indexterm><primary><option>-w</option></primary></indexterm>
<para>Turns off all warnings, including the standard ones.</para>
</listitem>
</varlistentry>
<para>Causes a warning to be emitted when a deprecated
function or type is used. Entities can be marked as
deprecated using a pragma, see <xref
- linkend="deprecated-pragma">.</para>
+ linkend="deprecated-pragma"/>.</para>
</listitem>
</varlistentry>
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>
f "2" = 2
</programlisting>
- <para>where the last pattern match in <Function>f</Function>
+ <para>where the last pattern match in <function>f</function>
won't ever be reached, as the second pattern overlaps
it. More often than not, redundant patterns is a programmer
mistake/error, so this option is enabled by default.</para>
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>
in. This is useful information when converting code from a
context that assumed one default into one with another,
e.g., the `default default' for Haskell 1.4 caused the
- otherwise unconstrained value <Constant>1</Constant> to be
+ otherwise unconstrained value <constant>1</constant> to be
given the type <literal>Int</literal>, whereas Haskell 98
defaults it to <literal>Integer</literal>. This may lead to
differences in performance and behaviour, hence the
<para>Report 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>
<indexterm><primary>unused imports, warning</primary></indexterm>
<indexterm><primary>imports, unused</primary></indexterm>
- <para>Report any objects that are explicitly imported but
- never used.</para>
+ <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>
<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. To
- eliminate the warning, all unused variables can be replaced
- with wildcards.</para>
+ <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>
+ </variablelist>
<para>If you're feeling really paranoid, the
<option>-dcore-lint</option>
</sect1>
- &separate;
&packages;
<sect1 id="options-optimise">
following “packages” of optimisations (or lack
thereof) should suffice.</para>
- <para>Once you choose a <option>-O*</option>
- “package,” stick with it—don't chop and
- change. Modules' interfaces <emphasis>will</emphasis> change
- with a shift to a new <option>-O*</option> option, and you may
- have to recompile a large chunk of all importing modules before
- your program can again be run safely (see <XRef
- LinkEnd="recomp">).</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>
<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>
<indexterm><primary>-Ofile <file> option</primary></indexterm>
<indexterm><primary>optimising, customised</primary></indexterm>
<listitem>
- <para>(NOTE: not supported yet in GHC 5.x. Please ask if
+ <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>
<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>-O -fvia-C</option> (and we 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.)
<literal>Exception.assert</literal> in source code (in
other words, rewriting <literal>Exception.assert p
e</literal> to <literal>e</literal> (see <xref
- linkend="sec-assertions">). This flag is turned on by
+ linkend="sec-assertions"/>). This flag is turned on by
<option>-O</option>.
</para>
</listitem>
<para>This option causes all constructor fields which are
marked strict (i.e. “!”) to be unboxed or
- unpacked if possible. For example:</para>
-
-<ProgramListing>
-data T = T !Float !Float
-</ProgramListing>
-
- <para>will create a constructor <literal>T</literal>
- containing two unboxed floats if the
- <option>-funbox-strict-fields</option> flag is given.
- This may not always be an optimisation: if the
- <Function>T</Function> constructor is scrutinised and the
- floats passed to a non-strict function for example, they
- will have to be reboxed (this is done automatically by the
- compiler).</para>
-
- <para>This option should only be used in conjunction with
- <option>-O</option>, in order to expose unfoldings to the
- compiler so the reboxing can be removed as often as
- possible. For example:</para>
-
-<ProgramListing>
-f :: T -> Float
-f (T f1 f2) = f1 + f2
-</ProgramListing>
-
- <para>The compiler will avoid reboxing
- <Function>f1</Function> and <Function>f2</Function> by
- inlining <Function>+</Function> on floats, but only when
- <option>-O</option> is on.</para>
-
- <para>Any single-constructor data is eligible for
- unpacking; for example</para>
-
-<ProgramListing>
-data T = T !(Int,Int)
-</ProgramListing>
-
- <para>will store the two <literal>Int</literal>s directly
- in the <Function>T</Function> constructor, by flattening
- the pair. Multi-level unpacking is also supported:</para>
-
-<ProgramListing>
-data T = T !S
-data S = S !Int !Int
-</ProgramListing>
-
- <para>will store two unboxed <literal>Int#</literal>s
- directly in the <Function>T</Function> constructor.</para>
+ 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>
Switching it on makes the compiler a little keener to
inline a function that returns a constructor, if the
context is that of a thunk.
-<ProgramListing>
+<programlisting>
x = plusInt a b
-</ProgramListing>
+</programlisting>
If we inlined plusInt we might get an opportunity to use
update-in-place for the thunk 'x'.</para>
</listitem>
<para>
RTS options are provided for modifying the behaviour of the threaded
-runtime system. See <XRef LinkEnd="parallel-rts-opts">.
+runtime system. See <xref linkend="parallel-rts-opts"/>.
</para>
<para>
for the <literal>Control.Concurrent</literal> module.
</para>
-</Sect1>
+</sect1>
-<Sect1 id="sec-using-parallel">
-<title>Using Parallel Haskell</title>
+<sect1 id="sec-using-parallel">
+<title>Using parallel Haskell</title>
<para>
-<indexterm><primary>Parallel Haskell—use</primary></indexterm>
+<indexterm><primary>parallel Haskell—use</primary></indexterm>
</para>
<para>
[You won't be able to execute parallel Haskell programs unless PVM3
-(Parallel Virtual Machine, version 3) is installed at your site.]
-</Para>
+(parallel Virtual Machine, version 3) is installed at your site.]
+</para>
<para>
To compile a Haskell program for parallel execution under PVM, use the
-<Option>-parallel</Option> option,<IndexTerm><Primary>-parallel
-option</Primary></IndexTerm> both when compiling <Emphasis>and
-linking</Emphasis>. You will probably want to <Literal>import
-Parallel</Literal> into your Haskell modules.
-</Para>
+<option>-parallel</option> option,<indexterm><primary>-parallel
+option</primary></indexterm> both when compiling <emphasis>and
+linking</emphasis>. You will probably want to <literal>import
+parallel</literal> into your Haskell modules.
+</para>
<para>
To run your parallel program, once PVM is going, just invoke it
“as normal”. The main extra RTS option is
-<Option>-qp<n></Option>, to say how many PVM
+<option>-qp<n></option>, to say how many PVM
“processors” your program to run on. (For more details of
-all relevant RTS options, please see <XRef
-LinkEnd="parallel-rts-opts">.)
+all relevant RTS options, please see <xref
+linkend="parallel-rts-opts"/>.)
</para>
<para>
-In truth, running Parallel Haskell programs and getting information
+In truth, running parallel Haskell programs and getting information
out of them (e.g., parallelism profiles) is a battle with the vagaries of
PVM, detailed in the following sections.
</para>
-<Sect2 id="pvm-dummies">
-<Title>Dummy's guide to using PVM</Title>
+<sect2 id="pvm-dummies">
+<title>Dummy's guide to using PVM</title>
<para>
<indexterm><primary>PVM, how to use</primary></indexterm>
-<indexterm><primary>Parallel Haskell—PVM use</primary></indexterm>
+<indexterm><primary>parallel Haskell—PVM use</primary></indexterm>
Before you can run a parallel program under PVM, you must set the
required environment variables (PVM's idea, not ours); something like,
probably in your <filename>.cshrc</filename> or equivalent:
-<ProgramListing>
+<programlisting>
setenv PVM_ROOT /wherever/you/put/it
setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
setenv PVM_DPATH $PVM_ROOT/lib/pvmd
-</ProgramListing>
+</programlisting>
</para>
<para>
Creating and/or controlling your “parallel machine” is a purely-PVM
-business; nothing specific to Parallel Haskell. The following paragraphs
+business; nothing specific to parallel Haskell. The following paragraphs
describe how to configure your parallel machine interactively.
-</Para>
+</para>
-<Para>
+<para>
If you use parallel Haskell regularly on the same machine configuration it
is a good idea to maintain a file with all machine names and to make the
environment variable PVM_HOST_FILE point to this file. Then you can avoid
the interactive operations described below by just saying
-</Para>
+</para>
-<ProgramListing>
+<programlisting>
pvm $PVM_HOST_FILE
-</ProgramListing>
+</programlisting>
-<Para>
-You use the <Command>pvm</Command><IndexTerm><Primary>pvm command</Primary></IndexTerm> command to start PVM on your
+<para>
+You use the <command>pvm</command><indexterm><primary>pvm command</primary></indexterm> command to start PVM on your
machine. You can then do various things to control/monitor your
“parallel machine;” the most useful being:
</para>
<para>
-<InformalTable>
-<TGroup Cols=2>
-<ColSpec Align="Left">
-<TBody>
+<informaltable>
+<tgroup cols="2">
+<colspec align="left"/>
+<tbody>
<row>
-<entry><KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo></entry>
+<entry><keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo></entry>
<entry>exit <command>pvm</command>, leaving it running</entry>
</row>
<entry>status of a particular process</entry>
</row>
-</TBody>
-</TGroup>
-</InformalTable>
+</tbody>
+</tgroup>
+</informaltable>
</para>
<para>
</sect2>
-<Sect2 id="par-profiles">
-<Title>Parallelism profiles</Title>
+<sect2 id="par-profiles">
+<title>parallelism profiles</title>
<para>
<indexterm><primary>parallelism profiles</primary></indexterm>
</para>
<para>
-With Parallel Haskell programs, we usually don't care about the
+With parallel Haskell programs, we usually don't care about the
results—only with “how parallel” it was! We want pretty pictures.
</para>
-<Para>
-Parallelism profiles (à la <Command>hbcpp</Command>) can be generated with the
-<Option>-qP</Option><IndexTerm><Primary>-qP RTS option (concurrent, parallel)</Primary></IndexTerm> RTS option. The
+<para>
+parallelism profiles (à la <command>hbcpp</command>) can be generated with the
+<option>-qP</option><indexterm><primary>-qP RTS option (concurrent, parallel)</primary></indexterm> RTS option. The
per-processor profiling info is dumped into files named
-<Filename><full-path><program>.gr</Filename>. These are then munged into a PostScript picture,
+<filename><full-path><program>.gr</filename>. These are then munged into a PostScript picture,
which you can then display. For example, to run your program
-<Filename>a.out</Filename> on 8 processors, then view the parallelism profile, do:
-</Para>
+<filename>a.out</filename> on 8 processors, then view the parallelism profile, do:
+</para>
-<Para>
+<para>
-<Screen>
+<screen>
<prompt>$</prompt> ./a.out +RTS -qP -qp8
<prompt>$</prompt> grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one
<prompt>$</prompt> gr2ps -O temp.gr # cvt to .ps; output in temp.ps
<prompt>$</prompt> ghostview -seascape temp.ps # look at it!
-</Screen>
+</screen>
-</Para>
+</para>
<para>
The scripts for processing the parallelism profiles are distributed
</sect2>
-<Sect2>
-<Title>Other useful info about running parallel programs</Title>
+<sect2>
+<title>Other useful info about running parallel programs</title>
-<Para>
+<para>
The “garbage-collection statistics” RTS options can be useful for
seeing what parallel programs are doing. If you do either
-<Option>+RTS -Sstderr</Option><IndexTerm><Primary>-Sstderr RTS option</Primary></IndexTerm> or <Option>+RTS -sstderr</Option>, then
+<option>+RTS -Sstderr</option><indexterm><primary>-Sstderr RTS option</primary></indexterm> or <option>+RTS -sstderr</option>, then
you'll get mutator, garbage-collection, etc., times on standard
error. The standard error of all PE's other than the `main thread'
appears in <filename>/tmp/pvml.nnn</filename>, courtesy of PVM.
</sect2>
-<Sect2 id="parallel-rts-opts">
-<title>RTS options for Concurrent/Parallel Haskell
+<sect2 id="parallel-rts-opts">
+<title>RTS options for Concurrent/parallel Haskell
</title>
<para>
<indexterm><primary>RTS options, concurrent</primary></indexterm>
<indexterm><primary>RTS options, parallel</primary></indexterm>
<indexterm><primary>Concurrent Haskell—RTS options</primary></indexterm>
-<indexterm><primary>Parallel Haskell—RTS options</primary></indexterm>
+<indexterm><primary>parallel Haskell—RTS options</primary></indexterm>
</para>
<para>
Besides the usual runtime system (RTS) options
-(<XRef LinkEnd="runtime-control">), there are a few options particularly
+(<xref linkend="runtime-control"/>), there are a few options particularly
for concurrent/parallel execution.
</para>
<para>
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-qp<N></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qp<N> RTS option</Primary></IndexTerm>
-(PARALLEL ONLY) Use <Literal><N></Literal> PVM processors to run this program;
+<variablelist>
+
+<varlistentry>
+<Term><option>-qp<N></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qp<N> RTS option</primary></indexterm>
+(paraLLEL ONLY) Use <literal><N></literal> PVM processors to run this program;
the default is 2.
</para>
</listitem>
<listitem>
<para>
<indexterm><primary>-q RTS option</primary></indexterm>
-(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
-in the file <FIlename><program>.qp</FIlename>. In the style of <command>hbcpp</command>, this profile
+(paraLLEL ONLY) Produce a quasi-parallel profile of thread activity,
+in the file <filename><program>.qp</filename>. In the style of <command>hbcpp</command>, this profile
records the movement of threads between the green (runnable) and red
(blocked) queues. If you specify the verbose suboption (<option>-qv</option>), the
green queue is split into green (for the currently running thread
only) and amber (for other runnable threads). We do not recommend
that you use the verbose suboption if you are planning to use the
-<Command>hbcpp</Command> profiling tools or if you are context switching at every heap
-check (with <Option>-C</Option>).
+<command>hbcpp</command> profiling tools or if you are context switching at every heap
+check (with <option>-C</option>).
-->
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-qt<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qt<num> RTS option</Primary></IndexTerm>
-(PARALLEL ONLY) Limit the thread pool size, i.e. the number of concurrent
-threads per processor to <Literal><num></Literal>. The default is
-32. Each thread requires slightly over 1K <Emphasis>words</Emphasis> in
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<Term><option>-qt<num></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qt<num> RTS option</primary></indexterm>
+(paraLLEL ONLY) Limit the thread pool size, i.e. the number of concurrent
+threads per processor to <literal><num></literal>. The default is
+32. Each thread requires slightly over 1K <emphasis>words</emphasis> in
the heap for thread state and stack objects. (For 32-bit machines, this
translates to 4K bytes, and for 64-bit machines, 8K bytes.)
-</Para>
-</ListItem>
-</VarListEntry>
+</para>
+</listitem>
+</varlistentry>
<!-- no more -HWL
-<VarListEntry>
-<Term><Option>-d</Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-d RTS option (parallel)</Primary></IndexTerm>
-(PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
-something…) per PVM processor. We use the standard <Command>debugger</Command>
+<varlistentry>
+<Term><option>-d</option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-d RTS option (parallel)</primary></indexterm>
+(paraLLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
+something…) per PVM processor. We use the standard <command>debugger</command>
script that comes with PVM3, but we sometimes meddle with the
-<Command>debugger2</Command> script. We include ours in the GHC distribution,
-in <Filename>ghc/utils/pvm/</Filename>.
-</Para>
-</ListItem>
-</VarListEntry>
+<command>debugger2</command> script. We include ours in the GHC distribution,
+in <filename>ghc/utils/pvm/</filename>.
+</para>
+</listitem>
+</varlistentry>
-->
-<VarListEntry>
-<Term><Option>-qe<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qe<num> RTS option
-(parallel)</Primary></IndexTerm> (PARALLEL ONLY) Limit the spark pool size
+<varlistentry>
+<Term><option>-qe<num></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qe<num> RTS option
+(parallel)</primary></indexterm> (paraLLEL ONLY) Limit the spark pool size
i.e. the number of pending sparks per processor to
-<Literal><num></Literal>. The default is 100. A larger number may be
+<literal><num></literal>. The default is 100. A larger number may be
appropriate if your program generates large amounts of parallelism
initially.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-qQ<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qQ<num> RTS option (parallel)</Primary></IndexTerm>
-(PARALLEL ONLY) Set the size of packets transmitted between processors
-to <Literal><num></Literal>. The default is 1024 words. A larger number may be
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<Term><option>-qQ<num></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qQ<num> RTS option (parallel)</primary></indexterm>
+(paraLLEL ONLY) Set the size of packets transmitted between processors
+to <literal><num></literal>. The default is 1024 words. A larger number may be
appropriate if your machine has a high communication cost relative to
computation speed.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-qh<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qh<num> RTS option (parallel)</Primary></IndexTerm>
-(PARALLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<Term><option>-qh<num></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qh<num> RTS option (parallel)</primary></indexterm>
+(paraLLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to
<num>-1 (0 means infinity). By default GUM uses full-subgraph
packing, i.e. the entire subgraph with the requested closure as root is
transmitted (provided it fits into one packet). Choosing a smaller value
reduces the amount of pre-fetching of work done in GUM. This can be
advantageous for improving data locality but it can also worsen the balance
of the load in the system.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-qg<num></Option>:</Term>
-<ListItem>
-<Para>
-<IndexTerm><Primary>-qg<num> RTS option
-(parallel)</Primary></IndexTerm> (PARALLEL ONLY) Select a globalisation
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<Term><option>-qg<num></option>:</Term>
+<listitem>
+<para>
+<indexterm><primary>-qg<num> RTS option
+(parallel)</primary></indexterm> (paraLLEL ONLY) Select a globalisation
scheme. This option affects the
generation of global addresses when transferring data. Global addresses are
globally unique identifiers required to maintain sharing in the distributed
used, which generated global address only for thunks. The latter case may
lose sharing of data but has a reduced overhead in packing graph structures
and maintaining internal tables of global addresses.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
</para>
</sect2>
-</Sect1>
+</sect1>
<sect1 id="options-platform">
<title>Platform-specific Flags</title>
compiling some modules with four stolen registers, it will
crash, probably saying:
-<Screen>
+<screen>
Foo.hc:533: fixed or forbidden register was spilled.
This may be due to a compiler bug or to impossible asm
statements or clauses.
-</Screen>
+</screen>
Just give some registers back with
<option>-monly-N-regs</option>. Try `3' first, then `2'.
&runtime;
<sect1 id="ext-core">
- <title>Generating External Core Files</title>
+ <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"
+ tools. The Core format is formally described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">
<citetitle>An External Representation for the GHC Core Language</citetitle></ulink>,
and sample tools (in Haskell)
for manipulating Core files are available in the GHC source distribution
directory <literal>/fptools/ghc/utils/ext-core</literal>.
Note that the format of <literal>.hcr</literal>
files is <emphasis>different</emphasis> (though similar) to the Core output format generated
- for debugging purposes (<xref linkend="options-debugging">).</para>
+ for debugging purposes (<xref linkend="options-debugging"/>).</para>
+
+ <para>The Core format natively supports notes which you can add to
+ your source code using the <literal>CORE</literal> pragma (see <xref
+ linkend="pragmas"/>).</para>
<variablelist>
</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>
+</chapter>
<!-- Emacs stuff:
;;; Local Variables: ***
projects / ghc-hetmet.git / blobdiff