<varlistentry>
<term>
+ <option>-pgmm</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgmm</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Use <replaceable>cmd</replaceable> as the
+ mangler.</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>
<varlistentry>
<term>
- <option>-pgmdep</option> <replaceable>cmd</replaceable>
- <indexterm><primary><option>-pgmdep</option></primary></indexterm>
+ <option>-pgmF</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgmF</option></primary></indexterm>
</term>
<listitem>
- <para>Use <replaceable>cmd</replaceable> as the dependency
- generator.</para>
+ <para>Use <replaceable>cmd</replaceable> as the
+ pre-processor (with <option>-F</option> only).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <option>-pgmF</option> <replaceable>cmd</replaceable>
- <indexterm><primary><option>-pgmF</option></primary></indexterm>
+ <option>-pgmwindres</option> <replaceable>cmd</replaceable>
+ <indexterm><primary><option>-pgmwindres</option></primary></indexterm>
</term>
<listitem>
<para>Use <replaceable>cmd</replaceable> as the
- pre-processor (with <option>-F</option> only).</para>
+ 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>
-
-
</variablelist>
</sect2>
</varlistentry>
<varlistentry>
<term>
+ <option>-optm</option> <replaceable>option</replaceable>
+ <indexterm><primary><option>-optm</option></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Pass <replaceable>option</replaceable> to the mangler.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
<option>-opta</option> <replaceable>option</replaceable>
<indexterm><primary><option>-opta</option></primary></indexterm>
</term>
dependency 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>
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>
<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>
+ compiling via C. <option>-fasm</option> is the default.</para>
</listitem>
</varlistentry>
</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>
+ generator. This is the default on architectures for which GHC
+ doesn't have a native code generator.</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>When generating code, assume that entities imported from a
different package will reside in a different shared library or
- binary. This currently works on Mac OS X; it works on PowerPC Linux when
- using the native code generator. As with <option>-fPIC</option>,
- x86 Linux support is not quite ready yet. Windows is not supported,
- and it is a no-op on PowerPC64 Linux.</para>
+ binary.</para>
<para>Note that this option also causes GHC to use shared libraries
when linking.</para>
</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
+ 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.
+ We use this feature for building GHC's libraries
(warning: don't use it unless you know what you're
doing!).</para>
</listitem>
<indexterm><primary><option>-dynamic</option></primary></indexterm>
</term>
<listitem>
- <para>Tell the linker to use shared Haskell libraries, if
- available (this option is only supported on Mac OS X at the
- moment, and also note that your distribution of GHC may
- not have been supplied with shared libraries).</para>
+ <para>This flag switches to shared Haskell libraries for
+ linking. See <xref linkend="building-packages" /> on how to
+ create them.</para>
+
<para>Note that this option also has an effect on
code generation (see above).</para>
</listitem>
<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>-main-is <replaceable>thing</replaceable></option>
<indexterm><primary><option>-main-is</option></primary></indexterm>
<indexterm><primary>specifying your own main function</primary></indexterm>
<literal>ghc</literal> is not clever
enough to figure out that they both need recompiling. You can
force recompilation by removing the object file, or by using the
- <option>-no-recomp</option> flag.
+ <option>-fforce-recomp</option> flag.
</para>
</listitem>
</varlistentry>
<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
+ <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>Parallelism<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>
+
+ <para>The ability to make a foreign call that does not
+ block all other Haskell threads.</para>
+
+ <para>The ability to invoke foreign exported Haskell
+ functions from multiple OS threads.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>With <option>-threaded</option>, calls to foreign
+ functions are made using the same OS thread that created the
+ Haskell thread (if it was created by a call to a foreign
+ exported Haskell function), 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>
+ </listitem>
+ </varlistentry>
- <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>
+ <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>
</variablelist>