+++ /dev/null
-<?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>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 uses GHC
- extensions, it will always need to be compiled with the
- <option>-fglasgow-exts</option> option. Rather than maintaining
- the list of per-file options in a <filename>Makefile</filename>,
- it is possible to do this directly in the source file using the
- <literal>OPTIONS_GHC</literal> pragma <indexterm><primary>OPTIONS_GHC
- pragma</primary></indexterm>:</para>
-
-<programlisting>
-{-# OPTIONS_GHC -fglasgow-exts #-}
-module X where
-...
-</programlisting>
-
- <para><literal>OPTIONS_GHC</literal> pragmas are only looked for at
- the top of your source files, upto the first
- (non-literate,non-empty) line not containing
- <literal>OPTIONS_GHC</literal>. Multiple <literal>OPTIONS_GHC</literal>
- pragmas are recognised. Do not put comments before, or on the same line
- as, the <literal>OPTIONS_GHC</literal> pragma.</para>
-
- <para>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 prepended to the
- command-line options, so you <emphasis>do</emphasis> have the
- ability to override OPTIONS_GHC settings via the command
- line.</para>
-
- <para>It is not recommended to move all the contents of your
- Makefiles into your source files, but in some circumstances, the
- <literal>OPTIONS_GHC</literal> pragma is the Right Thing. (If you
- use <option>-keep-hc-file-too</option> and have OPTION flags in
- 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 either
- <firstterm>static</firstterm> or <firstterm>dynamic</firstterm> or
- <firstterm>mode</firstterm>:</para>
-
- <variablelist>
- <varlistentry>
- <term>Mode flags</term>
- <listitem>
- <para>For example, <option>--make</option> or <option>-E</option>.
- There may be only a single mode flag on the command line. The
- available modes are listed in <xref linkend="modes"/>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Dynamic Flags</term>
- <listitem>
- <para>Most non-mode flags fall into this category. A dynamic flag
- may be used on the command line, in a
- <literal>GHC_OPTIONS</literal> pragma in a source file, or set
- using <literal>:set</literal> in GHCi.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Static Flags</term>
- <listitem>
- <para>A few flags are "static", which means they can only be used on
- the command-line, and remain in force over the entire GHC/GHCi
- run.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>The flag reference tables (<xref
- linkend="flag-reference"/>) lists the status of each flag.</para>
- </sect1>
-
- <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>.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>.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>
-
- <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. The available modes
- are:</para>
-
- <variablelist>
- <varlistentry>
- <term>
- <cmdsynopsis><command>ghc</command>
- <arg choice='plain'>––interactive</arg>
- </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</command>
- <arg choice='plain'>––make</arg>
- </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>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis><command>ghc</command>
- <arg choice='plain'>–e</arg> <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</command>
- <group>
- <arg>-E</arg>
- <arg>-C</arg>
- <arg>-S</arg>
- <arg>-c</arg>
- </group>
- </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. This mode also applies if
- there is no other mode flag specified on the command line,
- in which case it means that the specified files should be
- compiled and then linked to form a program. See <xref
- linkend="options-order"/>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>ghc</command>
- <arg choice='plain'>–M</arg>
- </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="sec-makefile-dependencies"/>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <cmdsynopsis>
- <command>ghc</command>
- <arg choice='plain'>––mk-dll</arg>
- </cmdsynopsis>
- <indexterm><primary>dependency-generation mode</primary></indexterm>
- </term>
- <listitem>
- <para>DLL-creation mode (Windows only). See <xref
- linkend="win32-dlls-create"/>.</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>When given the <option>––make</option> option,
- GHC will build a multi-module Haskell program by following
- dependencies from a single root module (usually
- <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>The command line may contain any number of source file
- names or module names; GHC will figure out all the modules in
- the program by following the imports from these initial modules.
- It will then attempt to compile each module which is out of
- date, and finally if there is a <literal>Main</literal> module,
- 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>
- </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>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 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
- whether a native-code generator<indexterm><primary>native-code
- generator</primary></indexterm> is used (producing assembly
- language) or not (producing C). See <xref
- linkend="options-codegen"/> 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. Note that this
- differs from the previous behaviour of dumping the file to
- standard output.</para>
-
- <sect3 id="overriding-suffixes">
- <title>Overriding the default behaviour for a file</title>
-
- <para>As described above, the way in which a file is processed by GHC
- depends on its suffix. This behaviour can be overriden using the
- <option>-x</option> option:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-x</option> <replaceable>suffix</replaceable>
- <indexterm><primary><option>-x</option></primary>
- </indexterm></term>
- <listitem>
- <para>Causes all files following this option on the command
- line to be processed as if they had the suffix
- <replaceable>suffix</replaceable>. For example, to compile a
- Haskell module in the file <literal>M.my-hs</literal>,
- use <literal>ghc -c -x hs M.my-hs</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
-
- </sect2>
- </sect1>
-
- <sect1 id="options-help">
- <title>Help and verbosity options</title>
-
- <indexterm><primary>help options</primary></indexterm>
- <indexterm><primary>verbosity options</primary></indexterm>
-
- <variablelist>
- <varlistentry>
- <term>
- <option>––help</option>
- <indexterm><primary><option>––help</option></primary></indexterm>
- </term>
- <term>
- <option>-?</option>
- <indexterm><primary><option>-?</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>
- <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>-V</option>
- <indexterm><primary><option>-V</option></primary></indexterm>
- </term>
- <term>
- <option>––version</option>
- <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>
- <option>––numeric-version</option>
- <indexterm><primary><option>––numeric-version</option></primary></indexterm>
- </term>
- <listitem>
- <para>Print GHC's numeric version number only.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>––print-libdir</option>
- <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>
-
- <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>-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-deprecations</option>,
- <option>-fwarn-duplicate-exports</option>,
- <option>-fwarn-missing-fields</option>, and
- <option>-fwarn-missing-methods</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-incomplete-patterns</option>,
- <option>-fwarn-unused-matches</option>,
- <option>-fwarn-unused-imports</option>,
- <option>-fwarn-misc</option>, and
- <option>-fwarn-unused-binds</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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-Wall</option>:</term>
- <listitem>
- <indexterm><primary><option>-Wall</option></primary></indexterm>
- <para>Turns on all warning options.</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>
-
- </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-deprecations</option>:</term>
- <listitem>
- <indexterm><primary><option>-fwarn-deprecations</option></primary>
- </indexterm>
- <indexterm><primary>deprecations</primary></indexterm>
- <para>Causes a warning to be emitted when a deprecated
- function or type is used. Entities can be marked as
- deprecated using a pragma, see <xref
- linkend="deprecated-pragma"/>.</para>
- </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-incomplete-patterns</option>:</term>
- <listitem>
- <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
- <indexterm><primary>incomplete patterns, warning</primary></indexterm>
- <indexterm><primary>patterns, incomplete</primary></indexterm>
-
- <para>Similarly for incomplete patterns, 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.</para>
-
-<programlisting>
-g [] = 2
-</programlisting>
-
- <para>This option isn't enabled be default because it can be
- a bit noisy, and it doesn't always indicate a bug in the
- program. However, it's generally considered good practice
- to cover all the cases in your functions.</para>
- </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 be default because it can be
- very noisy, and it often doesn't indicate a bug in the
- program.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-fwarn-misc</option>:
- <indexterm><primary><option>-fwarn-misc</option></primary></indexterm>
- </term>
- <listitem>
- <para>Turns on warnings for various harmless but untidy
- things. This currently includes: importing a type with
- <literal>(..)</literal> when the export is abstract, and
- listing duplicate class assertions in a qualified type.</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 initializers 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-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>
- </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. This
- 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 cyclic definition <literal>let x = ... x
- ... in</literal>.</para>
-
- <para>Consequently, this option does
- <emphasis>will</emphasis> complain about cyclic recursive
- definitions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-fwarn-orphans</option>:</term>
- <listitem>
- <indexterm><primary><option>-fwarn-orphans</option></primary></indexterm>
- <indexterm><primary>orphan instances, warning</primary></indexterm>
- <indexterm><primary>orphan rules, warning</primary></indexterm>
-
- <para>This option causes a warning to be emitted whenever the
- module contains an "orphan" instance declaration or rewrite rule.
- An instance declartion is an orphan if it appears in a module in
- which neither the class nor the type being instanced are declared
- in the same module. A rule is an orphan if it is a rule for a
- function declared in another module. A module containing any
- orphans is called an orphan module.</para>
- <para>The trouble with orphans is that GHC must pro-actively read the interface
- files for all orphan modules, just in case their instances or rules
- play a role, whether or not the module's interface would otherwise
- be of any use. Other things being equal, avoid orphan modules.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-fwarn-overlapping-patterns</option>:
- <indexterm><primary><option>-fwarn-overlapping-patterns</option></primary></indexterm>
- <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, i.e.,</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-simple-patterns</option>:</term>
- <listitem>
- <indexterm><primary><option>-fwarn-simple-patterns</option></primary>
- </indexterm>
- <para>Causes the compiler to warn about lambda-bound
- patterns that can fail, eg. <literal>\(x:xs)->...</literal>.
- Normally, these aren't treated as incomplete patterns by
- <option>-fwarn-incomplete-patterns</option>.</para>
- <para>``Lambda-bound patterns'' includes all places where there is a single pattern,
- including list comprehensions and do-notation. In these cases, a pattern-match
- failure is quite legitimate, and triggers filtering (list comprehensions) or
- the monad <literal>fail</literal> operation (monads). For example:
- <programlisting>
- f :: [Maybe a] -> [a]
- f xs = [y | Just y <- xs]
- </programlisting>
- Switching on <option>-fwarn-simple-patterns</option> will elicit warnings about
- these probably-innocent cases, which is why the flag is off by default. </para>
- <para> The <literal>deriving( Read )</literal> mechanism produces monadic code with
- pattern matches, so you will also get misleading warnings about the compiler-generated
- code. (This is arguably a Bad Thing, but it's awkward to fix.)</para>
-
- </listitem>
- </varlistentry>
-
- <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
- 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-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. For top-level functions, the warning is
- only given if the binding is not exported.</para>
- <para>A definition is regarded as "used" if (a) it is exported, or (b) it is
- mentioned in the right hand side of another definition that is used, or (c) the
- function it defines begins with an underscore. The last case provides a
- way to suppress unused-binding warnings selectively. </para>
- <para> Notice that a variable
- is reported as unused even if it appears in the right-hand side of another
- unused binding. </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>
-
- </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>
-
- <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 reaosn 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>
-
- <para><option>-O</option> currently also implies
- <option>-fvia-C</option>. This may change in the
- future.</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>-Ofile <file></option>:
- <indexterm><primary>-Ofile <file> option</primary></indexterm>
- <indexterm><primary>optimising, customised</primary></indexterm>
- </term>
- <listitem>
- <para>(NOTE: not supported since GHC 4.x. Please ask if
- you're interested in this.)</para>
-
- <para>For those who need <emphasis>absolute</emphasis>
- control over <emphasis>exactly</emphasis> what options are
- used (e.g., compiler writers, sometimes :-), a list of
- options can be put in a file and then slurped in with
- <option>-Ofile</option>.</para>
-
- <para>In that file, comments are of the
- <literal>#</literal>-to-end-of-line variety; blank
- lines and most whitespace is ignored.</para>
-
- <para>Please ask if you are baffled and would like an
- example of <option>-Ofile</option>!</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 -fvia-C</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.
- They are normally set via the <option>-O</option> options
- described above, and as such, you shouldn't need to set any of
- them explicitly (indeed, doing so could lead to unexpected
- results). However, there are one or two that may be of
- interest:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-fexcess-precision</option>:</term>
- <listitem>
- <indexterm><primary><option>-fexcess-precision</option></primary></indexterm>
- <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>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-fignore-asserts</option>:</term>
- <listitem>
- <indexterm><primary><option>-fignore-asserts</option></primary></indexterm>
- <para>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="sec-assertions"/>). This flag is turned on by
- <option>-O</option>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-fno-cse</option>
- <indexterm><primary><option>-fno-cse</option></primary></indexterm>
- </term>
- <listitem>
- <para>Turns off the common-sub-expression elimination optimisation.
- Can be useful if you have some <literal>unsafePerformIO</literal>
- expressions that you don't want commoned-up.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-fno-strictness</option>
- <indexterm><primary><option>-fno-strictness</option></primary></indexterm>
- </term>
- <listitem>
- <para>Turns off the strictness analyser; sometimes it eats
- too many cycles.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-fno-full-laziness</option>
- <indexterm><primary><option>-fno-full-laziness</option></primary></indexterm>
- </term>
- <listitem>
- <para>Turns off the full laziness optimisation (also known as
- let-floating). Full laziness increases sharing, which can lead
- to increased memory residency.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-fno-state-hack</option>
- <indexterm><primary><option>-fno-state-hack</option></primary></indexterm>
- </term>
- <listitem>
- <para>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>-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 unboxed or
- 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.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-funfolding-update-in-place<n></option>
- <indexterm><primary><option>-funfolding-update-in-place</option></primary></indexterm>
- </term>
- <listitem>
- <para>Switches on an experimental "optimisation".
- Switching it on makes the compiler a little keener to
- inline a function that returns a constructor, if the
- context is that of a thunk.
-<programlisting>
- x = plusInt a b
-</programlisting>
- If we inlined plusInt we might get an opportunity to use
- update-in-place for the thunk 'x'.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <option>-funfolding-creation-threshold<n></option>:
- <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: 45) 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 that unfolding at
- 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 next option is more
- useful:</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-funfolding-use-threshold<n></option>:</term>
- <listitem>
- <indexterm><primary><option>-funfolding-use-threshold</option></primary></indexterm>
- <indexterm><primary>inlining, controlling</primary></indexterm>
- <indexterm><primary>unfolding, controlling</primary></indexterm>
-
- <para>(Default: 8) This is the magic cut-off figure for
- unfolding: 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 (see <option>-funfolding-con-discount</option>).</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect2>
-
- </sect1>
-
- &phases;
-
- <sect1 id="sec-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="../libraries/base/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>. More information on Concurrent Haskell is provided in the documentation for that module.</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. Note that GHC's internal timer ticks
- every 20ms, and the context switch timer is always a multiple of
- this timer, so 20ms is the maximum granularity available for timed
- context switches.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect1>
-
-<sect1 id="sec-using-parallel">
-<title>Using parallel Haskell</title>
-
-<para>
-<indexterm><primary>Parallel Haskell</primary><secondary>using</secondary></indexterm>
-[NOTE: GHC does not support Parallel Haskell by default, you need to
- obtain a special version of GHC from the <ulink
- url="http://www.cee.hw.ac.uk/~dsg/gph/">GPH</ulink> site. Also,
-you won't be able to execute parallel Haskell programs unless PVM3
-(parallel Virtual Machine, version 3) is installed at your site.]
-</para>
-
-<para>
-To compile a Haskell program for parallel execution under PVM, use the
-<option>-parallel</option> option,<indexterm><primary>-parallel
-option</primary></indexterm> both when compiling <emphasis>and
-linking</emphasis>. You will probably want to <literal>import
-Control.Parallel</literal> into your Haskell modules.
-</para>
-
-<para>
-To run your parallel program, once PVM is going, just invoke it
-“as normal”. The main extra RTS option is
-<option>-qp<n></option>, to say how many PVM
-“processors” your program to run on. (For more details of
-all relevant RTS options, please see <xref
-linkend="parallel-rts-opts"/>.)
-</para>
-
-<para>
-In truth, running parallel Haskell programs and getting information
-out of them (e.g., parallelism profiles) is a battle with the vagaries of
-PVM, detailed in the following sections.
-</para>
-
-<sect2 id="pvm-dummies">
-<title>Dummy's guide to using PVM</title>
-
-<para>
-<indexterm><primary>PVM, how to use</primary></indexterm>
-<indexterm><primary>parallel Haskell—PVM use</primary></indexterm>
-Before you can run a parallel program under PVM, you must set the
-required environment variables (PVM's idea, not ours); something like,
-probably in your <filename>.cshrc</filename> or equivalent:
-
-<programlisting>
-setenv PVM_ROOT /wherever/you/put/it
-setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
-setenv PVM_DPATH $PVM_ROOT/lib/pvmd
-</programlisting>
-
-</para>
-
-<para>
-Creating and/or controlling your “parallel machine” is a purely-PVM
-business; nothing specific to parallel Haskell. The following paragraphs
-describe how to configure your parallel machine interactively.
-</para>
-
-<para>
-If you use parallel Haskell regularly on the same machine configuration it
-is a good idea to maintain a file with all machine names and to make the
-environment variable PVM_HOST_FILE point to this file. Then you can avoid
-the interactive operations described below by just saying
-</para>
-
-<programlisting>
-pvm $PVM_HOST_FILE
-</programlisting>
-
-<para>
-You use the <command>pvm</command><indexterm><primary>pvm command</primary></indexterm> command to start PVM on your
-machine. You can then do various things to control/monitor your
-“parallel machine;” the most useful being:
-</para>
-
-<para>
-<informaltable>
-<tgroup cols="2">
-<colspec align="left"/>
-<tbody>
-
-<row>
-<entry><keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo></entry>
-<entry>exit <command>pvm</command>, leaving it running</entry>
-</row>
-
-<row>
-<entry><command>halt</command></entry>
-<entry>kill off this “parallel machine” & exit</entry>
-</row>
-
-<row>
-<entry><command>add <host></command></entry>
-<entry>add <command><host></command> as a processor</entry>
-</row>
-
-<row>
-<entry><command>delete <host></command></entry>
-<entry>delete <command><host></command></entry>
-</row>
-
-<row>
-<entry><command>reset</command></entry>
-<entry>kill what's going, but leave PVM up</entry>
-</row>
-
-<row>
-<entry><command>conf</command></entry>
-<entry>list the current configuration</entry>
-</row>
-
-<row>
-<entry><command>ps</command></entry>
-<entry>report processes' status</entry>
-</row>
-
-<row>
-<entry><command>pstat <pid></command></entry>
-<entry>status of a particular process</entry>
-</row>
-
-</tbody>
-</tgroup>
-</informaltable>
-</para>
-
-<para>
-The PVM documentation can tell you much, much more about <command>pvm</command>!
-</para>
-
-</sect2>
-
-<sect2 id="par-profiles">
-<title>parallelism profiles</title>
-
-<para>
-<indexterm><primary>parallelism profiles</primary></indexterm>
-<indexterm><primary>profiles, parallelism</primary></indexterm>
-<indexterm><primary>visualisation tools</primary></indexterm>
-</para>
-
-<para>
-With parallel Haskell programs, we usually don't care about the
-results—only with “how parallel” it was! We want pretty pictures.
-</para>
-
-<para>
-parallelism profiles (à la <command>hbcpp</command>) can be generated with the
-<option>-qP</option><indexterm><primary>-qP RTS option</primary></indexterm> RTS option. The
-per-processor profiling info is dumped into files named
-<filename><full-path><program>.gr</filename>. These are then munged into a PostScript picture,
-which you can then display. For example, to run your program
-<filename>a.out</filename> on 8 processors, then view the parallelism profile, do:
-</para>
-
-<para>
-
-<screen>
-<prompt>$</prompt> ./a.out +RTS -qP -qp8
-<prompt>$</prompt> grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one
-<prompt>$</prompt> gr2ps -O temp.gr # cvt to .ps; output in temp.ps
-<prompt>$</prompt> ghostview -seascape temp.ps # look at it!
-</screen>
-
-</para>
-
-<para>
-The scripts for processing the parallelism profiles are distributed
-in <filename>ghc/utils/parallel/</filename>.
-</para>
-
-</sect2>
-
-<sect2>
-<title>Other useful info about running parallel programs</title>
-
-<para>
-The “garbage-collection statistics” RTS options can be useful for
-seeing what parallel programs are doing. If you do either
-<option>+RTS -Sstderr</option><indexterm><primary>-Sstderr RTS option</primary></indexterm> or <option>+RTS -sstderr</option>, then
-you'll get mutator, garbage-collection, etc., times on standard
-error. The standard error of all PE's other than the `main thread'
-appears in <filename>/tmp/pvml.nnn</filename>, courtesy of PVM.
-</para>
-
-<para>
-Whether doing <option>+RTS -Sstderr</option> or not, a handy way to watch
-what's happening overall is: <command>tail -f /tmp/pvml.nnn</command>.
-</para>
-
-</sect2>
-
-<sect2 id="parallel-rts-opts">
-<title>RTS options for Parallel Haskell
-</title>
-
-<para>
-<indexterm><primary>RTS options, parallel</primary></indexterm>
-<indexterm><primary>parallel Haskell—RTS options</primary></indexterm>
-</para>
-
-<para>
-Besides the usual runtime system (RTS) options
-(<xref linkend="runtime-control"/>), there are a few options particularly
-for parallel execution.
-</para>
-
-<para>
-<variablelist>
-
-<varlistentry>
-<term><option>-qp<N></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qp<N> RTS option</primary></indexterm>
-(paraLLEL ONLY) Use <literal><N></literal> PVM processors to run this program;
-the default is 2.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-C[<s>]</option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-C<s> RTS option</primary></indexterm> Sets
-the context switch interval to <literal><s></literal> seconds.
-A context switch will occur at the next heap block allocation after
-the timer expires (a heap block allocation occurs every 4k of
-allocation). With <option>-C0</option> or <option>-C</option>,
-context switches will occur as often as possible (at every heap block
-allocation). By default, context switches occur every 20ms. Note that GHC's internal timer ticks every 20ms, and
-the context switch timer is always a multiple of this timer, so 20ms
-is the maximum granularity available for timed context switches.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-q[v]</option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-q RTS option</primary></indexterm>
-(paraLLEL ONLY) Produce a quasi-parallel profile of thread activity,
-in the file <filename><program>.qp</filename>. In the style of <command>hbcpp</command>, this profile
-records the movement of threads between the green (runnable) and red
-(blocked) queues. If you specify the verbose suboption (<option>-qv</option>), the
-green queue is split into green (for the currently running thread
-only) and amber (for other runnable threads). We do not recommend
-that you use the verbose suboption if you are planning to use the
-<command>hbcpp</command> profiling tools or if you are context switching at every heap
-check (with <option>-C</option>).
--->
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-qt<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qt<num> RTS option</primary></indexterm>
-(paraLLEL ONLY) Limit the thread pool size, i.e. the number of
-threads per processor to <literal><num></literal>. The default is
-32. Each thread requires slightly over 1K <emphasis>words</emphasis> in
-the heap for thread state and stack objects. (For 32-bit machines, this
-translates to 4K bytes, and for 64-bit machines, 8K bytes.)
-</para>
-</listitem>
-</varlistentry>
-<!-- no more -HWL
-<varlistentry>
-<term><option>-d</option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-d RTS option (parallel)</primary></indexterm>
-(paraLLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or
-something…) per PVM processor. We use the standard <command>debugger</command>
-script that comes with PVM3, but we sometimes meddle with the
-<command>debugger2</command> script. We include ours in the GHC distribution,
-in <filename>ghc/utils/pvm/</filename>.
-</para>
-</listitem>
-</varlistentry>
--->
-<varlistentry>
-<term><option>-qe<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qe<num> RTS option
-(parallel)</primary></indexterm> (paraLLEL ONLY) Limit the spark pool size
-i.e. the number of pending sparks per processor to
-<literal><num></literal>. The default is 100. A larger number may be
-appropriate if your program generates large amounts of parallelism
-initially.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-qQ<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qQ<num> RTS option (parallel)</primary></indexterm>
-(paraLLEL ONLY) Set the size of packets transmitted between processors
-to <literal><num></literal>. The default is 1024 words. A larger number may be
-appropriate if your machine has a high communication cost relative to
-computation speed.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-qh<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qh<num> RTS option (parallel)</primary></indexterm>
-(paraLLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to
-<num>-1 (0 means infinity). By default GUM uses full-subgraph
-packing, i.e. the entire subgraph with the requested closure as root is
-transmitted (provided it fits into one packet). Choosing a smaller value
-reduces the amount of pre-fetching of work done in GUM. This can be
-advantageous for improving data locality but it can also worsen the balance
-of the load in the system.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-qg<num></option>:</term>
-<listitem>
-<para>
-<indexterm><primary>-qg<num> RTS option
-(parallel)</primary></indexterm> (paraLLEL ONLY) Select a globalisation
-scheme. This option affects the
-generation of global addresses when transferring data. Global addresses are
-globally unique identifiers required to maintain sharing in the distributed
-graph structure. Currently this is a binary option. With <num>=0 full globalisation is used
-(default). This means a global address is generated for every closure that
-is transmitted. With <num>=1 a thunk-only globalisation scheme is
-used, which generated global address only for thunks. The latter case may
-lose sharing of data but has a reduced overhead in packing graph structures
-and maintaining internal tables of global addresses.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</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>-mv8</option>:</term>
- <listitem>
- <para>(SPARC machines)<indexterm><primary>-mv8 option (SPARC
- only)</primary></indexterm> Means to pass the like-named
- option to GCC; it says to use the Version 8 SPARC
- instructions, notably integer multiply and divide. The
- similar <option>-m*</option> GCC options for SPARC also
- work, actually.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-monly-[32]-regs</option>:</term>
- <listitem>
- <para>(iX86 machines)<indexterm><primary>-monly-N-regs
- option (iX86 only)</primary></indexterm> GHC tries to
- “steal” four registers from GCC, for performance
- reasons; it almost always works. However, when GCC is
- compiling some modules with four stolen registers, it will
- crash, probably saying:
-
-<screen>
-Foo.hc:533: fixed or forbidden register was spilled.
-This may be due to a compiler bug or to impossible asm
-statements or clauses.
-</screen>
-
- Just give some registers back with
- <option>-monly-N-regs</option>. Try `3' first, then `2'.
- If `2' doesn't work, please report the bug to us.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect1>
-
-&runtime;
-
-<sect1 id="ext-core">
- <title>Generating and compiling External Core Files</title>
-
- <indexterm><primary>intermediate code generation</primary></indexterm>
-
- <para>GHC can dump its optimized intermediate code (said to be in “Core” format)
- to a file as a side-effect of compilation. Core files, which are given the suffix
- <filename>.hcr</filename>, can be read and processed by non-GHC back-end
- tools. The Core format is formally described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">
- <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>,
- and sample tools (in Haskell)
- for manipulating Core files are available in the GHC source distribution
- directory <literal>/fptools/ghc/utils/ext-core</literal>.
- Note that the format of <literal>.hcr</literal>
- files is <emphasis>different</emphasis> (though similar) to the Core output format generated
- for debugging purposes (<xref linkend="options-debugging"/>).</para>
-
- <para>The Core format natively supports notes which you can add to
- your source code using the <literal>CORE</literal> pragma (see <xref
- linkend="pragmas"/>).</para>
-
- <variablelist>
-
- <varlistentry>
- <term>
- <option>-fext-core</option>
- <indexterm><primary><option>-fext-core</option></primary></indexterm>
- </term>
- <listitem>
- <para>Generate <literal>.hcr</literal> files.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
-<para>GHC can also read in External Core files as source; just give the <literal>.hcr</literal> file on
-the command line, instead of the <literal>.hs</literal> or <literal>.lhs</literal> Haskell source.
-A current infelicity is that you need to give the <literal>-fglasgow-exts</literal> flag too, because
-ordinary Haskell 98, when translated to External Core, uses things like rank-2 types.</para>
-</sect1>
-
-&debug;
-&flags;
-
-</chapter>
-
-<!-- Emacs stuff:
- ;;; Local Variables: ***
- ;;; mode: xml ***
- ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
- ;;; End: ***
- -->
projects / ghc-hetmet.git / blobdiff