diff options
| author | simonmar <unknown> | 2004-08-17 16:00:59 +0000 |
|---|---|---|
| committer | simonmar <unknown> | 2004-08-17 16:00:59 +0000 |
| commit | ca440e06a6cb5661f10ff879c676ba22a56c4ca7 (patch) | |
| tree | 04953947aaa017de98540435d854860f86b261b6 /ghc/docs | |
| parent | 59c796f8e77325d35f29ddd3e724bfa780466d40 (diff) | |
| download | haskell-ca440e06a6cb5661f10ff879c676ba22a56c4ca7.tar.gz | |
[project @ 2004-08-17 16:00:58 by simonmar]
- phases.xml: add documentation on <os>_TARGET_OS and <arch>_TARGET_ARCH
symbols.
- some fixes for editing in emacs
Diffstat (limited to 'ghc/docs')
| -rw-r--r-- | ghc/docs/users_guide/license.xml | 7 | ||||
| -rw-r--r-- | ghc/docs/users_guide/phases.xml | 1595 | ||||
| -rw-r--r-- | ghc/docs/users_guide/ug-book.xml | 6 |
3 files changed, 832 insertions, 776 deletions
diff --git a/ghc/docs/users_guide/license.xml b/ghc/docs/users_guide/license.xml index d954d8861b..a381ab3a54 100644 --- a/ghc/docs/users_guide/license.xml +++ b/ghc/docs/users_guide/license.xml @@ -57,3 +57,10 @@ DAMAGE. </para> </preface> + +<!-- Emacs stuff: + ;;; Local Variables: *** + ;;; mode: xml *** + ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** + ;;; End: *** + --> diff --git a/ghc/docs/users_guide/phases.xml b/ghc/docs/users_guide/phases.xml index ea3730e476..c214c11430 100644 --- a/ghc/docs/users_guide/phases.xml +++ b/ghc/docs/users_guide/phases.xml @@ -1,787 +1,830 @@ <?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> - - <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 <replaceable>n</replaceable> of the GHC - system, this will be <literal>#define</literal>d to - <replaceable>100n</replaceable>. For example, for version - 5.00, it is 500.</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 Chalmers.)</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> - </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. There is no real pretty - way to do this, but you can use this hack from the - command-line:</para> +<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 -c '-#include <X/Xlib.h>' Xstuff.lhs + $ ghc -E -optP-dM -cpp foo.hs + $ cat foo.hspp </screen> - </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> - </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>-no-link</option> - <indexterm><primary><option>-no-link</option></primary></indexterm> - </term> - <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> - <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 Windows at the - moment, and also note that your distribution of GHC may - not have been supplied with shared libraries).</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>). - </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> + <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>_TARGET_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>_TARGET_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> + +rogramlisting> +rmod = "\ +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. There is no real pretty + way to do this, but you can use this hack from the + command-line:</para> + +creen> +ghc -c '-#include <X/Xlib.h>' Xstuff.lhs +screen> + + </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> + </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>-no-link</option> + <indexterm><primary><option>-no-link</option></primary></indexterm> + </term> + <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> + <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 Windows at the + moment, and also note that your distribution of GHC may + not have been supplied with shared libraries).</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>). + </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") *** + ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** ;;; End: *** --> diff --git a/ghc/docs/users_guide/ug-book.xml b/ghc/docs/users_guide/ug-book.xml index 7bebe69a1d..5b1ccd62e3 100644 --- a/ghc/docs/users_guide/ug-book.xml +++ b/ghc/docs/users_guide/ug-book.xml @@ -22,3 +22,9 @@ &bugs; &faq; +<!-- Emacs stuff: + ;;; Local Variables: *** + ;;; mode: xml *** + ;;; sgml-parent-document: ("users_guide.xml" "book") *** + ;;; End: *** + --> |