X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=20bb687b4f8b10dd0ff8048e783ad29ddde84f6b;hb=43e0bca04009902c16f8f764dcb9a78c8da277c9;hp=60b8f3effc75eefcf6151deda88f78d1dcd6ac6c;hpb=949ce3bb4ef2654a814b3549051e439daf82b5e9;p=ghc-hetmet.git diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index 60b8f3e..20bb687 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 @@ -841,11 +840,13 @@ ghc -c Foo.hs of warnings which are generally likely to indicate bugs in your program. These are: , - , + , , , - , and - . The following flags are + , + , and + . The following + flags are simple ways to select standard “packages” of warnings: @@ -917,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. @@ -945,6 +964,30 @@ ghc -c Foo.hs + : + + + + Causes a warning to be emitted for foreign imports of + the following form: + +foreign import "f" f :: FunPtr t + + on the grounds that it probably should be + +foreign import "&f" f :: FunPtr t + + The first form declares that `f` is a (pure) C + function that takes no arguments and returns a pointer to a + C function with type `t`, whereas the second form declares + that `f` itself is a C function with type `t`. The first + declaration is usually a mistake, and one that is hard to + debug because it results in a crash, hence this + warning. + + + + : @@ -1152,7 +1195,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. + @@ -1737,34 +1781,118 @@ f "2" = 2 linkend="lang-parallel" /> we describe the language features that affect parallelism. - - Options to enable 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 running the program. Normally x - should be chosen to match the number of CPU cores on the machine. - There is no means (currently) by which this value may vary after - the program has started. - - For example, on a dual-core machine we would probably use + should be chosen to match the number of CPU cores on the + machineWhether hyperthreading cores should be counted or not is an + open question; please feel free to experiment and let us know what + results you find.. For example, + on a dual-core machine we would probably use +RTS -N2 -RTS. - Whether hyperthreading cores should be counted or not is an - open question; please feel free to experiment and let us know what - results you find. + Setting also has the effect of + setting (the number of OS threads to + use for garbage collection) to the same value. + + There is no means (currently) by which this value + may vary after the program has started. + + The following options affect the way the runtime schedules + threads on CPUs: + + + + + RTS + option + + Disable automatic migration for load balancing. + Normally the runtime will automatically try to schedule + threads across the available CPUs to make use of idle + CPUs; this option disables that behaviour. It is probably + only of use if you are explicitly scheduling threads onto + CPUs with GHC.Conc.forkOnIO. + + + + + RTS + option + + Migrate a thread to the current CPU when it is woken + up. Normally when a thread is woken up after being + blocked it will be scheduled on the CPU it was running on + last; this option allows the thread to immediately migrate + to the CPU that unblocked it. + + The rationale for allowing this eager migration is + that it tends to move threads that are communicating with + each other onto the same CPU; however there are + pathalogical situations where it turns out to be a poor + strategy. Depending on the communication pattern in your + program, it may or may not be a good idea. + + + @@ -1837,7 +1965,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