X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fphases.xml;h=863838c9772e09bf42cd8964f1dd25a991f25a05;hb=67d845652defc09807eaf134c6d30c8bd26b665a;hp=ec1436434fbcdd4f2a1a2092a320213ae7993132;hpb=269949584b7c124e95543c5c006822db4cec4d8b;p=ghc-hetmet.git diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml index ec14364..863838c 100644 --- a/docs/users_guide/phases.xml +++ b/docs/users_guide/phases.xml @@ -5,7 +5,7 @@ Replacing the program for one or more phases phases, changing - + You may specify that a different program be used for one of the phases of the compilation system, in place of whatever the ghc has wired into it. For example, you @@ -49,12 +49,23 @@ - cmd - + cmd + - Use cmd as the - mangler. + Use cmd as the LLVM + optimiser. + + + + + + cmd + + + + Use cmd as the LLVM + compiler. @@ -178,6 +189,24 @@ + option + + + + Pass option to the LLVM optimiser. + + + + + option + + + + Pass option to the LLVM compiler. + + + + option @@ -319,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__ @@ -395,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 - version 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.). - + @@ -459,7 +437,7 @@ $ cat foo.hspp strmod = "\ \ p \ \ " - + don't work with ; /usr/bin/cpp elides the backslash-newline pairs. @@ -474,7 +452,7 @@ $ cat foo.hspp Options affecting a Haskell pre-processor - + pre-processing: custom Pre-processor options @@ -543,31 +521,6 @@ $ cat foo.hspp - - 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 @@ -579,21 +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. + compiling via LLVM. + is the default. - - + + - Compile via C instead of using the native code - generator. This is the default 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. @@ -658,7 +613,7 @@ $ cat foo.hspp different package will reside in a different shared library or binary. Note that using this option when linking causes GHC to link - against shared libraries. + against shared libraries. @@ -724,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. + @@ -824,9 +779,9 @@ $ cat foo.hspp 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 + 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 @@ -846,20 +801,20 @@ $ cat foo.hspp 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. + 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 + 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. + 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. @@ -870,9 +825,9 @@ $ cat foo.hspp - This flag selects one of a number of modes for finding shared - libraries at runtime. See for - a description of each mode. + This flag selects one of a number of modes for finding shared + libraries at runtime. See for + a description of each mode. @@ -889,22 +844,22 @@ $ 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. + @@ -973,7 +928,7 @@ $ cat foo.hspp The threaded runtime system provides the following benefits: - + Parallelismparallelism on a multiprocessormultiprocessorSMP or multicoremulticore machine. See . @@ -989,6 +944,109 @@ $ cat foo.hspp + + + + + + 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 . + + + + + + + + + + + + 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 . + + + + + + + + + + + + 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.) + + + + + + @@ -996,7 +1054,7 @@ $ cat foo.hspp On Windows, GHC normally generates a manifestmanifest - file when linking a binary. The + file when linking a binary. The manifest is placed in the file prog.exe.manifest where prog.exe is the name of the @@ -1016,7 +1074,7 @@ $ cat foo.hspp 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. @@ -1028,7 +1086,7 @@ $ cat foo.hspp , see below. - + @@ -1044,15 +1102,15 @@ $ cat foo.hspp ; 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 + linkend="replacing-phases" />) and (). - + @@ -1067,13 +1125,31 @@ $ cat foo.hspp 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. + + @@ -1081,7 +1157,6 @@ $ cat foo.hspp