X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=024a4e786963db7c0e2e3fef87fa9653dc679ffa;hp=ce7ef7680b2f174ce1cd8f478a42289a1b9481b6;hb=9d0c8f842e35dde3d570580cf62a32779f66a6de;hpb=6867d7a5ba5bdde3f6216d932d9486405c9115b3 diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index ce7ef76..024a4e7 100644 --- a/docs/users_guide/using.xml +++ b/docs/users_guide/using.xml @@ -46,26 +46,25 @@ ghc [argument...] Sometimes it is useful to make the connection between a source file and the command-line options it requires quite - tight. For instance, if a Haskell source file uses GHC - extensions, it will always need to be compiled with the - option. Rather than maintaining + tight. For instance, if a Haskell source file deliberately + uses name shadowing, it should be compiled with the + option. Rather than maintaining the list of per-file options in a Makefile, it is possible to do this directly in the source file using the OPTIONS_GHC pragma OPTIONS_GHC pragma: -{-# OPTIONS_GHC -fglasgow-exts #-} +{-# OPTIONS_GHC -fno-warn-name-shadowing #-} module X where ... - OPTIONS_GHC pragmas are only looked for at - the top of your source files, upto the first - (non-literate,non-empty) line not containing - OPTIONS_GHC. Multiple OPTIONS_GHC - pragmas are recognised. Do not put comments before, or on the same line - as, the OPTIONS_GHC pragma. + OPTIONS_GHC is a file-header pragma + (see ). + + Only dynamic flags can be used in an OPTIONS_GHC pragma + (see ). Note that your command shell does not get to the source file options, they are just included literally @@ -121,7 +120,7 @@ module X where Most non-mode flags fall into this category. A dynamic flag may be used on the command line, in a - GHC_OPTIONS pragma in a source file, or set + OPTIONS_GHC pragma in a source file, or set using :set in GHCi. @@ -845,7 +844,9 @@ ghc -c Foo.hs , , , - , and + , + , + , and . The following flags are simple ways to select standard “packages” of warnings: @@ -877,7 +878,8 @@ ghc -c Foo.hs , , , - , and + , + , and . @@ -919,6 +921,23 @@ ghc -c Foo.hs + : + + + + warnings + pragmas + Causes a warning to be emitted when a + pragma that GHC doesn't recognise is used. As well as pragmas + that GHC itself uses, GHC also recognises pragmas known to be used + by other tools, e.g. OPTIONS_HUGS and + DERIVE. + + This option is on by default. + + + + : @@ -976,7 +995,7 @@ foreign import "&f" f :: FunPtr t - Causes a warning to be emitted when a a datatype + Causes a warning to be emitted when a datatype T is imported with all constructors, i.e. T(..), but has been exported abstractly, i.e. T. @@ -984,6 +1003,20 @@ foreign import "&f" f :: FunPtr t + : + + + + Causes a warning to be emitted when an unlifted type + is bound in a way that looks lazy, e.g. + where (I# x) = .... Use + where !(I# x) = ... instead. This will be an + error, rather than a warning, in GHC 6.14. + + + + + : @@ -1159,6 +1192,11 @@ f foo = foo { x = 6 } typographical errors that turn into hard-to-find bugs, e.g., in the inadvertent capture of what would be a recursive call in f = ... let f = id in ... f .... + The warning is suppressed for names beginning with an underscore. For example + + f x = do { _ignore <- this; _ignore <- that; return (the other) } + + @@ -1329,6 +1367,56 @@ f "2" = 2 + + : + + + unused do binding, warning + do binding, unused + + Report expressions occuring in do and mdo blocks + that appear to silently throw information away. + For instance do { mapM popInt xs ; return 10 } would report + the first statement in the do block as suspicious, + as it has the type StackM [Int] and not StackM (), but that + [Int] value is not bound to anything. The warning is suppressed by + explicitly mentioning in the source code that your program is throwing something away: + + do { _ <- mapM popInt xs ; return 10 } + + Of course, in this particular situation you can do even better: + + do { mapM_ popInt xs ; return 10 } + + + + + + + : + + + apparently erroneous do binding, warning + do binding, apparently erroneous + + Report expressions occuring in do and mdo blocks + that appear to lack a binding. + For instance do { return (popInt 10) ; return 10 } would report + the first statement in the do block as suspicious, + as it has the type StackM (StackM Int) (which consists of two nested applications + of the same monad constructor), but which is not then "unpacked" by binding the result. + The warning is suppressed by explicitly mentioning in the source code that your program is throwing something away: + + do { _ <- return (popInt 10) ; return 10 } + + For almost all sensible programs this will indicate a bug, and you probably intended to write: + + do { popInt 10 ; return 10 } + + + + + If you're feeling really paranoid, the @@ -1765,17 +1853,60 @@ f "2" = 2 linkend="lang-parallel" /> we describe the language features that affect parallelism. - - Options for SMP parallelism + + Compile-time options for SMP parallelism In order to make use of multiple CPUs, your program must be linked with the option (see ). Then, to run a program on multiple - CPUs, use the RTS option: + linkend="options-linker" />). Additionally, the following + compiler options affect parallelism: + + + + + + Blackholing is the act of marking a thunk (lazy + computuation) as being under evaluation. It is useful for + three reasons: firstly it lets us detect certain kinds of + infinite loop (the NonTermination + exception), secondly it avoids certain kinds of space + leak, and thirdly it avoids repeating a computation in a + parallel program, because we can tell when a computation + is already in progress. + + + The option causes + each thunk to be blackholed as soon as evaluation begins. + The default is "lazy blackholing", whereby thunks are only + marked as being under evaluation when a thread is paused + for some reason. Lazy blackholing is typically more + efficient (by 1-2% or so), because most thunks don't + need to be blackholed. However, eager blackholing can + avoid more repeated computation in a parallel program, and + this often turns out to be important for parallelism. + + + + We recommend compiling any code that is intended to be run + in parallel with the + flag. + + + + + + + + RTS options for SMP parallelism + + To run a program on multiple CPUs, use the + RTS option: + + - + RTS option Use x simultaneous threads when @@ -1787,9 +1918,19 @@ f "2" = 2 on a dual-core machine we would probably use +RTS -N2 -RTS. + Omitting x, + i.e. +RTS -N -RTS, lets the runtime + choose the value of x itself + based on how many processors are in your machine. + + Be careful when using all the processors in your + machine: if some of your processors are in use by other + programs, this can actually harm performance rather than + improve it. + Setting also has the effect of - setting (the number of OS threads to - use for garbage collection) to the same value. + enabling the parallel garbage collector (see + ). There is no means (currently) by which this value may vary after the program has started.