X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fphases.xml;h=dfa10a5b11fe4dc86e8047ac0fc442a7917f6dd6;hb=6cec61d14a324285dbb8ce73d4c7215f1f8d6766;hp=fd034a305afc5dbdf30734b9b8a2775df0de8ea6;hpb=0065d5ab628975892cea1ec7303f968c3338cbe1;p=ghc-hetmet.git
diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml
index fd034a3..dfa10a5 100644
--- a/docs/users_guide/phases.xml
+++ b/docs/users_guide/phases.xml
@@ -49,6 +49,39 @@
+ cmd
+
+
+
+ Use cmd as the LLVM
+ optimiser.
+
+
+
+
+
+ cmd
+
+
+
+ Use cmd as the LLVM
+ compiler.
+
+
+
+
+
+ cmd
+
+
+
+ Use cmd as the
+ splitter.
+
+
+
+
+ cmd
@@ -82,27 +115,28 @@
- cmd
-
+ cmd
+
- Use cmd as the dependency
- generator.
+ Use cmd as the
+ pre-processor (with only).
- cmd
-
+ cmd
+ Use cmd as the
- pre-processor (with only).
+ program to use for embedding manifests on Windows. Normally this
+ is the program windres, which is supplied with a
+ GHC installation. See in .
-
-
@@ -110,7 +144,7 @@
Forcing options to a particular phaseforcing GHC-phase options
- Options can be forced through to a particlar compilation
+ Options can be forced through to a particular compilation
phase, using the following flags:
@@ -155,6 +189,33 @@
+ option
+
+
+
+ Pass option to the LLVM optimiser.
+
+
+
+
+ option
+
+
+
+ Pass option to the LLVM compiler.
+
+
+
+
+ option
+
+
+
+ Pass option to the mangler.
+
+
+
+ option
@@ -182,12 +243,14 @@
- option
-
+ option
+
- Pass option to the
- dependency generator.
+ Pass option to
+ windres when embedding manifests on Windows.
+ See in .
@@ -285,44 +348,6 @@ $ cat foo.hspp
- __HASKELL98__
- __HASKELL98__
-
-
- If defined, this means that GHC supports the
- language defined by the Haskell 98 report.
-
-
-
-
-
- __HASKELL__=98
- __HASKELL__=98
-
-
- In GHC 4.04 and later, the
- __HASKELL__
- macro is defined as having the value
- 98.
-
-
-
-
-
- __HASKELL1__
- __HASKELL1__
-
-
- If defined to n, that
- means GHC supports the Haskell language defined in the
- Haskell report version 1.n.
- Currently 5. This macro is deprecated, and will probably
- disappear in future versions.
-
-
-
-
- __GLASGOW_HASKELL____GLASGOW_HASKELL__
@@ -361,55 +386,42 @@ $ cat foo.hspp
-
- __CONCURRENT_HASKELL__
- __CONCURRENT_HASKELL__
-
-
- 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.
-
-
-
-
-
+ __PARALLEL_HASKELL____PARALLEL_HASKELL__
-
- Only defined when is in
+
+ Only defined when is in
use! This symbol is defined when pre-processing Haskell
(input) and pre-processing C (GHC output).
-
+
-
+ os_HOST_OS=1
-
- This define allows conditional compilation based on
+
+ This define allows conditional compilation based on
the Operating System, whereos is
the name of the current Operating System
(eg. linux, mingw32
for Windows, solaris, etc.).
-
+
-
+
-
+ arch_HOST_ARCH=1
-
- This define allows conditional compilation based on
+
+ This define allows conditional compilation based on
the host architecture, wherearch
is the name of the current architecture
(eg. i386, x86_64,
powerpc, sparc,
etc.).
-
+
@@ -486,36 +498,29 @@ $ cat foo.hspp
are fed to cmd on the command
line after the three standard input and output
arguments.
+
+
+ An example of a pre-processor is to convert your source files to the
+ input encoding that GHC expects, i.e. create a script
+ convert.sh containing the lines:
+
+
+#!/bin/sh
+( echo "{-# LINE 1 \"$2\" #-}" ; iconv -f l1 -t utf-8 $2 ) > $3
+
+ and pass -F -pgmF convert.sh to GHC.
+ The -f l1 option tells iconv to convert your
+ Latin-1 file, supplied in argument $2, while
+ the "-t utf-8" options tell iconv to return a UTF-8 encoded file.
+ The result is redirected into argument $3.
+ The echo "{-# LINE 1 \"$2\" #-}"
+ just makes sure that your error positions are reported as
+ in the original source file.
-
- Options affecting the C compiler (if applicable)
-
- include-file options
- C compiler options
- GCC options
-
- If you are compiling with lots of foreign calls, you may
- need to tell the C compiler about some
- #include files. The Right Way to do this is to
- add an INCLUDE pragma to the top of your source file
- ():
-
-{-# INCLUDE <X/Xlib.h> #-}
-
- Sometimes this isn't convenient. In those cases there's an
- equivalent command-line option:
-
-% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs
-
-
-
-
-
-
Options affecting code generation
@@ -527,24 +532,23 @@ $ cat foo.hspp
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. is the default
- when optimisation is off (see ).
+ compiling via LLVM.
+ is the default.
-
-
+
+
- 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.
+ Compile via LLVM 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 version 2.7 or later to be on the path.
@@ -562,17 +566,41 @@ $ cat foo.hspp
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+ 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
+ .
+
+
+
+
+ Generate position-independent code (code that can be put into
- shared libraries). This currently works on Mac OS X; it works on
- PowerPC Linux when using the native code generator (-fasm).
- It is not quite ready to be used yet for x86 Linux.
- On Windows, position-independent code is never used,
- and on PowerPC64 Linux, position-independent code is always used,
- so the flag is a no-op on those platforms.
+ shared libraries). This currently works on Linux x86 and x86-64 when
+ using the native code generator (-fasm).
+ On Windows, position-independent code is never used
+ so the flag is a no-op on that platform.
@@ -583,12 +611,9 @@ $ cat foo.hspp
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 ,
- x86 Linux support is not quite ready yet. Windows is not supported,
- and it is a no-op on PowerPC64 Linux.
- Note that this option also causes GHC to use shared libraries
- when linking.
+ binary.
+ Note that using this option when linking causes GHC to link
+ against shared libraries.
@@ -654,10 +679,10 @@ $ cat foo.hspp
Omits the link step. This option can be used with
- to avoid the automatic linking
- that takes place if the program contains a Main
- module.
-
+ to avoid the automatic linking
+ that takes place if the program contains a Main
+ module.
+
@@ -725,7 +750,12 @@ $ cat foo.hspp
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!).
@@ -748,10 +778,12 @@ $ cat foo.hspp
- 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).
+ 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 on how to
+ create them.
+
Note that this option also has an effect on
code generation (see above).
@@ -759,6 +791,49 @@ $ cat foo.hspp
+
+
+
+
+ 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.
+
+ The flags / control whether the
+ resulting shared object links statically or dynamically to
+ Haskell package libraries given as 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.
+
+ Object files linked into shared objects must be
+ compiled with , see
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+ This flag selects one of a number of modes for finding shared
+ libraries at runtime. See for
+ a description of each mode.
+
+
+
+
+
+ specifying your own main function
@@ -769,21 +844,21 @@ $ cat foo.hspp
to change which function is the "main" one, and the flag
allows you to do so. The thing can be one of:
- A lower-case identifier foo. GHC assumes that the main function is Main.foo.
- An module name A. GHC assumes that the main function is A.main.
- An qualified name A.foo. GHC assumes that the main function is A.foo.
-
+ A lower-case identifier foo. GHC assumes that the main function is Main.foo.
+ An module name A. GHC assumes that the main function is A.main.
+ An qualified name A.foo. GHC assumes that the main function is A.foo.
+
Strictly speaking, 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 A
in the latter two items above). It has no effect for other modules,
and hence can safely be given to ghc --make.
- 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;
- ghc 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
- flag.
+ 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;
+ ghc 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
+ flag.
@@ -839,26 +914,240 @@ $ cat foo.hspp
- 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
- forkIO).
+ 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.
+
+ Note that you do not need
+ in order to use concurrency; the
+ single-threaded runtime supports concurrency between Haskell
+ threads just fine.
+
+ The threaded runtime system provides the following
+ benefits:
+
+
+
+ Parallelismparallelism on a multiprocessormultiprocessorSMP or multicoremulticore
+ machine. See .
+
+ The ability to make a foreign call that does not
+ block all other Haskell threads, and to invoke
+ foreign-exported Haskell functions from multiple OS
+ threads. See .
+
+
+
+
+
+
+
+
+
+
+
+
+ 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
+ program.eventlog,
+ which can then be interpreted later by various tools. See
+ for more information.
+
+
+ can be used
+ with . It is implied
+ by .
+
+
+
- More details on the use of "bound threads" in the
- threaded runtime can be found in the Control.Concurrent module.
+
+
+
+
+
+
+
+ This option affects the processing of RTS control options given either
+ on the command line or via the GHCRTS environment variable.
+ There are three possibilities:
+
+
+
+
+
+
+ Disable all processing of RTS options.
+ If appears anywhere on the command
+ line, then the program will abort with an error message.
+ If the GHCRTS environment variable is
+ set, then the program will emit a warning message,
+ GHCRTS will be ignored, and the program
+ will run as normal.
+
+
+
+
+
+
+ [this is the default setting] Enable
+ only the "safe" RTS options: (Currently
+ only
+ and .) Any other RTS options
+ on the command line or in the GHCRTS
+ environment variable causes the program with to abort
+ with an error message.
+
+
+
+
+ , or
+ just
+
+
+ Enable all RTS option
+ processing, both on the command line and through
+ the GHCRTS environment variable.
+
+
+
+
+
+ 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 .
+
+
+
- The threaded RTS does not
- 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 it can be used safely in
- a multi-threaded environment.
+
+
+
+
+
+
+
+ This option allows you to set the default RTS options at link-time. For example,
+ 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, the user might
+ not have the ability to change RTS options at run-time, in which case
+ would be the only way to set
+ them.)
+
+
+
+
+
+
+
+
+
+
+
+ On Windows, GHC normally generates a
+ manifestmanifest
+ file when linking a binary. The
+ manifest is placed in the file
+ prog.exe.manifest
+ where prog.exe is the name of the
+ executable. The manifest file currently serves just one purpose:
+ it disables the "installer detection"installer detection
+ 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.
+
+ 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.
+
+ The disables generation of
+ the manifest file. One reason to do this would be if you had
+ a manifest file of your own, for example.
+
+ In the future, GHC might use the manifest file for more things,
+ such as supplying the location of dependent DLLs.
+
+ also implies
+ , see below.
+
+
+
+
+
+
+
+
+
+
+ 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
+ windreswindres
+ ; to see exactly what GHC does to embed the manifest,
+ use the flag. A GHC installation comes with
+ its own copy of windres for this reason.
+
+ See also () and
+ ().
+
+
+
+
+
+
+
+
+
+
+ DLLs on Windows are typically linked to by linking to a corresponding
+ .lib or .dll.a - the so-called import library.
+ GHC will typically generate such a file for every DLL you create by compiling in
+ -shared 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.
+
+ As long as you are happy to only be able to link to the DLL using
+ GetProcAddress and friends, you can supply the
+ flag to disable the creation of the import
+ library entirely.
+
+
+
+
+
+
+
+
+
+
+ On Darwin/MacOS 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
+ -install_name to Apple's linker.) Ignored on other
+ platforms.
@@ -868,7 +1157,6 @@ $ cat foo.hspp