diff options
Diffstat (limited to 'docs/users_guide/phases.xml')
| -rw-r--r-- | docs/users_guide/phases.xml | 1373 |
1 files changed, 0 insertions, 1373 deletions
diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml deleted file mode 100644 index eefef55d79..0000000000 --- a/docs/users_guide/phases.xml +++ /dev/null @@ -1,1373 +0,0 @@ -<?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>-pgmlo</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmlo</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the LLVM - optimiser.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgmlc</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmlc</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the LLVM - compiler.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgms</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgms</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the - splitter.</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>-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> - - <varlistentry> - <term> - <option>-pgmwindres</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmwindres</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the - program to use for embedding manifests on Windows. Normally this - is the program <literal>windres</literal>, which is supplied with a - GHC installation. See <option>-fno-embed-manifest</option> in <xref - linkend="options-linker" />.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-pgmlibtool</option> <replaceable>cmd</replaceable> - <indexterm><primary><option>-pgmlibtool</option></primary></indexterm> - </term> - <listitem> - <para>Use <replaceable>cmd</replaceable> as the libtool command - (when using <option>-staticlib</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 particular 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>-optlo</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optlo</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to the LLVM optimiser.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-optlc</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optlc</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to the LLVM 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>-optwindres</option> <replaceable>option</replaceable> - <indexterm><primary><option>-optwindres</option></primary></indexterm> - </term> - <listitem> - <para>Pass <replaceable>option</replaceable> to - <literal>windres</literal> when embedding manifests on Windows. - See <option>-fno-embed-manifest</option> in <xref - linkend="options-linker" />.</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>__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>__GLASGOW_HASKELL_PATCHLEVEL1__</constant> - <indexterm><primary><constant>__GLASGOW_HASKELL_PATCHLEVEL1__</constant></primary></indexterm> - </term> - <term> - <constant>__GLASGOW_HASKELL_PATCHLEVEL2__</constant> - <indexterm><primary><constant>__GLASGOW_HASKELL_PATCHLEVEL2__</constant></primary></indexterm> - </term> - <listitem> - <para>These macros are available starting with GHC 7.10.1.</para> - - <para>For three-part GHC version numbers - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal>, - the value of - <constant>__GLASGOW_HASKELL_PATCHLEVEL1__</constant> - is the integer <replaceable>z</replaceable>.</para> - - <para>For four-part GHC version numbers - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>.<replaceable>z'</replaceable></literal>, - the value of - <constant>__GLASGOW_HASKELL_PATCHLEVEL1__</constant> - is the integer <replaceable>z</replaceable> while the value of - <constant>__GLASGOW_HASKELL_PATCHLEVEL2__</constant> - is set to the integer <replaceable>z'</replaceable>.</para> - - <para>These macros are provided for allowing finer - granularity than is provided by - <literal>__GLASGOW_HASKELL__</literal>. Usually, this should - not be necessary as it's expected for most APIs to remain - stable between patchlevel releases, but occasionally - internal API changes are necessary to fix bugs. Also - conditional compilation on the patchlevel can be useful for - working around bugs in older releases.</para> - - <para>NB. These macros are 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>MIN_VERSION_GLASGOW_HASKELL(<replaceable>x</replaceable>,<replaceable>y</replaceable>,<replaceable>z</replaceable>,<replaceable>z'</replaceable>)</constant> - <indexterm><primary><constant>MIN_VERSION_GLASGOW_HASKELL</constant></primary></indexterm> - </term> - <listitem> - <para>This macro is available starting with GHC 7.10.1.</para> - - <para>This macro is provided for convenience to write CPP - conditionals testing whether the GHC version used is version - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>.<replaceable>z'</replaceable></literal> - or later.</para> - - <para>If compatibility with Haskell compilers (including GHC - prior to version 7.10.1) which do not define - <literal>MIN_VERSION_GLASGOW_HASKELL</literal> is required, - the presence of the - <literal>MIN_VERSION_GLASGOW_HASKELL</literal> macro needs - to be ensured before it is called, e.g.:</para> - -<programlisting>#ifdef MIN_VERSION_GLASGOW_HASKELL -#if MIN_VERSION_GLASGOW_HASKELL(7,10,2,0) -/* code that applies only to GHC 7.10.2 or later */ -#endif -#endif</programlisting> - - <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>__GLASGOW_HASKELL_TH__</constant> - <indexterm><primary><constant>__GLASGOW_HASKELL_TH__</constant></primary></indexterm> - </term> - <listitem> - <para> - This is set to <literal>YES</literal> when the compiler supports Template Haskell, and to - <literal>NO</literal> when not. The latter is the case for a stage-1 compiler during bootstrapping, or - on architectures where the interpreter is not available. - </para> - </listitem> - </varlistentry> - - - <varlistentry> - <term> - <constant>__GLASGOW_HASKELL_LLVM__</constant> - <indexterm><primary><constant>__GLASGOW_HASKELL_LLVM__</constant></primary></indexterm> - </term> - <listitem> - <para>Only defined when <option>-fllvm</option> is specified. When GHC - is using version - <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal> - of LLVM, the value of - <constant>__GLASGOW_HASKELL_LLVM__</constant> - is the integer <replaceable>xy</replaceable>.</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> - - <para> - An example of a pre-processor is to convert your source files to the - input encoding that GHC expects, i.e. create a script - <literal>convert.sh</literal> containing the lines: - </para> - -<screen>#!/bin/sh -( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3</screen> - - <para>and pass <literal>-F -pgmF convert.sh</literal> to GHC. - The <literal>-f l1</literal> option tells iconv to convert your - Latin-1 file, supplied in argument <literal>$2</literal>, while - the "-t utf-8" options tell iconv to return a UTF-8 encoded file. - The result is redirected into argument <literal>$3</literal>. - The <literal>echo "{-# LINE 1 \"$2\" #-}"</literal> - just makes sure that your error positions are reported as - in the original source file.</para> - </listitem> - </varlistentry> - </variablelist> - </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 <link linkend="native-code-gen">native code generator - </link>rather than compiling via LLVM. - <option>-fasm</option> is the default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fllvm</option> - <indexterm><primary><option>-fllvm</option></primary></indexterm> - </term> - <listitem> - <para>Compile via <link linkend="llvm-code-gen">LLVM</link>instead - of using the native code generator. This will generally take slightly - longer than the native code generator to compile. Produced code is - generally the same speed or faster than the other two code - generators. Compiling via LLVM requires LLVM to be on the - path.</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. This is useful if you're only interested in - type checking code.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fwrite-interface</option> - <indexterm><primary><option>-fwrite-interface</option></primary></indexterm> - </term> - <listitem> - <para>Always write interface files. GHC will normally write - interface files automatically, but this flag is useful with - <option>-fno-code</option>, which normally suppresses generation - of interface files. This is useful if you want to type check - over multiple runs of GHC without compiling dependencies.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fobject-code</option> - <indexterm><primary><option>-fobject-code</option></primary></indexterm> - </term> - <listitem> - <para>Generate object code. This is the default outside of - GHCi, and can be used with GHCi to cause object code to be - generated in preference to bytecode.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fbyte-code</option> - <indexterm><primary><option>-fbyte-code</option></primary></indexterm> - </term> - <listitem> - <para>Generate byte-code instead of object-code. This is - the default in GHCi. Byte-code can currently only be used - in the interactive interpreter, not saved to disk. This - option is only useful for reversing the effect of - <option>-fobject-code</option>.</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 Linux x86 and x86-64. On - Windows, position-independent code is never used so the flag is a - no-op on that platform.</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.</para> - <para>Note that using this option when linking causes GHC to link - against shared libraries.</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/OS X/iOS 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>-staticlib</option> - <indexterm><primary><option>-staticlib</option></primary></indexterm> - </term> - <listitem> - <para>On Darwin/OS X/iOS only, link all passed files into a static library suitable - for linking into an iOS (when using a cross-compiler) or Mac Xcode project. To control - the name, use the <option>-o</option> <replaceable>name</replaceable> option as usual. - The default name is <literal>liba.a</literal>. - This should nearly always be passed when compiling for iOS with a cross-compiler. - </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/OS X/iOS 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. - This only makes sense for libraries, where it means that - executables linked against the library are smaller as they only - link against the object files that they need. However, assembling - all the sections separately is expensive, so this is slower than - compiling normally. Additionally, the size of the library itself - (the <literal>.a</literal> file) can be a factor of 2 to 2.5 - larger. - We use this feature for building GHC's libraries.</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>This flag tells GHC to link against shared Haskell libraries. - This flag only affects the selection of dependent libraries, not - the form of the current target (see -shared). - See <xref linkend="using-shared-libs" /> on how to - create them.</para> - - <para>Note that this option also has an effect on - code generation (see above).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-shared</option> - <indexterm><primary><option>-shared</option></primary></indexterm> - </term> - <listitem> - <para>Instead of creating an executable, GHC produces a - shared object with this linker flag. Depending on the - operating system target, this might be an ELF DSO, a Windows - DLL, or a Mac OS dylib. GHC hides the operating system - details beneath this uniform flag.</para> - - <para>The flags <option>-dynamic</option>/<option>-static</option> control whether the - resulting shared object links statically or dynamically to - Haskell package libraries given as <option>-package</option> option. Non-Haskell - libraries are linked as gcc would regularly link it on your - system, e.g. on most ELF system the linker uses the dynamic - libraries when found.</para> - - <para>Object files linked into shared objects must be - compiled with <option>-fPIC</option>, see <xref linkend="options-codegen" /></para> - - <para>When creating shared objects for Haskell packages, the - shared object must be named properly, so that GHC recognizes - the shared object when linked against this package. See - shared object name mangling.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dynload</option> - <indexterm><primary><option>-dynload</option></primary></indexterm> - </term> - <listitem> - <para> - This flag selects one of a number of modes for finding shared - libraries at runtime. See <xref linkend="finding-shared-libs"/> for - a description of each mode. - </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>A module name <literal>A</literal>. GHC assumes that the main function is <literal>A.main</literal>.</para></listitem> - <listitem><para>A 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>-fforce-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> - - <para>The flags <option>-rtsopts</option> - and <option>-with-rtsopts</option> have no effect when - used with <option>-no-hs-main</option>, because they are - implemented by changing the definition - of <literal>main</literal> that GHC generates. See - <xref linkend="using-own-main" /> for how to get the - effect of <option>-rtsopts</option> - and <option>-with-rtsopts</option> when using your - own <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" version of the - runtime system. The threaded runtime system is so-called - because it manages multiple OS threads, as opposed to the - default runtime system which is purely - single-threaded.</para> - - <para>Note that you do <emphasis>not</emphasis> need - <option>-threaded</option> in order to use concurrency; the - single-threaded runtime supports concurrency between Haskell - threads just fine.</para> - - <para>The threaded runtime system provides the following - benefits:</para> - - <itemizedlist> - <listitem> - <para>It enables the <option>-N</option><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm> RTS option to be - used, which allows threads to run in - parallel<indexterm><primary>parallelism</primary></indexterm> - on a - multiprocessor<indexterm><primary>multiprocessor</primary></indexterm><indexterm><primary>SMP</primary></indexterm> - or - multicore<indexterm><primary>multicore</primary></indexterm> - machine. See <xref linkend="using-smp" />.</para> - </listitem> - <listitem> - <para>If a thread makes a foreign call (and the call is - not marked <literal>unsafe</literal>), then other - Haskell threads in the program will continue to run - while the foreign call is in progress. - Additionally, <literal>foreign export</literal>ed - Haskell functions may be called from multiple OS - threads simultaneously. See - <xref linkend="ffi-threads" />.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-eventlog</option> - <indexterm><primary><option>-eventlog</option></primary></indexterm> - </term> - <listitem> - <para> - Link the program with the "eventlog" version of the - runtime system. A program linked in this way can generate - a runtime trace of events (such as thread start/stop) to a - binary file - <literal><replaceable>program</replaceable>.eventlog</literal>, - which can then be interpreted later by various tools. See - <xref linkend="rts-eventlog" /> for more information. - </para> - <para> - <option>-eventlog</option> can be used - with <option>-threaded</option>. It is implied - by <option>-debug</option>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-rtsopts</option> - <indexterm><primary><option>-rtsopts</option></primary></indexterm> - </term> - <listitem> - <para> - This option affects the processing of RTS control options given either - on the command line or via the <envar>GHCRTS</envar> environment variable. - There are three possibilities: - </para> - <variablelist> - <varlistentry> - <term><option>-rtsopts=none</option></term> - <listitem> - <para> - Disable all processing of RTS options. - If <option>+RTS</option> appears anywhere on the command - line, then the program will abort with an error message. - If the <envar>GHCRTS</envar> environment variable is - set, then the program will emit a warning message, - <envar>GHCRTS</envar> will be ignored, and the program - will run as normal. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-rtsopts=some</option></term> - <listitem> - <para>[this is the default setting] Enable - only the "safe" RTS options: (Currently - only <option>-?</option> - and <option>--info</option>.) Any other RTS options - on the command line or in the <envar>GHCRTS</envar> - environment variable causes the program with to abort - with an error message. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-rtsopts=all</option>, or - just <option>-rtsopts</option></term> - <listitem> - <para> - Enable <emphasis>all</emphasis> RTS option - processing, both on the command line and through - the <envar>GHCRTS</envar> environment variable. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - In GHC 6.12.3 and earlier, the default was to process all - RTS options. However, since RTS options can be used to - write logging data to arbitrary files under the security - context of the running program, there is a potential - security problem. For this reason, GHC 7.0.1 and later - default to <option>-rtsops=some</option>. - </para> - - <para> - Note that <option>-rtsopts</option> has no effect when - used with <option>-no-hs-main</option>; see - <xref linkend="using-own-main" /> for details. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-with-rtsopts</option> - <indexterm><primary><option>-with-rtsopts</option></primary></indexterm> - </term> - <listitem> - <para> - This option allows you to set the default RTS options at link-time. For example, - <option>-with-rtsopts="-H128m"</option> sets the default heap size to 128MB. - This will always be the default heap size for this program, unless the user overrides it. - (Depending on the setting of the <option>-rtsopts</option> option, the user might - not have the ability to change RTS options at run-time, in which case - <option>-with-rtsopts</option> would be the <emphasis>only</emphasis> way to set - them.) - </para> - - <para> - Note that <option>-with-rtsopts</option> has no effect when - used with <option>-no-hs-main</option>; see - <xref linkend="using-own-main" /> for details. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-no-rtsopts-suggestions</option> - <indexterm><primary><option>-no-rtsopts-suggestions</option></primary></indexterm> - </term> - <listitem> - <para> - This option disables RTS suggestions about linking with <option>-rtsopts</option> - when they are not available. - - These suggestions would be unhelpful if the users have installed Haskell programs - through their package managers. - With this option enabled, these suggestions will not appear. - - It is recommended for people distributing binaries - to build with either <option>-rtsopts</option> or - <option>-no-rtsopts-suggestions</option>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-gen-manifest</option> - <indexterm><primary><option>-fno-gen-manifest</option></primary> - </indexterm> - </term> - <listitem> - <para>On Windows, GHC normally generates a - <firstterm>manifest</firstterm><indexterm><primary>manifest</primary> - </indexterm> file when linking a binary. The - manifest is placed in the file - <literal><replaceable>prog</replaceable>.exe.manifest</literal> - where <replaceable>prog.exe</replaceable> is the name of the - executable. The manifest file currently serves just one purpose: - it disables the "installer detection"<indexterm><primary>installer detection</primary> - </indexterm>in Windows Vista that - attempts to elevate privileges for executables with certain names - (e.g. names containing "install", "setup" or "patch"). Without the - manifest file to turn off installer detection, attempting to run an - executable that Windows deems to be an installer will return a - permission error code to the invoker. Depending on the invoker, - the result might be a dialog box asking the user for elevated - permissions, or it might simply be a permission denied - error.</para> - - <para>Installer detection can be also turned off globally for the - system using the security control panel, but GHC by default - generates binaries that don't depend on the user having disabled - installer detection.</para> - - <para>The <option>-fno-gen-manifest</option> disables generation of - the manifest file. One reason to do this would be if you had - a manifest file of your own, for example.</para> - - <para>In the future, GHC might use the manifest file for more things, - such as supplying the location of dependent DLLs.</para> - - <para><option>-fno-gen-manifest</option> also implies - <option>-fno-embed-manifest</option>, see below.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-embed-manifest</option> - <indexterm><primary><option>-fno-embed-manifest</option></primary> - </indexterm> - </term> - <listitem> - <para>The manifest file that GHC generates when linking a binary on - Windows is also embedded in the executable itself, by default. - This means that the binary can be distributed without having to - supply the manifest file too. The embedding is done by running - <literal>windres</literal><indexterm><primary><literal>windres</literal></primary> - </indexterm>; to see exactly what GHC does to embed the manifest, - use the <option>-v</option> flag. A GHC installation comes with - its own copy of <literal>windres</literal> for this reason.</para> - - <para>See also <option>-pgmwindres</option> (<xref - linkend="replacing-phases" />) and - <option>-optwindres</option> (<xref - linkend="forcing-options-through" - />).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-fno-shared-implib</option> - <indexterm><primary><option>-fno-shared-implib</option></primary> - </indexterm> - </term> - <listitem> - <para>DLLs on Windows are typically linked to by linking to a corresponding - <literal>.lib</literal> or <literal>.dll.a</literal> - the so-called import library. - GHC will typically generate such a file for every DLL you create by compiling in - <literal>-shared</literal> mode. However, sometimes you don't want to pay the - disk-space cost of creating this import library, which can be substantial - it - might require as much space as the code itself, as Haskell DLLs tend to export - lots of symbols.</para> - - <para>As long as you are happy to only be able to link to the DLL using - <literal>GetProcAddress</literal> and friends, you can supply the - <option>-fno-shared-implib</option> flag to disable the creation of the import - library entirely.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-dylib-install-name <replaceable>path</replaceable></option> - <indexterm><primary><option>-dylib-install-name</option></primary> - </indexterm> - </term> - <listitem> - <para>On Darwin/OS X, dynamic libraries are stamped at build time with an - "install name", which is the ultimate install path of the library file. - Any libraries or executables that subsequently link against it will pick - up that path as their runtime search location for it. By default, ghc sets - the install name to the location where the library is built. This option - allows you to override it with the specified file path. (It passes - <literal>-install_name</literal> to Apple's linker.) Ignored on other - platforms.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>-rdynamic</option> - <indexterm><primary><option>-rdynamic</option></primary> - </indexterm> - </term> - <listitem> - <para> - This instructs the linker to add all symbols, not only used ones, to the - dynamic symbol table. Currently Linux and Windows/MinGW32 only. - This is equivalent to using <literal>-optl -rdynamic</literal> on Linux, - and <literal>-optl -export-all-symbols</literal> on Windows.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - -</sect1> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") *** - ;;; ispell-local-dictionary: "british" *** - ;;; End: *** - --> |