<indexterm><primary>structure, command-line</primary></indexterm>
<indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm>
<indexterm><primary>structure, command-line</primary></indexterm>
<indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm>
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
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
<para><literal>OPTIONS</literal> pragmas are only looked for at
the top of your source files, upto the first
<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
<title>Setting options in GHCi</title>
<para>Options may also be modified from within GHCi, using the
<para>As a rule of thumb, options which relate to filenames are
static, and the rest are dynamic. The flag reference tables (<xref
<para>As a rule of thumb, options which relate to filenames are
static, and the rest are dynamic. The flag reference tables (<xref
<listitem>
<para>Interactive mode, which is also available as
<command>ghci</command>. Interactive mode is described in
<listitem>
<para>Interactive mode, which is also available as
<command>ghci</command>. Interactive mode is described in
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
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
<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
<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
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
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
<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
<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
<indexterm><primary>dependency-generation mode</primary>
</indexterm>
<listitem>
<para>DLL-creation mode (Windows only). See <xref
<indexterm><primary>dependency-generation mode</primary>
</indexterm>
<listitem>
<para>DLL-creation mode (Windows only). See <xref
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>
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>
<para>If the program needs to be linked with additional objects
(say, some auxilliary C code), then the object files can be
<para>If the program needs to be linked with additional objects
(say, some auxilliary C code), then the object files can be
<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
<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
whether a native-code generator<indexterm><primary>native-code
generator</primary></indexterm> is used (producing assembly
language) or not (producing C). See <xref
whether a native-code generator<indexterm><primary>native-code
generator</primary></indexterm> is used (producing assembly
language) or not (producing C). See <xref
<para>Note: C pre-processing is optional, the
<option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
<para>Note: C pre-processing is optional, the
<option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
- <para>Note: The option <option>-E</option><IndexTerm><Primary>-E
- option</Primary></IndexTerm> runs just the pre-processing passes
+ <para>Note: The option <option>-E</option><indexterm><primary>-E
+ option</primary></indexterm> runs just the pre-processing passes
of the compiler, dumping the result in a file. Note that this
differs from the previous behaviour of dumping the file to
standard output.</para>
of the compiler, dumping the result in a file. Note that this
differs from the previous behaviour of dumping the file to
standard output.</para>
- <IndexTerm><Primary>help options</Primary></IndexTerm>
- <IndexTerm><Primary>verbosity options</Primary></IndexTerm>
+ <indexterm><primary>help options</primary></indexterm>
+ <indexterm><primary>verbosity options</primary></indexterm>
is the value of
<literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
</indexterm>in the package configuration file (see <xref
is the value of
<literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
</indexterm>in the package configuration file (see <xref
<para>Provides the standard warnings plus
<option>-fwarn-incomplete-patterns</option>,
<option>-fwarn-unused-matches</option>,
<para>Provides the standard warnings plus
<option>-fwarn-incomplete-patterns</option>,
<option>-fwarn-unused-matches</option>,
<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
<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
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>
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>
</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>
</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>
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
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
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
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 all unused variables which arise from pattern
matches, including patterns consisting of a single variable.
For instance <literal>f x y = []</literal> would report
<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
<para>If you're feeling really paranoid, the
<option>-dcore-lint</option>
<para>If you're feeling really paranoid, the
<option>-dcore-lint</option>
<literal>Exception.assert</literal> in source code (in
other words, rewriting <literal>Exception.assert p
e</literal> to <literal>e</literal> (see <xref
<literal>Exception.assert</literal> in source code (in
other words, rewriting <literal>Exception.assert p
e</literal> to <literal>e</literal> (see <xref
unpacked if possible. It is equivalent to adding an
<literal>UNPACK</literal> pragma to every strict
constructor field (see <xref
unpacked if possible. It is equivalent to adding an
<literal>UNPACK</literal> pragma to every strict
constructor field (see <xref
<para>This option is a bit of a sledgehammer: it might
sometimes make things worse. Selectively unboxing fields
<para>This option is a bit of a sledgehammer: it might
sometimes make things worse. Selectively unboxing fields
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.
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.
-<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
<para>
To run your parallel program, once PVM is going, just invoke it
“as normal”. The main extra RTS option is
-all relevant RTS options, please see <XRef
-LinkEnd="parallel-rts-opts">.)
+all relevant RTS options, please see <xref
+linkend="parallel-rts-opts"/>.)
out of them (e.g., parallelism profiles) is a battle with the vagaries of
PVM, detailed in the following sections.
</para>
out of them (e.g., parallelism profiles) is a battle with the vagaries of
PVM, detailed in the following sections.
</para>
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:
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:
setenv PVM_ROOT /wherever/you/put/it
setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
setenv PVM_DPATH $PVM_ROOT/lib/pvmd
setenv PVM_ROOT /wherever/you/put/it
setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
setenv PVM_DPATH $PVM_ROOT/lib/pvmd
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
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
machine. You can then do various things to control/monitor your
“parallel machine;” the most useful being:
</para>
<para>
machine. You can then do various things to control/monitor your
“parallel machine;” the most useful being:
</para>
<para>
-<Para>
-Parallelism profiles (à la <Command>hbcpp</Command>) can be generated with the
-<Option>-qP</Option><IndexTerm><Primary>-qP RTS option (concurrent, parallel)</Primary></IndexTerm> RTS option. The
+<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
<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!
<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!
The “garbage-collection statistics” RTS options can be useful for
seeing what parallel programs are doing. If you do either
The “garbage-collection statistics” RTS options can be useful for
seeing what parallel programs are doing. If you do either
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.
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.
</title>
<para>
<indexterm><primary>RTS options, concurrent</primary></indexterm>
<indexterm><primary>RTS options, parallel</primary></indexterm>
<indexterm><primary>Concurrent Haskell—RTS options</primary></indexterm>
</title>
<para>
<indexterm><primary>RTS options, concurrent</primary></indexterm>
<indexterm><primary>RTS options, parallel</primary></indexterm>
<indexterm><primary>Concurrent Haskell—RTS options</primary></indexterm>
-<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;
-(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
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.)
the heap for thread state and stack objects. (For 32-bit machines, this
translates to 4K bytes, and for 64-bit machines, 8K bytes.)
-<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>
-<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
-</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
-</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.
<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
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.
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.
Foo.hc:533: fixed or forbidden register was spilled.
This may be due to a compiler bug or to impossible asm
statements or clauses.
Foo.hc:533: fixed or forbidden register was spilled.
This may be due to a compiler bug or to impossible asm
statements or clauses.
Just give some registers back with
<option>-monly-N-regs</option>. Try `3' first, then `2'.
Just give some registers back with
<option>-monly-N-regs</option>. Try `3' first, then `2'.
<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
<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
<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
<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
<para>The Core format natively supports notes which you can add to
your source code using the <literal>CORE</literal> pragma (see <xref
<para>The Core format natively supports notes which you can add to
your source code using the <literal>CORE</literal> pragma (see <xref