<indexterm><primary>GHC, using</primary></indexterm>
<indexterm><primary>using GHC</primary></indexterm>
- <para>GHC can work in one of three “modes”:</para>
-
- <variablelist>
- <varlistentry>
- <term><cmdsynopsis><command>ghc</command>
- <arg choice=plain>––interactive</arg>
- </cmdsynopsis></term>
- <indexterm><primary>interactive mode</primary>
- </indexterm>
- <indexterm><primary>ghci</primary>
- </indexterm>
- <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></term>
- <indexterm><primary>make mode</primary>
- </indexterm>
- <indexterm><primary><option>––make</option></primary>
- </indexterm>
- <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>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><cmdsynopsis>
- <command>ghc</command>
- <group>
- <arg>-E</arg>
- <arg>-C</arg>
- <arg>-S</arg>
- <arg>-c</arg>
- </group>
- </cmdsynopsis></term>
- <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>
- <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.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
<sect1>
<title>Options overview</title>
pragma in a source file or set from the GHCi command-line with
<literal>:set</literal>.</para>
- <para>As a rule of thumb, all the language options are dynamic, as
- are the warning options and the debugging options. The rest are
- static, with the notable exceptions of <option>-v</option>,
- <option>-cpp</option>, <option>-fasm</option>,
- <option>-fvia-C</option>, and <option>-#include</option>.
-
- The flag reference tables (<xref linkend="flag-reference">) lists
- the status of each flag.</para>
+ <para>As a rule of thumb, options which relate to filenames are
+ static, and the rest are dynamic. The flag reference tables (<xref
+ linkend="flag-reference">) lists the status of each flag.</para>
</sect1>
<sect1 id="file-suffixes">
</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></term>
+ <indexterm><primary>interactive mode</primary>
+ </indexterm>
+ <indexterm><primary>ghci</primary>
+ </indexterm>
+ <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></term>
+ <indexterm><primary>make mode</primary>
+ </indexterm>
+ <indexterm><primary><option>––make</option></primary>
+ </indexterm>
+ <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></term>
+ <indexterm><primary>eval mode</primary>
+ </indexterm>
+ <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></term>
+ <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>
+ <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></term>
+ <indexterm><primary>dependency-generation mode</primary>
+ </indexterm>
+ <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></term>
+ <indexterm><primary>dependency-generation mode</primary>
+ </indexterm>
+ <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 muli-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>
+ </listitem>
+ <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary>
+ </indexterm>
+ <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</literal>
+ pragma (see <xref linkend="source-file-options">).</para>
+
+ <para>If the program needs to be linked with additional objects
+ (say, some auxilliary C code), then the object files can be
+ 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 this mode, 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>
+ </sect2>
+ </sect1>
+
<sect1 id="options-help">
<title>Help and verbosity options</title>
</varlistentry>
<varlistentry>
+ <term><option>-V</option></term>
<term><option>––version</option></term>
+ <indexterm><primary><option>-V</option></primary></indexterm>
<indexterm><primary><option>––version</option></primary></indexterm>
<listitem>
<para>Print a one-line string including GHC's version number.</para>
</variablelist>
</sect1>
- <sect1 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 muli-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>
- </listitem>
- <indexterm><primary><literal>Makefile</literal>s</primary><secondary>avoiding</secondary>
- </indexterm>
- <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</literal> pragma (see <xref
- linkend="source-file-options">).</para>
-
- <para>If the program needs to be linked with additional objects
- (say, some auxilliary C code), then the object files can be
- 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="options-finding-imports">).</para>
-
- </sect1>
-
- <Sect1 id="options-order">
- <title>GHC without <option>––make</option></title>
-
- <para>Without <option>––make</option>, 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: <literal>ghc -c
- Foo.hs</literal></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>-ccp</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>
- </sect1>
-
- <sect1 id="options-output">
- <title>Re-directing the compilation output(s)</title>
-
- <indexterm><primary>output-directing options</primary></indexterm>
- <indexterm><primary>redirecting compilation output</primary></indexterm>
-
-
- <variablelist>
- <varlistentry>
- <term><option>-o</option></term>
- <indexterm><primary><option>-o</option></primary></indexterm>
- <listitem>
- <para>GHC's compiled output normally goes into a
- <filename>.hc</filename>, <filename>.o</filename>, etc.,
- file, depending on the last-run compilation phase. The
- option <option>-o foo</option><IndexTerm><Primary>-o
- option</Primary></IndexTerm> re-directs the output of that
- last-run phase to file <filename>foo</filename>.</para>
-
- <para>Note: this “feature” can be
- counterintuitive: <command>ghc -C -o foo.o foo.hs</command>
- will put the intermediate C code in the file
- <filename>foo.o</filename>, name notwithstanding!</para>
-
- <para>Note: on Windows, if the result is an executable file, the
- extension "<filename>.exe</filename>" is added if the specified filename
- does not already have an extension. Thus
- <programlisting>
- ghc -o foo Main.hs
- </programlisting>
- will compile and link the module <filename>Main.hs</filename>, and put the
- resulting executable in <filename>foo.exe</filename> (not <filename>foo</filename>).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-odir</option></term>
- <indexterm><primary><option>-odir</option></primary></indexterm>
- <listitem>
- <para>The <option>-o</option> option isn't of much use if
- you have <emphasis>several</emphasis> input files…
- Non-interface output files are normally put in the same
- directory as their corresponding input file came from. You
- may specify that they be put in another directory using the
- <option>-odir <dir></option><IndexTerm><Primary>-odir
- <dir> option</Primary></IndexTerm> (the “Oh,
- dear” option). For example:</para>
-
-<Screen>
-% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch`
-</Screen>
-
- <para>The output files, <filename>Foo.o</filename>,
- <filename>Bar.o</filename>, and
- <filename>Bumble.o</filename> would be put into a
- subdirectory named after the architecture of the executing
- machine (<filename>sun4</filename>,
- <filename>mips</filename>, etc). The directory must already
- exist; it won't be created.</para>
-
- <para>Note that the <option>-odir</option> option does
- <emphasis>not</emphasis> affect where the interface files
- are put. In the above example, they would still be put in
- <filename>parse/Foo.hi</filename>,
- <filename>parse/Bar.hi</filename>, and
- <filename>gurgle/Bumble.hi</filename>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-ohi</option> <replaceable>file</replaceable></term>
- <indexterm><primary><option>-ohi</option></primary>
- </indexterm>
- <listitem>
- <para>The interface output may be directed to another file
- <filename>bar2/Wurble.iface</filename> with the option
- <option>-ohi bar2/Wurble.iface</option> (not
- recommended).</para>
-
- <para>WARNING: if you redirect the interface file somewhere
- that GHC can't find it, then the recompilation checker may
- get confused (at the least, you won't get any recompilation
- avoidance). We recommend using a combination of
- <option>-hidir</option> and <option>-hisuf</option> options
- instead, if possible.</para>
-
- <para>To avoid generating an interface at all, you could use
- this option to redirect the interface into the bit bucket:
- <literal>-ohi /dev/null</literal>, for example.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-hidir</option> <replaceable>directory</replaceable></term>
- <indexterm><primary><option>-hidir</option></primary>
- </indexterm>
- <listitem>
- <para>Redirects all generated interface files into
- <replaceable>directory</replaceable>, instead of the default
- which is to place the interface file in the same directory
- as the source file.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-osuf</option> <replaceable>suffix</replaceable></term>
- <term><option>-hisuf</option> <replaceable>suffix</replaceable></term>
- <term><option>-hcsuf</option> <replaceable>suffix</replaceable></term>
- <indexterm><primary><option>-osuf</option></primary></indexterm>
- <indexterm><primary><option>-hisuf</option></primary></indexterm>
- <indexterm><primary><option>-hcsuf</option></primary></indexterm>
- <listitem>
- <para>EXOTICA: The <option>-osuf</option>
- <replaceable>suffix</replaceable> will change the
- <literal>.o</literal> file suffix for object files to
- whatever you specify. We use this when compiling libraries,
- so that objects for the profiling versions of the libraries
- don't clobber the normal ones.</para>
-
- <para>Similarly, the <option>-hisuf</option>
- <replaceable>suffix</replaceable> will change the
- <literal>.hi</literal> file suffix for non-system interface
- files (see <XRef LinkEnd="hi-options">).</para>
-
- <para>Finally, the option <option>-hcsuf</option>
- <replaceable>suffix</replaceable> will change the
- <literal>.hc</literal> file suffix for compiler-generated
- intermediate C files.</para>
-
- <para>The <option>-hisuf</option>/<option>-osuf</option>
- game is particularly useful if you want to compile a program both with and without
- profiling, in the same directory. You can say:
- <Screen>
- ghc ...
- </Screen>
- to get the ordinary version, and
- <Screen>
- ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all
- </Screen>
- to get the profiled version.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <sect2 id="keeping-intermediates">
- <title>Keeping Intermediate Files</title>
- <indexterm><primary>intermediate files, saving</primary>
- </indexterm>
- <indexterm><primary><literal>.hc</literal> files, saving</primary>
- </indexterm>
- <indexterm><primary><literal>.s</literal> files, saving</primary>
- </indexterm>
-
-
- <para>The following options are useful for keeping certain
- intermediate files around, when normally GHC would throw these
- away after compilation:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-keep-hc-files</option></term>
- <indexterm>
- <primary><option>-keep-hc-files</option></primary>
- </indexterm>
- <listitem>
- <para>Keep intermediate <literal>.hc</literal> files when
- doing <literal>.hs</literal>-to-<literal>.o</literal>
- compilations via C (NOTE: <literal>.hc</literal> files
- aren't generated when using the native code generator, you
- may need to use <option>-fvia-C</option> to force them
- to be produced).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-keep-s-files</option></term>
- <indexterm>
- <primary><option>-keep-s-files</option></primary>
- </indexterm>
- <listitem>
- <para>Keep intermediate <literal>.s</literal> files.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-keep-raw-s-files</option></term>
- <indexterm>
- <primary><option>-keep-raw-s-files</option></primary>
- </indexterm>
- <listitem>
- <para>Keep intermediate <literal>.raw-s</literal> files.
- These are the direct output from the C compiler, before
- GHC does “assembly mangling” to produce the
- <literal>.s</literal> file. Again, these are not produced
- when using the native code generator.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-keep-tmp-files</option></term>
- <indexterm>
- <primary><option>-keep-tmp-files</option></primary>
- </indexterm>
- <indexterm>
- <primary>temporary files</primary>
- <secondary>keeping</secondary>
- </indexterm>
- <listitem>
- <para>Instructs the GHC driver not to delete any of its
- temporary files, which it normally keeps in
- <literal>/tmp</literal> (or possibly elsewhere; see <xref
- linkend="temp-files">). Running GHC with
- <option>-v</option> will show you what temporary files
- were generated along the way.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="temp-files">
- <title>Redirecting temporary files</title>
-
- <indexterm>
- <primary>temporary files</primary>
- <secondary>redirecting</secondary>
- </indexterm>
-
- <variablelist>
- <varlistentry>
- <term><option>-tmpdir</option></term>
- <indexterm><primary><option>-tmpdir</option></primary></indexterm>
- <listitem>
- <para>If you have trouble because of running out of space
- in <filename>/tmp</filename> (or wherever your
- installation thinks temporary files should go), you may
- use the <option>-tmpdir
- <dir></option><IndexTerm><Primary>-tmpdir
- <dir> option</Primary></IndexTerm> option to specify
- an alternate directory. For example, <option>-tmpdir
- .</option> says to put temporary files in the current
- working directory.</para>
-
- <para>Alternatively, use your <Constant>TMPDIR</Constant>
- environment variable.<IndexTerm><Primary>TMPDIR
- environment variable</Primary></IndexTerm> Set it to the
- name of the directory where temporary files should be put.
- GCC and other programs will honour the
- <Constant>TMPDIR</Constant> variable as well.</para>
-
- <para>Even better idea: Set the
- <Constant>DEFAULT_TMPDIR</Constant> make variable when
- building GHC, and never worry about
- <Constant>TMPDIR</Constant> again. (see the build
- documentation).</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- </sect1>
+ &separate;
<sect1 id="options-sanity">
<title>Warnings and sanity-checking</title>
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>
</sect1>
- &separate;
&packages;
<sect1 id="options-optimise">
following “packages” of optimisations (or lack
thereof) should suffice.</para>
- <para>Once you choose a <option>-O*</option>
- “package,” stick with it—don't chop and
- change. Modules' interfaces <emphasis>will</emphasis> change
- with a shift to a new <option>-O*</option> option, and you may
- have to recompile a large chunk of all importing modules before
- your program can again be run safely (see <XRef
- LinkEnd="recomp">).</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>
<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>
<indexterm><primary>-Ofile <file> option</primary></indexterm>
<indexterm><primary>optimising, customised</primary></indexterm>
<listitem>
- <para>(NOTE: not supported yet in GHC 5.x. Please ask if
+ <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>
<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>-O -fvia-C</option> (and we 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.)
<para>This option causes all constructor fields which are
marked strict (i.e. “!”) to be unboxed or
- unpacked if possible. For example:</para>
-
-<ProgramListing>
-data T = T !Float !Float
-</ProgramListing>
-
- <para>will create a constructor <literal>T</literal>
- containing two unboxed floats if the
- <option>-funbox-strict-fields</option> flag is given.
- This may not always be an optimisation: if the
- <Function>T</Function> constructor is scrutinised and the
- floats passed to a non-strict function for example, they
- will have to be reboxed (this is done automatically by the
- compiler).</para>
-
- <para>This option should only be used in conjunction with
- <option>-O</option>, in order to expose unfoldings to the
- compiler so the reboxing can be removed as often as
- possible. For example:</para>
-
-<ProgramListing>
-f :: T -> Float
-f (T f1 f2) = f1 + f2
-</ProgramListing>
-
- <para>The compiler will avoid reboxing
- <Function>f1</Function> and <Function>f2</Function> by
- inlining <Function>+</Function> on floats, but only when
- <option>-O</option> is on.</para>
-
- <para>Any single-constructor data is eligible for
- unpacking; for example</para>
-
-<ProgramListing>
-data T = T !(Int,Int)
-</ProgramListing>
-
- <para>will store the two <literal>Int</literal>s directly
- in the <Function>T</Function> constructor, by flattening
- the pair. Multi-level unpacking is also supported:</para>
-
-<ProgramListing>
-data T = T !S
-data S = S !Int !Int
-</ProgramListing>
-
- <para>will store two unboxed <literal>Int#</literal>s
- directly in the <Function>T</Function> constructor.</para>
+ 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>
&runtime;
<sect1 id="ext-core">
- <title>Generating External Core Files</title>
+ <title>Generating and compiling External Core Files</title>
<indexterm><primary>intermediate code generation</primary></indexterm>
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>
</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 teh <literal>-fglasgow-exts</literal> flag too, because
+ordinary Haskell 98, when translated to External Core, uses things like rank-2 types.</para>
</sect1>
&debug;