<title>Options related to a particular phase</title>
<sect2 id="replacing-phases">
- <title>Replacing the program for one or more phases.</title>
+ <title>Replacing the program for one or more phases</title>
<indexterm><primary>phases, changing</primary></indexterm>
<para>You may specify that a different program be used for one
of the phases of the compilation system, in place of whatever
- the <Command>ghc</Command> has wired into it. For example, you
+ the <command>ghc</command> has wired into it. For example, you
might want to try a different assembler. The following options
allow you to change the external program used for a given
- compilation phases:</para>
+ compilation phase:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-pgmL</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmL</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the literate
+ pre-processor.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgmP</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmP</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the C
+ pre-processor (with <option>-cpp</option> only).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgmc</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmc</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the C
+ compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgma</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgma</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the
+ assembler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgml</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgml</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the
+ linker.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgmdll</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmdll</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the DLL
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgmdep</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmdep</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the dependency
+ generator.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-pgmF</option> <replaceable>cmd</replaceable></term>
+ <indexterm><primary><option>-pgmF</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the
+ pre-processor (with <option>-F</option> only).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect2>
<sect2 id="forcing-options-through">
- <title>Forcing options to a particular phase.</title>
+ <title>Forcing options to a particular phase</title>
<indexterm><primary>forcing GHC-phase options</primary></indexterm>
<para>Options can be forced through to a particlar compilation
phase, using the following flags:</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-optL</option> <replaceable>option</replaceable></term>
+ <indexterm><primary><option>-optL</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the
+ literate pre-processor</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-optP</option> <replaceable>option</replaceable></term>
+ <indexterm><primary><option>-optP</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to CPP (makes
+ sense only if <option>-cpp</option> is also on).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-optF</option> <replaceable>option</replaceable></term>
+ <indexterm><primary><option>-optF</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the
+ custom pre-processor (see <xref linkend="pre-processor"/>).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-optc</option> <replaceable>option</replaceable></term>
+ <indexterm><primary><option>-optc</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the C compiler.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-opta</option> <replaceable>option</replaceable></term>
+ <indexterm><primary><option>-opta</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the assembler.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-optl</option> <replaceable>option</replaceable></term>
+ <indexterm><primary><option>-optl</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the linker.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-optdll</option> <replaceable>option</replaceable></term>
+ <indexterm><primary><option>-optdll</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the DLL generator.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-optdep</option> <replaceable>option</replaceable></term>
+ <indexterm><primary><option>-optdep</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the
+ dependency generator.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<para>So, for example, to force an <option>-Ewurble</option>
option to the assembler, you would tell the driver
<para>GHC is itself a Haskell program, so if you need to pass
options directly to GHC's runtime system you can enclose them in
<literal>+RTS ... -RTS</literal> (see <xref
- linkend="runtime-control">).</para>
+ linkend="runtime-control"/>).</para>
</sect2>
<option>-D</option> macros passed to the C compiler
when compiling via C! For those, use the
<option>-optc-Dfoo</option> hack… (see <xref
- linkend="forcing-options-through">).</para>
+ linkend="forcing-options-through"/>).</para>
</listitem>
</varlistentry>
</varlistentry>
</variablelist>
- <para>A small word of warning: <option>-cpp</option> is not
- friendly to “string gaps”.<indexterm><primary>-cpp
- vs string gaps</primary></indexterm><indexterm><primary>string
- gaps vs -cpp</primary></indexterm>. In other words, strings
- such as the following:</para>
+ <sect3 id="cpp-string-gaps">
+ <title>CPP and string gaps</title>
-<ProgramListing>
+ <para>A small word of warning: <option>-cpp</option> is not
+ friendly to “string gaps”.<indexterm><primary>-cpp
+ vs string gaps</primary></indexterm><indexterm><primary>string
+ gaps vs -cpp</primary></indexterm>. In other words, strings
+ such as the following:</para>
+
+<programlisting>
strmod = "\
\ p \
\ "
-</ProgramListing>
+</programlisting>
+
+ <para>don't work with <option>-cpp</option>;
+ <filename>/usr/bin/cpp</filename> elides the backslash-newline
+ pairs.</para>
+
+ <para>However, it appears that if you add a space at the end
+ of the line, then <command>cpp</command> (at least GNU
+ <command>cpp</command> and possibly other
+ <command>cpp</command>s) leaves the backslash-space pairs
+ alone and the string gap works as expected.</para>
+ </sect3>
+ </sect2>
- <para>don't work with <option>-cpp</option>;
- <filename>/usr/bin/cpp</filename> elides the backslash-newline
- pairs.</para>
+ <sect2 id="pre-processor">
+ <title>Options affecting a Haskell pre-processor</title>
+
+ <indexterm><primary>pre-processing: custom</primary></indexterm>
+ <indexterm><primary>Pre-processor options</primary></indexterm>
- <para>However, it appears that if you add a space at the end of
- the line, then <command>cpp</command> (at least GNU
- <command>cpp</command> and possibly other
- <command>cpp</command>s) leaves the backslash-space pairs alone
- and the string gap works as expected.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-F</option></term>
+ <indexterm><primary><option>-F</option></primary></indexterm>
+ <listitem>
+ <para>A custom pre-processor is run over your Haskell
+ source file only if the <option>-F</option> option
+ <indexterm><primary>-F</primary></indexterm> is
+ given.</para>
+
+ <para>Running a custom pre-processor at compile-time is in
+ some settings appropriate and useful. The
+ <option>-F</option> option lets you run a pre-processor as
+ part of the overall GHC compilation pipeline, which has
+ the advantage over running a Haskell pre-processor
+ separately in that it works in interpreted mode and you
+ can continue to take reap the benefits of GHC's
+ recompilation checker.</para>
+
+ <para>The pre-processor is run just before the Haskell
+ compiler proper processes the Haskell input, but after the
+ literate markup has been stripped away and (possibly) the
+ C pre-processor has washed the Haskell input.</para>
+
+ <para>Use
+ <option>-pgmF <replaceable>cmd</replaceable></option>
+ to select the program to use as the preprocessor. When
+ invoked, the <replaceable>cmd</replaceable> pre-processor
+ is given at least three arguments on its command-line: the
+ first argument is the name of the original source file,
+ the second is the name of the file holding the input, and
+ the third is the name of the file where
+ <replaceable>cmd</replaceable> should write its output
+ to.</para>
+
+ <para>Additional arguments to the pre-processor can be
+ passed in using the <option>-optF</option> option. These
+ are fed to <replaceable>cmd</replaceable> on the command
+ line after the three standard input and output
+ arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect2>
<sect2 id="options-C-compiler">
way to do this, but you can use this hack from the
command-line:</para>
-<Screen>
+<screen>
% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
-</Screen>
+</screen>
</sect2>
fast), but may produce code that is slightly slower than
compiling via C. <option>-fasm</option> is the default
when optimisation is off (see <xref
- linkend="options-optimise">).</para>
+ linkend="options-optimise"/>).</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
+ <term><option>-no-link</option></term>
+ <indexterm>
+ <primary><option>-no-link</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Omit the link step. This flag can be useful if you
+ want to avoid linking in <option>--make</option> mode,
+ where linking is normally done automatically if the program
+ contains a <literal>Main</literal> module.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-package</option> <replaceable>name</replaceable></term>
<indexterm><primary><option>-package</option></primary></indexterm>
<listitem>
<para>If you are using a Haskell “package”
- (see <xref linkend="packages">), don't forget to add the
+ (see <xref linkend="packages"/>), don't forget to add the
relevant <option>-package</option> option when linking the
program too: it will cause the appropriate libraries to be
linked in with the program. Forgetting the
</varlistentry>
<varlistentry>
+ <term><option>-framework</option> <replaceable>name</replaceable></term>
+ <indexterm><primary><option>-framework</option></primary></indexterm>
+ <listitem>
+ <para>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
+ This option corresponds to the <option>-framework</option> option for Apple's Linker.
+ Please note that frameworks and packages are two different things - frameworks don't
+ contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
+ To link to Apple's “Carbon” API, for example, you'd use
+ <option>-framework Carbon</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-L</option><replaceable>dir</replaceable></term>
<indexterm><primary><option>-L</option></primary></indexterm>
<listitem>
</varlistentry>
<varlistentry>
+ <term><option>-framework-path</option><replaceable>dir</replaceable></term>
+ <indexterm><primary><option>-framework-path</option></primary></indexterm>
+ <listitem>
+ <para>On Darwin/MacOS X only, prepend the directory <replaceable>dir</replaceable> to
+ the framework directories path. This option corresponds to the <option>-F</option>
+ option for Apple's Linker (<option>-F</option> already means something else for GHC).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-split-objs</option></term>
<indexterm><primary><option>-split-objs</option></primary></indexterm>
<listitem>
</varlistentry>
<varlistentry>
+ <term><option>-main-is <replaceable>thing</replaceable></option></term>
+ <indexterm><primary><option>-main-is</option></primary></indexterm>
+ <indexterm><primary>specifying your own main function</primary></indexterm>
+ <listitem>
+ <para> The normal rule in Haskell is that your program must supply a <literal>main</literal>
+ function in module <literal>Main</literal>. When testing, it is often convenient
+ to change which function is the "main" one, and the <option>-main-is</option> flag
+ allows you to do so. The <replaceable>thing</replaceable> can be one of:
+ <itemizedlist>
+ <listitem><para>A lower-case identifier <literal>foo</literal>. GHC assumes that the main function is <literal>Main.foo</literal>.</para></listitem>
+ <listitem><para>An module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem>
+ <listitem><para>An qualified name <literal>A.foo</literal>. GHC assumes that the main function is <literal>A.foo</literal>.</para></listitem>
+ </itemizedlist>
+ Strictly speaking, <option>-main-is</option> is not a link-phase flag at all; it has no effect on the link step.
+ The flag must be specified when compiling the module containing the specified main function (e.g. module <literal>A</literal>
+ in the latter two items above. It has no effect for other modules (and hence can safely be given to <literal>ghc --make</literal>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-no-hs-main</option></term>
<indexterm><primary><option>-no-hs-main</option></primary></indexterm>
<indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm>
as part of another (non-Haskell) program, the RTS will not
be supplying its definition of <function>main()</function>
at link-time, you will have to. To signal that to the
- driver script when linking, use
- <option>-no-hs-main</option>.</para>
+ compiler when linking, use
+ <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para>
<para>Notice that since the command-line passed to the
linker is rather involved, you probably want to use
though, just try linking once with <option>-v</option> on
to see what options the driver passes through to the
linker.</para>
+
+ <para>The <option>-no-hs-main</option> flag can also be
+ used to persuade the compiler to do the link step in
+ <option>--make</option> mode when there is no Haskell
+ <literal>Main</literal> module present (normally the
+ compiler will not attempt linking when there is no
+ <literal>Main</literal>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-debug</option></term>
+ <indexterm><primary><option>-debug</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Link the program with a debugging version of the
+ runtime system. The debugging runtime turns on numerous
+ assertions and sanity checks, and provides extra options
+ for producing debugging output at runtime (run the program
+ with <literal>+RTS -?</literal> to see a list).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-threaded</option></term>
+ <indexterm><primary><option>-threaded</option></primary>
+ </indexterm>
+ <listitem>
+ <para>Link the program with the "threaded" runtime system.
+ This version of the runtime is designed to be used in
+ programs that use multiple operating-system threads. It
+ supports calls to foreign-exported functions from multiple
+ OS threads. Calls to foreign functions are made using the
+ same OS thread that created the Haskell thread (if it was
+ created by a call-in), or an arbitrary OS thread otherwise
+ (if the Haskell thread was created by
+ <literal>forkIO</literal>).</para>
+
+ <para>More details on the use of "bound threads" in the
+ threaded runtime can be found in the <ulink
+ url="../libraries/base/Control.Concurrent.html"><literal>Control.Concurrent</literal></ulink> module.</para>
+
+ <para>The threaded RTS does <emphasis>not</emphasis>
+ support using multiple CPUs to speed up execution of a
+ multi-threaded Haskell program. The GHC runtime platform
+ is still single-threaded, but using the
+ <option>-threaded</option> option it can be used safely in
+ a multi-threaded environment.</para>
</listitem>
</varlistentry>
+
</variablelist>
</sect2>
projects / ghc-hetmet.git / blobdiff