X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fphases.sgml;h=81f529731b561c197043dd3bf662e152d0f59f3f;hb=6e5df3a4551b8d8b83e936b3f7b52edfc778ca8a;hp=a0e1994b132d3fa5e16caedd52fac9db4beb1ec6;hpb=7d67a216958e8986cf067f96f9e9c7a4101fd29b;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/phases.sgml b/ghc/docs/users_guide/phases.sgml index a0e1994..81f5297 100644 --- a/ghc/docs/users_guide/phases.sgml +++ b/ghc/docs/users_guide/phases.sgml @@ -2,7 +2,7 @@ Options related to a particular phase - Replacing the program for one or more phases. + Replacing the program for one or more phases phases, changing You may specify that a different program be used for one @@ -10,12 +10,94 @@ 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 phases: + 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 options to a particular phase forcing GHC-phase options Options can be forced through to a particlar compilation @@ -41,15 +123,23 @@ 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. - + + + + 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 @@ -138,7 +228,9 @@ (For reference: the comparable symbols for other systems are: __HUGS__ - for Hugs and + for Hugs, + __NHC__ + for nhc98, and __HBC__ for Chalmers.) @@ -173,27 +265,87 @@ - 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: + + 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. + + - don't work with ; - /usr/bin/cpp elides the backslash-newline - pairs. + + Options affecting a Haskell pre-processor + + pre-processing: custom + Pre-processor options - 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. + + + + + + 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. + + + + + cmd + cmd + + Use cmd as the Haskell + pre-processor. 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 + cmd 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. + + + + @@ -203,28 +355,6 @@ strmod = "\ C compiler options GCC options - - - - - Flag - Description - Static/Dynamic - Reverse - - - - - file - Include file when - compiling the .hc file - dynamic - - - - - - - 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 @@ -237,6 +367,48 @@ strmod = "\ + + 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 @@ -269,6 +441,22 @@ strmod = "\ 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. @@ -287,6 +475,20 @@ strmod = "\ + 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 @@ -297,6 +499,16 @@ strmod = "\ + 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). + + + +