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 arguments structure, command-line command-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 files source-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 GHCi Options 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 + ––interactive interactive 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 + ––make make 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 - –e expr + –e expr eval 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 + –M dependency-generation mode Dependency-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-dll dependency-generation mode DLL-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 $libdirlibdir in 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 option Provides 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 PVM PVM, 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 +ControlD exit 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 profiles parallelism 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 +<sect2 id="parallel-rts-opts"> +<title>RTS options for Concurrent/parallel Haskell RTS options, concurrent RTS options, parallel Concurrent 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; - +