<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>
+ <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>
- <group>
- <arg>-E</arg>
- <arg>-C</arg>
- <arg>-S</arg>
- <arg>-c</arg>
- </group>
- </cmdsynopsis></term>
- <indexterm><primary><option>--make</option></primary>
- </indexterm>
- <listitem>
- <para>This is the traditional batch-compiler mode, in which
+ <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>
-
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
<sect1>
<title>Options overview</title>
<variablelist>
<varlistentry>
- <term><literal>-help</literal></term>
- <term><literal>-?</literal></term>
- <indexterm><primary><literal>-?</literal></primary></indexterm>
- <indexterm><primary><literal>-help</literal></primary></indexterm>
+ <term><option>––help</option></term>
+ <term><option>-?</option></term>
+ <indexterm><primary><option>-?</option></primary></indexterm>
+ <indexterm><primary><option>––help</option></primary></indexterm>
<listitem>
<para>Cause GHC to spew a long usage message to standard
output and then exit.</para>
</varlistentry>
<varlistentry>
- <term><literal>-v</literal></term>
- <indexterm><primary><literal>-v</literal></primary></indexterm>
+ <term><option>-v</option></term>
+ <indexterm><primary><option>-v</option></primary></indexterm>
<listitem>
<para>The <option>-v</option> option makes GHC
<emphasis>verbose</emphasis>: it reports its version number
</varlistentry>
<varlistentry>
- <term><literal>-v</literal><replaceable>n</replaceable></term>
+ <term><option>-v</option><replaceable>n</replaceable></term>
<indexterm><primary><option>-v</option></primary></indexterm>
<listitem>
<para>To provide more control over the compiler's verbosity,
<variablelist>
<varlistentry>
- <term><literal>-v0</literal></term>
+ <term><option>-v0</option></term>
<listitem>
<para>Disable all non-essential messages (this is the
default).</para>
</varlistentry>
<varlistentry>
- <term><literal>-v1</literal></term>
+ <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>
+ <option>––make</option> or
+ <option>––interactive</option> is on).</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>-v2</literal></term>
+ <term><option>-v2</option></term>
<listitem>
<para>Print the name of each compilation phase as it
is executed. (equivalent to
</varlistentry>
<varlistentry>
- <term><literal>-v3</literal></term>
+ <term><option>-v3</option></term>
<listitem>
<para>The same as <option>-v2</option>, except that in
addition the full command line (if appropriate) for
</varlistentry>
<varlistentry>
- <term><literal>-v4</literal></term>
+ <term><option>-v4</option></term>
<listitem>
<para>The same as <option>-v3</option> except that the
intermediate program representation after each
</varlistentry>
<varlistentry>
- <term><literal>--version</literal></term>
- <indexterm><primary><literal>--version</literal></primary></indexterm>
+ <term><option>––version</option></term>
+ <indexterm><primary><option>––version</option></primary></indexterm>
<listitem>
<para>Print a one-line string including GHC's version number.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>--numeric-version</literal></term>
- <indexterm><primary><literal>--numeric-version</literal></primary></indexterm>
+ <term><option>––numeric-version</option></term>
+ <indexterm><primary><option>––numeric-version</option></primary></indexterm>
<listitem>
<para>Print GHC's numeric version number only.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>––print-libdir</option></term>
+ <indexterm><primary><option>––print-libdir</option></primary></indexterm>
+ <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>
<sect1 id="make-mode">
- <title>Using <command>ghc</command> <option>--make</option></title>
+ <title>Using <command>ghc</command> <option>––make</option></title>
- <indexterm><primary><option>--make</option></primary>
+ <indexterm><primary><option>––make</option></primary>
</indexterm>
<indexterm><primary>separate compilation</primary>
</indexterm>
- <para>When given the <option>--make</option> option, GHC will
+ <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
the program like this:</para>
<screen>
-ghc --make Main.hs
+ghc ––make Main.hs
</screen>
<para>The command line must contain one source file or module
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>
+ <para>The main advantages to using <literal>ghc ––make</literal>
over traditional <literal>Makefile</literal>s are:</para>
<itemizedlist>
<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
+ ––make</literal> can be up to twice as fast as running
<literal>ghc</literal> individually on each source
file.</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
+ 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
<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>
+ <title>GHC without <option>––make</option></title>
- <para>Without <option>--make</option>, GHC will compile one or
+ <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
<variablelist>
<varlistentry>
- <term><literal>-o</literal></term>
- <indexterm><primary><literal>-o</literal></primary></indexterm>
+ <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.,
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><literal>-odir</literal></term>
- <indexterm><primary><literal>-odir</literal></primary></indexterm>
+ <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…
</varlistentry>
<varlistentry>
- <term><literal>-ohi</literal></term>
- <indexterm><primary><literal>-ohi</literal></primary></indexterm>
+ <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></para>
+ <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><literal>-osuf</literal></term>
- <term><literal>-hisuf</literal></term>
- <indexterm><primary><literal>-osuf</literal></primary></indexterm>
- <indexterm><primary><literal>-hisuf</literal></primary></indexterm>
+ <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
- <suffix></option><IndexTerm><Primary>-osuf
- <suffix> option</Primary></IndexTerm> will change the
- <filename>.o</filename> file suffix for object files to
- whatever you specify. (We use this in compiling the
- prelude.).</para>
-
- <para>Similarly, the <option>-hisuf
- <suffix></option><IndexTerm><Primary>-hisuf
- <suffix> option</Primary></IndexTerm> will change the
- <filename>.hi</filename> file suffix for non-system
- interface files (see <XRef LinkEnd="hi-options">).</para>
+ <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 useful if you want to compile a program with both
<variablelist>
<varlistentry>
- <term><literal>-keep-hc-files</literal></term>
+ <term><option>-keep-hc-files</option></term>
<indexterm>
- <primary><literal>-keep-hc-files</literal></primary>
+ <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 <literal>-fvia-C</literal> to force them
+ may need to use <option>-fvia-C</option> to force them
to be produced).</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>-keep-s-files</literal></term>
+ <term><option>-keep-s-files</option></term>
<indexterm>
- <primary><literal>-keep-s-files</literal></primary>
+ <primary><option>-keep-s-files</option></primary>
</indexterm>
<listitem>
<para>Keep intermediate <literal>.s</literal> files.</para>
</varlistentry>
<varlistentry>
- <term><literal>-keep-raw-s-files</literal></term>
+ <term><option>-keep-raw-s-files</option></term>
<indexterm>
- <primary><literal>-keep-raw-s-files</literal></primary>
+ <primary><option>-keep-raw-s-files</option></primary>
</indexterm>
<listitem>
<para>Keep intermediate <literal>.raw-s</literal> files.
</varlistentry>
<varlistentry>
- <term><literal>-keep-tmp-files</literal></term>
+ <term><option>-keep-tmp-files</option></term>
<indexterm>
- <primary><literal>-keep-tmp-files</literal></primary>
+ <primary><option>-keep-tmp-files</option></primary>
</indexterm>
<indexterm>
<primary>temporary files</primary>
temporary files, which it normally keeps in
<literal>/tmp</literal> (or possibly elsewhere; see <xref
linkend="temp-files">). Running GHC with
- <literal>-v</literal> will show you what temporary files
+ <option>-v</option> will show you what temporary files
were generated along the way.</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
- <term><literal>-tmpdir</literal></term>
- <indexterm><primary><literal>-tmpdir</literal></primary></indexterm>
+ <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
<para>Provides the standard warnings plus
<option>-fwarn-incomplete-patterns</option>,
<option>-fwarn-unused-matches</option>,
- <option>-fwarn-unused-imports</option> and
+ <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>-w option</Primary></IndexTerm>
+ <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>-Wall option</primary></indexterm>
+ <indexterm><primary><option>-Wall</option></primary></indexterm>
<para>Turns on all warning options.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-fwarn-duplicate-exports</option>:</term>
<listitem>
- <indexterm><primary>-fwarn-duplicate-exports option</primary></indexterm>
+ <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
<indexterm><primary>duplicate exports, warning</primary></indexterm>
<indexterm><primary>export lists, duplicates</primary></indexterm>
<varlistentry>
<term><option>-fwarn-hi-shadowing</option>:</term>
<listitem>
- <indexterm><primary>-fwarn-hi-shadowing option</primary></indexterm>
+ <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm>
<indexterm><primary>shadowing</primary>
<secondary>interface files</secondary></indexterm>
<varlistentry>
<term><option>-fwarn-incomplete-patterns</option>:</term>
<listitem>
- <indexterm><primary>-fwarn-incomplete-patterns option</primary></indexterm>
+ <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
<indexterm><primary>incomplete patterns, warning</primary></indexterm>
<indexterm><primary>patterns, incomplete</primary></indexterm>
</varlistentry>
<varlistentry>
+ <term><option>-fwarn-misc</option>:</term>
+ <indexterm><primary><option>-fwarn-misc</option></primary></indexterm>
+ <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>:</term>
<listitem>
- <indexterm><primary>-fwarn-missing-fields option</primary></indexterm>
+ <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm>
<indexterm><primary>missing fields, warning</primary></indexterm>
<indexterm><primary>fields, missing</primary></indexterm>
<varlistentry>
<term><option>-fwarn-missing-methods</option>:</term>
<listitem>
- <indexterm><primary>-fwarn-missing-methods option</primary></indexterm>
+ <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm>
<indexterm><primary>missing methods, warning</primary></indexterm>
<indexterm><primary>methods, missing</primary></indexterm>
<varlistentry>
<term><option>-fwarn-missing-signatures</option>:</term>
<listitem>
- <indexterm><primary>-fwarn-missing-signatures option</primary></indexterm>
+ <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
<varlistentry>
<term><option>-fwarn-name-shadowing</option>:</term>
<listitem>
- <indexterm><primary>-fwarn-name-shadowing option</primary></indexterm>
+ <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
<varlistentry>
<term><option>-fwarn-overlapping-patterns</option>:</term>
- <indexterm><primary>-fwarn-overlapping-patterns option</primary></indexterm>
+ <indexterm><primary><option>-fwarn-overlapping-patterns</option></primary></indexterm>
<indexterm><primary>overlapping patterns, warning</primary></indexterm>
<indexterm><primary>patterns, overlapping</primary></indexterm>
<listitem>
<varlistentry>
<term><option>-fwarn-type-defaults</option>:</term>
<listitem>
- <indexterm><primary>-fwarn-type-defaults option</primary></indexterm>
+ <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
<varlistentry>
<term><option>-fwarn-unused-binds</option>:</term>
<listitem>
- <indexterm><primary>-fwarn-unused-binds option</primary></indexterm>
+ <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)
<varlistentry>
<term><option>-fwarn-unused-imports</option>:</term>
<listitem>
- <indexterm><primary>-fwarn-unused-imports option</primary></indexterm>
+ <indexterm><primary><option>-fwarn-unused-imports</option></primary></indexterm>
<indexterm><primary>unused imports, warning</primary></indexterm>
<indexterm><primary>imports, unused</primary></indexterm>
<varlistentry>
<term><option>-fwarn-unused-matches</option>:</term>
<listitem>
- <indexterm><primary>-fwarn-unused-matches option</primary></indexterm>
+ <indexterm><primary><option>-fwarn-unused-matches</option></primary></indexterm>
<indexterm><primary>unused matches, warning</primary></indexterm>
<indexterm><primary>matches, unused</primary></indexterm>
</VariableList>
<para>If you're feeling really paranoid, the
- <option>-dcore-lint</option> option<indexterm><primary>-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>
+ <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>
</varlistentry>
<varlistentry>
- <term><option>-O2-for-C</option>:</term>
- <indexterm><primary>-O2-for-C option</primary></indexterm>
- <indexterm><primary>gcc, invoking with -O2</primary></indexterm>
- <listitem>
- <para>Says to run GCC with <option>-O2</option>, which may
- be worth a few percent in execution speed. Don't forget
- <option>-fvia-C</option>, lest you use the native-code
- generator and bypass GCC altogether!</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><option>-Ofile <file></option>:</term>
<indexterm><primary>-Ofile <file> option</primary></indexterm>
<indexterm><primary>optimising, customised</primary></indexterm>
<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 -O2-for-C</option> (and
- we go for lots of coffee breaks).</para>
+ broke, we tend to use <option>-O -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>,
</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>
</varlistentry>
<varlistentry>
- <term><option>-funfolding-interface-threshold<n></option>:</term>
- <listitem>
- <indexterm><primary><option>-funfolding-interface-threshold</option></primary></indexterm>
- <indexterm><primary>inlining, controlling</primary></indexterm>
- <indexterm><primary>unfolding, controlling</primary></indexterm>
-
- <para>(Default: 30) By raising or lowering this number,
- you can raise or lower the amount of pragmatic junk that
- gets spewed into interface files. (An unfolding has a
- “size” that reflects the cost in terms of
- “code bloat” of expanding that unfolding in
- another module. A bigger function would be assigned a
- bigger cost.)</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: 30) This option is similar to
- <option>-funfolding-interface-threshold</option>, except
- that it governs unfoldings within a single module.
- Increasing this figure is more likely to result in longer
+ <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>
</variablelist>
</sect2>
-
+
</sect1>
-
-&phases;
-
-<Sect1 id="sec-using-concurrent">
+
+ &phases;
+
+ <sect1 id="sec-using-concurrent">
<title>Using Concurrent Haskell</title>
-<para>
-<indexterm><primary>Concurrent Haskell—use</primary></indexterm>
-</para>
+ <indexterm><primary>Concurrent Haskell—use</primary></indexterm>
<para>
-GHC (as of version 4.00) 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
-(i.e. <literal>Concurrent</literal> and friends), use the
-<option>-package concurrent</option> option.
-</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>
-Three RTS options are provided for modifying the behaviour of the
-threaded runtime system. See the descriptions of
-<option>-C[<us>]</option>, <option>-q</option>, and
-<option>-t<num></option> in <XRef LinkEnd="parallel-rts-opts">.
+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 <XRef
-LinkEnd="sec-Concurrent">.
+Concurrent Haskell is described in more detail in the documentation
+for the <literal>Control.Concurrent</literal> module.
</para>
</Sect1>
<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>-N<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">.)
PVM, detailed in the following sections.
</para>
-<sect2>
-<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>
<para>
Creating and/or controlling your “parallel machine” is a purely-PVM
-business; nothing specific to Parallel Haskell.
-</para>
+business; nothing specific to Parallel Haskell. The following paragraphs
+describe how to configure your parallel machine interactively.
+</Para>
-<para>
-You use the <command>pvm</command><indexterm><primary>pvm command</primary></indexterm> command to start PVM on your
+<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>
</sect2>
-<sect2>
-<title>Parallelism profiles</title>
+<Sect2 id="par-profiles">
+<Title>Parallelism profiles</Title>
<para>
<indexterm><primary>parallelism profiles</primary></indexterm>
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>-q</option><indexterm><primary>-q 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>
-% ./a.out +RTS -N8 -q
-% grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one
-% gr2ps -O temp.gr # cvt to .ps; output in temp.ps
-% ghostview -seascape temp.ps # look at it!
+<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>
<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.
<para>
<VariableList>
-<varlistentry>
-<term><option>-N<N></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-N<N> RTS option (parallel)</primary></indexterm>
-(PARALLEL ONLY) Use <literal><N></literal> PVM processors to run this program;
+<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>
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>-t<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-t<num> RTS option</primary></indexterm>
-(PARALLEL ONLY) Limit 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>
-<varlistentry>
-<term><option>-d</option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-d RTS option (parallel)</primary></indexterm>
+<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>
+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>-e<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-e<num> RTS option (parallel)</primary></indexterm>
-(PARALLEL ONLY) Limit 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>-Q<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-Q<num> RTS option (parallel)</primary></indexterm>
+<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
+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>
+</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>
</sect1>
&runtime;
+
+<sect1 id="ext-core">
+ <title>Generating 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>
+
+ <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>
+
+</sect1>
+
&debug;
&flags;
projects / ghc-hetmet.git / blobdiff