<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>
+ <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>
- <group>
- <arg>-E</arg>
- <arg>-C</arg>
- <arg>-S</arg>
- <arg>-c</arg>
- </group>
- </cmdsynopsis></term>
- <indexterm><primary><option>--make</option></primary>
- </indexterm>
- <listitem>
- <para>This is the traditional batch-compiler mode, in which
+ <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>
-
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
<sect1>
<title>Options overview</title>
<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
if the top module is <literal>Main</literal>, 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
<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>
+
+ <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>
+ <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.,
</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…
</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>
<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
</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>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><option>-Ofile <file></option>:</term>
<indexterm><primary>-Ofile <file> option</primary></indexterm>
<indexterm><primary>optimising, customised</primary></indexterm>
<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 -O2-for-C</option> (and
- we go for lots of coffee breaks).</para>
+ broke, we tend to use <option>-O -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>,
</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 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>
+
+ <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>
+
+</sect1>
+
&debug;
&flags;
projects / ghc-hetmet.git / blobdiff