X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=024a4e786963db7c0e2e3fef87fa9653dc679ffa;hp=3c19be5de233e485b6ef3a2a446cf69b43c162b2;hb=9d0c8f842e35dde3d570580cf62a32779f66a6de;hpb=3b6382e443ed57d08dc676337621fc3d5cd0cb05
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 3c19be5..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.
@@ -841,11 +840,13 @@ ghc -c Foo.hs
of warnings which are generally likely to indicate bugs in your
program. These are:
,
- ,
+ ,
,
,
,
- , 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,15 +921,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.
+
+
+
+
+ :
+
+
+
+ warningsdeprecations
- 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.
@@ -975,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.
@@ -983,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.
+
+
+
+
+ :
@@ -1158,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) }
+
+
@@ -1178,7 +1217,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.
+
@@ -1327,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
@@ -1763,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 parallelismIn 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 +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.
@@ -1904,7 +2047,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