X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fusing.sgml;h=0abae40ba1d51b632774ada27f9950c2fad0c691;hb=0dfa678a3be85a7b8353b510a026ae684b1ee7cc;hp=cf0b95ab944ad73eb451f662b347fd70aa0bb9f2;hpb=05a9c035960327b23bad8d8dc501141b183f33b5;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index cf0b95a..0abae40 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -4,63 +4,6 @@ GHC, using using GHC - GHC can work in one of three “modes”: - - - - ghc - ––interactive - - interactive mode - - ghci - - - Interactive mode, which is also available as - ghci. Interactive mode is described in - more detail in . - - - - - ghc - ––make - - make mode - - - - - In this mode, GHC will build a multi-module Haskell - program automatically, figuring out dependencies for itself. - If you have a straightforward Haskell program, this is likely - to be much easier, and faster, than using - make. - - - - - - ghc - - -E - -C - -S - -c - - - - - - - - This is the traditional batch-compiler mode, in which - GHC can compile source files one at a time, or link objects - together into an executable. - - - - Options overview @@ -162,14 +105,9 @@ module X where pragma in a source file or set from the GHCi command-line with :set. - As a rule of thumb, all the language options are dynamic, as - are the warning options and the debugging options. The rest are - static, with the notable exceptions of , - , , - , and . - - The flag reference tables () lists - the status of each flag. + As a rule of thumb, options which relate to filenames are + static, and the rest are dynamic. The flag reference tables () lists the status of each flag. @@ -244,6 +182,332 @@ module X where + + Modes of operation + + GHC's behaviour is firstly controlled by a mode flag. Only + one of these flags may be given, but it does not necessarily need + to be the first option on the command-line. The available modes + are: + + + + ghc + ––interactive + + interactive mode + + ghci + + + Interactive mode, which is also available as + ghci. Interactive mode is described in + more detail in . + + + + + ghc + ––make + + make mode + + + + + In this mode, GHC will build a multi-module Haskell + program automatically, figuring out dependencies for itself. + If you have a straightforward Haskell program, this is + likely to be much easier, and faster, than using + make. Make mode is described in . + + + + + ghc + –e expr + + eval mode + + + Expression-evaluation mode. This is very similar to + interactive mode, except that there is a single expression + to evaluate (expr) which is given + on the command line. See for + more details. + + + + + + ghc + + -E + -C + -S + -c + + + + + + + + This is the traditional batch-compiler mode, in which + GHC can compile source files one at a time, or link objects + together into an executable. This mode also applies if + there is no other mode flag specified on the command line, + in which case it means that the specified files should be + compiled and then linked to form a program. See . + + + + + ghc + –M + dependency-generation mode + + + Dependency-generation mode. In this mode, GHC can be + used to generate dependency information suitable for use in + a Makefile. See . + + + + + ghc + ––mk-dll + dependency-generation mode + + + DLL-creation mode (Windows only). See . + + + + + + Using <command>ghc</command> <option>––make</option> + + + + separate compilation + + + When given the option, + GHC will build a multi-module Haskell program by following + dependencies from a single root module (usually + Main). For example, if your + Main module is in a file called + Main.hs, you could compile and link the + program like this: + + +ghc ––make Main.hs + + + The command line may contain any number of source file + names or module names; GHC will figure out all the modules in + the program by following the imports from these initial modules. + It will then attempt to compile each module which is out of + date, and finally if there is a Main module, + the program will also be linked into an executable. + + The main advantages to using ghc + ––make over traditional + Makefiles are: + + + + GHC doesn't have to be restarted for each compilation, + which means it can cache information between compilations. + Compiling a muli-module program with ghc + ––make can be up to twice as fast as + running ghc individually on each source + file. + + + You don't have to write a + Makefile. + + Makefilesavoiding + + + GHC re-calculates the dependencies each time it is + invoked, so the dependencies never get out of sync with the + source. + + + + Any of the command-line options described in the rest of + this chapter can be used with + , but note that any options + you give on the command line will apply to all the source files + compiled, so if you want any options to apply to a single source + file only, you'll need to use an OPTIONS + pragma (see ). + + If the program needs to be linked with additional objects + (say, some auxilliary C code), then the object files can be + given on the command line and GHC will include them when linking + the executable. + + Note that GHC can only follow dependencies if it has the + source file available, so if your program includes a module for + which there is no source file, even if you have an object and an + interface file for the module, then GHC will complain. The + exception to this rule is for package modules, which may or may + not have source files. + + The source files for the program don't all need to be in + the same directory; the option can be used + to add directories to the search path (see ). + + + + Expression evaluation mode + + This mode is very similar to interactive mode, except that + there is a single expression to evaluate which is specified on + the command line as an argument to the + option: + + +ghc -e expr + + + Haskell source files may be named on the command line, and + they will be loaded exactly as in interactive mode. The + expression is evaluated in the context of the loaded + modules. + + For example, to load and run a Haskell program containing + a module Main, we might say + + +ghc -e Main.main Main.hs + + + or we can just use this mode to evaluate expressions in + the context of the Prelude: + + +$ ghc -e "interact (unlines.map reverse.lines)" +hello +olleh + + + + + Batch compiler mode + + In this mode, GHC will compile one or more source files + given on the command line. + + The first phase to run is determined by each input-file + suffix, and the last phase is determined by a flag. If no + relevant flag is present, then go all the way through linking. + This table summarises: + + + + + + + + + + + Phase of the compilation system + Suffix saying “start here” + Flag saying “stop after” + (suffix of) output file + + + + + literate pre-processor + .lhs + - + .hs + + + + C pre-processor (opt.) + .hs (with + ) + + .hspp + + + + Haskell compiler + .hs + , + .hc, .s + + + + C compiler (opt.) + .hc or .c + + .s + + + + assembler + .s + + .o + + + + linker + other + - + a.out + + + + + + + + + + + Thus, a common invocation would be: + + +ghc -c Foo.hs + + to compile the Haskell source file + Foo.hs to an object file + Foo.o. + + Note: What the Haskell compiler proper produces depends on + whether a native-code generatornative-code + generator is used (producing assembly + language) or not (producing C). See for more details. + + Note: C pre-processing is optional, the + + flag turns it on. See for more + details. + + Note: The option -E + option runs just the pre-processing passes + of the compiler, dumping the result in a file. Note that this + differs from the previous behaviour of dumping the file to + standard output. + + + Help and verbosity options @@ -341,7 +605,9 @@ module X where + + Print a one-line string including GHC's version number. @@ -374,444 +640,7 @@ module X where - - Using <command>ghc</command> <option>––make</option> - - - - separate compilation - - - When given the option, GHC will - build a multi-module Haskell program by following dependencies - from a single root module (usually Main). For - example, if your Main module is in a file - called Main.hs, you could compile and link - the program like this: - - -ghc ––make Main.hs - - - The command line must contain one source file or module - name; GHC will figure out all the modules in the program by - following the imports from this initial module. It will then - attempt to compile each module which is out of date, and finally - if the top module is Main, the program - will also be linked into an executable. - - The main advantages to using ghc ––make - over traditional Makefiles are: - - - - GHC doesn't have to be restarted for each compilation, - which means it can cache information between compilations. - Compiling a muli-module program with ghc - ––make can be up to twice as fast as running - ghc individually on each source - file. - - - You don't have to write a - Makefile. - - Makefilesavoiding - - - GHC re-calculates the dependencies each time it is - invoked, so the dependencies never get out of sync with the - source. - - - - Any of the command-line options described in the rest of - this chapter can be used with , but note - that any options you give on the command line will apply to all - the source files compiled, so if you want any options to apply to - a single source file only, you'll need to use an - OPTIONS pragma (see ). - - If the program needs to be linked with additional objects - (say, some auxilliary C code), these can be specified on the - command line as usual. - - Note that GHC can only follow dependencies if it has the - source file available, so if your program includes a module for - which there is no source file, even if you have an object and an - interface file for the module, then GHC will complain. The - exception to this rule is for package modules, which may or may - not have source files. - - The source files for the program don't all need to be in the - same directory; the option can be used to add - directories to the search path (see ). - - - - - GHC without <option>––make</option> - - Without , GHC will compile one or - more source files given on the command line. - - The first phase to run is determined by each input-file - suffix, and the last phase is determined by a flag. If no - relevant flag is present, then go all the way through linking. - This table summarises: - - - - - - - - - - - Phase of the compilation system - Suffix saying “start here” - Flag saying “stop after” - (suffix of) output file - - - - - literate pre-processor - .lhs - - - .hs - - - - C pre-processor (opt.) - - .hs (with - ) - - .hspp - - - - Haskell compiler - .hs - , - .hc, .s - - - - C compiler (opt.) - .hc or .c - - .s - - - - assembler - .s - - .o - - - - linker - other - - - a.out - - - - - - - - - - - Thus, a common invocation would be: ghc -c - Foo.hs - - Note: What the Haskell compiler proper produces depends on - whether a native-code generatornative-code - generator is used (producing assembly - language) or not (producing C). See for more details. - - Note: C pre-processing is optional, the - - flag turns it on. See for more details. - - Note: The option -E - option runs just the pre-processing passes - of the compiler, dumping the result in a file. Note that this - differs from the previous behaviour of dumping the file to - standard output. - - - - Re-directing the compilation output(s) - - output-directing options - redirecting compilation output - - - - - - - - GHC's compiled output normally goes into a - .hc, .o, etc., - file, depending on the last-run compilation phase. The - option -o - option re-directs the output of that - last-run phase to file foo. - - Note: this “feature” can be - counterintuitive: ghc -C -o foo.o foo.hs - will put the intermediate C code in the file - foo.o, name notwithstanding! - - Note: on Windows, if the result is an executable file, the - extension ".exe" is added if the specified filename - does not already have an extension. Thus - - ghc -o foo Main.hs - - will compile and link the module Main.hs, and put the - resulting executable in foo.exe (not foo). - - - - - - - - - The option isn't of much use if - you have several input files… - Non-interface output files are normally put in the same - directory as their corresponding input file came from. You - may specify that they be put in another directory using the - -odir - <dir> option (the “Oh, - dear” option). For example: - - -% ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` - - - The output files, Foo.o, - Bar.o, and - Bumble.o would be put into a - subdirectory named after the architecture of the executing - machine (sun4, - mips, etc). The directory must already - exist; it won't be created. - - Note that the option does - not affect where the interface files - are put. In the above example, they would still be put in - parse/Foo.hi, - parse/Bar.hi, and - gurgle/Bumble.hi. - - - - - file - - - - The interface output may be directed to another file - bar2/Wurble.iface with the option - (not - recommended). - - WARNING: if you redirect the interface file somewhere - that GHC can't find it, then the recompilation checker may - get confused (at the least, you won't get any recompilation - avoidance). We recommend using a combination of - and options - instead, if possible. - - To avoid generating an interface at all, you could use - this option to redirect the interface into the bit bucket: - -ohi /dev/null, for example. - - - - - directory - - - - Redirects all generated interface files into - directory, instead of the default - which is to place the interface file in the same directory - as the source file. - - - - - suffix - suffix - suffix - - - - - EXOTICA: The - suffix will change the - .o file suffix for object files to - whatever you specify. We use this when compiling libraries, - so that objects for the profiling versions of the libraries - don't clobber the normal ones. - - Similarly, the - suffix will change the - .hi file suffix for non-system interface - files (see ). - - Finally, the option - suffix will change the - .hc file suffix for compiler-generated - intermediate C files. - - The / - game is particularly useful if you want to compile a program both with and without - profiling, in the same directory. You can say: - - ghc ... - - to get the ordinary version, and - - ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all - - to get the profiled version. - - - - - - Keeping Intermediate Files - intermediate files, saving - - .hc files, saving - - .s files, saving - - - - The following options are useful for keeping certain - intermediate files around, when normally GHC would throw these - away after compilation: - - - - - - - - - Keep intermediate .hc files when - doing .hs-to-.o - compilations via C (NOTE: .hc files - aren't generated when using the native code generator, you - may need to use to force them - to be produced). - - - - - - - - - - Keep intermediate .s files. - - - - - - - - - - Keep intermediate .raw-s files. - These are the direct output from the C compiler, before - GHC does “assembly mangling” to produce the - .s file. Again, these are not produced - when using the native code generator. - - - - - - - - - - temporary files - keeping - - - Instructs the GHC driver not to delete any of its - temporary files, which it normally keeps in - /tmp (or possibly elsewhere; see ). Running GHC with - will show you what temporary files - were generated along the way. - - - - - - - Redirecting temporary files - - - temporary files - redirecting - - - - - - - - If you have trouble because of running out of space - in /tmp (or wherever your - installation thinks temporary files should go), you may - use the -tmpdir - <dir> option option to specify - an alternate directory. For example, says to put temporary files in the current - working directory. - - Alternatively, use your TMPDIR - environment variable.TMPDIR - environment variable Set it to the - name of the directory where temporary files should be put. - GCC and other programs will honour the - TMPDIR variable as well. - - Even better idea: Set the - DEFAULT_TMPDIR make variable when - building GHC, and never worry about - TMPDIR again. (see the build - documentation). - - - - - - + &separate; Warnings and sanity-checking @@ -825,7 +654,7 @@ ghc ––make Main.hs generated during compilation. By default, you get a standard set of warnings which are generally likely to indicate bugs in your program. These are: - , + , , , , and @@ -864,6 +693,15 @@ ghc ––make Main.hs + + : + + + Makes any warning into a fatal error. Useful so that you don't + miss warnings when doing batch compilation. + + + The full set of warning options is described below. To turn @@ -977,6 +815,18 @@ g [] = 2 an instance declaration is missing one or more methods, and the corresponding class declaration has no default declaration for them. + The warning is suppressed if the method name + begins with an underscore. Here's an example where this is useful: + + class C a where + _simpleFn :: a -> String + complexFn :: a -> a -> String + complexFn x y = ... _simpleFn ... + + The idea is that: (a) users of the class will only call complexFn; + never _simpleFn; and (b) + instance declarations can define either complexFn or _simpleFn. + @@ -1044,6 +894,20 @@ f "2" = 2 patterns that can fail, eg. \(x:xs)->.... Normally, these aren't treated as incomplete patterns by . + ``Lambda-bound patterns'' includes all places where there is a single pattern, + including list comprehensions and do-notation. In these cases, a pattern-match + failure is quite legitimate, and triggers filtering (list comprehensions) or + the monad fail operation (monads). For example: + + f :: [Maybe a] -> [a] + f xs = [y | Just y <- xs] + + Switching on will elicit warnings about + these probably-innocent cases, which is why the flag is off by default. + The deriving( Read ) mechanism produces monadic code with + pattern matches, so you will also get misleading warnings about the compiler-generated + code. (This is arguably a Bad Thing, but it's awkward to fix.) + @@ -1101,9 +965,12 @@ f "2" = 2 Report all unused variables which arise from pattern matches, including patterns consisting of a single variable. For instance f x y = [] would report - x and y as unused. To - eliminate the warning, all unused variables can be replaced - with wildcards. + x and y as unused. The + warning is suppressed if the variable name begins with an underscore, thus: + + f _x = True + + @@ -1118,7 +985,6 @@ f "2" = 2 - &separate; &packages; @@ -1145,13 +1011,11 @@ f "2" = 2 following “packages” of optimisations (or lack thereof) should suffice. - Once you choose a - “package,” stick with it—don't chop and - change. Modules' interfaces will change - with a shift to a new option, and you may - have to recompile a large chunk of all importing modules before - your program can again be run safely (see ). + Note that higher optimisation levels cause more + cross-module optimisation to be performed, which can have an + impact on how much of your program needs to be recompiled when + you change something. This is one reaosn to stick to + no-optimisation when developing code. @@ -1188,6 +1052,10 @@ f "2" = 2 Means: “Generate good-quality code without taking too long about it.” Thus, for example: ghc -c -O Main.lhs + + currently also implies + . This may change in the + future. @@ -1216,7 +1084,7 @@ f "2" = 2 -Ofile <file> option optimising, customised - (NOTE: not supported yet in GHC 5.x. Please ask if + (NOTE: not supported since GHC 4.x. Please ask if you're interested in this.) For those who need absolute @@ -1238,7 +1106,7 @@ f "2" = 2 We don't use a flag for day-to-day work. We use to get respectable speed; e.g., when we want to measure something. When we want to go for - broke, we tend to use (and we go for + broke, we tend to use (and we go for lots of coffee breaks). The easiest way to see what (etc.) @@ -1860,7 +1728,7 @@ statements or clauses. &runtime; - Generating External Core Files + Generating and compiling External Core Files intermediate code generation @@ -1876,6 +1744,10 @@ statements or clauses. files is different (though similar) to the Core output format generated for debugging purposes (). + The Core format natively supports notes which you can add to + your source code using the CORE pragma (see ). + @@ -1890,6 +1762,10 @@ statements or clauses. +GHC can also read in External Core files as source; just give the .hcr file on +the command line, instead of the .hs or .lhs Haskell source. +A current infelicity is that you need to give teh -fglasgow-exts flag too, because +ordinary Haskell 98, when translated to External Core, uses things like rank-2 types. &debug;