X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fusing.xml;h=8cbcd35fca6cb6f6dcf01dbb8865bcaa9dc42ea1;hb=c6b2930d3f7d91217a634bd592d184e383598e67;hp=ec6187b4661545d0b358c438591c95ad5fcaf9a8;hpb=b9de29ac3fbf5192049a0bcaf1ab0c8bbbd57a83;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/using.xml b/ghc/docs/users_guide/using.xml
index ec6187b..8cbcd35 100644
--- a/ghc/docs/users_guide/using.xml
+++ b/ghc/docs/users_guide/using.xml
@@ -51,35 +51,38 @@ ghc [argument...]
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 pragma OPTIONS
+ OPTIONS_GHC pragma OPTIONS_GHC
pragma:
-{-# OPTIONS -fglasgow-exts #-}
+{-# OPTIONS_GHC -fglasgow-exts #-}
module X where
...
- OPTIONS pragmas are only looked for at
+ 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. Multiple OPTIONS
- pragmas are recognised. Note that your command shell does not
+ OPTIONS_GHC. Multiple OPTIONS_GHC
+ pragmas are recognised. Do not put comments before, or on the same line
+ as, the OPTIONS_GHC pragma.
+
+ Note that your command shell does not
get to the source file options, they are just included literally
- in the array of command-line arguments the compiler driver
+ in the array of command-line arguments the compiler
maintains internally, so you'll be desperately disappointed if
- you try to glob etc. inside OPTIONS.
+ you try to glob etc. inside OPTIONS_GHC.
- NOTE: the contents of OPTIONS are prepended to the
+ NOTE: the contents of OPTIONS_GHC are prepended to the
command-line options, so you do have the
- ability to override OPTIONS settings via the command
+ ability to override OPTIONS_GHC settings via the command
line.It is not recommended to move all the contents of your
Makefiles into your source files, but in some circumstances, the
- OPTIONS pragma is the Right Thing. (If you
+ OPTIONS_GHC pragma is the Right Thing. (If you
use and have OPTION flags in
- your module, the OPTIONS will get put into the generated .hc
+ your module, the OPTIONS_GHC will get put into the generated .hc
file).
@@ -93,21 +96,47 @@ module X where
- Static vs. Dynamic options
+ Static, Dynamic, and Mode optionsstaticoptionsdynamicoptions
+ modeoptions
+ Each of GHC's command line options is classified as either
- static or dynamic.
- A static flag may only be specified on the command line, whereas a
- dynamic flag may also be given in an OPTIONS
- pragma in a source file or set from the GHCi command-line with
- :set.
-
- As a rule of thumb, options which relate to filenames are
- static, and the rest are dynamic. The flag reference tables (static or dynamic or
+ mode:
+
+
+
+ Mode flags
+
+ For example, or .
+ There may be only a single mode flag on the command line. The
+ available modes are listed in .
+
+
+
+ Dynamic Flags
+
+ 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
+ using :set in GHCi.
+
+
+
+ Static Flags
+
+ A few flags are "static", which means they can only be used on
+ the command-line, and remain in force over the entire GHC/GHCi
+ run.
+
+
+
+
+ The flag reference tables () lists the status of each flag.
@@ -124,19 +153,19 @@ module X where
-
- .lhs
- lhs suffix
-
+ .hs
- A “literate Haskell” module.
+ A Haskell module.
- .hs
+
+ .lhs
+ lhs suffix
+
- A not-so-literate Haskell module.
+ A “literate Haskell” module.
@@ -333,13 +362,13 @@ ghc ––make Main.hs
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
+ Compiling a multi-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 aMakefile.
+ You don't have to write a Makefile.Makefilesavoiding
@@ -354,11 +383,11 @@ ghc ––make Main.hs
, 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
+ file only, you'll need to use an OPTIONS_GHC
pragma (see ).If the program needs to be linked with additional objects
- (say, some auxilliary C code), then the object files can be
+ (say, some auxiliary C code), then the object files can be
given on the command line and GHC will include them when linking
the executable.
@@ -512,6 +541,30 @@ ghc -c Foo.hs
of the compiler, dumping the result in a file. Note that this
differs from the previous behaviour of dumping the file to
standard output.
+
+
+ Overriding the default behaviour for a file
+
+ As described above, the way in which a file is processed by GHC
+ depends on its suffix. This behaviour can be overriden using the
+ option:
+
+
+
+ suffix
+
+
+
+ Causes all files following this option on the command
+ line to be processed as if they had the suffix
+ suffix. For example, to compile a
+ Haskell module in the file M.my-hs,
+ use ghc -c -x hs M.my-hs.
+
+
+
+
+
@@ -660,6 +713,52 @@ ghc -c Foo.hs
+
+
+
+
+
+
+ Causes GHC to emit the full source span of the
+ syntactic entity relating to an error message. Normally, GHC
+ emits the source location of the start of the syntactic
+ entity only.
+
+ For example:
+
+test.hs:3:6: parse error on input `where'
+
+ becomes:
+
+test296.hs:3:6-10: parse error on input `where'
+
+ And multi-line spans are possible too:
+
+test.hs:(5,4)-(6,7):
+ Conflicting definitions for `a'
+ Bound at: test.hs:5:4
+ test.hs:6:7
+ In the binding group for: a, b, a
+
+ Note that line numbers start counting at one, but
+ column numbers start at zero. This choice was made to
+ follow existing convention (i.e. this is how Emacs does
+ it).
+
+
+
+
+
+
+
+
+ Prints a one-line summary of timing statistics for the
+ GHC run. This option is equivalent to
+ +RTS -tstderr, see .
+
+
+
@@ -802,6 +901,33 @@ g [] = 2
+ :
+
+
+ incomplete record updates, warning
+ record updates, incomplete
+
+ The function
+ f below will fail when applied to
+ Bar, so the compiler will emit a warning about
+ this when is
+ enabled.
+
+
+data Foo = Foo { x :: Int }
+ | Bar
+
+f :: Foo -> Foo
+f foo = foo { x = 6 }
+
+
+ This option isn't enabled be default because it can be
+ very noisy, and it often doesn't indicate a bug in the
+ program.
+
+
+
+
:
@@ -890,6 +1016,27 @@ g [] = 2
+ :
+
+
+ orphan instances, warning
+ orphan rules, warning
+
+ This option causes a warning to be emitted whenever the
+ module contains an "orphan" instance declaration or rewrite rule.
+ An instance declartion is an orphan if it appears in a module in
+ which neither the class nor the type being instanced are declared
+ in the same module. A rule is an orphan if it is a rule for a
+ function declared in another module. A module containing any
+ orphans is called an orphan module.
+ 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.
+
+
+
+
:
@@ -1058,8 +1205,10 @@ f "2" = 2
- No -type option specified:
- -O* not specified
+
+ No -type option specified:
+ -O* not specified
+ This is taken to mean: “Please compile
quickly; I'm not over-bothered about compiled-code
@@ -1069,8 +1218,10 @@ f "2" = 2
- :
-
+
+ :
+
+ Means “turn off all optimisation”,
reverting to the same settings as if no
@@ -1082,10 +1233,12 @@ f "2" = 2
- or :
- -O option
- -O1 option
- optimisenormally
+
+ or :
+ -O option
+ -O1 option
+ optimisenormally
+ Means: “Generate good-quality code without
taking too long about it.” Thus, for example:
@@ -1098,9 +1251,11 @@ f "2" = 2
- :
- -O2 option
- optimiseaggressively
+
+ :
+ -O2 option
+ optimiseaggressively
+ Means: “Apply every non-dangerous
optimisation, even if it means significantly longer
@@ -1118,9 +1273,11 @@ f "2" = 2
- :
- -Ofile <file> option
- optimising, customised
+
+ :
+ -Ofile <file> option
+ optimising, customised
+ (NOTE: not supported since GHC 4.x. Please ask if
you're interested in this.)
@@ -1195,9 +1352,22 @@ f "2" = 2
-
-
-
+
+
+
+
+
+ Turns off the common-sub-expression elimination optimisation.
+ Can be useful if you have some unsafePerformIO
+ expressions that you don't want commoned-up.
+
+
+
+
+
+
+
+ Turns off the strictness analyser; sometimes it eats
too many cycles.
@@ -1205,22 +1375,39 @@ f "2" = 2
-
-
-
+
+
+
+
- Turns off the CPR (constructed product result)
- analysis; it is somewhat experimental.
+ Turns off the full laziness optimisation (also known as
+ let-floating). Full laziness increases sharing, which can lead
+ to increased memory residency.
- :
+
+
+
+
+ Turn off the "state hack" whereby any lambda with a
+ State# token as argument is considered to be
+ single-entry, hence it is considered OK to inline things inside
+ it. This can improve performance of IO and ST monad code, but it
+ runs the risk of reducing sharing.
+
+
+
+
+
+ :
strict constructor fieldsconstructor fields, strict
-
+
+ This option causes all constructor fields which are
marked strict (i.e. “!”) to be unboxed or
unpacked if possible. It is equivalent to adding an
@@ -1236,8 +1423,10 @@ f "2" = 2
-
-
+
+
+
+ Switches on an experimental "optimisation".
Switching it on makes the compiler a little keener to
@@ -1252,12 +1441,13 @@ f "2" = 2
- :
-
+
+ :
inlining, controllingunfolding, controlling
-
+
+ (Default: 45) Governs the maximum size that GHC will
allow a function unfolding to be. (An unfolding has a
“size” that reflects the cost in terms of
@@ -1301,38 +1491,47 @@ f "2" = 2
&phases;
-Using Concurrent Haskell
+ Using Concurrent Haskell
+ Concurrent Haskellusing
- Concurrent Haskell—use
+ GHC supports Concurrent Haskell by default, without requiring a
+ special option or libraries compiled in a certain way. To get access to
+ the support libraries for Concurrent Haskell, just import
+ Control.Concurrent. More information on Concurrent Haskell is provided in the documentation for that module.
-
-GHC supports Concurrent Haskell by default, without requiring a
-special option or libraries compiled in a certain way. To get access
-to the support libraries for Concurrent Haskell, just import
-Control.Concurrent (details are in the accompanying
-library documentation).
-
-
-RTS options are provided for modifying the behaviour of the threaded
-runtime system. See .
-
-
-
-Concurrent Haskell is described in more detail in the documentation
-for the Control.Concurrent module.
-
+ The following RTS option(s) affect the behaviour of Concurrent
+ Haskell programs:RTS options, concurrent
-
+
+
+
+
+ RTS option
+ Sets the context switch interval to s
+ seconds. A context switch will occur at the next heap block
+ allocation after the timer expires (a heap block allocation occurs
+ every 4k of allocation). With or
+ , context switches will occur as often as
+ possible (at every heap block allocation). By default, context
+ switches occur every 20ms. Note that GHC's internal timer ticks
+ every 20ms, and the context switch timer is always a multiple of
+ this timer, so 20ms is the maximum granularity available for timed
+ context switches.
+
+
+
+
Using parallel Haskell
-parallel Haskell—use
-
-
-
-[You won't be able to execute parallel Haskell programs unless PVM3
+Parallel Haskellusing
+[NOTE: GHC does not support Parallel Haskell by default, you need to
+ obtain a special version of GHC from the GPH site. Also,
+you won't be able to execute parallel Haskell programs unless PVM3
(parallel Virtual Machine, version 3) is installed at your site.]
@@ -1341,7 +1540,7 @@ To compile a Haskell program for parallel execution under PVM, use the
option,-parallel
option both when compiling and
linking. You will probably want to import
-parallel into your Haskell modules.
+Control.Parallel into your Haskell modules.
@@ -1473,7 +1672,7 @@ results—only with “how parallel” it was! We want pretty pictu
parallelism profiles (à la hbcpp) can be generated with the
--qP RTS option (concurrent, parallel) RTS option. The
+-qP RTS option RTS option. The
per-processor profiling info is dumped into files named
<full-path><program>.gr. These are then munged into a PostScript picture,
which you can then display. For example, to run your program
@@ -1518,20 +1717,18 @@ what's happening overall is: tail -f /tmp/pvml.nnn.
-RTS options for Concurrent/parallel Haskell
+RTS options for Parallel Haskell
-RTS options, concurrentRTS options, parallel
-Concurrent Haskell—RTS optionsparallel Haskell—RTS options
Besides the usual runtime system (RTS) options
(), there are a few options particularly
-for concurrent/parallel execution.
+for parallel execution.
@@ -1548,17 +1745,16 @@ the default is 2.
-:
+:
--C<us> RTS option Sets
+-C<s> RTS option Sets
the context switch interval to <s> seconds.
A context switch will occur at the next heap block allocation after
the timer expires (a heap block allocation occurs every 4k of
allocation). With or ,
context switches will occur as often as possible (at every heap block
-allocation). By default, context switches occur every 20ms
-milliseconds. Note that GHC's internal timer ticks every 20ms, and
+allocation). By default, context switches occur every 20ms. Note that GHC's internal timer ticks every 20ms, and
the context switch timer is always a multiple of this timer, so 20ms
is the maximum granularity available for timed context switches.
@@ -1587,7 +1783,7 @@ check (with ).
-qt<num> RTS option
-(paraLLEL ONLY) Limit the thread pool size, i.e. the number of concurrent
+(paraLLEL ONLY) Limit the thread pool size, i.e. the number of
threads per processor to <num>. The default is
32. Each thread requires slightly over 1K words in
the heap for thread state and stack objects. (For 32-bit machines, this
@@ -1694,7 +1890,7 @@ and maintaining internal tables of global addresses.
only) Means to pass the like-named
option to GCC; it says to use the Version 8 SPARC
instructions, notably integer multiply and divide. The
- similiar GCC options for SPARC also
+ similar GCC options for SPARC also
work, actually.
@@ -1750,10 +1946,10 @@ statements or clauses.
-
-
-
-
+
+
+
+ Generate .hcr files.
@@ -1763,7 +1959,7 @@ 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
+A current infelicity is that you need to give the -fglasgow-exts flag too, because
ordinary Haskell 98, when translated to External Core, uses things like rank-2 types.