diff options
Diffstat (limited to 'docs/users_guide/phases.xml')
| -rw-r--r-- | docs/users_guide/phases.xml | 874 |
1 files changed, 874 insertions, 0 deletions
diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml new file mode 100644 index 0000000000..fd034a305a --- /dev/null +++ b/docs/users_guide/phases.xml @@ -0,0 +1,874 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<sect1 id="options-phases"> + <title>Options related to a particular phase</title> + + <sect2 id="replacing-phases"> + <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 + might want to try a different assembler. The following options + allow you to change the external program used for a given + compilation phase:</para> + + <variablelist> + <varlistentry> + <term> + <option>-pgmL</option> <replaceable>cmd</replaceable> + <indexterm><primary><option>-pgmL</option></primary></indexterm> + </term> + <listitem> + <para>Use <replaceable>cmd</replaceable> as the literate + pre-processor.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-pgmP</option> <replaceable>cmd</replaceable> + <indexterm><primary><option>-pgmP</option></primary></indexterm> + </term> + <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> + <indexterm><primary><option>-pgmc</option></primary></indexterm> + </term> + <listitem> + <para>Use <replaceable>cmd</replaceable> as the C + compiler.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-pgma</option> <replaceable>cmd</replaceable> + <indexterm><primary><option>-pgma</option></primary></indexterm> + </term> + <listitem> + <para>Use <replaceable>cmd</replaceable> as the + assembler.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-pgml</option> <replaceable>cmd</replaceable> + <indexterm><primary><option>-pgml</option></primary></indexterm> + </term> + <listitem> + <para>Use <replaceable>cmd</replaceable> as the + linker.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-pgmdll</option> <replaceable>cmd</replaceable> + <indexterm><primary><option>-pgmdll</option></primary></indexterm> + </term> + <listitem> + <para>Use <replaceable>cmd</replaceable> as the DLL + generator.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-pgmdep</option> <replaceable>cmd</replaceable> + <indexterm><primary><option>-pgmdep</option></primary></indexterm> + </term> + <listitem> + <para>Use <replaceable>cmd</replaceable> as the dependency + generator.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-pgmF</option> <replaceable>cmd</replaceable> + <indexterm><primary><option>-pgmF</option></primary></indexterm> + </term> + <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> + <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> + <indexterm><primary><option>-optL</option></primary></indexterm> + </term> + <listitem> + <para>Pass <replaceable>option</replaceable> to the + literate pre-processor</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-optP</option> <replaceable>option</replaceable> + <indexterm><primary><option>-optP</option></primary></indexterm> + </term> + <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> + <indexterm><primary><option>-optF</option></primary></indexterm> + </term> + <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> + <indexterm><primary><option>-optc</option></primary></indexterm> + </term> + <listitem> + <para>Pass <replaceable>option</replaceable> to the C compiler.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-opta</option> <replaceable>option</replaceable> + <indexterm><primary><option>-opta</option></primary></indexterm> + </term> + <listitem> + <para>Pass <replaceable>option</replaceable> to the assembler.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-optl</option> <replaceable>option</replaceable> + <indexterm><primary><option>-optl</option></primary></indexterm> + </term> + <listitem> + <para>Pass <replaceable>option</replaceable> to the linker.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-optdll</option> <replaceable>option</replaceable> + <indexterm><primary><option>-optdll</option></primary></indexterm> + </term> + <listitem> + <para>Pass <replaceable>option</replaceable> to the DLL generator.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-optdep</option> <replaceable>option</replaceable> + <indexterm><primary><option>-optdep</option></primary></indexterm> + </term> + <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 + <option>-opta-Ewurble</option> (the dash before the E is + required).</para> + + <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> + + </sect2> + + <sect2 id="c-pre-processor"> + <title>Options affecting the C pre-processor</title> + + <indexterm><primary>pre-processing: cpp</primary></indexterm> + <indexterm><primary>C pre-processor options</primary></indexterm> + <indexterm><primary>cpp, pre-processing with</primary></indexterm> + + <variablelist> + + <varlistentry> + <term> + <option>-cpp</option> + <indexterm><primary><option>-cpp</option></primary></indexterm> + </term> + <listitem> + <para>The C pre-processor <command>cpp</command> is run + over your Haskell code only if the <option>-cpp</option> + option <indexterm><primary>-cpp + option</primary></indexterm> is given. Unless you are + building a large system with significant doses of + conditional compilation, you really shouldn't need + it.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-D</option><replaceable>symbol</replaceable><optional>=<replaceable>value</replaceable></optional> + <indexterm><primary><option>-D</option></primary></indexterm> + </term> + <listitem> + <para>Define macro <replaceable>symbol</replaceable> in the + usual way. NB: does <emphasis>not</emphasis> affect + <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> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-U</option><replaceable>symbol</replaceable> + <indexterm><primary><option>-U</option></primary></indexterm> + </term> + <listitem> + <para> Undefine macro <replaceable>symbol</replaceable> in the + usual way.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-I</option><replaceable>dir</replaceable> + <indexterm><primary><option>-I</option></primary></indexterm> + </term> + <listitem> + <para> Specify a directory in which to look for + <literal>#include</literal> files, in the usual C + way.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The GHC driver pre-defines several macros when processing + Haskell source code (<filename>.hs</filename> or + <filename>.lhs</filename> files).</para> + + <para>The symbols defined by GHC are listed below. To check which + symbols are defined by your local GHC installation, the following + trick is useful:</para> + +<screen>$ ghc -E -optP-dM -cpp foo.hs +$ cat foo.hspp</screen> + + <para>(you need a file <filename>foo.hs</filename>, but it isn't + actually used).</para> + + <variablelist> + <varlistentry> + <term> + <constant>__HASKELL98__</constant> + <indexterm><primary><literal>__HASKELL98__</literal></primary></indexterm> + </term> + <listitem> + <para>If defined, this means that GHC supports the + language defined by the Haskell 98 report.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <constant>__HASKELL__=98</constant> + <indexterm><primary><constant>__HASKELL__=98</constant></primary></indexterm> + </term> + <listitem> + <para>In GHC 4.04 and later, the + <constant>__HASKELL__</constant> + macro is defined as having the value + <constant>98</constant>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <constant>__HASKELL1__</constant> + <indexterm><primary><constant>__HASKELL1__</constant></primary></indexterm> + </term> + <listitem> + <para>If defined to <replaceable>n</replaceable>, that + means GHC supports the Haskell language defined in the + Haskell report version <emphasis>1.n</emphasis>. + Currently 5. This macro is deprecated, and will probably + disappear in future versions.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <constant>__GLASGOW_HASKELL__</constant> + <indexterm><primary><constant>__GLASGOW_HASKELL__</constant></primary></indexterm> + </term> + <listitem> + <para>For version + <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal> + of GHC, the value of + <constant>__GLASGOW_HASKELL__</constant> + is the integer <replaceable>xyy</replaceable> (if + <replaceable>y</replaceable> is a single digit, then a leading zero + is added, so for example in version 6.2 of GHC, + <literal>__GLASGOW_HASKELL__==602</literal>). More + information in <xref linkend="version-numbering"/>.</para> + + <para>With any luck, + <constant>__GLASGOW_HASKELL__</constant> + will be undefined in all other implementations that + support C-style pre-processing.</para> + + <para>(For reference: the comparable symbols for other + systems are: + <constant>__HUGS__</constant> + for Hugs, + <constant>__NHC__</constant> + for nhc98, and + <constant>__HBC__</constant> + for hbc.)</para> + + <para>NB. This macro is set when pre-processing both + Haskell source and C source, including the C source + generated from a Haskell module + (i.e. <filename>.hs</filename>, <filename>.lhs</filename>, + <filename>.c</filename> and <filename>.hc</filename> + files).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <constant>__CONCURRENT_HASKELL__</constant> + <indexterm><primary><constant>__CONCURRENT_HASKELL__</constant></primary></indexterm> + </term> + <listitem> + <para>This symbol is defined when pre-processing Haskell + (input) and pre-processing C (GHC output). Since GHC from + verion 4.00 now supports concurrent haskell by default, + this symbol is always defined.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <constant>__PARALLEL_HASKELL__</constant> + <indexterm><primary><constant>__PARALLEL_HASKELL__</constant></primary></indexterm> + </term> + <listitem> + <para>Only defined when <option>-parallel</option> is in + use! This symbol is defined when pre-processing Haskell + (input) and pre-processing C (GHC output).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <constant><replaceable>os</replaceable>_HOST_OS=1</constant> + </term> + <listitem> + <para>This define allows conditional compilation based on + the Operating System, where<replaceable>os</replaceable> is + the name of the current Operating System + (eg. <literal>linux</literal>, <literal>mingw32</literal> + for Windows, <literal>solaris</literal>, etc.).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <constant><replaceable>arch</replaceable>_HOST_ARCH=1</constant> + </term> + <listitem> + <para>This define allows conditional compilation based on + the host architecture, where<replaceable>arch</replaceable> + is the name of the current architecture + (eg. <literal>i386</literal>, <literal>x86_64</literal>, + <literal>powerpc</literal>, <literal>sparc</literal>, + etc.).</para> + </listitem> + </varlistentry> + </variablelist> + + <sect3 id="cpp-string-gaps"> + <title>CPP and string gaps</title> + + <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> + + <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> + + <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> + + <variablelist> + <varlistentry> + <term> + <option>-F</option> + <indexterm><primary><option>-F</option></primary></indexterm> + </term> + <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"> + <title>Options affecting the C compiler (if applicable)</title> + + <indexterm><primary>include-file options</primary></indexterm> + <indexterm><primary>C compiler options</primary></indexterm> + <indexterm><primary>GCC options</primary></indexterm> + + <para>If you are compiling with lots of foreign calls, you may + need to tell the C compiler about some + <literal>#include</literal> files. The Right Way to do this is to + add an <literal>INCLUDE</literal> pragma to the top of your source file + (<xref linkend="include-pragma" />):</para> + +<programlisting>{-# INCLUDE <X/Xlib.h> #-}</programlisting> + + <para>Sometimes this isn't convenient. In those cases there's an + equivalent command-line option:</para> + +<screen>% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs</screen> + + <indexterm><primary><option>-#include</option></primary> + </indexterm> + + </sect2> + + <sect2 id="options-codegen"> + <title>Options affecting code generation</title> + + <variablelist> + <varlistentry> + <term> + <option>-fasm</option> + <indexterm><primary><option>-fasm</option></primary></indexterm> + </term> + <listitem> + <para>Use GHC's native code generator rather than + compiling via C. This will compile faster (up to twice as + 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> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-fvia-C</option> + <indexterm><primary><option>-fvia-C</option></primary></indexterm> + </term> + <listitem> + <para>Compile via C instead of using the native code + generator. This is default for optimised compilations, + and on architectures for which GHC doesn't have a native + code generator.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-fno-code</option> + <indexterm><primary><option>-fno-code</option></primary></indexterm> + </term> + <listitem> + <para>Omit code generation (and all later phases) + altogether. Might be of some use if you just want to see + dumps of the intermediate compilation phases.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-fPIC</option> + <indexterm><primary><option>-fPIC</option></primary></indexterm> + </term> + <listitem> + <para>Generate position-independent code (code that can be put into + shared libraries). This currently works on Mac OS X; it works on + PowerPC Linux when using the native code generator (-fasm). + It is not quite ready to be used yet for x86 Linux. + On Windows, position-independent code is never used, + and on PowerPC64 Linux, position-independent code is always used, + so the flag is a no-op on those platforms.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-dynamic</option> + </term> + <listitem> + <para>When generating code, assume that entities imported from a + different package will reside in a different shared library or + binary. This currently works on Mac OS X; it works on PowerPC Linux when + using the native code generator. As with <option>-fPIC</option>, + x86 Linux support is not quite ready yet. Windows is not supported, + and it is a no-op on PowerPC64 Linux.</para> + <para>Note that this option also causes GHC to use shared libraries + when linking.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="options-linker"> + <title>Options affecting linking</title> + + <indexterm><primary>linker options</primary></indexterm> + <indexterm><primary>ld options</primary></indexterm> + + + <para>GHC has to link your code with various libraries, possibly + including: user-supplied, GHC-supplied, and system-supplied + (<option>-lm</option> math library, for example).</para> + + <variablelist> + + <varlistentry> + <term> + <option>-l</option><replaceable>lib</replaceable> + <indexterm><primary><option>-l</option></primary></indexterm> + </term> + <listitem> + <para>Link in the <replaceable>lib</replaceable> library. + On Unix systems, this will be in a file called + <filename>lib<replaceable>lib</replaceable>.a</filename> + or + <filename>lib<replaceable>lib</replaceable>.so</filename> + which resides somewhere on the library directories path.</para> + + <para>Because of the sad state of most UNIX linkers, the + order of such options does matter. If library + <replaceable>foo</replaceable> requires library + <replaceable>bar</replaceable>, then in general + <option>-l</option><replaceable>foo</replaceable> should + come <emphasis>before</emphasis> + <option>-l</option><replaceable>bar</replaceable> on the + command line.</para> + + <para>There's one other gotcha to bear in mind when using + external libraries: if the library contains a + <literal>main()</literal> function, then this will be + linked in preference to GHC's own + <literal>main()</literal> function + (eg. <literal>libf2c</literal> and <literal>libl</literal> + have their own <literal>main()</literal>s). This is + because GHC's <literal>main()</literal> comes from the + <literal>HSrts</literal> library, which is normally + included <emphasis>after</emphasis> all the other + libraries on the linker's command line. To force GHC's + <literal>main()</literal> to be used in preference to any + other <literal>main()</literal>s from external libraries, + just add the option <option>-lHSrts</option> before any + other libraries on the command line.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-c</option> + <indexterm><primary><option>-c</option></primary></indexterm> + </term> + <listitem> + <para>Omits the link step. This option can be used with + <option>––make</option> to avoid the automatic linking + that takes place if the program contains a <literal>Main</literal> + module.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-package</option> <replaceable>name</replaceable> + <indexterm><primary><option>-package</option></primary></indexterm> + </term> + <listitem> + <para>If you are using a Haskell “package” + (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 + <option>-package</option> option will likely result in + several pages of link errors.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-framework</option> <replaceable>name</replaceable> + <indexterm><primary><option>-framework</option></primary></indexterm> + </term> + <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> + <indexterm><primary><option>-L</option></primary></indexterm> + </term> + <listitem> + <para>Where to find user-supplied libraries… + Prepend the directory <replaceable>dir</replaceable> to + the library directories path.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-framework-path</option><replaceable>dir</replaceable> + <indexterm><primary><option>-framework-path</option></primary></indexterm> + </term> + <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> + <indexterm><primary><option>-split-objs</option></primary></indexterm> + </term> + <listitem> + <para>Tell the linker to split the single object file that + would normally be generated into multiple object files, + one per top-level Haskell function or type in the module. + We use this feature for building GHC's libraries libraries + (warning: don't use it unless you know what you're + doing!).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-static</option> + <indexterm><primary><option>-static</option></primary></indexterm> + </term> + <listitem> + <para>Tell the linker to avoid shared Haskell libraries, + if possible. This is the default.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-dynamic</option> + <indexterm><primary><option>-dynamic</option></primary></indexterm> + </term> + <listitem> + <para>Tell the linker to use shared Haskell libraries, if + available (this option is only supported on Mac OS X at the + moment, and also note that your distribution of GHC may + not have been supplied with shared libraries).</para> + <para>Note that this option also has an effect on + code generation (see above).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-main-is <replaceable>thing</replaceable></option> + <indexterm><primary><option>-main-is</option></primary></indexterm> + <indexterm><primary>specifying your own main function</primary></indexterm> + </term> + <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>. + However, if all the modules are otherwise up to date, you may need to force + recompilation both of the module where the new "main" is, and of the + module where the "main" function used to be; + <literal>ghc</literal> is not clever + enough to figure out that they both need recompiling. You can + force recompilation by removing the object file, or by using the + <option>-no-recomp</option> flag. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>-no-hs-main</option> + <indexterm><primary><option>-no-hs-main</option></primary></indexterm> + <indexterm><primary>linking Haskell libraries with foreign code</primary></indexterm> + </term> + <listitem> + <para>In the event you want to include ghc-compiled code + 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 + 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 + <command>ghc</command> to do the final link of your + `mixed-language' application. This is not a requirement + 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> + <indexterm><primary><option>-debug</option></primary></indexterm> + </term> + <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> + <indexterm><primary><option>-threaded</option></primary></indexterm> + </term> + <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> + +</sect1> + +<!-- Emacs stuff: + ;;; Local Variables: *** + ;;; mode: xml *** + ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** + ;;; End: *** + --> |