<variablelist>
<varlistentry>
<term><cmdsynopsis><command>ghc</command>
- <arg choice=plain>--interactive</arg>
+ <arg choice=plain>––interactive</arg>
</cmdsynopsis></term>
<indexterm><primary>interactive mode</primary>
</indexterm>
<varlistentry>
<term><cmdsynopsis><command>ghc</command>
- <arg choice=plain>--make</arg>
+ <arg choice=plain>––make</arg>
</cmdsynopsis></term>
<indexterm><primary>make mode</primary>
</indexterm>
- <indexterm><primary><option>--make</option></primary>
+ <indexterm><primary><option>––make</option></primary>
</indexterm>
<listitem>
<para>In this mode, GHC will build a multi-module Haskell
<variablelist>
<varlistentry>
- <term><literal>-help</literal></term>
- <term><literal>-?</literal></term>
- <indexterm><primary><literal>-?</literal></primary></indexterm>
- <indexterm><primary><literal>-help</literal></primary></indexterm>
+ <term><option>––help</option></term>
+ <term><option>-?</option></term>
+ <indexterm><primary><option>-?</option></primary></indexterm>
+ <indexterm><primary><option>––help</option></primary></indexterm>
<listitem>
<para>Cause GHC to spew a long usage message to standard
output and then exit.</para>
</varlistentry>
<varlistentry>
- <term><literal>-v</literal></term>
- <indexterm><primary><literal>-v</literal></primary></indexterm>
+ <term><option>-v</option></term>
+ <indexterm><primary><option>-v</option></primary></indexterm>
<listitem>
<para>The <option>-v</option> option makes GHC
<emphasis>verbose</emphasis>: it reports its version number
</varlistentry>
<varlistentry>
- <term><literal>-v</literal><replaceable>n</replaceable></term>
+ <term><option>-v</option><replaceable>n</replaceable></term>
<indexterm><primary><option>-v</option></primary></indexterm>
<listitem>
<para>To provide more control over the compiler's verbosity,
<variablelist>
<varlistentry>
- <term><literal>-v0</literal></term>
+ <term><option>-v0</option></term>
<listitem>
<para>Disable all non-essential messages (this is the
default).</para>
</varlistentry>
<varlistentry>
- <term><literal>-v1</literal></term>
+ <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>
+ <option>––make</option> or
+ <option>––interactive</option> is on).</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>-v2</literal></term>
+ <term><option>-v2</option></term>
<listitem>
<para>Print the name of each compilation phase as it
is executed. (equivalent to
</varlistentry>
<varlistentry>
- <term><literal>-v3</literal></term>
+ <term><option>-v3</option></term>
<listitem>
<para>The same as <option>-v2</option>, except that in
addition the full command line (if appropriate) for
</varlistentry>
<varlistentry>
- <term><literal>-v4</literal></term>
+ <term><option>-v4</option></term>
<listitem>
<para>The same as <option>-v3</option> except that the
intermediate program representation after each
</varlistentry>
<varlistentry>
- <term><literal>--version</literal></term>
- <indexterm><primary><literal>--version</literal></primary></indexterm>
+ <term><option>––version</option></term>
+ <indexterm><primary><option>––version</option></primary></indexterm>
<listitem>
<para>Print a one-line string including GHC's version number.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>--numeric-version</literal></term>
- <indexterm><primary><literal>--numeric-version</literal></primary></indexterm>
+ <term><option>––numeric-version</option></term>
+ <indexterm><primary><option>––numeric-version</option></primary></indexterm>
<listitem>
<para>Print GHC's numeric version number only.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>––print-libdir</option></term>
+ <indexterm><primary><option>––print-libdir</option></primary></indexterm>
+ <listitem>
+ <para>Print the path to GHC's library directory. This is
+ the top of the directory tree containing GHC's libraries,
+ interfaces, and include files (usually something like
+ <literal>/usr/local/lib/ghc-5.04</literal> on Unix). This
+ is the value of
+ <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
+ </indexterm>in the package configuration file (see <xref
+ linkend="packages">).</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect1>
<sect1 id="make-mode">
- <title>Using <command>ghc</command> <option>--make</option></title>
+ <title>Using <command>ghc</command> <option>––make</option></title>
- <indexterm><primary><option>--make</option></primary>
+ <indexterm><primary><option>––make</option></primary>
</indexterm>
<indexterm><primary>separate compilation</primary>
</indexterm>
- <para>When given the <option>--make</option> option, GHC will
+ <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
the program like this:</para>
<screen>
-ghc --make Main.hs
+ghc ––make Main.hs
</screen>
- <para>The command line must contain one source file or module
- name; GHC will figure out all the modules in the program by
- following the imports from this initial module. It will then
- attempt to compile each module which is out of date, and finally
- if the top module is <literal>Main</literal>, the program
+ <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>
+ <para>The main advantages to using <literal>ghc ––make</literal>
over traditional <literal>Makefile</literal>s are:</para>
<itemizedlist>
<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
+ ––make</literal> can be up to twice as fast as running
<literal>ghc</literal> individually on each source
file.</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
+ 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
linkend="source-file-options">).</para>
<para>If the program needs to be linked with additional objects
- (say, some auxilliary C code), these can be specified on the
- command line as usual.</para>
+ (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
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>
+ <title>GHC without <option>––make</option></title>
- <para>Without <option>--make</option>, GHC will compile one or
+ <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
<variablelist>
<varlistentry>
- <term><literal>-o</literal></term>
- <indexterm><primary><literal>-o</literal></primary></indexterm>
+ <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.,
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><literal>-odir</literal></term>
- <indexterm><primary><literal>-odir</literal></primary></indexterm>
+ <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…
intermediate C files.</para>
<para>The <option>-hisuf</option>/<option>-osuf</option>
- game is useful if you want to compile a program with both
- GHC and HBC (say) in the same directory. Let HBC use the
- standard <filename>.hi</filename>/<filename>.o</filename>
- suffixes; add <option>-hisuf g_hi -osuf
- g_o</option> to your <command>make</command> rule for
- GHC compiling…</para>
+ 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>
<variablelist>
<varlistentry>
- <term><literal>-keep-hc-files</literal></term>
+ <term><option>-keep-hc-files</option></term>
<indexterm>
- <primary><literal>-keep-hc-files</literal></primary>
+ <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 <literal>-fvia-C</literal> to force them
+ may need to use <option>-fvia-C</option> to force them
to be produced).</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>-keep-s-files</literal></term>
+ <term><option>-keep-s-files</option></term>
<indexterm>
- <primary><literal>-keep-s-files</literal></primary>
+ <primary><option>-keep-s-files</option></primary>
</indexterm>
<listitem>
<para>Keep intermediate <literal>.s</literal> files.</para>
</varlistentry>
<varlistentry>
- <term><literal>-keep-raw-s-files</literal></term>
+ <term><option>-keep-raw-s-files</option></term>
<indexterm>
- <primary><literal>-keep-raw-s-files</literal></primary>
+ <primary><option>-keep-raw-s-files</option></primary>
</indexterm>
<listitem>
<para>Keep intermediate <literal>.raw-s</literal> files.
</varlistentry>
<varlistentry>
- <term><literal>-keep-tmp-files</literal></term>
+ <term><option>-keep-tmp-files</option></term>
<indexterm>
- <primary><literal>-keep-tmp-files</literal></primary>
+ <primary><option>-keep-tmp-files</option></primary>
</indexterm>
<indexterm>
<primary>temporary files</primary>
temporary files, which it normally keeps in
<literal>/tmp</literal> (or possibly elsewhere; see <xref
linkend="temp-files">). Running GHC with
- <literal>-v</literal> will show you what temporary files
+ <option>-v</option> will show you what temporary files
were generated along the way.</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
- <term><literal>-tmpdir</literal></term>
- <indexterm><primary><literal>-tmpdir</literal></primary></indexterm>
+ <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
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-overlpapping-patterns</option>,
+ <option>-fwarn-overlapping-patterns</option>,
<option>-fwarn-deprecations</option>,
<option>-fwarn-duplicate-exports</option>,
<option>-fwarn-missing-fields</option>, and
</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
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>
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>
<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. To
- eliminate the warning, all unused variables can be replaced
- with wildcards.</para>
+ <VarName>x</VarName> and <VarName>y</VarName> as unused. The
+ warning is suppressed if the variable name begins with an underscore, thus:
+ <programlisting>
+ f _x = True
+ </programlisting>
+ </para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term><option>-O2-for-C</option>:</term>
- <indexterm><primary>-O2-for-C option</primary></indexterm>
- <indexterm><primary>gcc, invoking with -O2</primary></indexterm>
- <listitem>
- <para>Says to run GCC with <option>-O2</option>, which may
- be worth a few percent in execution speed. Don't forget
- <option>-fvia-C</option>, lest you use the native-code
- generator and bypass GCC altogether!</para>
-
- <para><emphasis>Note: some versions of gcc are known to
- have code generation bugs with <option>-O2</option>. Use
- this option at your own risk! But we'd be keen to here
- any reports of whether (a) it works or (b) it improves
- performance at all.</emphasis></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><option>-Ofile <file></option>:</term>
<indexterm><primary>-Ofile <file> option</primary></indexterm>
<indexterm><primary>optimising, customised</primary></indexterm>
</variablelist>
</sect2>
-
+
</sect1>
-
-&phases;
-
-<Sect1 id="sec-using-concurrent">
+
+ &phases;
+
+ <sect1 id="sec-using-concurrent">
<title>Using Concurrent Haskell</title>
-<para>
-<indexterm><primary>Concurrent Haskell—use</primary></indexterm>
-</para>
+ <indexterm><primary>Concurrent Haskell—use</primary></indexterm>
<para>
-GHC (as of version 4.00) 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
-(i.e. <literal>Concurrent</literal> and friends), use the
-<option>-package concurrent</option> option.
-</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
+<literal>Control.Concurrent</literal> (details are in the accompanying
+library documentation).</para>
<para>
-Three RTS options are provided for modifying the behaviour of the
-threaded runtime system. See the descriptions of
-<option>-C[<us>]</option>, <option>-q</option>, and
-<option>-t<num></option> in <XRef LinkEnd="parallel-rts-opts">.
+RTS options are provided for modifying the behaviour of the threaded
+runtime system. See <XRef LinkEnd="parallel-rts-opts">.
</para>
<para>
-Concurrent Haskell is described in more detail in <XRef
-LinkEnd="sec-Concurrent">.
+Concurrent Haskell is described in more detail in the documentation
+for the <literal>Control.Concurrent</literal> module.
</para>
</Sect1>
</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></term>
+ <indexterm>
+ <primary><option>-fext-core</option></primary>
+ </indexterm>
+ <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 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;
&flags;
projects / ghc-hetmet.git / blobdiff