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>
ghc [argument...]
</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
</sect2>
<sect2 id="source-file-options">
- <title>command line options in source files</title>
+ <title>Command line options in source files</title>
<indexterm><primary>source-file options</primary></indexterm>
maintains internally, so you'll be desperately disappointed if
you try to glob etc. inside <literal>OPTIONS_GHC</literal>.</para>
- <para>NOTE: the contents of OPTIONS_GHC are prepended to the
- command-line options, so you <emphasis>do</emphasis> have the
- ability to override OPTIONS_GHC settings via the command
- line.</para>
+ <para>NOTE: the contents of OPTIONS_GHC are appended to the
+ command-line options, so options given in the source file
+ override those given on the command-line.</para>
<para>It is not recommended to move all the contents of your
Makefiles into your source files, but in some circumstances, the
<literal>OPTIONS_GHC</literal> pragma is the Right Thing. (If you
- use <option>-keep-hc-file-too</option> and have OPTION flags in
+ use <option>-keep-hc-file</option> and have OPTION flags in
your module, the OPTIONS_GHC will get put into the generated .hc
file).</para>
</sect2>
<indexterm><primary>mode</primary><secondary>options</secondary>
</indexterm>
- <para>Each of GHC's command line options is classified as either
- <firstterm>static</firstterm> or <firstterm>dynamic</firstterm> or
+ <para>Each of GHC's command line options is classified as
+ <firstterm>static</firstterm>, <firstterm>dynamic</firstterm> or
<firstterm>mode</firstterm>:</para>
<variablelist>
<term>Mode flags</term>
<listitem>
<para>For example, <option>--make</option> or <option>-E</option>.
- There may be only a single mode flag on the command line. The
+ There may only be a single mode flag on the command line. The
available modes are listed in <xref linkend="modes"/>.</para>
</listitem>
</varlistentry>
<para>The flag reference tables (<xref
linkend="flag-reference"/>) lists the status of each flag.</para>
+
+ <para>There are a few flags that are static except that they can
+ also be used with GHCi's <literal>:set</literal> command; these
+ are listed as “static/<literal>:set</literal>” in the
+ table.</para>
</sect1>
<sect1 id="file-suffixes">
<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>
+ linkend="makefile-dependencies"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
- <command>ghc --version</command> <command>ghc -V</command>
+ <command>ghc --show-iface <replaceable>file</replaceable></command>
+ </cmdsynopsis>
+ <indexterm><primary><option>––--show-iface</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Read the interface in
+ <replaceable>file</replaceable> and dump it as text to
+ <literal>stdout</literal>. For example <literal>ghc --show-iface M.hi</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc --supported-languages</command>
+ </cmdsynopsis>
+ <indexterm><primary><option>––supported-languages</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Print the supported language extensions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc --info</command>
+ </cmdsynopsis>
+ <indexterm><primary><option>––info</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Print information about the compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>ghc --version</command>
+ <command>ghc -V</command>
+ </cmdsynopsis>
<indexterm><primary><option>-V</option></primary></indexterm>
<indexterm><primary><option>––version</option></primary></indexterm>
- </cmdsynopsis>
</term>
<listitem>
<para>Print a one-line string including GHC's version number.</para>
<varlistentry>
<term>
<cmdsynopsis>
- <command>ghc --numeric-version</command>
+ <command>ghc --numeric-version</command>
+ </cmdsynopsis>
<indexterm><primary><option>––numeric-version</option></primary></indexterm>
- </cmdsynopsis>
</term>
<listitem>
<para>Print GHC's numeric version number only.</para>
<varlistentry>
<term>
<cmdsynopsis>
- <command>ghc --print-libdir</command>
+ <command>ghc --print-libdir</command>
+ </cmdsynopsis>
<indexterm><primary><option>––print-libdir</option></primary></indexterm>
- </cmdsynopsis>
</term>
<listitem>
<para>Print the path to GHC's library directory. This is
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>
+ <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary></indexterm>
+ in the package configuration file
+ (see <xref linkend="packages"/>).</para>
</listitem>
</varlistentry>
<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
+ dependencies from one or more root modules (usually just
<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
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,
+ 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
<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.
+ relevant flag is present, then go all the way through to linking.
This table summarises:</para>
<informaltable>
<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.</para>
<sect3 id="overriding-suffixes">
<title>Overriding the default behaviour for a file</title>
<para>As described above, the way in which a file is processed by GHC
- depends on its suffix. This behaviour can be overriden using the
+ depends on its suffix. This behaviour can be overridden using the
<option>-x</option> option:</para>
<variablelist>
<indexterm><primary>help options</primary></indexterm>
<indexterm><primary>verbosity options</primary></indexterm>
- See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
- and <option>--print-libdir</option> modes in <xref linkend="modes"/>.
+ <para>See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
+ and <option>--print-libdir</option> modes in <xref linkend="modes"/>.</para>
<variablelist>
<varlistentry>
<term>
<indexterm><primary>-W option</primary></indexterm>
<para>Provides the standard warnings plus
<option>-fwarn-incomplete-patterns</option>,
+ <option>-fwarn-dodgy-imports</option>,
<option>-fwarn-unused-matches</option>,
<option>-fwarn-unused-imports</option>, and
<option>-fwarn-unused-binds</option>.</para>
</varlistentry>
<varlistentry>
- <term><option>-w</option>:</term>
+ <term><option>-Wall</option>:</term>
<listitem>
- <indexterm><primary><option>-w</option></primary></indexterm>
- <para>Turns off all warnings, including the standard ones.</para>
+ <indexterm><primary><option>-Wall</option></primary></indexterm>
+ <para>Turns on all warning options that indicate potentially
+ suspicious code. The warnings that are
+ <emphasis>not</emphasis> enabled by <option>-Wall</option>
+ are
+ <option>-fwarn-simple-patterns</option>,
+ <option>-fwarn-tabs</option>,
+ <option>-fwarn-incomplete-record-updates</option>,
+ <option>-fwarn-monomorphism-restriction</option>, and
+ <option>-fwarn-implicit-prelude</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-Wall</option>:</term>
+ <term><option>-w</option>:</term>
<listitem>
- <indexterm><primary><option>-Wall</option></primary></indexterm>
- <para>Turns on all warning options.</para>
+ <indexterm><primary><option>-w</option></primary></indexterm>
+ <para>Turns off all warnings, including the standard ones and
+ those that <literal>-Wall</literal> doesn't enable.</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-Wwarn</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-Wwarn</option></primary></indexterm>
+ <para>Warnings are treated only as warnings, not as errors. This is
+ the default, but can be useful to negate a
+ <option>-Werror</option> flag.</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
<para>The full set of warning options is described below. To turn
function or type is used. Entities can be marked as
deprecated using a pragma, see <xref
linkend="deprecated-pragma"/>.</para>
+
+ <para>This option is on by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-fwarn-dodgy-imports</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-dodgy-imports</option></primary>
+ </indexterm>
+ <para>Causes a warning to be emitted when a 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>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
+ <term><option>-fwarn-implicit-prelude</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-implicit-prelude</option></primary></indexterm>
+ <indexterm><primary>implicit prelude, warning</primary></indexterm>
+ <para>Have the compiler warn if the Prelude is implicitly
+ imported. This happens unless either the Prelude module is
+ explicitly imported with an <literal>import ... Prelude ...</literal>
+ line, or this implicit import is disabled (either by
+ <option>-fno-implicit-prelude</option> or a
+ <literal>LANGUAGE NoImplicitPrelude</literal> pragma).</para>
+
+ <para>Note that no warning is given for syntax that implicitly
+ refers to the Prelude, even if <option>-fno-implicit-prelude</option>
+ would change whether it refers to the Prelude.
+ For example, no warning is given when
+ <literal>368</literal> means
+ <literal>Prelude.fromInteger (368::Prelude.Integer)</literal>
+ (where <literal>Prelude</literal> refers to the actual Prelude module,
+ regardless of the imports of the module being compiled).</para>
+
+ <para>This warning is off by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-fwarn-incomplete-patterns</option>:</term>
<listitem>
<indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
g [] = 2
</programlisting>
- <para>This option isn't enabled be default because it can be
+ <para>This option isn't enabled by default because it can be
a bit noisy, and it doesn't always indicate a bug in the
program. However, it's generally considered good practice
to cover all the cases in your functions.</para>
f foo = foo { x = 6 }
</programlisting>
- <para>This option isn't enabled be default because it can be
+ <para>This option isn't enabled by default because it can be
very noisy, and it often doesn't indicate a bug in the
program.</para>
</listitem>
<para>If you would like GHC to check that every top-level
function/value has a type signature, use the
- <option>-fwarn-missing-signatures</option> option. This
+ <option>-fwarn-missing-signatures</option> option. As part of
+ the warning GHC also reports the inferred type. The
option is off by default.</para>
</listitem>
</varlistentry>
inner-scope value has the same name as an outer-scope value,
i.e. the inner value shadows the outer one. This can catch
typographical errors that turn into hard-to-find bugs, e.g.,
- in the inadvertent cyclic definition <literal>let x = ... x
- ... in</literal>.</para>
-
- <para>Consequently, this option does
- <emphasis>will</emphasis> complain about cyclic recursive
- definitions.</para>
+ in the inadvertent capture of what would be a recursive call in
+ <literal>f = ... let f = id in ... f ...</literal>.</para>
</listitem>
</varlistentry>
<para>This option causes a warning to be emitted whenever the
module contains an "orphan" instance declaration or rewrite rule.
- An instance declartion is an orphan if it appears in a module in
+ An instance declaration is an orphan if it appears in a module in
which neither the class nor the type being instanced are declared
in the same module. A rule is an orphan if it is a rule for a
function declared in another module. A module containing any
</term>
<listitem>
<para>By default, the compiler will warn you if a set of
- patterns are overlapping, i.e.,</para>
+ patterns are overlapping, e.g.,</para>
<programlisting>
f :: String -> Int
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,
+ <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>
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>
the Haskell defaulting mechanism for numeric types kicks
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
+ e.g., the ‘default default’ for Haskell 1.4 caused the
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
</varlistentry>
<varlistentry>
+ <term><option>-fwarn-monomorphism-restriction</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-monomorphism-restriction</option></primary></indexterm>
+ <indexterm><primary>monomorphism restriction, warning</primary></indexterm>
+ <para>Have the compiler warn/inform you where in your source
+ the Haskell Monomorphism Restriction is applied. If applied silently
+ the MR can give rise to unexpected behaviour, so it can be helpful
+ to have an explicit warning that it is being applied.</para>
+
+ <para>This warning is off by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-fwarn-unused-binds</option>:</term>
<listitem>
<indexterm><primary><option>-fwarn-unused-binds</option></primary></indexterm>
<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
+ you change something. This is one reason to stick to
no-optimisation when developing code.</para>
<variablelist>
<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="assertions"/>). This flag is turned on by
<option>-O</option>.
</para>
</listitem>
<varlistentry>
<term>
+ <option>-fno-state-hack</option>
+ <indexterm><primary><option>-fno-state-hack</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Turn off the "state hack" whereby any lambda with a
+ <literal>State#</literal> token as argument is considered to be
+ single-entry, hence it is considered OK to inline things inside
+ it. This can improve performance of IO and ST monad code, but it
+ runs the risk of reducing sharing.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-fomit-interface-pragmas</option>
+ <indexterm><primary><option>-fomit-interface-pragmas</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Tells GHC to omit all inessential information from the interface file
+ generated for the module being compiled (say M). This means that a module
+ importing M will see only the <emphasis>types</emphasis> of the functions that M exports, but not
+ their unfoldings, strictness info, etc. Hence, for example,
+ no function exported by M will be inlined
+ into an importing module. The benefit is that modules that import M will
+ need to be recompiled less often (only when M's exports change their type,
+ not when they change their implementation).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-fignore-interface-pragmas</option>
+ <indexterm><primary><option>-fignore-interface-pragmas</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Tells GHC to ignore all inessential information when reading interface files.
+ That is, even if <filename>M.hi</filename> contains unfolding or strictness information
+ for a function, GHC will ignore that information.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<option>-funbox-strict-fields</option>:
<indexterm><primary><option>-funbox-strict-fields</option></primary></indexterm>
<indexterm><primary>strict constructor fields</primary></indexterm>
<varlistentry>
<term>
- <option>-funfolding-update-in-place<n></option>
- <indexterm><primary><option>-funfolding-update-in-place</option></primary></indexterm>
- </term>
- <listitem>
- <para>Switches on an experimental "optimisation".
- 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>
- x = plusInt a b
-</programlisting>
- If we inlined plusInt we might get an opportunity to use
- update-in-place for the thunk 'x'.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-funfolding-creation-threshold<n></option>:
+ <option>-funfolding-creation-threshold=<replaceable>n</replaceable></option>:
<indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
<indexterm><primary>inlining, controlling</primary></indexterm>
<indexterm><primary>unfolding, controlling</primary></indexterm>
</varlistentry>
<varlistentry>
- <term><option>-funfolding-use-threshold<n></option>:</term>
+ <term><option>-funfolding-use-threshold=<replaceable>n</replaceable></option></term>
<listitem>
<indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
<indexterm><primary>inlining, controlling</primary></indexterm>
&phases;
- <sect1 id="sec-using-concurrent">
+ <sect1 id="using-concurrent">
<title>Using Concurrent Haskell</title>
<indexterm><primary>Concurrent Haskell</primary><secondary>using</secondary></indexterm>
</variablelist>
</sect1>
- <sect1 id="sec-using-smp">
+ <sect1 id="using-smp">
<title>Using SMP parallelism</title>
<indexterm><primary>parallelism</primary>
</indexterm>
is also possible to obtain performance improvements with parallelism
on programs that do not use concurrency. This section describes how to
use GHC to compile and run parallel programs, in <xref
- linkend="lang-parallel" /> we desribe the language features that affect
+ linkend="lang-parallel" /> we describe the language features that affect
parallelism.</para>
<sect2 id="parallel-options">
<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">
+ 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">
<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>.
+ and sample tools
+ for manipulating Core files (in Haskell) are in the GHC source distribution
+ directory under <literal>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>
+ files is <emphasis>different</emphasis> from the Core output format that GHC generates
+ for debugging purposes (<xref linkend="options-debugging"/>), though the two formats appear somewhat similar.</para>
<para>The Core format natively supports notes which you can add to
your source code using the <literal>CORE</literal> pragma (see <xref
</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 the <literal>-fglasgow-exts</literal> flag too, because
-ordinary Haskell 98, when translated to External Core, uses things like rank-2 types.</para>
+<para>Currently (as of version 6.8.2), GHC does not have the ability to read in External Core files as source. If you would like GHC to have this ability, please <ulink url="http://hackage.haskell.org/trac/ghc/wiki/MailingListsAndIRC">make your wishes known to the GHC Team</ulink>.</para>
+
</sect1>
&debug;
projects / ghc-hetmet.git / blobdiff