X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fphases.xml;h=467f6adb00fe8fddb3e8fc0a7b215d64eb9f6e18;hp=cc9fbfbf1649c72ae41911b5bf22972aa2a78cdc;hb=432b9c9322181a3644083e3c19b7e240d90659e7;hpb=bebf54b1fefef0c337955ec1e653b44f4ec63d10 diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml index cc9fbfb..467f6ad 100644 --- a/docs/users_guide/phases.xml +++ b/docs/users_guide/phases.xml @@ -49,6 +49,28 @@ + cmd + + + + Use cmd as the + mangler. + + + + + + cmd + + + + Use cmd as the + splitter. + + + + + cmd @@ -82,27 +104,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 +133,7 @@ Forcing options to a particular phase forcing 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 +178,15 @@ + option + + + + Pass option to the mangler. + + + + option @@ -182,12 +214,14 @@ - option - + option + - Pass option to the - dependency generator. + Pass option to + windres when embedding manifests on Windows. + See in . @@ -368,7 +402,7 @@ $ cat foo.hspp 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, + version 4.00 now supports concurrent haskell by default, this symbol is always defined. @@ -486,6 +520,24 @@ $ 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. @@ -529,9 +581,7 @@ $ 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 C. is the default. @@ -542,9 +592,8 @@ $ cat foo.hspp 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. + generator. This is the default on architectures for which GHC + doesn't have a native code generator. @@ -562,6 +611,32 @@ $ 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 + . + + + + + @@ -583,10 +658,7 @@ $ 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. + binary. Note that this option also causes GHC to use shared libraries when linking. @@ -753,10 +825,10 @@ $ 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 switches to shared Haskell libraries for + linking. See on how to + create them. + Note that this option also has an effect on code generation (see above). @@ -764,6 +836,36 @@ $ 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. + + + + + + specifying your own main function @@ -788,7 +890,7 @@ $ cat foo.hspp 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. + flag. @@ -861,26 +963,80 @@ $ cat foo.hspp Parallelismparallelism on a multiprocessormultiprocessorSMP or multicoremulticore - machine. See . + machine. See . The ability to make a foreign call that does not - block all other Haskell threads. - - The ability to invoke foreign exported Haskell - functions from multiple OS threads. + block all other Haskell threads, and to invoke + foreign-exported Haskell functions from multiple OS + threads. See . + + - With , 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 - forkIO). - - More details on the use of "bound threads" in the - threaded runtime can be found in the Control.Concurrent module. + + + + + + + + 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 + ().