X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fusing.sgml;h=a79c54968a29d746d37e4ca7e3c77c97dc32d7b9;hb=2dfd507259664e6f28df4a9467a8de34d01d70a0;hp=8b65f308abfaf9e8cf157d5d4c243c1d7eb974b1;hpb=dc801dc275fb8f81d482535b4d6317e234bb10f8;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml
index 8b65f30..a79c549 100644
--- a/ghc/docs/users_guide/using.sgml
+++ b/ghc/docs/users_guide/using.sgml
@@ -13,7 +13,7 @@
Options can be specified in three ways:
- Command-line arguments
+ command-line argumentsstructure, command-linecommand-linearguments
@@ -21,13 +21,13 @@
An invocation of GHC takes the following form:
-
+
ghc [argument...]
-
+
- Command-line arguments are either options or file names.
+ command-line arguments are either options or file names.
- Command-line options begin with -.
+ command-line options begin with -.
They may not be grouped:
is different from .
Options need not precede filenames: e.g., ghc *.o -o
@@ -38,8 +38,8 @@ ghc [argument...]
Bar.hs.
-
- Command line options in source files
+
+ command line options in source filessource-file options
@@ -53,11 +53,11 @@ ghc [argument...]
OPTIONS pragma OPTIONS
pragma:
-
+
{-# OPTIONS -fglasgow-exts #-}
module X where
...
-
+OPTIONS pragmas are only looked for at
the top of your source files, upto the first
@@ -86,7 +86,7 @@ module X where
Setting options in GHCiOptions may also be modified from within GHCi, using the
- :set command. See
+ :set command. See
for more details.
@@ -107,7 +107,7 @@ module X where
As a rule of thumb, options which relate to filenames are
static, and the rest are dynamic. The flag reference tables () lists the status of each flag.
+ linkend="flag-reference"/>) lists the status of each flag.
@@ -193,7 +193,7 @@ module X where
ghc
- ––interactive
+ ––interactiveinteractive mode
@@ -202,13 +202,13 @@ module X where
Interactive mode, which is also available as
ghci. Interactive mode is described in
- more detail in .
+ more detail in .
ghc
- ––make
+ ––makemake mode
@@ -220,13 +220,13 @@ module X where
If you have a straightforward Haskell program, this is
likely to be much easier, and faster, than using
make. Make mode is described in .
+ linkend="make-mode"/>.
ghc
- –eexpr
+ –eexpreval mode
@@ -234,7 +234,7 @@ module X where
Expression-evaluation mode. This is very similar to
interactive mode, except that there is a single expression
to evaluate (expr) which is given
- on the command line. See for
+ on the command line. See for
more details.
@@ -260,31 +260,31 @@ module X where
there is no other mode flag specified on the command line,
in which case it means that the specified files should be
compiled and then linked to form a program. See .
+ linkend="options-order"/>.
ghc
- –M
+ –Mdependency-generation modeDependency-generation mode. In this mode, GHC can be
used to generate dependency information suitable for use in
a Makefile. See .
+ linkend="sec-makefile-dependencies"/>.
ghc
- ––mk-dll
+ ––mk-dlldependency-generation modeDLL-creation mode (Windows only). See .
+ linkend="win32-dlls-create"/>.
@@ -348,7 +348,7 @@ ghc ––make Main.hs
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
- pragma (see ).
+ pragma (see ).
If the program needs to be linked with additional objects
(say, some auxilliary C code), then the object files can be
@@ -365,7 +365,7 @@ ghc ––make Main.hs
The source files for the program don't all need to be in
the same directory; the option can be used
to add directories to the search path (see ).
+ linkend="search-path"/>).
@@ -415,10 +415,10 @@ olleh
-
-
-
-
+
+
+
+
@@ -493,15 +493,15 @@ ghc -c Foo.hs
whether a native-code generatornative-code
generator is used (producing assembly
language) or not (producing C). See for more details.
+ linkend="options-codegen"/> for more details.
Note: C pre-processing is optional, the
- flag turns it on. See for more
+ flag turns it on. See for more
details.
- Note: The option -E
- option runs just the pre-processing passes
+ Note: The option -E
+ option runs just the pre-processing passes
of the compiler, dumping the result in a file. Note that this
differs from the previous behaviour of dumping the file to
standard output.
@@ -511,8 +511,8 @@ ghc -c Foo.hs
Help and verbosity options
- help options
- verbosity options
+ help options
+ verbosity options
@@ -633,7 +633,7 @@ ghc -c Foo.hs
is the value of
$libdirlibdirin the package configuration file (see ).
+ linkend="packages"/>).
@@ -662,12 +662,12 @@ ghc -c Foo.hs
simple ways to select standard “packages” of warnings:
-
+ :
- -W option
+ -W optionProvides the standard warnings plus
,
,
@@ -680,7 +680,7 @@ ghc -c Foo.hs
:
-
+ Turns off all warnings, including the standard ones.
@@ -719,7 +719,7 @@ ghc -c Foo.hs
Causes a warning to be emitted when a deprecated
function or type is used. Entities can be marked as
deprecated using a pragma, see .
+ linkend="deprecated-pragma"/>.
@@ -878,7 +878,7 @@ f (_:xs) = 1
f "2" = 2
- where the last pattern match in f
+ where the last pattern match in f
won't ever be reached, as the second pattern overlaps
it. More often than not, redundant patterns is a programmer
mistake/error, so this option is enabled by default.
@@ -900,7 +900,7 @@ f "2" = 2
the monad fail operation (monads). For example:
f :: [Maybe a] -> [a]
- f xs = [y | Just y <- xs]
+ f xs = [y | Just y <- xs]
Switching on will elicit warnings about
these probably-innocent cases, which is why the flag is off by default.
@@ -921,7 +921,7 @@ f "2" = 2
in. This is useful information when converting code from a
context that assumed one default into one with another,
e.g., the `default default' for Haskell 1.4 caused the
- otherwise unconstrained value 1 to be
+ otherwise unconstrained value 1 to be
given the type Int, whereas Haskell 98
defaults it to Integer. This may lead to
differences in performance and behaviour, hence the
@@ -974,7 +974,7 @@ f "2" = 2
Report all unused variables which arise from pattern
matches, including patterns consisting of a single variable.
For instance f x y = [] would report
- x and y as unused. The
+ x and y as unused. The
warning is suppressed if the variable name begins with an underscore, thus:
f _x = True
@@ -983,7 +983,7 @@ f "2" = 2
-
+ If you're feeling really paranoid, the
@@ -1159,7 +1159,7 @@ f "2" = 2
Exception.assert in source code (in
other words, rewriting Exception.assert p
e to e (see ). This flag is turned on by
+ linkend="sec-assertions"/>). This flag is turned on by
.
@@ -1197,7 +1197,7 @@ f "2" = 2
unpacked if possible. It is equivalent to adding an
UNPACK pragma to every strict
constructor field (see ).
+ linkend="unpack-pragma"/>).
This option is a bit of a sledgehammer: it might
sometimes make things worse. Selectively unboxing fields
@@ -1214,9 +1214,9 @@ f "2" = 2
Switching it on makes the compiler a little keener to
inline a function that returns a constructor, if the
context is that of a thunk.
-
+
x = plusInt a b
-
+
If we inlined plusInt we might get an opportunity to use
update-in-place for the thunk 'x'.
@@ -1285,7 +1285,7 @@ library documentation).
RTS options are provided for modifying the behaviour of the threaded
-runtime system. See .
+runtime system. See .
@@ -1293,92 +1293,92 @@ Concurrent Haskell is described in more detail in the documentation
for the Control.Concurrent module.
-
+
-
-Using Parallel Haskell
+
+Using parallel Haskell
-Parallel Haskell—use
+parallel Haskell—use
[You won't be able to execute parallel Haskell programs unless PVM3
-(Parallel Virtual Machine, version 3) is installed at your site.]
-
+(parallel Virtual Machine, version 3) is installed at your site.]
+
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.
-
+ option,-parallel
+option both when compiling and
+linking. You will probably want to import
+parallel into your Haskell modules.
+
To run your parallel program, once PVM is going, just invoke it
“as normal”. The main extra RTS option is
-, to say how many PVM
+, to say how many PVM
“processors” your program to run on. (For more details of
-all relevant RTS options, please see .)
+all relevant RTS options, please see .)
-In truth, running Parallel Haskell programs and getting information
+In truth, running parallel Haskell programs and getting information
out of them (e.g., parallelism profiles) is a battle with the vagaries of
PVM, detailed in the following sections.
-
-Dummy's guide to using PVM
+
+Dummy's guide to using PVMPVM, how to use
-Parallel Haskell—PVM use
+parallel Haskell—PVM use
Before you can run a parallel program under PVM, you must set the
required environment variables (PVM's idea, not ours); something like,
probably in your .cshrc or equivalent:
-
+
setenv PVM_ROOT /wherever/you/put/it
setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch`
setenv PVM_DPATH $PVM_ROOT/lib/pvmd
-
+
Creating and/or controlling your “parallel machine” is a purely-PVM
-business; nothing specific to Parallel Haskell. The following paragraphs
+business; nothing specific to parallel Haskell. The following paragraphs
describe how to configure your parallel machine interactively.
-
+
-
+
If you use parallel Haskell regularly on the same machine configuration it
is a good idea to maintain a file with all machine names and to make the
environment variable PVM_HOST_FILE point to this file. Then you can avoid
the interactive operations described below by just saying
-
+
-
+
pvm $PVM_HOST_FILE
-
+
-
-You use the pvmpvm command command to start PVM on your
+
+You use the pvmpvm command command to start PVM on your
machine. You can then do various things to control/monitor your
“parallel machine;” the most useful being:
-
-
-
-
+
+
+
+
-ControlD
+ControlDexit pvm, leaving it running
@@ -1417,9 +1417,9 @@ machine. You can then do various things to control/monitor your
status of a particular process
-
-
-
+
+
+
@@ -1428,8 +1428,8 @@ The PVM documentation can tell you much, much more about pvm!
-
-Parallelism profiles
+
+parallelism profilesparallelism profiles
@@ -1438,29 +1438,29 @@ The PVM documentation can tell you much, much more about pvm!
-With Parallel Haskell programs, we usually don't care about the
+With parallel Haskell programs, we usually don't care about the
results—only with “how parallel” it was! We want pretty pictures.
-
-Parallelism profiles (à la hbcpp) can be generated with the
--qP RTS option (concurrent, parallel) RTS option. The
+
+parallelism profiles (à la hbcpp) can be generated with the
+-qP RTS option (concurrent, parallel) RTS option. The
per-processor profiling info is dumped into files named
-<full-path><program>.gr. These are then munged into a PostScript picture,
+<full-path><program>.gr. These are then munged into a PostScript picture,
which you can then display. For example, to run your program
-a.out on 8 processors, then view the parallelism profile, do:
-
+a.out on 8 processors, then view the parallelism profile, do:
+
-
+
-
+$ ./a.out +RTS -qP -qp8
$ grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one
$ gr2ps -O temp.gr # cvt to .ps; output in temp.ps
$ ghostview -seascape temp.ps # look at it!
-
+
-
+
The scripts for processing the parallelism profiles are distributed
@@ -1469,13 +1469,13 @@ in ghc/utils/parallel/.
-
-Other useful info about running parallel programs
+
+Other useful info about running parallel programs
-
+
The “garbage-collection statistics” RTS options can be useful for
seeing what parallel programs are doing. If you do either
--Sstderr RTS option or , then
+-Sstderr RTS option or , then
you'll get mutator, garbage-collection, etc., times on standard
error. The standard error of all PE's other than the `main thread'
appears in /tmp/pvml.nnn, courtesy of PVM.
@@ -1488,32 +1488,32 @@ what's happening overall is: tail -f /tmp/pvml.nnn.
-
-RTS options for Concurrent/Parallel Haskell
+
+RTS options for Concurrent/parallel Haskell
RTS options, concurrentRTS options, parallelConcurrent Haskell—RTS options
-Parallel Haskell—RTS options
+parallel Haskell—RTS options
Besides the usual runtime system (RTS) options
-(), there are a few options particularly
+(), there are a few options particularly
for concurrent/parallel execution.
-
-
-
-:
-
-
--qp<N> RTS option
-(PARALLEL ONLY) Use <N> PVM processors to run this program;
+
+
+
+:
+
+
+-qp<N> RTS option
+(paraLLEL ONLY) Use <N> PVM processors to run this program;
the default is 2.
@@ -1540,93 +1540,93 @@ is the maximum granularity available for timed context switches.
-q RTS option
-(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity,
-in the file <program>.qp. In the style of hbcpp, this profile
+(paraLLEL ONLY) Produce a quasi-parallel profile of thread activity,
+in the file <program>.qp. In the style of hbcpp, this profile
records the movement of threads between the green (runnable) and red
(blocked) queues. If you specify the verbose suboption (), the
green queue is split into green (for the currently running thread
only) and amber (for other runnable threads). We do not recommend
that you use the verbose suboption if you are planning to use the
-hbcpp profiling tools or if you are context switching at every heap
-check (with ).
+hbcpp profiling tools or if you are context switching at every heap
+check (with ).
-->
-
-
-
-
-:
-
-
--qt<num> RTS option
-(PARALLEL ONLY) Limit the thread pool size, i.e. the number of concurrent
-threads per processor to <num>. The default is
-32. Each thread requires slightly over 1K words in
+
+
+
+
+:
+
+
+-qt<num> RTS option
+(paraLLEL ONLY) Limit the thread pool size, i.e. the number of concurrent
+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
translates to 4K bytes, and for 64-bit machines, 8K bytes.)
-
-
-
+
+
+
-
-:
-
-
--qe<num> RTS option
-(parallel) (PARALLEL ONLY) Limit the spark pool size
+
+:
+
+
+-qe<num> RTS option
+(parallel) (paraLLEL ONLY) Limit the spark pool size
i.e. the number of pending sparks per processor to
-<num>. The default is 100. A larger number may be
+<num>. The default is 100. A larger number may be
appropriate if your program generates large amounts of parallelism
initially.
-
-
-
-
-:
-
-
--qQ<num> RTS option (parallel)
-(PARALLEL ONLY) Set the size of packets transmitted between processors
-to <num>. The default is 1024 words. A larger number may be
+
+
+
+
+:
+
+
+-qQ<num> RTS option (parallel)
+(paraLLEL ONLY) Set the size of packets transmitted between processors
+to <num>. The default is 1024 words. A larger number may be
appropriate if your machine has a high communication cost relative to
computation speed.
-
-
-
-
-:
-
-
--qh<num> RTS option (parallel)
-(PARALLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to
+
+
+
+
+:
+
+
+-qh<num> RTS option (parallel)
+(paraLLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to
<num>-1 (0 means infinity). By default GUM uses full-subgraph
packing, i.e. the entire subgraph with the requested closure as root is
transmitted (provided it fits into one packet). Choosing a smaller value
reduces the amount of pre-fetching of work done in GUM. This can be
advantageous for improving data locality but it can also worsen the balance
of the load in the system.
-
-
-
-
-:
-
-
--qg<num> RTS option
-(parallel) (PARALLEL ONLY) Select a globalisation
+
+
+
+
+:
+
+
+-qg<num> RTS option
+(parallel) (paraLLEL ONLY) Select a globalisation
scheme. This option affects the
generation of global addresses when transferring data. Global addresses are
globally unique identifiers required to maintain sharing in the distributed
@@ -1636,15 +1636,15 @@ is transmitted. With <num>=1 a thunk-only globalisation scheme is
used, which generated global address only for thunks. The latter case may
lose sharing of data but has a reduced overhead in packing graph structures
and maintaining internal tables of global addresses.
-
-
-
-
+
+
+
+
-
+Platform-specific Flags
@@ -1680,11 +1680,11 @@ and maintaining internal tables of global addresses.
compiling some modules with four stolen registers, it will
crash, probably saying:
-
+
Foo.hc:533: fixed or forbidden register was spilled.
This may be due to a compiler bug or to impossible asm
statements or clauses.
-
+
Just give some registers back with
. Try `3' first, then `2'.
@@ -1705,18 +1705,18 @@ 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. Core files, which are given the suffix
.hcr, can be read and processed by non-GHC back-end
- tools. The Core format is formally described in An External Representation for the GHC Core Language,
and sample tools (in Haskell)
for manipulating Core files are available in the GHC source distribution
directory /fptools/ghc/utils/ext-core.
Note that the format of .hcr
files is different (though similar) to the Core output format generated
- for debugging purposes ().
+ for debugging purposes ().
The Core format natively supports notes which you can add to
your source code using the CORE pragma (see ).
+ linkend="pragmas"/>).
@@ -1741,7 +1741,7 @@ ordinary Haskell 98, when translated to External Core, uses things like rank-2 t
&debug;
&flags;
-
+