<option>-fglasgow-exts</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</literal> pragma <indexterm><primary>OPTIONS
+ <literal>OPTIONS_GHC</literal> pragma <indexterm><primary>OPTIONS_GHC
pragma</primary></indexterm>:</para>
<programlisting>
-{-# OPTIONS -fglasgow-exts #-}
+{-# OPTIONS_GHC -fglasgow-exts #-}
module X where
...
</programlisting>
- <para><literal>OPTIONS</literal> pragmas are only looked for at
+ <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</literal>. Multiple <literal>OPTIONS</literal>
- pragmas are recognised. Note that your command shell does not
+ <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>Note that your command shell does not
get to the source file options, they are just included literally
- in the array of command-line arguments the compiler driver
+ in the array of command-line arguments the compiler
maintains internally, so you'll be desperately disappointed if
- you try to glob etc. inside <literal>OPTIONS</literal>.</para>
+ you try to glob etc. inside <literal>OPTIONS_GHC</literal>.</para>
- <para>NOTE: the contents of OPTIONS are prepended to the
+ <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 settings via the command
+ ability to override OPTIONS_GHC settings via 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</literal> pragma is the Right Thing. (If you
+ <literal>OPTIONS_GHC</literal> pragma is the Right Thing. (If you
use <option>-keep-hc-file-too</option> and have OPTION flags in
- your module, the OPTIONS will get put into the generated .hc
+ your module, the OPTIONS_GHC will get put into the generated .hc
file).</para>
</sect2>
</sect1>
<sect1 id="static-dynamic-flags">
- <title>Static vs. Dynamic options</title>
+ <title>Static, Dynamic, and Mode options</title>
<indexterm><primary>static</primary><secondary>options</secondary>
</indexterm>
<indexterm><primary>dynamic</primary><secondary>options</secondary>
</indexterm>
+ <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>.
- A static flag may only be specified on the command line, whereas a
- dynamic flag may also be given in an <literal>OPTIONS</literal>
- pragma in a source file or set from the GHCi command-line with
- <literal>:set</literal>.</para>
-
- <para>As a rule of thumb, options which relate to filenames are
- static, and the rest are dynamic. The flag reference tables (<xref
+ <firstterm>static</firstterm> or <firstterm>dynamic</firstterm> or
+ <firstterm>mode</firstterm>:</para>
+
+ <variablelist>
+ <varlistentry>
+ <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
+ available modes are listed in <xref linkend="modes"/>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dynamic Flags</term>
+ <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
+ using <literal>:set</literal> in GHCi.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Static Flags</term>
+ <listitem>
+ <para>A few flags are "static", which means they can only be used on
+ the command-line, and remain in force over the entire GHC/GHCi
+ run.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The flag reference tables (<xref
linkend="flag-reference"/>) lists the status of each flag.</para>
</sect1>
<listitem>
<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
+ Compiling a multi-module program with <literal>ghc
––make</literal> can be up to twice as fast as
running <literal>ghc</literal> individually on each source
file.</para>
<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 <literal>OPTIONS</literal>
+ file only, you'll need to use an <literal>OPTIONS_GHC</literal>
pragma (see <xref linkend="source-file-options"/>).</para>
<para>If the program needs to be linked with additional objects
- (say, some auxilliary C code), then the object files can be
+ (say, some auxiliary C code), then the object files can be
given on the command line and GHC will include them when linking
the executable.</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>
+
+ <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
+ <option>-x</option> option:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-x</option> <replaceable>suffix</replaceable>
+ <indexterm><primary><option>-x</option></primary>
+ </indexterm></term>
+ <listitem>
+ <para>Causes all files following this option on the command
+ line to be processed as if they had the suffix
+ <replaceable>suffix</replaceable>. For example, to compile a
+ Haskell module in the file <literal>M.my-hs</literal>,
+ use <literal>ghc -c -x hs M.my-hs</literal>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+
</sect2>
</sect1>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-ferror-spans</option>
+ <indexterm><primary><option>-ferror-spans</option></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>Causes GHC to emit the full source span of the
+ syntactic entity relating to an error message. Normally, GHC
+ emits the source location of the start of the syntactic
+ entity only.</para>
+
+ <para>For example:</para>
+
+<screen>test.hs:3:6: parse error on input `where'</screen>
+
+ <para>becomes:</para>
+
+<screen>test296.hs:3:6-10: parse error on input `where'</screen>
+
+ <para>And multi-line spans are possible too:</para>
+
+<screen>test.hs:(5,4)-(6,7):
+ Conflicting definitions for `a'
+ Bound at: test.hs:5:4
+ test.hs:6:7
+ In the binding group for: a, b, a</screen>
+
+ <para>Note that line numbers start counting at one, but
+ column numbers start at zero. This choice was made to
+ follow existing convention (i.e. this is how Emacs does
+ it).</para>
+ </listitem>
+ </varlistentry>
</variablelist>
</sect1>
</varlistentry>
<varlistentry>
+ <term><option>-fwarn-incomplete-record-updates</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-incomplete-record-updates</option></primary></indexterm>
+ <indexterm><primary>incomplete record updates, warning</primary></indexterm>
+ <indexterm><primary>record updates, incomplete</primary></indexterm>
+
+ <para>The function
+ <function>f</function> below will fail when applied to
+ <literal>Bar</literal>, so the compiler will emit a warning about
+ this when <option>-fwarn-incomplete-record-updates</option> is
+ enabled.</para>
+
+<programlisting>
+data Foo = Foo { x :: Int }
+ | Bar
+
+f :: Foo -> Foo
+f foo = foo { x = 6 }
+</programlisting>
+
+ <para>This option isn't enabled be default because it can be
+ very noisy, and it often doesn't indicate a bug in the
+ program.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>
<option>-fwarn-misc</option>:
<indexterm><primary><option>-fwarn-misc</option></primary></indexterm>
</varlistentry>
<varlistentry>
+ <term><option>-fwarn-orphans</option>:</term>
+ <listitem>
+ <indexterm><primary><option>-fwarn-orphans</option></primary></indexterm>
+ <indexterm><primary>orphan instances, warning</primary></indexterm>
+ <indexterm><primary>orphan rules, warning</primary></indexterm>
+
+ <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
+ 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
+ orphans is called an orphan module.</para>
+ <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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>
<option>-fwarn-overlapping-patterns</option>:
<indexterm><primary><option>-fwarn-overlapping-patterns</option></primary></indexterm>
<varlistentry>
<term>
+ <option>-fno-cse</option>
+ <indexterm><primary><option>-fno-cse</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Turns off the common-sub-expression elimination optimisation.
+ Can be useful if you have some <literal>unsafePerformIO</literal>
+ expressions that you don't want commoned-up.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<option>-fno-strictness</option>
<indexterm><primary><option>-fno-strictness</option></primary></indexterm>
</term>
<varlistentry>
<term>
- <option>-fno-cpr-analyse</option>
- <indexterm><primary><option>-fno-cpr-analyse</option></primary></indexterm>
+ <option>-fno-full-laziness</option>
+ <indexterm><primary><option>-fno-full-laziness</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Turns off the full laziness optimisation (also known as
+ let-floating). Full laziness increases sharing, which can lead
+ to increased memory residency.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-fno-state-hack</option>
+ <indexterm><primary><option>-fno-state-hack</option></primary></indexterm>
</term>
<listitem>
- <para>Turns off the CPR (constructed product result)
- analysis; it is somewhat experimental.</para>
+ <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>
</listitem>
</varlistentry>
<varlistentry>
-<term><option>-C[<us>]</option>:</term>
+<term><option>-C[<s>]</option>:</term>
<listitem>
<para>
-<indexterm><primary>-C<us> RTS option</primary></indexterm> Sets
+<indexterm><primary>-C<s> RTS option</primary></indexterm> Sets
the context switch interval to <literal><s></literal> seconds.
A context switch will occur at the next heap block allocation after
the timer expires (a heap block allocation occurs every 4k of
allocation). With <option>-C0</option> or <option>-C</option>,
context switches will occur as often as possible (at every heap block
-allocation). By default, context switches occur every 20ms
-milliseconds. Note that GHC's internal timer ticks every 20ms, and
+allocation). By default, context switches occur every 20ms. Note that GHC's internal timer ticks every 20ms, and
the context switch timer is always a multiple of this timer, so 20ms
is the maximum granularity available for timed context switches.
</para>
only)</primary></indexterm> Means to pass the like-named
option to GCC; it says to use the Version 8 SPARC
instructions, notably integer multiply and divide. The
- similiar <option>-m*</option> GCC options for SPARC also
+ similar <option>-m*</option> GCC options for SPARC also
work, actually.</para>
</listitem>
</varlistentry>
<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 teh <literal>-fglasgow-exts</literal> flag too, because
+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>
</sect1>
projects / ghc-hetmet.git / blobdiff