X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=fad30ac245558c17c752a0e1622d10647e6c8238;hb=433558226790dfa88d215cf12a39df44a3ed01fd;hp=3c19be5de233e485b6ef3a2a446cf69b43c162b2;hpb=3b6382e443ed57d08dc676337621fc3d5cd0cb05;p=ghc-hetmet.git diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index 3c19be5..fad30ac 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. @@ -841,7 +840,7 @@ ghc -c Foo.hs of warnings which are generally likely to indicate bugs in your program. These are: , - , + , , , , @@ -919,15 +918,33 @@ 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. + + + + + : + + + + warnings deprecations - Causes a warning to be emitted when a deprecated - function or type is used. Entities can be marked as - deprecated using a pragma, see . + Causes a warning to be emitted when a + module, function or type with a WARNING or DEPRECATED pragma + is used. See for more + details on the pragmas. This option is on by default. @@ -1158,6 +1175,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) } + + @@ -1178,7 +1200,8 @@ f foo = foo { x = 6 } The trouble with orphans is that GHC must pro-actively read the interface files for all orphan modules, just in case their instances or rules play a role, whether or not the module's interface would otherwise - be of any use. Other things being equal, avoid orphan modules. + be of any use. See for details. + @@ -1763,17 +1786,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 @@ -1785,9 +1851,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. @@ -1904,7 +1980,7 @@ statements or clauses. GHC can dump its optimized intermediate code (said to be in “Core” format) to a file as a side-effect of compilation. Non-GHC back-end tools can read and process Core files; these files have the suffix - .hcr. The Core format is described in + .hcr. The Core format is described in An External Representation for the GHC Core Language, and sample tools for manipulating Core files (in Haskell) are in the GHC source distribution