X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fphases.sgml;h=e0f92b3fd23b408d63061bdb816631ddabf936dc;hb=d28ba8c800901bea01f70c4719278c2a364cf9fc;hp=0c394254504cee62c7aa41f3043a0313d9d3bfc6;hpb=d0e3d09a41f351f95d49e7d1a39bcb29e5f2a30b;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/phases.sgml b/ghc/docs/users_guide/phases.sgml index 0c39425..e0f92b3 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 @@ -183,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. + + + + @@ -253,6 +395,17 @@ strmod = "\ 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. + + @@ -288,6 +441,35 @@ 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. + + + + + + + + + + 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. @@ -306,6 +488,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 @@ -316,6 +512,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). + + + + @@ -349,6 +555,27 @@ strmod = "\ + + + 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 @@ -357,12 +584,8 @@ strmod = "\ 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 - driver script when linking, use - . In fact, this only has an - effect when the RTS is compiled into a DLL; the - rest of the time, static linking allows the RTS's - main() to be overridden in the same - way as any other library routine. + compiler when linking, use + . See also . Notice that since the command-line passed to the linker is rather involved, you probably want to use @@ -371,6 +594,13 @@ strmod = "\ 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).