of warnings which are generally likely to indicate bugs in your
program. These are:
<option>-fwarn-overlapping-patterns</option>,
- <option>-fwarn-deprecations</option>,
+ <option>-fwarn-warnings-deprecations</option>,
<option>-fwarn-deprecated-flags</option>,
<option>-fwarn-duplicate-exports</option>,
- <option>-fwarn-missing-fields</option>, and
- <option>-fwarn-missing-methods</option>. The following flags are
+ <option>-fwarn-missing-fields</option>,
+ <option>-fwarn-missing-methods</option>, and
+ <option>-fwarn-dodgy-foreign-imports</option>. The following
+ flags are
simple ways to select standard “packages” of warnings:
</para>
<variablelist>
<varlistentry>
- <term><option>-fwarn-deprecations</option>:</term>
+ <term><option>-fwarn-warnings-deprecations</option>:</term>
<listitem>
- <indexterm><primary><option>-fwarn-deprecations</option></primary>
+ <indexterm><primary><option>-fwarn-warnings-deprecations</option></primary>
</indexterm>
+ <indexterm><primary>warnings</primary></indexterm>
<indexterm><primary>deprecations</primary></indexterm>
- <para>Causes a warning to be emitted when a deprecated
- function or type is used. Entities can be marked as
- deprecated using a pragma, see <xref
- linkend="deprecated-pragma"/>.</para>
+ <para>Causes a warning to be emitted when a
+ module, function or type with a WARNING or DEPRECATED pragma
+ is used. See <xref linkend="warning-deprecated-pragma"/> for more
+ details on the pragmas.</para>
<para>This option is on by default.</para>
</listitem>
</varlistentry>
<varlistentry>
+ <term><option>-fwarn-dodgy-foreign-imports</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-dodgy-foreign-imports</option></primary>
+ </indexterm>
+ <para>Causes a warning to be emitted for foreign imports of
+ the following form:</para>
+<programlisting>
+foreign import "f" f :: FunPtr t
+</programlisting>
+ <para>on the grounds that it probably should be</para>
+<programlisting>
+foreign import "&f" f :: FunPtr t
+</programlisting>
+ <para>The first form declares that `f` is a (pure) C
+ function that takes no arguments and returns a pointer to a
+ C function with type `t`, whereas the second form declares
+ that `f` itself is a C function with type `t`. The first
+ declaration is usually a mistake, and one that is hard to
+ debug because it results in a crash, hence this
+ warning.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-fwarn-dodgy-imports</option>:</term>
<listitem>
<indexterm><primary><option>-fwarn-dodgy-imports</option></primary>
<para>The trouble with orphans is that GHC must pro-actively read the interface
files for all orphan modules, just in case their instances or rules
play a role, whether or not the module's interface would otherwise
- be of any use. Other things being equal, avoid orphan modules.</para>
+ be of any use. See <xref linkend="orphan-modules"/> for details.
+ </para>
</listitem>
</varlistentry>
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>
<listitem>
<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