</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>
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>
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
<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>
+ linkend="search-path">).</para>
</sect1>
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>
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
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>
</sect1>
- &separate;
&packages;
<sect1 id="options-optimise">
&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;