diff options
Diffstat (limited to 'docs/users_guide/using.xml')
| -rw-r--r-- | docs/users_guide/using.xml | 3648 |
1 files changed, 0 insertions, 3648 deletions
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml deleted file mode 100644 index 797e78485f..0000000000 --- a/docs/users_guide/using.xml +++ /dev/null @@ -1,3648 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="using-ghc"> - <title>Using GHC</title> - - <indexterm><primary>GHC, using</primary></indexterm> - <indexterm><primary>using GHC</primary></indexterm> - - <sect1> - <title>Getting started: compiling programs</title> - - <para> - In this chapter you'll find a complete reference to the GHC - command-line syntax, including all 400+ flags. It's a large and - complex system, and there are lots of details, so it can be - quite hard to figure out how to get started. With that in mind, - this introductory section provides a quick introduction to the - basic usage of GHC for compiling a Haskell program, before the - following sections dive into the full syntax. - </para> - - <para> - Let's create a Hello World program, and compile and run it. - First, create a file <filename>hello.hs</filename> containing - the Haskell code: - </para> - -<programlisting> -main = putStrLn "Hello, World!" -</programlisting> - - <para>To compile the program, use GHC like this:</para> - -<screen> -$ ghc hello.hs -</screen> - - <para>(where <literal>$</literal> represents the prompt: don't - type it). GHC will compile the source - file <filename>hello.hs</filename>, producing - an <firstterm>object - file</firstterm> <filename>hello.o</filename> and - an <firstterm>interface - file</firstterm> <filename>hello.hi</filename>, and then it - will link the object file to the libraries that come with GHC - to produce an executable called <filename>hello</filename> on - Unix/Linux/Mac, or <filename>hello.exe</filename> on - Windows.</para> - - <para> - By default GHC will be very quiet about what it is doing, only - printing error messages. If you want to see in more detail - what's going on behind the scenes, add <option>-v</option> to - the command line. - </para> - - <para> - Then we can run the program like this: - </para> - -<screen> -$ ./hello -Hello World! -</screen> - - <para> - If your program contains multiple modules, then you only need to - tell GHC the name of the source file containing - the <filename>Main</filename> module, and GHC will examine - the <literal>import</literal> declarations to find the other - modules that make up the program and find their source files. - This means that, with the exception of - the <literal>Main</literal> module, every source file should be - named after the module name that it contains (with dots replaced - by directory separators). For example, the - module <literal>Data.Person</literal> would be in the - file <filename>Data/Person.hs</filename> on Unix/Linux/Mac, - or <filename>Data\Person.hs</filename> on Windows. - </para> - </sect1> - - <sect1> - <title>Options overview</title> - - <para>GHC's behaviour is controlled by - <firstterm>options</firstterm>, which for historical reasons are - also sometimes referred to as command-line flags or arguments. - Options can be specified in three ways:</para> - - <sect2> - <title>Command-line arguments</title> - - <indexterm><primary>structure, command-line</primary></indexterm> - <indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm> - <indexterm><primary>arguments</primary><secondary>command-line</secondary></indexterm> - - <para>An invocation of GHC takes the following form:</para> - -<screen> -ghc [argument...] -</screen> - - <para>Command-line arguments are either options or file names.</para> - - <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 - foo</literal>. All options are processed and then applied to - all files; you cannot, for example, invoke <literal>ghc -c -O1 - Foo.hs -O2 Bar.hs</literal> to apply different optimisation - levels to the files <filename>Foo.hs</filename> and - <filename>Bar.hs</filename>.</para> - </sect2> - - <sect2 id="source-file-options"> - <title>Command line options in source files</title> - - <indexterm><primary>source-file options</primary></indexterm> - - <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 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 -fno-warn-name-shadowing #-} -module X where -... -</programlisting> - - <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 - 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_GHC</literal>.</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</option> and have OPTION flags in - your module, the OPTIONS_GHC will get put into the generated .hc - file).</para> - </sect2> - - <sect2> - <title>Setting options in GHCi</title> - - <para>Options may also be modified from within GHCi, using the - <literal>:set</literal> command. See <xref linkend="ghci-set"/> - for more details.</para> - </sect2> - </sect1> - - <sect1 id="static-dynamic-flags"> - <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 - <firstterm>static</firstterm>, <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 only be 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>OPTIONS_GHC</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> - - <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"> - <title>Meaningful file suffixes</title> - - <indexterm><primary>suffixes, file</primary></indexterm> - <indexterm><primary>file suffixes for GHC</primary></indexterm> - - <para>File names with “meaningful” suffixes (e.g., - <filename>.lhs</filename> or <filename>.o</filename>) cause the - “right thing” to happen to those files.</para> - - <variablelist> - - <varlistentry> - <term><filename>.hs</filename></term> - <listitem> - <para>A Haskell module.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <filename>.lhs</filename> - <indexterm><primary><literal>lhs</literal> suffix</primary></indexterm> - </term> - <listitem> - <para>A “literate Haskell” module.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.hspp</filename></term> - <listitem> - <para>A file created by the preprocessor.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.hi</filename></term> - <listitem> - <para>A Haskell interface file, probably - compiler-generated.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.hc</filename></term> - <listitem> - <para>Intermediate C file produced by the Haskell - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.c</filename></term> - <listitem> - <para>A C file not produced by the Haskell - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.ll</filename></term> - <listitem> - <para>An llvm-intermediate-language source file, usually - produced by the compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.bc</filename></term> - <listitem> - <para>An llvm-intermediate-language bitcode file, usually - produced by the compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.s</filename></term> - <listitem> - <para>An assembly-language source file, usually produced by - the compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>.o</filename></term> - <listitem> - <para>An object file, produced by an assembler.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Files with other suffixes (or without suffixes) are passed - straight to the linker.</para> - - </sect1> - - <sect1 id="modes"> - <title>Modes of operation</title> - <indexterm><primary>help options</primary></indexterm> - - <para> - GHC's behaviour is firstly controlled by a mode flag. Only one - of these flags may be given, but it does not necessarily need to - be the first option on the command-line. - </para> - - <para> - If no mode flag is present, then GHC will enter make mode - (<xref linkend="make-mode" />) if there are any Haskell source - files given on the command line, or else it will link the - objects named on the command line to produce an executable. - </para> - - <para>The available mode flags are:</para> - - <variablelist> - <varlistentry> - <term> - <cmdsynopsis><command>ghc --interactive</command> - </cmdsynopsis> - <indexterm><primary>interactive mode</primary></indexterm> - <indexterm><primary>ghci</primary></indexterm> - </term> - <listitem> - <para>Interactive mode, which is also available as - <command>ghci</command>. Interactive mode is described in - more detail in <xref linkend="ghci"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis><command>ghc --make</command> - </cmdsynopsis> - <indexterm><primary>make mode</primary></indexterm> - <indexterm><primary><option>--make</option></primary></indexterm> - </term> - <listitem> - <para>In this mode, GHC will build a multi-module Haskell - program automatically, figuring out dependencies for itself. - 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 - linkend="make-mode"/>.</para> - - <para> - This mode is the default if there are any Haskell - source files mentioned on the command line, and in this case - the <option>--make</option> option can be omitted. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis><command>ghc -e</command> - <arg choice='plain'><replaceable>expr</replaceable></arg> - </cmdsynopsis> - <indexterm><primary>eval mode</primary></indexterm> - </term> - <listitem> - <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 - on the command line. See <xref linkend="eval-mode"/> for - more details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc -E</command> - <command>ghc -C</command> - <command>ghc -S</command> - <command>ghc -c</command> - </cmdsynopsis> - <indexterm><primary><option>-E</option></primary></indexterm> - <indexterm><primary><option>-C</option></primary></indexterm> - <indexterm><primary><option>-S</option></primary></indexterm> - <indexterm><primary><option>-c</option></primary></indexterm> - </term> - <listitem> - <para>This is the traditional batch-compiler mode, in which - GHC can compile source files one at a time, or link objects - together into an executable. See <xref - linkend="options-order"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc -M</command> - </cmdsynopsis> - <indexterm><primary>dependency-generation mode</primary></indexterm> - </term> - <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 - linkend="makefile-dependencies"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --mk-dll</command> - </cmdsynopsis> - <indexterm><primary>DLL-creation mode</primary></indexterm> - </term> - <listitem> - <para>DLL-creation mode (Windows only). See <xref - linkend="win32-dlls-create"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --help</command> <command>ghc -?</command> - </cmdsynopsis> - <indexterm><primary><option>--help</option></primary></indexterm> - </term> - <listitem> - <para>Cause GHC to spew a long usage message to standard - output and then exit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <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-extensions</command> - <command>ghc --supported-languages</command> - </cmdsynopsis> - <indexterm><primary><option>--supported-extensions</option></primary><primary><option>--supported-languages</option></primary></indexterm> - </term> - <listitem> - <para>Print the supported language extensions.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --show-options</command> - </cmdsynopsis> - <indexterm><primary><option>--show-options</option></primary></indexterm> - </term> - <listitem> - <para>Print the supported command line options. This flag can be used for autocompletion in a shell.</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> - </term> - <listitem> - <para>Print a one-line string including GHC's version number.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --numeric-version</command> - </cmdsynopsis> - <indexterm><primary><option>--numeric-version</option></primary></indexterm> - </term> - <listitem> - <para>Print GHC's numeric version number only.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <cmdsynopsis> - <command>ghc --print-libdir</command> - </cmdsynopsis> - <indexterm><primary><option>--print-libdir</option></primary></indexterm> - </term> - <listitem> - <para>Print the path to GHC's library directory. This is - the top of the directory tree containing GHC's libraries, - 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> - </listitem> - </varlistentry> - - </variablelist> - - <sect2 id="make-mode"> - <title>Using <command>ghc</command> <option>--make</option></title> - <indexterm><primary><option>--make</option></primary></indexterm> - <indexterm><primary>separate compilation</primary></indexterm> - - <para>In this mode, GHC will build a multi-module Haskell program by following - 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 - program like this:</para> - -<screen> -ghc --make Main.hs -</screen> - - <para> - In fact, GHC enters make mode automatically if there are any - Haskell source files on the command line and no other mode is - specified, so in this case we could just type - </para> - -<screen> -ghc Main.hs -</screen> - - <para>Any number of source file names or module names may be - specified; 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, the - program will also be linked into an executable.</para> - - <para>The main advantages to using <literal>ghc - --make</literal> over traditional - <literal>Makefile</literal>s are:</para> - - <itemizedlist> - <listitem> - <para>GHC doesn't have to be restarted for each compilation, - which means it can cache information between compilations. - 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> - </listitem> - <listitem> - <para>You don't have to write a <literal>Makefile</literal>.</para> - <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary></indexterm> - </listitem> - <listitem> - <para>GHC re-calculates the dependencies each time it is - invoked, so the dependencies never get out of sync with the - source.</para> - </listitem> - <listitem> - <para>Using the <literal>-j</literal> flag, you can compile - modules in parallel. Specify <literal>-jN</literal> to - compile <replaceable>N</replaceable> jobs in parallel.</para> - </listitem> - </itemizedlist> - - <para>Any of the command-line options described in the rest of - this chapter can be used with - <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_GHC</literal> - pragma (see <xref linkend="source-file-options"/>).</para> - - <para>If the program needs to be linked with additional objects - (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> - - <para>For backward compatibility with existing make scripts, when - used in combination with <option>-c</option>, the linking phase - is omitted (same as <option>--make</option> - <option>-no-link</option>).</para> - - <para>Note that GHC can only follow dependencies if it has the - source file available, so if your program includes a module for - which there is no source file, even if you have an object and an - interface file for the module, then GHC will complain. The - exception to this rule is for package modules, which may or may - not have source files.</para> - - <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 - linkend="search-path"/>).</para> - </sect2> - - <sect2 id="eval-mode"> - <title>Expression evaluation mode</title> - - <para>This mode is very similar to interactive mode, except that - there is a single expression to evaluate which is specified on - the command line as an argument to the <option>-e</option> - option:</para> - -<screen> -ghc -e <replaceable>expr</replaceable> -</screen> - - <para>Haskell source files may be named on the command line, and - they will be loaded exactly as in interactive mode. The - expression is evaluated in the context of the loaded - modules.</para> - - <para>For example, to load and run a Haskell program containing - a module <literal>Main</literal>, we might say</para> - -<screen> -ghc -e Main.main Main.hs -</screen> - - <para>or we can just use this mode to evaluate expressions in - the context of the <literal>Prelude</literal>:</para> - -<screen> -$ ghc -e "interact (unlines.map reverse.lines)" -hello -olleh -</screen> - </sect2> - - <sect2 id="options-order"> - <title>Batch compiler mode</title> - - <para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files - given on the command line.</para> - - <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 to linking. - This table summarises:</para> - - <informaltable> - <tgroup cols="4"> - <colspec align="left"/> - <colspec align="left"/> - <colspec align="left"/> - <colspec align="left"/> - - <thead> - <row> - <entry>Phase of the compilation system</entry> - <entry>Suffix saying “start here”</entry> - <entry>Flag saying “stop after”</entry> - <entry>(suffix of) output file</entry> - </row> - </thead> - <tbody> - <row> - <entry>literate pre-processor</entry> - <entry><literal>.lhs</literal></entry> - <entry>-</entry> - <entry><literal>.hs</literal></entry> - </row> - - <row> - <entry>C pre-processor (opt.) </entry> - <entry><literal>.hs</literal> (with - <option>-cpp</option>)</entry> - <entry><option>-E</option></entry> - <entry><literal>.hspp</literal></entry> - </row> - - <row> - <entry>Haskell compiler</entry> - <entry><literal>.hs</literal></entry> - <entry><option>-C</option>, <option>-S</option></entry> - <entry><literal>.hc</literal>, <literal>.s</literal></entry> - </row> - - <row> - <entry>C compiler (opt.)</entry> - <entry><literal>.hc</literal> or <literal>.c</literal></entry> - <entry><option>-S</option></entry> - <entry><literal>.s</literal></entry> - </row> - - <row> - <entry>assembler</entry> - <entry><literal>.s</literal></entry> - <entry><option>-c</option></entry> - <entry><literal>.o</literal></entry> - </row> - - <row> - <entry>linker</entry> - <entry><replaceable>other</replaceable></entry> - <entry>-</entry> - <entry><filename>a.out</filename></entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <indexterm><primary><option>-C</option></primary></indexterm> - <indexterm><primary><option>-E</option></primary></indexterm> - <indexterm><primary><option>-S</option></primary></indexterm> - <indexterm><primary><option>-c</option></primary></indexterm> - - <para>Thus, a common invocation would be: </para> - -<screen> -ghc -c Foo.hs -</screen> - - <para>to compile the Haskell source file - <filename>Foo.hs</filename> to an object file - <filename>Foo.o</filename>.</para> - - <para>Note: What the Haskell compiler proper produces depends on what - backend code generator is used. See <xref linkend="code-generators"/> - for more details.</para> - - <para>Note: C pre-processing is optional, the - <option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm> - flag turns it on. See <xref linkend="c-pre-processor"/> for more - details.</para> - - <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.</para> - - <para>Note: The option <option>-C</option> is only available when - GHC is built in unregisterised mode. See <xref linkend="unreg"/> - for more details.</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 overridden 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> - - <sect1 id="options-help"> - <title>Verbosity options</title> - - <indexterm><primary>verbosity options</primary></indexterm> - - <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> - <option>-v</option> - <indexterm><primary><option>-v</option></primary></indexterm> - </term> - <listitem> - <para>The <option>-v</option> option makes GHC - <emphasis>verbose</emphasis>: it reports its version number - and shows (on stderr) exactly how it invokes each phase of - the compilation system. Moreover, it passes the - <option>-v</option> flag to most phases; each reports its - version number (and possibly some other information).</para> - - <para>Please, oh please, use the <option>-v</option> option - when reporting bugs! Knowing that you ran the right bits in - the right order is always the first thing we want to - verify.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-v</option><replaceable>n</replaceable> - <indexterm><primary><option>-v</option></primary></indexterm> - </term> - <listitem> - <para>To provide more control over the compiler's verbosity, - the <option>-v</option> flag takes an optional numeric - argument. Specifying <option>-v</option> on its own is - equivalent to <option>-v3</option>, and the other levels - have the following meanings:</para> - - <variablelist> - <varlistentry> - <term><option>-v0</option></term> - <listitem> - <para>Disable all non-essential messages (this is the - default).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v1</option></term> - <listitem> - <para>Minimal verbosity: print one line per - compilation (this is the default when - <option>--make</option> or - <option>--interactive</option> is on).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v2</option></term> - <listitem> - <para>Print the name of each compilation phase as it - is executed. (equivalent to - <option>-dshow-passes</option>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v3</option></term> - <listitem> - <para>The same as <option>-v2</option>, except that in - addition the full command line (if appropriate) for - each compilation phase is also printed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-v4</option></term> - <listitem> - <para>The same as <option>-v3</option> except that the - intermediate program representation after each - compilation phase is also printed (excluding - preprocessed and C/assembly files).</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--fprint-potential-instances</option> - <indexterm><primary><option>-fprint-potential-instances</option></primary></indexterm> - </term> - <listitem> - <para>When GHC can't find an instance for a class, it displays a short list of some - in the instances it knows about. With this flag it prints <emphasis>all</emphasis> - the instances it knows about. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-fprint-explicit-foralls, -fprint-explicit-kinds, -fprint-unicode-syntax</option> - <indexterm><primary><option>-fprint-explicit-foralls</option></primary></indexterm> - <indexterm><primary><option>-fprint-explicit-kinds</option></primary></indexterm> - <indexterm><primary><option>-fprint-unicode-syntax</option></primary></indexterm> - </term> - <listitem> - <para>These three flags control the way in which GHC displays types, in error messages and in GHCi. - Using <option>-fprint-explicit-foralls</option> makes GHC print explicit <literal>forall</literal> - quantification at the top level of a type; normally this is suppressed. For example, in GHCi: -<screen> -ghci> let f x = x -ghci> :t f -f :: a -> a -ghci> :set -fprint-explicit-foralls -ghci> :t f -f :: forall a. a -> a -</screen> -However, regardless of the flag setting, the quantifiers are printed under these circumstances: -<itemizedlist> -<listitem><para>For nested <literal>foralls</literal>, e.g. -<screen> -ghci> :t GHC.ST.runST -GHC.ST.runST :: (forall s. GHC.ST.ST s a) -> a -</screen> -</para></listitem> -<listitem><para>If any of the quantified type variables has a kind -that mentions a kind variable, e.g. -<screen> -ghci> :i Data.Type.Equality.sym -Data.Type.Equality.sym :: - forall (k :: BOX) (a :: k) (b :: k). - (a Data.Type.Equality.:~: b) -> b Data.Type.Equality.:~: a - -- Defined in Data.Type.Equality -</screen> -</para></listitem> -</itemizedlist> - </para> - <para> - Using <option>-fprint-explicit-kinds</option> makes GHC print kind arguments - in types, which are normally suppressed. This can be important when you are using kind polymorphism. - For example: -<screen> -ghci> :set -XPolyKinds -ghci> data T a = MkT -ghci> :t MkT -MkT :: forall (k :: BOX) (a :: k). T a -ghci> :set -fprint-explicit-foralls -ghci> :t MkT -MkT :: forall (k :: BOX) (a :: k). T k a -</screen> - </para> - <para> - When <option>-fprint-unicode-syntax</option> is enabled, GHC prints type signatures using - the unicode symbols from the <option>-XUnicodeSyntax</option> extension. -<screen> -ghci> :set -fprint-unicode-syntax -ghci> :t (>>) -(>>) :: ∀ (m :: * → *) a b. Monad m ⇒ m a → m b → m b -</screen> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fprint-expanded-synonyms</option> - <indexterm><primary><option>-fprint-expanded-synonyms</option></primary></indexterm> - </term> - <listitem> - <para> - When enabled, GHC also prints type-synonym-expanded types in type - errors. - - For example, with this type synonyms: - -<screen> -type Foo = Int -type Bar = Bool -type MyBarST s = ST s Bar -</screen> - - This error message: - -<screen> -Couldn't match type 'Int' with 'Bool' -Expected type: ST s Foo - Actual type: MyBarST s -</screen> - - Becomes this: - -<screen> -Couldn't match type 'Int' with 'Bool' -Expected type: ST s Foo - Actual type: MyBarST s -Type synonyms expanded: -Expected type: ST s Int - Actual type: ST s Bool -</screen> - </para> - </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> - - <varlistentry> - <term><option>-H</option><replaceable>size</replaceable> - <indexterm><primary><option>-H</option></primary></indexterm> - </term> - <listitem> - <para>Set the minimum size of the heap to - <replaceable>size</replaceable>. - This option is equivalent to - <literal>+RTS -H<replaceable>size</replaceable></literal>, - see <xref linkend="rts-options-gc" />. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-Rghc-timing</option> - <indexterm><primary><option>-Rghc-timing</option></primary></indexterm> - </term> - <listitem> - <para>Prints a one-line summary of timing statistics for the - GHC run. This option is equivalent to - <literal>+RTS -tstderr</literal>, see <xref - linkend="rts-options-gc" />. - </para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - &separate; - - <sect1 id="options-sanity"> - <title>Warnings and sanity-checking</title> - - <indexterm><primary>sanity-checking options</primary></indexterm> - <indexterm><primary>warnings</primary></indexterm> - - - <para>GHC has a number of options that select which types of - non-fatal error messages, otherwise known as warnings, can be - generated during compilation. By default, you get a standard set - of warnings which are generally likely to indicate bugs in your - program. These are: - <option>-fwarn-overlapping-patterns</option>, - <option>-fwarn-warnings-deprecations</option>, - <option>-fwarn-deprecated-flags</option>, - <option>-fwarn-unrecognised-pragmas</option>, - <option>-fwarn-missed-specialisations</option>, - <option>-fwarn-duplicate-constraints</option>, - <option>-fwarn-duplicate-exports</option>, - <option>-fwarn-overflowed-literals</option>, - <option>-fwarn-empty-enumerations</option>, - <option>-fwarn-missing-fields</option>, - <option>-fwarn-missing-methods</option>, - <option>-fwarn-wrong-do-bind</option>, - <option>-fwarn-unsupported-calling-conventions</option>, - <option>-fwarn-dodgy-foreign-imports</option>, - <option>-fwarn-inline-rule-shadowing</option>, - <option>-fwarn-unsupported-llvm-version</option>, - <option>-fwarn-context-quantification</option>, and - <option>-fwarn-tabs</option>. - The following flags are simple ways to select standard - “packages” of warnings: - </para> - - <variablelist> - - <varlistentry> - <term><option>-W</option>:</term> - <listitem> - <indexterm><primary>-W option</primary></indexterm> - <para>Provides the standard warnings plus - <option>-fwarn-unused-binds</option>, - <option>-fwarn-unused-matches</option>, - <option>-fwarn-unused-imports</option>, - <option>-fwarn-incomplete-patterns</option>, - <option>-fwarn-dodgy-exports</option>, and - <option>-fwarn-dodgy-imports</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-Wall</option>:</term> - <listitem> - <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-incomplete-uni-patterns</option>, - <option>-fwarn-incomplete-record-updates</option>, - <option>-fwarn-monomorphism-restriction</option>, - <option>-fwarn-auto-orphans</option>, - <option>-fwarn-implicit-prelude</option>, - <option>-fwarn-missing-local-sigs</option>, - <option>-fwarn-missing-exported-sigs</option>, - <option>-fwarn-missing-import-lists</option> and - <option>-fwarn-identities</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-w</option>:</term> - <listitem> - <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> - - <varlistentry> - <term><option>-Werror</option>:</term> - <listitem> - <indexterm><primary><option>-Werror</option></primary></indexterm> - <para>Makes any warning into a fatal error. Useful so that you don't - miss warnings when doing batch compilation. </para> - </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 - off any warning, simply give the corresponding - <option>-fno-warn-...</option> option on the command line.</para> - - <variablelist> - - <varlistentry> - <term><option>-fwarn-typed-holes</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-typed-holes</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para> - Determines whether the compiler reports typed holes warnings. Has - no effect unless typed holes errors are deferred until runtime. - See <xref linkend="typed-holes"/> and <xref linkend="defer-type-errors"/> - </para> - - <para>This warning is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-type-errors</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-type-errors</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para>Causes a warning to be reported when a type error is deferred - until runtime. See <xref linkend="defer-type-errors"/></para> - <para>This warning is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fdefer-type-errors</option>:</term> - <listitem> - <indexterm><primary><option>-fdefer-type-errors</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para>Defer as many type errors as possible until runtime. - At compile time you get a warning (instead of an error). At - runtime, if you use a value that depends on a type error, you - get a runtime error; but you can run any type-correct parts of your code - just fine. See <xref linkend="defer-type-errors"/></para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fdefer-typed-holes</option>:</term> - <listitem> - <indexterm><primary><option>-fdefer-typed-holes</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para> - Defer typed holes errors until runtime. This will turn the errors - produced by <link linked="typed-holes">typed holes</link> into - warnings. Using a value that depends on a typed hole produces a - runtime error, the same as <option>-fdefer-type-errors</option> - (which implies this option). See <xref linkend="typed-holes"/> - and <xref linkend="defer-type-errors"/>. - </para> - <para> - Implied by <option>-fdefer-type-errors</option>. See also - <option>-fwarn-typed-holes</option>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-partial-type-signatures</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-partial-type-signatures</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para> - Determines whether the compiler reports holes in partial type - signatures as warnings. Has no effect unless - <option>-XPartialTypeSignatures</option> is enabled, which - controls whether errors should be generated for holes in types - or not. See <xref linkend="partial-type-signatures"/>. - </para> - - <para>This warning is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fhelpful-errors</option>:</term> - <listitem> - <indexterm><primary><option>-fhelpful-errors</option></primary> - </indexterm> - <indexterm><primary>warnings</primary></indexterm> - <para>When a name or package is not found in scope, make - suggestions for the name or package you might have meant instead.</para> - <para>This option is on by default.</para> - </listitem> - </varlistentry> - - <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-missed-specialisations</option>, <option>-fwarn-all-missed-specialisations</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-missed-specialisations</option></primary></indexterm> - <indexterm><primary><option>-fwarn-all-missed-specialisations</option></primary></indexterm> - <indexterm><primary>warnings</primary></indexterm> - <indexterm><primary>pragmas</primary></indexterm> - <para>Emits a warning if GHC cannot specialise a function that is - imported and overloaded, usually because the function needs an - <literal>INLINEABLE</literal> pragma.. The "all" form reports all - such situations. The "non-all" form only reports when the situation - arises during specialisation of an imported function; presumably teh latter - was marked <literal>INLINEABLE</literal> so that it would specialise - but if it, in turn, calls other functions that are not specialised - you won't get the performance boost you expect.</para> - - <para><option>-fwarn-missed-specialisations</option> is on by default; - <option>-fwarn-all-missed-specialisations</option> is implied by <option>-Wall</option>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-warnings-deprecations</option>:</term> - <listitem> - <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 - 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-amp</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-amp</option></primary> - </indexterm> - <indexterm><primary>amp</primary></indexterm> - <indexterm><primary>applicative-monad proposal</primary></indexterm> - <para>Causes a warning to be emitted when a definition - is in conflict with the AMP (Applicative-Monad proosal), - namely: - 1. Instance of Monad without Applicative; - 2. Instance of MonadPlus without Alternative; - 3. Custom definitions of join/pure/<*></para> - - <para>This option is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-deprecated-flags</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-deprecated-flags</option></primary> - </indexterm> - <indexterm><primary>deprecated-flags</primary></indexterm> - <para>Causes a warning to be emitted when a deprecated - command-line flag is used.</para> - - <para>This option is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unsupported-calling-conventions</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unsupported-calling-conventions</option></primary> - </indexterm> - <para>Causes a warning to be emitted for foreign declarations - that use unsupported calling conventions. In particular, - if the <literal>stdcall</literal> calling convention is used - on an architecture other than i386 then it will be treated - as <literal>ccall</literal>.</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-exports</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-dodgy-exports</option></primary> - </indexterm> - <para>Causes a warning to be emitted when a datatype - <literal>T</literal> is exported - with all constructors, i.e. <literal>T(..)</literal>, but is it - just a type synonym.</para> - <para>Also causes a warning to be emitted when a module is - re-exported, but that module exports nothing.</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 in the following cases:</para> - <itemizedlist> - <listitem> - <para>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> - </listitem> - <listitem> - <para>When an <literal>import</literal> statement hides an - entity that is not exported.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-overflowed-literals</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-overflowed-literals</option></primary> - </indexterm> - <para> - Causes a warning to be emitted if a literal will overflow, - e.g. <literal>300 :: Word8</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-empty-enumerations</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-empty-enumerations</option></primary> - </indexterm> - <para> - Causes a warning to be emitted if an enumeration is - empty, e.g. <literal>[5 .. 3]</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-lazy-unlifted-bindings</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-lazy-unlifted-bindings</option></primary> - </indexterm> - <para>This flag is a no-op, and will be removed in GHC 7.10.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-duplicate-constraints</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-duplicate-constraints</option></primary></indexterm> - <indexterm><primary>duplicate constraints, warning</primary></indexterm> - - <para>Have the compiler warn about duplicate constraints in a type signature. For - example - <programlisting> - f :: (Eq a, Show a, Eq a) => a -> a - </programlisting> - The warning will indicate the duplicated <literal>Eq a</literal> constraint. - </para> - - <para>This option is now deprecated in favour of <option>-fwarn-redundant-constraints</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-redundant-constraints</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-redundant-constraints</option></primary></indexterm> - <indexterm><primary>redundant constraints, warning</primary></indexterm> - - <para>Have the compiler warn about redundant constraints in a type signature. - In particular: - <itemizedlist> - <listitem><para> - A redundant constraint within the type signature itself: - <programlisting> - f :: (Eq a, Ord a) => a -> a - </programlisting> - The warning will indicate the redundant <literal>Eq a</literal> constraint: - it is subsumed by the <literal>Ord a</literal> constraint. - </para></listitem> - <listitem><para> - A constraint in the type signature is not used in the code it covers: - <programlisting> - f :: Eq a => a -> a -> Bool - f x y = True - </programlisting> - The warning will indicate the redundant <literal>Eq a</literal> constraint: - : it is not used by the definition of <literal>f</literal>.) - </para></listitem> - </itemizedlist> - Similar warnings are given for a redundant constraint in an instance declaration. - </para> - <para>This option is on by default. As usual you can suppress it on a per-module basis - with <option>-fno-warn-redundant-constraints</option>. Occasionally you may specifically - want a function to have a more constrained signature than necessary, perhaps to - leave yourself wiggle-room for changing the implementation without changing the - API. In that case, you can suppress the warning on a per-function basis, using a - call in a dead binding. For example: - <programlisting> - f :: Eq a => a -> a -> Bool - f x y = True - where - _ = x == x -- Suppress the redundant-constraint warning for (Eq a) - </programlisting> - Here the call to <literal>(==)</literal> makes GHC think that the <literal>(Eq a)</literal> - constraint is needed, so no warning is issued. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-duplicate-exports</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-duplicate-exports</option></primary></indexterm> - <indexterm><primary>duplicate exports, warning</primary></indexterm> - <indexterm><primary>export lists, duplicates</primary></indexterm> - - <para>Have the compiler warn about duplicate entries in - export lists. This is useful information if you maintain - large export lists, and want to avoid the continued export - of a definition after you've deleted (one) mention of it in - the export list.</para> - - <para>This option is on by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-hi-shadowing</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-hi-shadowing</option></primary></indexterm> - <indexterm><primary>shadowing</primary> - <secondary>interface files</secondary></indexterm> - - <para>Causes the compiler to emit a warning when a module or - interface file in the current directory is shadowing one - with the same module name in a library or other - directory.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-identities</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-identities</option></primary></indexterm> - <para>Causes the compiler to emit a warning when a Prelude numeric - conversion converts a type T to the same type T; such calls - are probably no-ops and can be omitted. The functions checked for - are: <literal>toInteger</literal>, - <literal>toRational</literal>, - <literal>fromIntegral</literal>, - and <literal>realToFrac</literal>. - </para> - </listitem> - </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>-XNoImplicitPrelude</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>-XNoImplicitPrelude</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>, - <option>-fwarn-incomplete-uni-patterns</option>: - </term> - <listitem> - <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm> - <indexterm><primary><option>-fwarn-incomplete-uni-patterns</option></primary></indexterm> - <indexterm><primary>incomplete patterns, warning</primary></indexterm> - <indexterm><primary>patterns, incomplete</primary></indexterm> - - <para>The option <option>-fwarn-incomplete-patterns</option> warns - about places where - a pattern-match might fail at runtime. - The function - <function>g</function> below will fail when applied to - non-empty lists, so the compiler will emit a warning about - this when <option>-fwarn-incomplete-patterns</option> is - enabled. - -<programlisting> -g [] = 2 -</programlisting> - - 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, and it is switched - on by <option>-W</option>.</para> - - <para>The flag <option>-fwarn-incomplete-uni-patterns</option> is - similar, except that it - applies only to lambda-expressions and pattern bindings, constructs - that only allow a single pattern: - -<programlisting> -h = \[] -> 2 -Just k = f y -</programlisting> - - </para> - </listitem> - </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 by 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-missing-fields</option>: - <indexterm><primary><option>-fwarn-missing-fields</option></primary></indexterm> - <indexterm><primary>missing fields, warning</primary></indexterm> - <indexterm><primary>fields, missing</primary></indexterm> - </term> - <listitem> - - <para>This option is on by default, and warns you whenever - the construction of a labelled field constructor isn't - complete, missing initialisers for one or more fields. While - not an error (the missing fields are initialised with - bottoms), it is often an indication of a programmer error.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fwarn-missing-import-lists</option>: - <indexterm><primary><option>-fwarn-import-lists</option></primary></indexterm> - <indexterm><primary>missing import lists, warning</primary></indexterm> - <indexterm><primary>import lists, missing</primary></indexterm> - </term> - <listitem> - - <para>This flag warns if you use an unqualified - <literal>import</literal> declaration - that does not explicitly list the entities brought into scope. For - example - </para> - -<programlisting> -module M where - import X( f ) - import Y - import qualified Z - p x = f x x -</programlisting> - - <para> - The <option>-fwarn-import-lists</option> flag will warn about the import - of <literal>Y</literal> but not <literal>X</literal> - If module <literal>Y</literal> is later changed to export (say) <literal>f</literal>, - then the reference to <literal>f</literal> in <literal>M</literal> will become - ambiguous. No warning is produced for the import of <literal>Z</literal> - because extending <literal>Z</literal>'s exports would be unlikely to produce - ambiguity in <literal>M</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-missing-methods</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-missing-methods</option></primary></indexterm> - <indexterm><primary>missing methods, warning</primary></indexterm> - <indexterm><primary>methods, missing</primary></indexterm> - - <para>This option is on by default, and warns you whenever - an instance declaration is missing one or more methods, and - the corresponding class declaration has no default - declaration for them.</para> - <para>The warning is suppressed if the method name - begins with an underscore. Here's an example where this is useful: - <programlisting> - class C a where - _simpleFn :: a -> String - complexFn :: a -> a -> String - complexFn x y = ... _simpleFn ... - </programlisting> - The idea is that: (a) users of the class will only call <literal>complexFn</literal>; - never <literal>_simpleFn</literal>; and (b) - instance declarations can define either <literal>complexFn</literal> or <literal>_simpleFn</literal>. - </para> - <para>The MINIMAL pragma can be used to change which combination of methods will be required for instances of a particular class. See <xref linkend="minimal-pragma"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-missing-signatures</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-missing-signatures</option></primary></indexterm> - <indexterm><primary>type signatures, missing</primary></indexterm> - - <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. As part of - the warning GHC also reports the inferred type. The - option is off by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-missing-exported-sigs</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-missing-exported-sigs</option></primary></indexterm> - <indexterm><primary>type signatures, missing</primary></indexterm> - - <para>If you would like GHC to check that every exported top-level - function/value has a type signature, but not check unexported values, use the - <option>-fwarn-missing-exported-sigs</option> option. This option - takes precedence over <option>-fwarn-missing-signatures</option>. - As part of the warning GHC also reports the inferred type. The - option is off by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-missing-local-sigs</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-missing-local-sigs</option></primary></indexterm> - <indexterm><primary>type signatures, missing</primary></indexterm> - - <para>If you use the - <option>-fwarn-missing-local-sigs</option> flag GHC will warn - you about any polymorphic local bindings. As part of - the warning GHC also reports the inferred type. The - option is off by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-name-shadowing</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-name-shadowing</option></primary></indexterm> - <indexterm><primary>shadowing, warning</primary></indexterm> - - <para>This option causes a warning to be emitted whenever an - 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 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> - - <varlistentry> - <term><option>-fwarn-orphans, -fwarn-auto-orphans</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-orphans</option></primary></indexterm> - <indexterm><primary><option>-fwarn-auto-orphans</option></primary></indexterm> - <indexterm><primary>orphan instances, warning</primary></indexterm> - <indexterm><primary>orphan rules, warning</primary></indexterm> - - <para>These flags cause a warning to be emitted whenever the - module contains an "orphan" instance declaration or rewrite rule. - 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 - 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. See <xref linkend="orphan-modules"/> for details. - </para> - <para>The flag <option>-fwarn-orphans</option> warns about user-written - orphan rules or instances. The flag <option>-fwarn-auto-orphans</option> - warns about automatically-generated orphan rules, notably as a result of - specialising functions, for type classes (<literal>Specialise</literal>) - or argument values (<literal>-fspec-constr</literal>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fwarn-overlapping-patterns</option>: - <indexterm><primary><option>-fwarn-overlapping-patterns</option></primary></indexterm> - <indexterm><primary>overlapping patterns, warning</primary></indexterm> - <indexterm><primary>patterns, overlapping</primary></indexterm> - </term> - <listitem> - <para>By default, the compiler will warn you if a set of - patterns are overlapping, e.g.,</para> - -<programlisting> -f :: String -> Int -f [] = 0 -f (_:xs) = 1 -f "2" = 2 -</programlisting> - - <para>where the last pattern match in <function>f</function> - 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> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-tabs</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-tabs</option></primary></indexterm> - <indexterm><primary>tabs, warning</primary></indexterm> - <para>Have the compiler warn if there are tabs in your source - file.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-type-defaults</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-type-defaults</option></primary></indexterm> - <indexterm><primary>defaulting mechanism, warning</primary></indexterm> - <para>Have the compiler warn/inform you where in your source - 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 - otherwise unconstrained value <constant>1</constant> to be - given the type <literal>Int</literal>, whereas Haskell 98 - and later - defaults it to <literal>Integer</literal>. This may lead to - differences in performance and behaviour, hence the - usefulness of being non-silent about this.</para> - - <para>This warning is off by default.</para> - </listitem> - </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-unticked-promoted-constructors</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unticked-promoted-constructors</option></primary></indexterm> - <indexterm><primary>promoted constructor, warning</primary></indexterm> - <para>Warn if a promoted data constructor is used without a tick preceding it's name. - </para> - <para>For example: - </para> -<programlisting> -data Nat = Succ Nat | Zero - -data Vec n s where - Nil :: Vec Zero a - Cons :: a -> Vec n a -> Vec (Succ n) a -</programlisting> - <para> Will raise two warnings because <function>Zero</function> - and <function>Succ</function> are not written as <function>'Zero</function> and - <function>'Succ</function>. - </para> - <para>This warning is is enabled by default in <literal>-Wall</literal> mode.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-binds</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-binds</option></primary></indexterm> - <indexterm><primary>unused binds, warning</primary></indexterm> - <indexterm><primary>binds, unused</primary></indexterm> - <para>Report any function definitions (and local bindings) which are unused. An alias for - <itemizedlist> - <listitem><option>-fwarn-unused-top-binds</option></listitem> - <listitem><option>-fwarn-unused-local-binds</option></listitem> - <listitem><option>-fwarn-unused-pattern-binds</option></listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-top-binds</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-top-binds</option></primary></indexterm> - <indexterm><primary>unused binds, warning</primary></indexterm> - <indexterm><primary>binds, unused</primary></indexterm> - <para>Report any function definitions which are unused.</para> - - <para>More precisely, warn if a binding brings into scope a variable that is not used, - except if the variable's name starts with an underscore. The "starts-with-underscore" - condition provides a way to selectively disable the warning. - </para> - <para> - A variable is regarded as "used" if - <itemizedlist> - <listitem><para>It is exported, or</para></listitem> - <listitem><para>It appears in the right hand side of a binding that binds at - least one used variable that is used</para></listitem> - </itemizedlist> - For example - <programlisting> -module A (f) where -f = let (p,q) = rhs1 in t p -- No warning: q is unused, but is locally bound -t = rhs3 -- No warning: f is used, and hence so is t -g = h x -- Warning: g unused -h = rhs2 -- Warning: h is only used in the right-hand side of another unused binding -_w = True -- No warning: _w starts with an underscore - </programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-local-binds</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-local-binds</option></primary></indexterm> - <indexterm><primary>unused binds, warning</primary></indexterm> - <indexterm><primary>binds, unused</primary></indexterm> - <para>Report any local definitions which are unused. For example - <programlisting> -module A (f) where -f = let (p,q) = rhs1 in t p -- Warning: q is unused -g = h x -- No warning: g is unused, but is a top-level binding - </programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-pattern-binds</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-pattern-binds</option></primary></indexterm> - <indexterm><primary>unused binds, warning</primary></indexterm> - <indexterm><primary>binds, unused</primary></indexterm> - <para> - Warn if a pattern binding binds no variables at all, unless it is a lone, possibly-banged, wild-card pattern. - For example: - <programlisting> -Just _ = rhs3 -- Warning: unused pattern binding -(_, _) = rhs4 -- Warning: unused pattern binding -_ = rhs3 -- No warning: lone wild-card pattern -!_ = rhs4 -- No warning: banged wild-card pattern; behaves like seq - </programlisting> - The motivation for allowing lone wild-card patterns is they - are not very different from <literal>_v = rhs3</literal>, - which elicits no warning; and they can be useful to add a type - constraint, e.g. <literal>_ = x::Int</literal>. A lone - banged wild-card pattern is useful as an alternative - (to <literal>seq</literal>) way to force evaluation. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-imports</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-imports</option></primary></indexterm> - <indexterm><primary>unused imports, warning</primary></indexterm> - <indexterm><primary>imports, unused</primary></indexterm> - - <para>Report any modules that are explicitly imported but - never used. However, the form <literal>import M()</literal> is - never reported as an unused import, because it is a useful idiom - for importing instance declarations, which are anonymous in Haskell.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-fwarn-unused-matches</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-unused-matches</option></primary></indexterm> - <indexterm><primary>unused matches, warning</primary></indexterm> - <indexterm><primary>matches, unused</primary></indexterm> - - <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 - <varname>x</varname> and <varname>y</varname> as unused. The - warning is suppressed if the variable name begins with an underscore, thus: - <programlisting> - f _x = True - </programlisting> - </para> - </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 occurring 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-context-quantification</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-context-quantification</option></primary></indexterm> - <indexterm><primary>implicit context quantification, warning</primary></indexterm> - <indexterm><primary>context, implicit quantification</primary></indexterm> - - <para>Report if a variable is quantified only due to its presence - in a context (see <xref linkend="universal-quantification"/>). For example, - <programlisting> - type T a = Monad m => a -> f a - </programlisting> - It is recommended to write this polymorphic type as - <programlisting> - type T a = forall m. Monad m => a -> f a - </programlisting> - instead. - </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 occurring 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> - - <varlistentry> - <term><option>-fwarn-inline-rule-shadowing</option>:</term> - <listitem> - <indexterm><primary><option>-fwarn-inline-rule-shadowing</option></primary></indexterm> - <para>Warn if a rewrite RULE might fail to fire because the function might be - inlined before the rule has a chance to fire. See <xref linkend="rules-inline"/>. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para>If you're feeling really paranoid, the - <option>-dcore-lint</option> - option<indexterm><primary><option>-dcore-lint</option></primary></indexterm> - is a good choice. It turns on heavyweight intra-pass - sanity-checking within GHC. (It checks GHC's sanity, not - yours.)</para> - - </sect1> - - &packages; - - <sect1 id="options-optimise"> - <title>Optimisation (code improvement)</title> - - <indexterm><primary>optimisation</primary></indexterm> - <indexterm><primary>improvement, code</primary></indexterm> - - <para>The <option>-O*</option> options specify convenient - “packages” of optimisation flags; the - <option>-f*</option> options described later on specify - <emphasis>individual</emphasis> optimisations to be turned on/off; - the <option>-m*</option> options specify - <emphasis>machine-specific</emphasis> optimisations to be turned - on/off.</para> - - <para>Most of these options are boolean and have options to turn them both - “on” and “off” (beginning with the prefix - <option>no-</option>). For instance, while <option>-fspecialise</option> - enables specialisation, <option>-fno-specialise</option> disables it. When - multiple flags for the same option appear in the command-line they are - evaluated from left to right. For instance <option>-fno-specialise - -fspecialise</option> will enable specialisation. - </para> - - <para>It is important to note that the <option>-O*</option> flags are roughly - equivalent to combinations of <option>-f*</option> flags. For this reason, - the effect of the <option>-O*</option> and <option>-f*</option> flags is - dependent upon the order in which they occur on the command line. - </para> - - <para>For instance, take the example of <option>-fno-specialise - -O1</option>. Despite the <option>-fno-specialise</option> appearing in the - command line, specialisation will still be enabled. This is the case - as <option>-O1</option> implies <option>-fspecialise</option>, overriding - the previous flag. By contrast, <option>-O1 -fno-specialise</option> will - compile without specialisation, as one would expect. - </para> - - <sect2 id="optimise-pkgs"> - <title><option>-O*</option>: convenient “packages” of optimisation flags.</title> - - <para>There are <emphasis>many</emphasis> options that affect - the quality of code produced by GHC. Most people only have a - general goal, something like “Compile quickly” or - “Make my program run like greased lightning.” The - following “packages” of optimisations (or lack - thereof) should suffice.</para> - - <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 reason to stick to - no-optimisation when developing code.</para> - - <variablelist> - - <varlistentry> - <term> - No <option>-O*</option>-type option specified: - <indexterm><primary>-O* not specified</primary></indexterm> - </term> - <listitem> - <para>This is taken to mean: “Please compile - quickly; I'm not over-bothered about compiled-code - quality.” So, for example: <command>ghc -c - Foo.hs</command></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-O0</option>: - <indexterm><primary><option>-O0</option></primary></indexterm> - </term> - <listitem> - <para>Means “turn off all optimisation”, - reverting to the same settings as if no - <option>-O</option> options had been specified. Saying - <option>-O0</option> can be useful if - eg. <command>make</command> has inserted a - <option>-O</option> on the command line already.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-O</option> or <option>-O1</option>: - <indexterm><primary>-O option</primary></indexterm> - <indexterm><primary>-O1 option</primary></indexterm> - <indexterm><primary>optimise</primary><secondary>normally</secondary></indexterm> - </term> - <listitem> - <para>Means: “Generate good-quality code without - taking too long about it.” Thus, for example: - <command>ghc -c -O Main.lhs</command></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-O2</option>: - <indexterm><primary>-O2 option</primary></indexterm> - <indexterm><primary>optimise</primary><secondary>aggressively</secondary></indexterm> - </term> - <listitem> - <para>Means: “Apply every non-dangerous - optimisation, even if it means significantly longer - compile times.”</para> - - <para>The avoided “dangerous” optimisations - are those that can make runtime or space - <emphasis>worse</emphasis> if you're unlucky. They are - normally turned on or off individually.</para> - - <para>At the moment, <option>-O2</option> is - <emphasis>unlikely</emphasis> to produce better code than - <option>-O</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-Odph</option>: - <indexterm><primary>-Odph</primary></indexterm> - <indexterm><primary>optimise</primary><secondary>DPH</secondary></indexterm> - </term> - <listitem> - <para>Enables all <option>-O2</option> optimisation, sets - <option>-fmax-simplifier-iterations=20</option> - and <option>-fsimplifier-phases=3</option>. Designed for use with - <link linkend="dph">Data Parallel Haskell (DPH)</link>.</para> - </listitem> - </varlistentry> - - </variablelist> - - <para>We don't use a <option>-O*</option> flag for day-to-day - work. We use <option>-O</option> to get respectable speed; - e.g., when we want to measure something. When we want to go for - broke, we tend to use <option>-O2</option> (and we go for - lots of coffee breaks).</para> - - <para>The easiest way to see what <option>-O</option> (etc.) - “really mean” is to run with <option>-v</option>, - then stand back in amazement.</para> - </sect2> - - <sect2 id="options-f"> - <title><option>-f*</option>: platform-independent flags</title> - - <indexterm><primary>-f* options (GHC)</primary></indexterm> - <indexterm><primary>-fno-* options (GHC)</primary></indexterm> - - <para>These flags turn on and off individual optimisations. - Flags marked as <emphasis>Enabled by default</emphasis> are - enabled by <option>-O</option>, and as such you shouldn't - need to set any of them explicitly. A flag <option>-fwombat</option> - can be negated by saying <option>-fno-wombat</option>. - See <xref linkend="options-f-compact"/> for a compact list. - </para> - - <variablelist> - <varlistentry> - <term> - <option>-fcase-merge</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Merge immediately-nested case expressions that scrutinse the same variable. Example -<programlisting> - case x of - Red -> e1 - _ -> case x of - Blue -> e2 - Green -> e3 -==> - case x of - Red -> e1 - Blue -> e2 - Green -> e2 -</programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcall-arity</option> - <indexterm><primary><option>-fcall-arity</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcmm-elim-common-blocks</option> - <indexterm><primary><option>-felim-common-blocks</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. Enables the common block - elimination optimisation in the code generator. This optimisation - attempts to find identical Cmm blocks and eliminate the duplicates. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcmm-sink</option> - <indexterm><primary><option>-fcmm-sink</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. Enables the sinking pass - in the code generator. This optimisation - attempts to find identical Cmm blocks and eliminate the duplicates - attempts to move variable bindings closer to their usage sites. It - also inlines simple expressions like literals or registers. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcpr-off</option> - <indexterm><primary><option>-fcpr-Off</option></primary></indexterm> - </term> - <listitem> - <para>Switch off CPR analysis in the demand analyser. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcse</option> - <indexterm><primary><option>-fcse</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. Enables the common-sub-expression - elimination optimisation. - Switching this off can be useful if you have some <literal>unsafePerformIO</literal> - expressions that you don't want commoned-up.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fdicts-cheap</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>A very experimental flag that makes dictionary-valued - expressions seem cheap to the optimiser. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fdicts-strict</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>Make dictionaries strict. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fdmd-tx-dict-sel</option> - <indexterm><primary><option>-fdmd-tx-dict-sel</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default for <option>-O0</option>, <option>-O</option>, - <option>-O2</option>.</emphasis> - </para> - <para>Use a special demand transformer for dictionary selectors. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fdo-eta-reduction</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Eta-reduce lambda expressions, if doing so gets rid of a whole - group of lambdas. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fdo-lambda-eta-expansion</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Eta-expand let-bindings to increase their arity. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-feager-blackholing</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>Usually GHC black-holes a thunk only when it switches - threads. This flag makes it do so as soon as the thunk is - entered. See <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/parallel/"> - Haskell on a shared-memory multiprocessor</ulink>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fexcess-precision</option> - <indexterm><primary><option>-fexcess-precision</option></primary></indexterm> - </term> - <listitem> - <para>When this option is given, intermediate floating - point values can have a <emphasis>greater</emphasis> - precision/range than the final type. Generally this is a - good thing, but some programs may rely on the exact - precision/range of - <literal>Float</literal>/<literal>Double</literal> values - and should not use this option for their compilation.</para> - - <para> - Note that the 32-bit x86 native code generator only - supports excess-precision mode, so neither - <option>-fexcess-precision</option> nor - <option>-fno-excess-precision</option> has any effect. - This is a known bug, see <xref linkend="bugs-ghc" />. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fexpose-all-unfoldings</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>An experimental flag to expose all unfoldings, even for very - large or recursive functions. This allows for all functions to be - inlined while usually GHC would avoid inlining larger functions. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ffloat-in</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Float let-bindings inwards, nearer their binding site. See - <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz"> - Let-floating: moving bindings to give faster programs (ICFP'96)</ulink>. - </para> - - <para>This optimisation moves let bindings closer to their use - site. The benefit here is that this may avoid unnecessary - allocation if the branch the let is now on is never executed. It - also enables other optimisation passes to work more effectively - as they have more information locally. - </para> - - <para>This optimisation isn't always beneficial though (so GHC - applies some heuristics to decide when to apply it). The details - get complicated but a simple example is that it is often beneficial - to move let bindings outwards so that multiple let bindings can be - grouped into a larger single let binding, effectively batching - their allocation and helping the garbage collector and allocator. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ffull-laziness</option> - <indexterm><primary><option>-ffull-laziness</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Run the full laziness optimisation (also known as let-floating), - which floats let-bindings outside enclosing lambdas, in the hope - they will be thereby be computed less often. See - <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/float.ps.gz">Let-floating: - moving bindings to give faster programs (ICFP'96)</ulink>. - Full laziness increases sharing, which can lead to increased memory - residency. - </para> - - <para>NOTE: GHC doesn't implement complete full-laziness. - When optimisation in on, and <option>-fno-full-laziness</option> - is not given, some transformations that increase sharing are - performed, such as extracting repeated computations from a loop. - These are the same transformations that a fully lazy - implementation would do, the difference is that GHC doesn't - consistently apply full-laziness, so don't rely on it. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-ffun-to-thunk</option> - <indexterm><primary><option>-ffun-to-thunk</option></primary></indexterm> - </term> - <listitem> - <para>Worker-wrapper removes unused arguments, but usually we do - not remove them all, lest it turn a function closure into a thunk, - thereby perhaps creating a space leak and/or disrupting inlining. - This flag allows worker/wrapper to remove <emphasis>all</emphasis> - value lambdas. Off by default. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fignore-asserts</option> - <indexterm><primary><option>-fignore-asserts</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. - Causes GHC to ignore uses of the function - <literal>Exception.assert</literal> in source code (in - other words, rewriting <literal>Exception.assert p - e</literal> to <literal>e</literal> (see <xref - linkend="assertions"/>). - </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>-flate-dmd-anal</option> - <indexterm><primary><option>-flate-dmd-anal</option></primary></indexterm> - </term> - <listitem> - <para>Run demand analysis - again, at the end of the simplification pipeline. We found some opportunities - for discovering strictness that were not visible earlier; and optimisations like - <literal>-fspec-constr</literal> can create functions with unused arguments which - are eliminated by late demand analysis. Improvements are modest, but so is the - cost. See notes on the <ulink url="http://ghc.haskell.org/trac/ghc/wiki/LateDmd">Trac wiki page</ulink>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fliberate-case</option> - <indexterm><primary><option>-fliberate-case</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>Off by default, but enabled by -O2.</emphasis> - Turn on the liberate-case transformation. This unrolls recursive - function once in its own RHS, to avoid repeated case analysis of - free variables. It's a bit like the call-pattern specialiser - (<option>-fspec-constr</option>) but for free variables rather than - arguments. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fliberate-case-threshold=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fliberate-case-threshold</option></primary></indexterm> - </term> - <listitem> - <para>Set the size threshold for the liberate-case transformation. Default: 2000 - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-floopification</option> - <indexterm><primary><option>-floopification</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - </para> - <para>When this optimisation is enabled the code generator will turn - all self-recursive saturated tail calls into local jumps rather - than function calls. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-inline-alloc-size=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-inline-alloc-size</option></primary></indexterm> - </term> - <listitem> - <para>Set the maximum size of inline array allocations to n bytes - (default: 128). GHC will allocate non-pinned arrays of statically - known size in the current nursery block if they're no bigger - than n bytes, ignoring GC overheap. This value should be quite - a bit smaller than the block size (typically: 4096). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-inline-memcpy-insn=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-inline-memcpy-insn</option></primary></indexterm> - </term> - <listitem> - <para>Inline <literal>memcpy</literal> calls if they would generate - no more than n pseudo instructions (default: 32). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-inline-memset-insns=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-inline-memset-insns</option></primary></indexterm> - </term> - <listitem> - <para>Inline <literal>memset</literal> calls if they would generate - no more than n pseudo instructions (default: 32). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-relevant-binds=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-relevant-bindings</option></primary></indexterm> - </term> - <listitem> - <para>The type checker sometimes displays a fragment of the type environment - in error messages, but only up to some maximum number, set by this flag. - The default is 6. Turning it off with <option>-fno-max-relevant-bindings</option> - gives an unlimited number. Syntactically top-level bindings are also - usually excluded (since they may be numerous), but - <option>-fno-max-relevant-bindings</option> includes them too. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-simplifier-iterations=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-simplifier-iterations</option></primary></indexterm> - </term> - <listitem> - <para>Sets the maximal number of iterations for the simplifier. Defult: 4. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fmax-worker-args=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fmax-worker-args</option></primary></indexterm> - </term> - <listitem> - <para>If a worker has that many arguments, none will be unpacked anymore (default: 10) - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-opt-coercion</option> - <indexterm><primary><option>-fno-opt-coercion</option></primary></indexterm> - </term> - <listitem> - <para>Turn off the coercion optimiser. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-pre-inlining</option> - <indexterm><primary><option>-fno-pre-inlining</option></primary></indexterm> - </term> - <listitem> - <para>Turn off pre-inlining. - </para> - </listitem> - </varlistentry> - - <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>-fomit-yields</option> - <indexterm><primary><option>-fomit-yields</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> Tells GHC to omit - heap checks when no allocation is being performed. While this improves - binary sizes by about 5%, it also means that threads run in - tight non-allocating loops will not get preempted in a timely - fashion. If it is important to always be able to interrupt such - threads, you should turn this optimization off. Consider also - recompiling all libraries with this optimization turned off, if you - need to guarantee interruptibility. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fpedantic-bottoms</option> - <indexterm><primary><option>-fpedantic-bottoms</option></primary></indexterm> - </term> - <listitem> - <para>Make GHC be more precise about its treatment of bottom (but see also - <option>-fno-state-hack</option>). In particular, stop GHC - eta-expanding through a case expression, which is good for - performance, but bad if you are using <literal>seq</literal> on - partial applications. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fregs-graph</option> - <indexterm><primary><option>-fregs-graph</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>Off by default due to a performance regression bug. - Only applies in combination with the native code generator.</emphasis> - Use the graph colouring register allocator for register allocation - in the native code generator. By default, GHC uses a simpler, - faster linear register allocator. The downside being that the - linear register allocator usually generates worse code. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fregs-iterative</option> - <indexterm><primary><option>-fregs-iterative</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>Off by default, only applies in combination with - the native code generator.</emphasis> - Use the iterative coalescing graph colouring register allocator for - register allocation in the native code generator. This is the same - register allocator as the <option>-fregs-graph</option> one but also - enables iterative coalescing during register allocation. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fsimplifier-phases=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fsimplifier-phases</option></primary></indexterm> - </term> - <listitem> - <para>Set the number of phases for the simplifier (default 2). Ignored with -O0. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fsimpl-tick-factor=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fsimpl-tick-factor</option></primary></indexterm> - </term> - <listitem> - <para>GHC's optimiser can diverge if you write rewrite rules ( - <xref linkend="rewrite-rules"/>) that don't terminate, or (less - satisfactorily) if you code up recursion through data types - (<xref linkend="bugs-ghc"/>). To avoid making the compiler fall - into an infinite loop, the optimiser carries a "tick count" and - stops inlining and applying rewrite rules when this count is - exceeded. The limit is set as a multiple of the program size, so - bigger programs get more ticks. The - <option>-fsimpl-tick-factor</option> flag lets you change the - multiplier. The default is 100; numbers larger than 100 give more - ticks, and numbers smaller than 100 give fewer. - </para> - - <para>If the tick-count expires, GHC summarises what simplifier - steps it has done; you can use - <option>-fddump-simpl-stats</option> to generate a much more - detailed list. Usually that identifies the loop quite - accurately, because some numbers are very large. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fspec-constr</option> - <indexterm><primary><option>-fspec-constr</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>Off by default, but enabled by -O2.</emphasis> - Turn on call-pattern specialisation; see - <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/spec-constr/index.htm"> - Call-pattern specialisation for Haskell programs</ulink>. - </para> - - <para>This optimisation specializes recursive functions according to - their argument "shapes". This is best explained by example so - consider: -<programlisting> -last :: [a] -> a -last [] = error "last" -last (x : []) = x -last (x : xs) = last xs -</programlisting> - In this code, once we pass the initial check for an empty list we - know that in the recursive case this pattern match is redundant. As - such <option>-fspec-constr</option> will transform the above code - to: -<programlisting> -last :: [a] -> a -last [] = error "last" -last (x : xs) = last' x xs - where - last' x [] = x - last' x (y : ys) = last' y ys -</programlisting> - </para> - - <para>As well avoid unnecessary pattern matching it also helps avoid - unnecessary allocation. This applies when a argument is strict in - the recursive call to itself but not on the initial entry. As - strict recursive branch of the function is created similar to the - above example. - </para> - - <para>It is also possible for library writers to instruct - GHC to perform call-pattern specialisation extremely - aggressively. This is necessary for some highly optimized - libraries, where we may want to specialize regardless of - the number of specialisations, or the size of the code. As - an example, consider a simplified use-case from the - <literal>vector</literal> library:</para> -<programlisting> -import GHC.Types (SPEC(..)) - -foldl :: (a -> b -> a) -> a -> Stream b -> a -{-# INLINE foldl #-} -foldl f z (Stream step s _) = foldl_loop SPEC z s - where - foldl_loop !sPEC z s = case step s of - Yield x s' -> foldl_loop sPEC (f z x) s' - Skip -> foldl_loop sPEC z s' - Done -> z -</programlisting> - - <para>Here, after GHC inlines the body of - <literal>foldl</literal> to a call site, it will perform - call-pattern specialisation very aggressively on - <literal>foldl_loop</literal> due to the use of - <literal>SPEC</literal> in the argument of the loop - body. <literal>SPEC</literal> from - <literal>GHC.Types</literal> is specifically recognised by - the compiler.</para> - - <para>(NB: it is extremely important you use - <literal>seq</literal> or a bang pattern on the - <literal>SPEC</literal> argument!)</para> - - <para>In particular, after inlining this will - expose <literal>f</literal> to the loop body directly, - allowing heavy specialisation over the recursive - cases.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fspec-constr-count=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fspec-constr-count</option></primary></indexterm> - </term> - <listitem> - <para>Set the maximum number of specialisations - that will be created for any one function by the SpecConstr - transformation (default: 3). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fspec-constr-threshold=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fspec-constr-threshold</option></primary></indexterm> - </term> - <listitem> - <para>Set the size threshold for the SpecConstr transformation (default: 2000). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fspecialise</option> - <indexterm><primary><option>-fspecialise</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Specialise each type-class-overloaded function defined in this - module for the types at which it is called in this module. If - <literal>-fcross-module-specialise</literal> is set imported - functions that have an INLINABLE pragma - (<xref linkend="inlinable-pragma"/>) will be specialised as well. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fcross-module-specialise</option> - <indexterm><primary><option>-fcross-module-specialise</option></primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis> - Specialise <literal>INLINABLE</literal> (<xref linkend="inlinable-pragma"/>) - type-class-overloaded functions imported from other modules for the - types at which they are called in this module. Note that specialisation must - be enabled (by <literal>-fspecialise</literal>) for this to have any effect. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fstatic-argument-transformation</option> - <indexterm><primary><option>-fstatic-argument-transformation</option></primary></indexterm> - </term> - <listitem> - <para>Turn on the static argument transformation, which turns a - recursive function into a non-recursive one with a local - recursive loop. See Chapter 7 of - <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/santos-thesis.ps.gz"> - Andre Santos's PhD thesis</ulink> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fstrictness</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para> <emphasis>On by default.</emphasis>. - Switch on the strictness analyser. There is a very old paper about GHC's - strictness analyser, <ulink url="http://research.microsoft.com/en-us/um/people/simonpj/papers/simple-strictnes-analyser.ps.gz"> - Measuring the effectiveness of a simple strictness analyser</ulink>, - but the current one is quite a bit different. - </para> - - <para>The strictness analyser figures out when arguments and - variables in a function can be treated 'strictly' (that is they - are always evaluated in the function at some point). This allow - GHC to apply certain optimisations such as unboxing that - otherwise don't apply as they change the semantics of the program - when applied to lazy arguments. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fstrictness-before=<replaceable>n</replaceable></option> - <indexterm><primary><option>-fstrictness-before</option></primary></indexterm> - </term> - <listitem> - <para>Run an additional strictness analysis before simplifier phase n. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funbox-small-strict-fields</option>: - <indexterm><primary><option>-funbox-small-strict-fields</option></primary></indexterm> - <indexterm><primary>strict constructor fields</primary></indexterm> - <indexterm><primary>constructor fields, strict</primary></indexterm> - </term> - <listitem> - <para><emphasis>On by default.</emphasis>. This option - causes all constructor fields which are marked strict - (i.e. “!”) and which representation is smaller - or equal to the size of a pointer to be unpacked, if - possible. It is equivalent to adding an - <literal>UNPACK</literal> pragma (see <xref - linkend="unpack-pragma"/>) to every strict constructor - field that fulfils the size restriction. - </para> - - <para>For example, the constructor fields in the following - data types -<programlisting> -data A = A !Int -data B = B !A -newtype C = C B -data D = D !C -</programlisting> - would all be represented by a single - <literal>Int#</literal> (see <xref linkend="primitives"/>) - value with - <option>-funbox-small-strict-fields</option> enabled. - </para> - - <para>This option is less of a sledgehammer than - <option>-funbox-strict-fields</option>: it should rarely make things - worse. If you use <option>-funbox-small-strict-fields</option> - to turn on unboxing by default you can disable it for certain - constructor fields using the <literal>NOUNPACK</literal> pragma (see - <xref linkend="nounpack-pragma"/>).</para> - - <para> - Note that for consistency <literal>Double</literal>, - <literal>Word64</literal>, and <literal>Int64</literal> constructor - fields are unpacked on 32-bit platforms, even though they are - technically larger than a pointer on those platforms. - </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> - <indexterm><primary>constructor fields, strict</primary></indexterm> - </term> - <listitem> - <para>This option causes all constructor fields which are marked - strict (i.e. “!”) to be unpacked if possible. It is - equivalent to adding an <literal>UNPACK</literal> pragma to every - strict constructor field (see <xref linkend="unpack-pragma"/>). - </para> - - <para>This option is a bit of a sledgehammer: it might sometimes - make things worse. Selectively unboxing fields by using - <literal>UNPACK</literal> pragmas might be better. An alternative - is to use <option>-funbox-strict-fields</option> to turn on - unboxing by default but disable it for certain constructor - fields using the <literal>NOUNPACK</literal> pragma (see - <xref linkend="nounpack-pragma"/>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <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> - </term> - <listitem> - <para>(Default: 750) Governs the maximum size that GHC will allow a - function unfolding to be. (An unfolding has a “size” - that reflects the cost in terms of “code bloat” of - expanding (aka inlining) that unfolding at a call site. A bigger - function would be assigned a bigger cost.) - </para> - - <para>Consequences: (a) nothing larger than this will be inlined - (unless it has an INLINE pragma); (b) nothing larger than this - will be spewed into an interface file. - </para> - - <para>Increasing this figure is more likely to result in longer - compile times than faster code. The - <option>-funfolding-use-threshold</option> is more useful. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funfolding-dict-discount=<replaceable>n</replaceable></option>: - <indexterm><primary><option>-funfolding-dict-discount</option></primary></indexterm> - <indexterm><primary>inlining, controlling</primary></indexterm> - <indexterm><primary>unfolding, controlling</primary></indexterm> - </term> - <listitem> - <para>Default: 30 - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funfolding-fun-discount=<replaceable>n</replaceable></option>: - <indexterm><primary><option>-funfolding-fun-discount</option></primary></indexterm> - <indexterm><primary>inlining, controlling</primary></indexterm> - <indexterm><primary>unfolding, controlling</primary></indexterm> - </term> - <listitem> - <para>Default: 60 - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funfolding-keeness-factor=<replaceable>n</replaceable></option>: - <indexterm><primary><option>-funfolding-keeness-factor</option></primary></indexterm> - <indexterm><primary>inlining, controlling</primary></indexterm> - <indexterm><primary>unfolding, controlling</primary></indexterm> - </term> - <listitem> - <para>Default: 1.5 - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-funfolding-use-threshold=<replaceable>n</replaceable></option> - <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm> - <indexterm><primary>inlining, controlling</primary></indexterm> - <indexterm><primary>unfolding, controlling</primary></indexterm> - </term> - <listitem> - <para>(Default: 60) This is the magic cut-off figure for unfolding - (aka inlining): below this size, a function definition will be - unfolded at the call-site, any bigger and it won't. The size - computed for a function depends on two things: the actual size of - the expression minus any discounts that apply depending on the - context into which the expression is to be inlined. - </para> - - <para>The difference between this and - <option>-funfolding-creation-threshold</option> is that this one - determines if a function definition will be inlined <emphasis>at - a call site</emphasis>. The other option determines if a - function definition will be kept around at all for potential - inlining. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fvectorisation-avoidance</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>Part of <link linkend="dph">Data Parallel Haskell - (DPH)</link>.</para> - - <para><emphasis>On by default.</emphasis> Enable the - <emphasis>vectorisation</emphasis> avoidance optimisation. This - optimisation only works when used in combination with the - <option>-fvectorise</option> transformation.</para> - - <para>While vectorisation of code using DPH is often a big win, it - can also produce worse results for some kinds of code. This - optimisation modifies the vectorisation transformation to try to - determine if a function would be better of unvectorised and if - so, do just that.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fvectorise</option> - <indexterm><primary><option></option></primary></indexterm> - </term> - <listitem> - <para>Part of <link linkend="dph">Data Parallel Haskell - (DPH)</link>.</para> - - <para><emphasis>Off by default.</emphasis> Enable the - <emphasis>vectorisation</emphasis> optimisation transformation. This - optimisation transforms the nested data parallelism code of programs - using DPH into flat data parallelism. Flat data parallel programs - should have better load balancing, enable SIMD parallelism and - friendlier cache behaviour.</para> - </listitem> - </varlistentry> - - </variablelist> - - </sect2> - - </sect1> - - &code-gens; - - &phases; - - &shared_libs; - - <sect1 id="using-concurrent"> - <title>Using Concurrent Haskell</title> - <indexterm><primary>Concurrent Haskell</primary><secondary>using</secondary></indexterm> - - <para>GHC supports Concurrent Haskell by default, without requiring a - special option or libraries compiled in a certain way. To get access to - the support libraries for Concurrent Haskell, just import - <ulink - url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>. More information on Concurrent Haskell is provided in the documentation for that module.</para> - - <para> - Optionally, the program may be linked with - the <option>-threaded</option> option (see - <xref linkend="options-linker" />. This provides two benefits: - - <itemizedlist> - <listitem> - <para>It enables the <option>-N</option><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm> RTS option to be - used, which allows threads to run in - parallel<indexterm><primary>parallelism</primary></indexterm> - on a - multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm> - or - multicore<indexterm><primary>multicore</primary></indexterm> - machine. See <xref linkend="using-smp" />.</para> - </listitem> - <listitem> - <para>If a thread makes a foreign call (and the call is - not marked <literal>unsafe</literal>), then other - Haskell threads in the program will continue to run - while the foreign call is in progress. - Additionally, <literal>foreign export</literal>ed - Haskell functions may be called from multiple OS - threads simultaneously. See - <xref linkend="ffi-threads" />.</para> - </listitem> - </itemizedlist> - </para> - - <para>The following RTS option(s) affect the behaviour of Concurrent - Haskell programs:<indexterm><primary>RTS options, concurrent</primary></indexterm></para> - - <variablelist> - <varlistentry> - <term><option>-C<replaceable>s</replaceable></option></term> - <listitem> - <para><indexterm><primary><option>-C<replaceable>s</replaceable></option></primary><secondary>RTS option</secondary></indexterm> - Sets the context switch interval to <replaceable>s</replaceable> - 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.</para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - - <sect1 id="using-smp"> - <title>Using SMP parallelism</title> - <indexterm><primary>parallelism</primary> - </indexterm> - <indexterm><primary>SMP</primary> - </indexterm> - - <para>GHC supports running Haskell programs in parallel on an SMP - (symmetric multiprocessor).</para> - - <para>There's a fine distinction between - <emphasis>concurrency</emphasis> and <emphasis>parallelism</emphasis>: - parallelism is all about making your program run - <emphasis>faster</emphasis> by making use of multiple processors - simultaneously. Concurrency, on the other hand, is a means of - abstraction: it is a convenient way to structure a program that must - respond to multiple asynchronous events.</para> - - <para>However, the two terms are certainly related. By making use of - multiple CPUs it is possible to run concurrent threads in parallel, - and this is exactly what GHC's SMP parallelism support does. But it - 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 describe the language features that affect - parallelism.</para> - - <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" />). 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>There are two ways to run a program on multiple - processors: - call <literal>Control.Concurrent.setNumCapabilities</literal> from your - program, or use the RTS <option>-N</option> option.</para> - - <variablelist> - <varlistentry> - <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 - running the program.</para> - - <para>The runtime manages a set of virtual processors, - which we call <emphasis>capabilities</emphasis>, the - number of which is determined by the <option>-N</option> - option. Each capability can run one Haskell thread at a - time, so the number of capabilities is equal to the - number of Haskell threads that can run physically in - parallel. A capability is animated by one or more OS - threads; the runtime manages a pool of OS threads for - each capability, so that if a Haskell thread makes a - foreign call (see <xref linkend="ffi-threads" />) - another OS thread can take over that capability. - </para> - - <para>Normally <replaceable>x</replaceable> should be - chosen to match the number of CPU cores on the - machine<footnote><para>Whether hyperthreading cores - should be counted or not is an open question; please - feel free to experiment and let us know what results you - find.</para></footnote>. For example, 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 - enabling the parallel garbage collector (see - <xref linkend="rts-options-gc" />).</para> - - <para>The current value of the <option>-N</option> option - is available to the Haskell program via - <literal>Control.Concurrent.getNumCapabilities</literal>, - and it may be changed while the program is running by - calling - <literal>Control.Concurrent.setNumCapabilities</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The following options affect the way the runtime schedules - threads on CPUs:</para> - - <variablelist> - <varlistentry> - <term><option>-qa</option></term> - <indexterm><primary><option>-qa</option></primary><secondary>RTS - option</secondary></indexterm> - <listitem> - <para>Use the OS's affinity facilities to try to pin OS - threads to CPU cores.</para> - - <para>When this option is enabled, the OS threads for a - capability <emphasis>i</emphasis> are bound to the CPU - core <emphasis>i</emphasis> using the API provided by the - OS for setting thread affinity. e.g. on Linux - GHC uses <literal>sched_setaffinity()</literal>.</para> - - <para>Depending on your workload and the other activity on - the machine, this may or may not result in a performance - improvement. We recommend trying it out and measuring the - difference.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-qm</option></term> - <indexterm><primary><option>-qm</option></primary><secondary>RTS - option</secondary></indexterm> - <listitem> - <para>Disable automatic migration for load balancing. - Normally the runtime will automatically try to schedule - threads across the available CPUs to make use of idle - CPUs; this option disables that behaviour. Note that - migration only applies to threads; sparks created - by <literal>par</literal> are load-balanced separately - by work-stealing.</para> - - <para> - This option is probably only of use for concurrent - programs that explicitly schedule threads onto CPUs - with <literal>Control.Concurrent.forkOn</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>Hints for using SMP parallelism</title> - - <para>Add the <literal>-s</literal> RTS option when - running the program to see timing stats, which will help to tell you - whether your program got faster by using more CPUs or not. If the user - time is greater than - the elapsed time, then the program used more than one CPU. You should - also run the program without <literal>-N</literal> for - comparison.</para> - - <para>The output of <literal>+RTS -s</literal> tells you how - many “sparks” were created and executed during the - run of the program (see <xref linkend="rts-options-gc" />), which - will give you an idea how well your <literal>par</literal> - annotations are working.</para> - - <para>GHC's parallelism support has improved in 6.12.1 as a - result of much experimentation and tuning in the runtime - system. We'd still be interested to hear how well it works - for you, and we're also interested in collecting parallel - programs to add to our benchmarking suite.</para> - </sect2> - </sect1> - - <sect1 id="options-platform"> - <title>Platform-specific Flags</title> - - <indexterm><primary>-m* options</primary></indexterm> - <indexterm><primary>platform-specific options</primary></indexterm> - <indexterm><primary>machine-specific options</primary></indexterm> - - <para>Some flags only make sense for particular target - platforms.</para> - - <variablelist> - - <varlistentry> - <term><option>-msse2</option>:</term> - <listitem> - <para> - (x86 only, added in GHC 7.0.1) Use the SSE2 registers and - instruction set to implement floating point operations when using - the <link linkend="native-code-gen">native code generator</link>. - This gives a substantial performance improvement for floating - point, but the resulting compiled code - will only run on processors that support SSE2 (Intel Pentium 4 and - later, or AMD Athlon 64 and later). The - <link linkend="llvm-code-gen">LLVM backend</link> will also use SSE2 - if your processor supports it but detects this automatically so no - flag is required. - </para> - <para> - SSE2 is unconditionally used on x86-64 platforms. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-msse4.2</option>:</term> - <listitem> - <para> - (x86 only, added in GHC 7.4.1) Use the SSE4.2 instruction set to - implement some floating point and bit operations when using the - <link linkend="native-code-gen">native code generator</link>. The - resulting compiled code will only run on processors that - support SSE4.2 (Intel Core i7 and later). The - <link linkend="llvm-code-gen">LLVM backend</link> will also use - SSE4.2 if your processor supports it but detects this automatically - so no flag is required. - </para> - </listitem> - </varlistentry> - - </variablelist> - - </sect1> - -&runtime; -&debug; -&flags; - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> |