X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fusing.sgml;h=184c02dac8e5daba95630919e12dfc5e4c64f4a4;hb=136e0eeecfc5b1d6574d38977a1e52f106c442f7;hp=a5a691ba875afd95e341fab5a2783fee4a39ccf0;hpb=ecaf93533a3d2d82b2665ed776a387334804ecdd;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index a5a691b..184c02d 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -581,31 +581,64 @@ ghc --make Main.hs - -ohi - -ohi + file + + + + The interface output may be directed to another file + bar2/Wurble.iface with the option + (not + recommended). + + WARNING: if you redirect the interface file somewhere + that GHC can't find it, then the recompilation checker may + get confused (at the least, you won't get any recompilation + avoidance). We recommend using a combination of + and options + instead, if possible. + + To avoid generating an interface at all, you could use + this option to redirect the interface into the bit bucket: + -ohi /dev/null, for example. + + + + + directory + + - + Redirects all generated interface files into + directory, instead of the default + which is to place the interface file in the same directory + as the source file. - -osuf - -hisuf - -osuf - -hisuf + suffix + suffix + suffix + + + - EXOTICA: The -osuf - <suffix> option will change the - .o file suffix for object files to - whatever you specify. (We use this in compiling the - prelude.). - - Similarly, the -hisuf - <suffix> option will change the - .hi file suffix for non-system - interface files (see ). + EXOTICA: The + suffix will change the + .o file suffix for object files to + whatever you specify. We use this when compiling libraries, + so that objects for the profiling versions of the libraries + don't clobber the normal ones. + + Similarly, the + suffix will change the + .hi file suffix for non-system interface + files (see ). + + Finally, the option + suffix will change the + .hc file suffix for compiler-generated + intermediate C files. The / game is useful if you want to compile a program with both @@ -764,7 +797,8 @@ ghc --make Main.hs Provides the standard warnings plus , , - and + , + , and . @@ -772,7 +806,7 @@ ghc --make Main.hs : - -w option + Turns off all warnings, including the standard ones. @@ -780,7 +814,7 @@ ghc --make Main.hs : - -Wall option + Turns on all warning options. @@ -809,7 +843,7 @@ ghc --make Main.hs : - -fwarn-duplicate-exports option + duplicate exports, warning export lists, duplicates @@ -826,7 +860,7 @@ ghc --make Main.hs : - -fwarn-hi-shadowing option + shadowing interface files @@ -840,7 +874,7 @@ ghc --make Main.hs : - -fwarn-incomplete-patterns option + incomplete patterns, warning patterns, incomplete @@ -862,9 +896,20 @@ g [] = 2 + : + + + Turns on warnings for various harmless but untidy + things. This currently includes: importing a type with + (..) when the export is abstract, and + listing duplicate class assertions in a qualified type. + + + + : - -fwarn-missing-fields option + missing fields, warning fields, missing @@ -879,7 +924,7 @@ g [] = 2 : - -fwarn-missing-methods option + missing methods, warning methods, missing @@ -893,7 +938,7 @@ g [] = 2 : - -fwarn-missing-signatures option + type signatures, missing If you would like GHC to check that every top-level @@ -906,7 +951,7 @@ g [] = 2 : - -fwarn-name-shadowing option + shadowing, warning This option causes a warning to be emitted whenever an @@ -924,7 +969,7 @@ g [] = 2 : - -fwarn-overlapping-patterns option + overlapping patterns, warning patterns, overlapping @@ -960,7 +1005,7 @@ f "2" = 2 : - -fwarn-type-defaults option + defaulting mechanism, warning Have the compiler warn/inform you where in your source the Haskell defaulting mechanism for numeric types kicks @@ -980,7 +1025,7 @@ f "2" = 2 : - -fwarn-unused-binds option + unused binds, warning binds, unused Report any function definitions (and local bindings) @@ -992,7 +1037,7 @@ f "2" = 2 : - -fwarn-unused-imports option + unused imports, warning imports, unused @@ -1004,7 +1049,7 @@ f "2" = 2 : - -fwarn-unused-matches option + unused matches, warning matches, unused @@ -1020,10 +1065,11 @@ f "2" = 2 If you're feeling really paranoid, the - option-dcore-lint - option is a good choice. It turns on - heavyweight intra-pass sanity-checking within GHC. (It checks - GHC's sanity, not yours.) + + option + is a good choice. It turns on heavyweight intra-pass + sanity-checking within GHC. (It checks GHC's sanity, not + yours.) @@ -1196,6 +1242,20 @@ f "2" = 2 + : + + + Causes GHC to ignore uses of the function + Exception.assert in source code (in + other words, rewriting Exception.assert p + e to e (see ). This flag is turned on by + . + + + + + @@ -1305,9 +1365,10 @@ data S = S !Int !Int at a call site. A bigger function would be assigned a bigger cost.) - Consequences: (a) nothing larger than - this will be inlined (unless it has an INLINE pragma); (b) nothing larger - than this will be spewed into an interface file. + Consequences: (a) nothing larger than this will be + inlined (unless it has an INLINE pragma); (b) nothing + larger than this will be spewed into an interface + file. Increasing this figure is more likely to result in longer @@ -1377,21 +1438,21 @@ LinkEnd="sec-Concurrent">. [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 .) @@ -1403,8 +1464,8 @@ 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 @@ -1423,11 +1484,23 @@ setenv PVM_DPATH $PVM_ROOT/lib/pvmd Creating and/or controlling your “parallel machine” is a purely-PVM -business; nothing specific to Parallel Haskell. - +business; nothing specific to Parallel Haskell. The following paragraphs +describe how to configure your parallel machine interactively. + - -You use the pvmpvm command command to start PVM on your + +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 machine. You can then do various things to control/monitor your “parallel machine;” the most useful being: @@ -1489,8 +1562,8 @@ The PVM documentation can tell you much, much more about pvm! - -Parallelism profiles + +Parallelism profiles parallelism profiles @@ -1503,25 +1576,25 @@ 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 --q 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 -N8 -q -% 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! +$ ./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 @@ -1530,13 +1603,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. @@ -1569,12 +1642,12 @@ for concurrent/parallel execution. - -: - - --N<N> RTS option (parallel) -(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. @@ -1608,60 +1681,98 @@ records the movement of threads between the green (runnable) and red 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 ). - - - - -: - - --t<num> RTS option -(PARALLEL ONLY) Limit 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.) - - - - -: - - --d RTS option (parallel) +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 +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 +i.e. the number of pending sparks per processor to +<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 +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 +<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 +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 +graph structure. Currently this is a binary option. With <num>=0 full globalisation is used +(default). This means a global address is generated for every closure that +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. + + +