From: simonmar Date: Tue, 17 Aug 2004 16:00:59 +0000 (+0000) Subject: [project @ 2004-08-17 16:00:58 by simonmar] X-Git-Tag: Initial_conversion_from_CVS_complete~1721 X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=ca440e06a6cb5661f10ff879c676ba22a56c4ca7;ds=sidebyside [project @ 2004-08-17 16:00:58 by simonmar] - phases.xml: add documentation on _TARGET_OS and _TARGET_ARCH symbols. - some fixes for editing in emacs --- diff --git a/ghc/docs/users_guide/license.xml b/ghc/docs/users_guide/license.xml index d954d88..a381ab3 100644 --- a/ghc/docs/users_guide/license.xml +++ b/ghc/docs/users_guide/license.xml @@ -57,3 +57,10 @@ DAMAGE. + + diff --git a/ghc/docs/users_guide/phases.xml b/ghc/docs/users_guide/phases.xml index ea3730e..c214c11 100644 --- a/ghc/docs/users_guide/phases.xml +++ b/ghc/docs/users_guide/phases.xml @@ -1,787 +1,830 @@ - - Options related to a particular phase - - - 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 - might want to try a different assembler. The following options - allow you to change the external program used for a given - compilation phase: - - - - - cmd - - - - Use cmd as the literate - pre-processor. - - - - - - cmd - - - - Use cmd as the C - pre-processor (with only). - - - - - - cmd - - - - Use cmd as the C - compiler. - - - - - - cmd - - - - Use cmd as the - assembler. - - - - - - cmd - - - - Use cmd as the - linker. - - - - - - cmd - - - - Use cmd as the DLL - generator. - - - - - - cmd - - - - Use cmd as the dependency - generator. - - - - - - cmd - - - - Use cmd as the - pre-processor (with only). - - - - - - - - Forcing options to a particular phase - forcing GHC-phase options - - Options can be forced through to a particlar compilation - phase, using the following flags: - - - - - option - - - - Pass option to the - literate pre-processor - - - - - option - - - - Pass option to CPP (makes - sense only if is also on). - - - - - option - - - - Pass option to the - custom pre-processor (see ). - - - - - option - - - - Pass option to the C compiler. - - - - - option - - - - Pass option to the assembler. - - - - - option - - - - Pass option to the linker. - - - - - option - - - - Pass option to the DLL generator. - - - - - option - - - - Pass option to the - dependency generator. - - - - - So, for example, to force an - option to the assembler, you would tell the driver - (the dash before the E is - required). - - GHC is itself a Haskell program, so if you need to pass - options directly to GHC's runtime system you can enclose them in - +RTS ... -RTS (see ). - - - - - Options affecting the C pre-processor - - pre-processing: cpp - C pre-processor options - cpp, pre-processing with - - - - - - - - - - The C pre-processor cpp is run - over your Haskell code only if the - option -cpp - option is given. Unless you are - building a large system with significant doses of - conditional compilation, you really shouldn't need - it. - - - - - - symbol=value - - - - Define macro symbol in the - usual way. NB: does not affect - macros passed to the C compiler - when compiling via C! For those, use the - hack… (see ). - - - - - - symbol - - - - Undefine macro symbol in the - usual way. - - - - - - dir - - - - Specify a directory in which to look for - #include files, in the usual C - way. - - - - - The GHC driver pre-defines several macros when processing - Haskell source code (.hs or - .lhs files): - - - - - - __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__ - - - For version n of the GHC - system, this will be #defined to - 100n. For example, for version - 5.00, it is 500. - - With any luck, - __GLASGOW_HASKELL__ - will be undefined in all other implementations that - support C-style pre-processing. - - (For reference: the comparable symbols for other - systems are: - __HUGS__ - for Hugs, - __NHC__ - for nhc98, and - __HBC__ - for Chalmers.) - - 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. .hs, .lhs, - .c and .hc - files). - - - - - - __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 - use! This symbol is defined when pre-processing Haskell - (input) and pre-processing C (GHC output). - - - - - - CPP and string gaps - - A small word of warning: is not - friendly to “string gaps”.-cpp - vs string gapsstring - gaps vs -cpp. In other words, strings - such as the following: - - -strmod = "\ -\ p \ -\ " - - - don't work with ; - /usr/bin/cpp elides the backslash-newline - pairs. - - However, it appears that if you add a space at the end - of the line, then cpp (at least GNU - cpp and possibly other - cpps) leaves the backslash-space pairs - alone and the string gap works as expected. - - - - - Options affecting a Haskell pre-processor - - pre-processing: custom - Pre-processor options - - - - - - - - - A custom pre-processor is run over your Haskell - source file only if the option - -F is - given. - - Running a custom pre-processor at compile-time is in - some settings appropriate and useful. The - 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. - - 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. - - Use - - to select the program to use as the preprocessor. When - invoked, the cmd 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 - cmd should write its output - to. - - Additional arguments to the pre-processor can be - passed in using the option. These - are fed to cmd on the command - line after the three standard input and output - arguments. - - - - - - - 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. There is no real pretty - way to do this, but you can use this hack from the - command-line: + + Options related to a particular phase + + + 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 + might want to try a different assembler. The following options + allow you to change the external program used for a given + compilation phase: + + + + + cmd + + + + Use cmd as the literate + pre-processor. + + + + + + cmd + + + + Use cmd as the C + pre-processor (with only). + + + + + + cmd + + + + Use cmd as the C + compiler. + + + + + + cmd + + + + Use cmd as the + assembler. + + + + + + cmd + + + + Use cmd as the + linker. + + + + + + cmd + + + + Use cmd as the DLL + generator. + + + + + + cmd + + + + Use cmd as the dependency + generator. + + + + + + cmd + + + + Use cmd as the + pre-processor (with only). + + + + + + + + + Forcing options to a particular phase + forcing GHC-phase options + + Options can be forced through to a particlar compilation + phase, using the following flags: + + + + + option + + + + Pass option to the + literate pre-processor + + + + + option + + + + Pass option to CPP (makes + sense only if is also on). + + + + + option + + + + Pass option to the + custom pre-processor (see ). + + + + + option + + + + Pass option to the C compiler. + + + + + option + + + + Pass option to the assembler. + + + + + option + + + + Pass option to the linker. + + + + + option + + + + Pass option to the DLL generator. + + + + + option + + + + Pass option to the + dependency generator. + + + + + So, for example, to force an + option to the assembler, you would tell the driver + (the dash before the E is + required). + + GHC is itself a Haskell program, so if you need to pass + options directly to GHC's runtime system you can enclose them in + +RTS ... -RTS (see ). + + + + + Options affecting the C pre-processor + + pre-processing: cpp + C pre-processor options + cpp, pre-processing with + + + + + + + + + + The C pre-processor cpp is run + over your Haskell code only if the + option -cpp + option is given. Unless you are + building a large system with significant doses of + conditional compilation, you really shouldn't need + it. + + + + + + symbol=value + + + + Define macro symbol in the + usual way. NB: does not affect + macros passed to the C compiler + when compiling via C! For those, use the + hack… (see ). + + + + + + symbol + + + + Undefine macro symbol in the + usual way. + + + + + + dir + + + + Specify a directory in which to look for + #include files, in the usual C + way. + + + + + The GHC driver pre-defines several macros when processing + Haskell source code (.hs or + .lhs files). + + The symbols defined by GHC are listed below. To check which + symbols are defined by your local GHC installation, the following + trick is useful: -% ghc -c '-#include <X/Xlib.h>' Xstuff.lhs + $ ghc -E -optP-dM -cpp foo.hs + $ cat foo.hspp - - - - Options affecting code generation - - - - - - - - - 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 ). - - - - - - - - - - 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. - - - - - - - - - - Omit code generation (and all later phases) - altogether. Might be of some use if you just want to see - dumps of the intermediate compilation phases. - - - - - - - Options affecting linking - - linker options - ld options - - - GHC has to link your code with various libraries, possibly - including: user-supplied, GHC-supplied, and system-supplied - ( math library, for example). - - - - - - lib - - - - Link in the lib library. - On Unix systems, this will be in a file called - liblib.a - or - liblib.so - which resides somewhere on the library directories path. - - Because of the sad state of most UNIX linkers, the - order of such options does matter. If library - foo requires library - bar, then in general - foo should - come before - bar on the - command line. - - There's one other gotcha to bear in mind when using - external libraries: if the library contains a - main() function, then this will be - linked in preference to GHC's own - main() function - (eg. libf2c and libl - have their own main()s). This is - because GHC's main() comes from the - HSrts library, which is normally - included after all the other - libraries on the linker's command line. To force GHC's - main() to be used in preference to any - other main()s from external libraries, - just add the option before any - other libraries on the command line. - - - - - - - - - - Omit the link step. This flag can be useful if you - want to avoid linking in mode, - where linking is normally done automatically if the program - contains a Main module. - - - - - - name - - - - If you are using a Haskell “package” - (see ), don't forget to add the - relevant option when linking the - program too: it will cause the appropriate libraries to be - linked in with the program. Forgetting the - option will likely result in - several pages of link errors. - - - - - - name - - - - On Darwin/MacOS X only, link in the framework name. - This option corresponds to the 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 - . - - - - - - - dir - - - - Where to find user-supplied libraries… - Prepend the directory dir to - the library directories path. - - - - - - dir - - - - On Darwin/MacOS X only, prepend the directory dir to - the framework directories path. This option corresponds to the - option for Apple's Linker ( already means something else for GHC). - - - - - - - - - - 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 - (warning: don't use it unless you know what you're - doing!). - - - - - - - - - - Tell the linker to avoid shared Haskell libraries, - if possible. This is the default. - - - - - - - - - - Tell the linker to use shared Haskell libraries, if - available (this option is only supported on Windows at the - moment, and also note that your distribution of GHC may - not have been supplied with shared libraries). - - - - - - - - specifying your own main function - - - The normal rule in Haskell is that your program must supply a main - function in module Main. When testing, it is often convenient - 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. - - 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). - - - - - - - - - linking Haskell libraries with foreign code - - - 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 main() - at link-time, you will have to. To signal that to the - compiler when linking, use - . See also . - - Notice that since the command-line passed to the - linker is rather involved, you probably want to use - ghc to do the final link of your - `mixed-language' application. This is not a requirement - though, just try linking once with on - to see what options the driver passes through to the - linker. - - The flag can also be - used to persuade the compiler to do the link step in - mode when there is no Haskell - Main module present (normally the - compiler will not attempt linking when there is no - Main). - - - - - - - - - - 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 +RTS -? to see a list). - - - - - - - - - - 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). - - More details on the use of "bound threads" in the - threaded runtime can be found in the Control.Concurrent module. - - 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. - - - - - - - + (you need a file foo.hs, but it isn't + actually used). + + + + + __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__ + + + For version + x.y.z + of GHC, the value of + __GLASGOW_HASKELL__ + is the integer xyy (if + y is a single digit, then a leading zero + is added, so for example in version 6.2 of GHC, + __GLASGOW_HASKELL__==602). More + information in . + + With any luck, + __GLASGOW_HASKELL__ + will be undefined in all other implementations that + support C-style pre-processing. + + (For reference: the comparable symbols for other + systems are: + __HUGS__ + for Hugs, + __NHC__ + for nhc98, and + __HBC__ + for hbc.) + + 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. .hs, .lhs, + .c and .hc + files). + + + + + + __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 + use! This symbol is defined when pre-processing Haskell + (input) and pre-processing C (GHC output). + + + + + + os_TARGET_OS=1 + + + 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_TARGET_ARCH=1 + + + 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.). + + + + + + CPP and string gaps + + A small word of warning: is not + friendly to “string gaps”.-cpp + vs string gapsstring + gaps vs -cpp. In other words, strings + such as the following: + +rogramlisting> +rmod = "\ +p \ +" +programlisting> + + don't work with ; + /usr/bin/cpp elides the backslash-newline + pairs. + + However, it appears that if you add a space at the end + of the line, then cpp (at least GNU + cpp and possibly other + cpps) leaves the backslash-space pairs + alone and the string gap works as expected. + + + + + Options affecting a Haskell pre-processor + + pre-processing: custom + Pre-processor options + + + + + + + + + A custom pre-processor is run over your Haskell + source file only if the option + -F is + given. + + Running a custom pre-processor at compile-time is in + some settings appropriate and useful. The + 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. + + 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. + + Use + + to select the program to use as the preprocessor. When + invoked, the cmd 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 + cmd should write its output + to. + + Additional arguments to the pre-processor can be + passed in using the option. These + are fed to cmd on the command + line after the three standard input and output + arguments. + + + + + + + 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. There is no real pretty + way to do this, but you can use this hack from the + command-line: + +creen> +ghc -c '-#include <X/Xlib.h>' Xstuff.lhs +screen> + + + + + Options affecting code generation + + + + + + + + + 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 ). + + + + + + + + + + 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. + + + + + + + + + + Omit code generation (and all later phases) + altogether. Might be of some use if you just want to see + dumps of the intermediate compilation phases. + + + + + + + Options affecting linking + + linker options + ld options + + + GHC has to link your code with various libraries, possibly + including: user-supplied, GHC-supplied, and system-supplied + ( math library, for example). + + + + + + lib + + + + Link in the lib library. + On Unix systems, this will be in a file called + liblib.a + or + liblib.so + which resides somewhere on the library directories path. + + Because of the sad state of most UNIX linkers, the + order of such options does matter. If library + foo requires library + bar, then in general + foo should + come before + bar on the + command line. + + There's one other gotcha to bear in mind when using + external libraries: if the library contains a + main() function, then this will be + linked in preference to GHC's own + main() function + (eg. libf2c and libl + have their own main()s). This is + because GHC's main() comes from the + HSrts library, which is normally + included after all the other + libraries on the linker's command line. To force GHC's + main() to be used in preference to any + other main()s from external libraries, + just add the option before any + other libraries on the command line. + + + + + + + + + + Omit the link step. This flag can be useful if you + want to avoid linking in mode, + where linking is normally done automatically if the program + contains a Main module. + + + + + + name + + + + If you are using a Haskell “package” + (see ), don't forget to add the + relevant option when linking the + program too: it will cause the appropriate libraries to be + linked in with the program. Forgetting the + option will likely result in + several pages of link errors. + + + + + + name + + + + On Darwin/MacOS X only, link in the framework name. + This option corresponds to the 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 + . + + + + + + + dir + + + + Where to find user-supplied libraries… + Prepend the directory dir to + the library directories path. + + + + + + dir + + + + On Darwin/MacOS X only, prepend the directory dir to + the framework directories path. This option corresponds to the + option for Apple's Linker ( already means something else for GHC). + + + + + + + + + + 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 + (warning: don't use it unless you know what you're + doing!). + + + + + + + + + + Tell the linker to avoid shared Haskell libraries, + if possible. This is the default. + + + + + + + + + + Tell the linker to use shared Haskell libraries, if + available (this option is only supported on Windows at the + moment, and also note that your distribution of GHC may + not have been supplied with shared libraries). + + + + + + + + specifying your own main function + + + The normal rule in Haskell is that your program must supply a main + function in module Main. When testing, it is often convenient + 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. + + 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). + + + + + + + + + linking Haskell libraries with foreign code + + + 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 main() + at link-time, you will have to. To signal that to the + compiler when linking, use + . See also . + + Notice that since the command-line passed to the + linker is rather involved, you probably want to use + ghc to do the final link of your + `mixed-language' application. This is not a requirement + though, just try linking once with on + to see what options the driver passes through to the + linker. + + The flag can also be + used to persuade the compiler to do the link step in + mode when there is no Haskell + Main module present (normally the + compiler will not attempt linking when there is no + Main). + + + + + + + + + + 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 +RTS -? to see a list). + + + + + + + + + + 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). + + More details on the use of "bound threads" in the + threaded runtime can be found in the Control.Concurrent module. + + 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. + + + + + + diff --git a/ghc/docs/users_guide/ug-book.xml b/ghc/docs/users_guide/ug-book.xml index 7bebe69..5b1ccd6 100644 --- a/ghc/docs/users_guide/ug-book.xml +++ b/ghc/docs/users_guide/ug-book.xml @@ -22,3 +22,9 @@ &bugs; &faq; +