<para>Sometimes it is useful to make the connection between a
source file and the command-line options it requires quite
- tight. For instance, if a Haskell source file uses GHC
- extensions, it will always need to be compiled with the
- <option>-fglasgow-exts</option> option. Rather than maintaining
+ tight. For instance, if a Haskell source file deliberately
+ uses name shadowing, it should be compiled with the
+ <option>-fno-warn-name-shadowing</option> option. Rather than maintaining
the list of per-file options in a <filename>Makefile</filename>,
it is possible to do this directly in the source file using the
<literal>OPTIONS_GHC</literal> pragma <indexterm><primary>OPTIONS_GHC
pragma</primary></indexterm>:</para>
<programlisting>
-{-# OPTIONS_GHC -fglasgow-exts #-}
+{-# OPTIONS_GHC -fno-warn-name-shadowing #-}
module X where
...
</programlisting>
- <para><literal>OPTIONS_GHC</literal> pragmas are only looked for at
- the top of your source files, upto the first
- (non-literate,non-empty) line not containing
- <literal>OPTIONS_GHC</literal>. Multiple <literal>OPTIONS_GHC</literal>
- pragmas are recognised. Do not put comments before, or on the same line
- as, the <literal>OPTIONS_GHC</literal> pragma.</para>
+ <para><literal>OPTIONS_GHC</literal> is a <emphasis>file-header pragma</emphasis>
+ (see <xref linkend="pragmas"/>).</para>
+
+ <para>Only <emphasis>dynamic</emphasis> flags can be used in an <literal>OPTIONS_GHC</literal> pragma
+ (see <xref linkend="static-dynamic-flags"/>).</para>
<para>Note that your command shell does not
get to the source file options, they are just included literally
<listitem>
<para>Most non-mode flags fall into this category. A dynamic flag
may be used on the command line, in a
- <literal>GHC_OPTIONS</literal> pragma in a source file, or set
+ <literal>OPTIONS_GHC</literal> pragma in a source file, or set
using <literal>:set</literal> in GHCi.</para>
</listitem>
</varlistentry>
<option>-fwarn-deprecated-flags</option>,
<option>-fwarn-duplicate-exports</option>,
<option>-fwarn-missing-fields</option>,
- <option>-fwarn-missing-methods</option>, and
+ <option>-fwarn-missing-methods</option>,
+ <option>-fwarn-lazy-unlifted-bindings</option>,
+ <option>-fwarn-wrong-do-bind</option>, and
<option>-fwarn-dodgy-foreign-imports</option>. The following
flags are
simple ways to select standard “packages” of warnings:
<option>-fwarn-simple-patterns</option>,
<option>-fwarn-tabs</option>,
<option>-fwarn-incomplete-record-updates</option>,
- <option>-fwarn-monomorphism-restriction</option>, and
+ <option>-fwarn-monomorphism-restriction</option>,
+ <option>-fwarn-unused-do-bind</option>, and
<option>-fwarn-implicit-prelude</option>.</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
+ <term><option>-fwarn-unrecognised-pragmas</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-unrecognised-pragmas</option></primary>
+ </indexterm>
+ <indexterm><primary>warnings</primary></indexterm>
+ <indexterm><primary>pragmas</primary></indexterm>
+ <para>Causes a warning to be emitted when a
+ pragma that GHC doesn't recognise is used. As well as pragmas
+ that GHC itself uses, GHC also recognises pragmas known to be used
+ by other tools, e.g. <literal>OPTIONS_HUGS</literal> and
+ <literal>DERIVE</literal>.</para>
+
+ <para>This option is on by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-fwarn-warnings-deprecations</option>:</term>
<listitem>
<indexterm><primary><option>-fwarn-warnings-deprecations</option></primary>
<listitem>
<indexterm><primary><option>-fwarn-dodgy-imports</option></primary>
</indexterm>
- <para>Causes a warning to be emitted when a a datatype
+ <para>Causes a warning to be emitted when a datatype
<literal>T</literal> is imported
with all constructors, i.e. <literal>T(..)</literal>, but has been
exported abstractly, i.e. <literal>T</literal>.</para>
</varlistentry>
<varlistentry>
+ <term><option>-fwarn-lazy-unlifted-bindings</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-lazy-unlifted-bindings</option></primary>
+ </indexterm>
+ <para>Causes a warning to be emitted when an unlifted type
+ is bound in a way that looks lazy, e.g.
+ <literal>where (I# x) = ...</literal>. Use
+ <literal>where !(I# x) = ...</literal> instead. This will be an
+ error, rather than a warning, in GHC 6.14.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-fwarn-duplicate-exports</option>:</term>
<listitem>
<indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm>
typographical errors that turn into hard-to-find bugs, e.g.,
in the inadvertent capture of what would be a recursive call in
<literal>f = ... let f = id in ... f ...</literal>.</para>
+ <para>The warning is suppressed for names beginning with an underscore. For example
+ <programlisting>
+ f x = do { _ignore <- this; _ignore <- that; return (the other) }
+ </programlisting>
+ </para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-fwarn-unused-do-bind</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-unused-do-bind</option></primary></indexterm>
+ <indexterm><primary>unused do binding, warning</primary></indexterm>
+ <indexterm><primary>do binding, unused</primary></indexterm>
+
+ <para>Report expressions occuring in <literal>do</literal> and <literal>mdo</literal> blocks
+ that appear to silently throw information away.
+ For instance <literal>do { mapM popInt xs ; return 10 }</literal> would report
+ the first statement in the <literal>do</literal> block as suspicious,
+ as it has the type <literal>StackM [Int]</literal> and not <literal>StackM ()</literal>, but that
+ <literal>[Int]</literal> value is not bound to anything. The warning is suppressed by
+ explicitly mentioning in the source code that your program is throwing something away:
+ <programlisting>
+ do { _ <- mapM popInt xs ; return 10 }
+ </programlisting>
+ Of course, in this particular situation you can do even better:
+ <programlisting>
+ do { mapM_ popInt xs ; return 10 }
+ </programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-wrong-do-bind</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-wrong-do-bind</option></primary></indexterm>
+ <indexterm><primary>apparently erroneous do binding, warning</primary></indexterm>
+ <indexterm><primary>do binding, apparently erroneous</primary></indexterm>
+
+ <para>Report expressions occuring in <literal>do</literal> and <literal>mdo</literal> blocks
+ that appear to lack a binding.
+ For instance <literal>do { return (popInt 10) ; return 10 }</literal> would report
+ the first statement in the <literal>do</literal> block as suspicious,
+ as it has the type <literal>StackM (StackM Int)</literal> (which consists of two nested applications
+ of the same monad constructor), but which is not then "unpacked" by binding the result.
+ The warning is suppressed by explicitly mentioning in the source code that your program is throwing something away:
+ <programlisting>
+ do { _ <- return (popInt 10) ; return 10 }
+ </programlisting>
+ For almost all sensible programs this will indicate a bug, and you probably intended to write:
+ <programlisting>
+ do { popInt 10 ; return 10 }
+ </programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
<para>If you're feeling really paranoid, the
linkend="lang-parallel" /> we describe the language features that affect
parallelism.</para>
- <sect2 id="parallel-options">
- <title>Options for SMP parallelism</title>
+ <sect2 id="parallel-compile-options">
+ <title>Compile-time options for SMP parallelism</title>
<para>In order to make use of multiple CPUs, your program must be
linked with the <option>-threaded</option> option (see <xref
- linkend="options-linker" />). Then, to run a program on multiple
- CPUs, use the RTS <option>-N</option> option:</para>
+ linkend="options-linker" />). Additionally, the following
+ compiler options affect parallelism:</para>
<variablelist>
+ <varlistentry>
+ <term><option>-feager-blackholing</option></term>
+ <indexterm><primary><option>-feager-blackholing</option></primary></indexterm>
+ <listitem>
+ <para>
+ Blackholing is the act of marking a thunk (lazy
+ computuation) as being under evaluation. It is useful for
+ three reasons: firstly it lets us detect certain kinds of
+ infinite loop (the <literal>NonTermination</literal>
+ exception), secondly it avoids certain kinds of space
+ leak, and thirdly it avoids repeating a computation in a
+ parallel program, because we can tell when a computation
+ is already in progress.</para>
+
+ <para>
+ The option <option>-feager-blackholing</option> causes
+ each thunk to be blackholed as soon as evaluation begins.
+ The default is "lazy blackholing", whereby thunks are only
+ marked as being under evaluation when a thread is paused
+ for some reason. Lazy blackholing is typically more
+ efficient (by 1-2% or so), because most thunks don't
+ need to be blackholed. However, eager blackholing can
+ avoid more repeated computation in a parallel program, and
+ this often turns out to be important for parallelism.
+ </para>
+
+ <para>
+ We recommend compiling any code that is intended to be run
+ in parallel with the <option>-feager-blackholing</option>
+ flag.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="parallel-options">
+ <title>RTS options for SMP parallelism</title>
+
+ <para>To run a program on multiple CPUs, use the
+ RTS <option>-N</option> option:</para>
+
+ <variablelist>
<varlistentry>
- <term><option>-N<replaceable>x</replaceable></option></term>
+ <term><option>-N<optional><replaceable>x</replaceable></optional></option></term>
<listitem>
<para><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm>
Use <replaceable>x</replaceable> simultaneous threads when
on a dual-core machine we would probably use
<literal>+RTS -N2 -RTS</literal>.</para>
+ <para>Omitting <replaceable>x</replaceable>,
+ i.e. <literal>+RTS -N -RTS</literal>, lets the runtime
+ choose the value of <replaceable>x</replaceable> itself
+ based on how many processors are in your machine.</para>
+
+ <para>Be careful when using all the processors in your
+ machine: if some of your processors are in use by other
+ programs, this can actually harm performance rather than
+ improve it.</para>
+
<para>Setting <option>-N</option> also has the effect of
- setting <option>-g</option> (the number of OS threads to
- use for garbage collection) to the same value.</para>
+ enabling the parallel garbage collector (see
+ <xref linkend="rts-options-gc" />).</para>
<para>There is no means (currently) by which this value
may vary after the program has started.</para>
<para>GHC can dump its optimized intermediate code (said to be in “Core” format)
to a file as a side-effect of compilation. Non-GHC back-end tools can read and process Core files; these files have the suffix
- <filename>.hcr</filename>. The Core format is described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">
+ <filename>.hcr</filename>. The Core format is described in <ulink url="../ext-core/core.pdf">
<citetitle>An External Representation for the GHC Core Language</citetitle></ulink>,
and sample tools
for manipulating Core files (in Haskell) are in the GHC source distribution
projects / ghc-hetmet.git / blobdiff