X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=2fe5959b594998abddee6758b0732e976912dbe6;hb=6a05ec5ef5373f61b7f9f5bdc344483417fa801b;hp=8cbcd35fca6cb6f6dcf01dbb8865bcaa9dc42ea1;hpb=0065d5ab628975892cea1ec7303f968c3338cbe1;p=ghc-hetmet.git diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index 8cbcd35..2fe5959 100644 --- a/docs/users_guide/using.xml +++ b/docs/users_guide/using.xml @@ -14,7 +14,7 @@ Options can be specified in three ways: - command-line arguments + Command-line arguments structure, command-line command-linearguments @@ -26,9 +26,9 @@ 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 @@ -40,7 +40,7 @@ ghc [argument...] - command line options in source files + Command line options in source files source-file options @@ -73,15 +73,14 @@ module X where maintains internally, so you'll be desperately disappointed if you try to glob etc. inside OPTIONS_GHC. - NOTE: the contents of OPTIONS_GHC are prepended to the - command-line options, so you do have the - ability to override OPTIONS_GHC settings via the command - line. + NOTE: the contents of OPTIONS_GHC are appended to the + command-line options, so options given in the source file + override those given on 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_GHC pragma is the Right Thing. (If you - use and have OPTION flags in + use and have OPTION flags in your module, the OPTIONS_GHC will get put into the generated .hc file). @@ -104,8 +103,8 @@ module X where modeoptions - Each of GHC's command line options is classified as either - static or dynamic or + Each of GHC's command line options is classified as + static, dynamic or mode: @@ -113,7 +112,7 @@ module X where Mode flags For example, or . - There may be only a single mode flag on the command line. The + There may only be a single mode flag on the command line. The available modes are listed in . @@ -138,6 +137,11 @@ module X where The flag reference tables () lists the status of each flag. + + There are a few flags that are static except that they can + also be used with GHCi's :set command; these + are listed as “static/:set” in the + table. @@ -225,8 +229,7 @@ module X where - ghc - ––interactive + ghc --interactive interactive mode ghci @@ -240,8 +243,7 @@ module X where - ghc - ––make + ghc --make make mode @@ -258,8 +260,8 @@ module X where - ghc - –e expr + ghc -e + expr eval mode @@ -275,13 +277,10 @@ module X where - ghc - - -E - -C - -S - -c - + ghc -E + ghc -c + ghc -S + ghc -c @@ -302,8 +301,7 @@ module X where - ghc - –M + ghc -M dependency-generation mode @@ -311,23 +309,119 @@ module X where Dependency-generation mode. In this mode, GHC can be used to generate dependency information suitable for use in a Makefile. See . + linkend="makefile-dependencies"/>. - ghc - ––mk-dll + ghc --mk-dll - dependency-generation mode + DLL-creation mode DLL-creation mode (Windows only). See . + + + + + ghc --help ghc -? + + + + + Cause GHC to spew a long usage message to standard + output and then exit. + + + + + + + ghc --supported-languages + + + + + Print the supported language extensions. + + + + + + + ghc --info + + + + + Print information about the compiler. + + + + + + + ghc --version + ghc -V + + + + + + Print a one-line string including GHC's version number. + + + + + + + ghc --numeric-version + + + + + Print GHC's numeric version number only. + + + + + + + ghc --print-libdir + + + + + Print the path to GHC's library directory. This is + the top of the directory tree containing GHC's libraries, + interfaces, and include files (usually something like + /usr/local/lib/ghc-5.04 on Unix). This + is the value of + $libdirlibdir + in the package configuration file + (see ). + + + + + + + ghc --print-docdir + + + + + Print the path to GHC's documentation directory. Note that + some distributions do no include the documentation, in which case + this directory may be empty or may not exist. + + + @@ -337,7 +431,7 @@ module X where When given the option, GHC will build a multi-module Haskell program by following - dependencies from a single root module (usually + dependencies from one or more root modules (usually just Main). For example, if your Main module is in a file called Main.hs, you could compile and link the @@ -351,7 +445,7 @@ ghc ––make Main.hs names or module names; GHC will figure out all the modules in the program by following the imports from these initial modules. It will then attempt to compile each module which is out of - date, and finally if there is a Main module, + date, and finally, if there is a Main module, the program will also be linked into an executable. The main advantages to using ghc @@ -446,7 +540,7 @@ olleh The first phase to run is determined by each input-file suffix, and the last phase is determined by a flag. If no - relevant flag is present, then go all the way through linking. + relevant flag is present, then go all the way through to linking. This table summarises: @@ -538,9 +632,7 @@ ghc -c Foo.hs 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. + of the compiler, dumping the result in a file. Overriding the default behaviour for a file @@ -574,19 +666,18 @@ ghc -c Foo.hs help options verbosity options + See also the , , , + and modes in . - - - - - - + + - Cause GHC to spew a long usage message to standard - output and then exit. + Does a dry-run, i.e. GHC goes through all the motions + of compiling as normal, but does not actually run any + external commands. @@ -673,47 +764,6 @@ ghc -c Foo.hs - - - - - - - - - - Print a one-line string including GHC's version number. - - - - - - - - - - Print GHC's numeric version number only. - - - - - - - - - - Print the path to GHC's library directory. This is - the top of the directory tree containing GHC's libraries, - interfaces, and include files (usually something like - /usr/local/lib/ghc-5.04 on Unix). This - is the value of - $libdirlibdir - in the package configuration file (see ). - - - - @@ -748,6 +798,20 @@ ghc -c Foo.hs + size + + + + Set the minimum size of the heap to + size. + This option is equivalent to + +RTS -Hsize, + see . + + + + + @@ -792,26 +856,35 @@ ghc -c Foo.hs -W option Provides the standard warnings plus , + , , - , - , and + , and . - : + : - - Turns off all warnings, including the standard ones. + + Turns on all warning options that indicate potentially + suspicious code. The warnings that are + not enabled by + are + , + , + , + , and + . - : + : - - Turns on all warning options. + + Turns off all warnings, including the standard ones and + those that -Wall doesn't enable. @@ -824,6 +897,16 @@ ghc -c Foo.hs + + : + + + Warnings are treated only as warnings, not as errors. This is + the default, but can be useful to negate a + flag. + + + The full set of warning options is described below. To turn @@ -842,6 +925,20 @@ ghc -c Foo.hs function or type is used. Entities can be marked as deprecated using a pragma, see . + + This option is on by default. + + + + + : + + + + Causes a warning to be emitted when a a datatype + T is imported + with all constructors, i.e. T(..), but has been + exported abstractly, i.e. T. @@ -877,6 +974,31 @@ ghc -c Foo.hs + : + + + implicit prelude, warning + Have the compiler warn if the Prelude is implicitly + imported. This happens unless either the Prelude module is + explicitly imported with an import ... Prelude ... + line, or this implicit import is disabled (either by + or a + LANGUAGE NoImplicitPrelude pragma). + + Note that no warning is given for syntax that implicitly + refers to the Prelude, even if + would change whether it refers to the Prelude. + For example, no warning is given when + 368 means + Prelude.fromInteger (368::Prelude.Integer) + (where Prelude refers to the actual Prelude module, + regardless of the imports of the module being compiled). + + This warning is off by default. + + + + : @@ -893,7 +1015,7 @@ ghc -c Foo.hs g [] = 2 - This option isn't enabled be default because it can be + This option isn't enabled by default because it can be a bit noisy, and it doesn't always indicate a bug in the program. However, it's generally considered good practice to cover all the cases in your functions. @@ -921,7 +1043,7 @@ f :: Foo -> Foo f foo = foo { x = 6 } - This option isn't enabled be default because it can be + This option isn't enabled by default because it can be very noisy, and it often doesn't indicate a bug in the program. @@ -929,19 +1051,6 @@ f foo = foo { x = 6 } - : - - - - 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. - - - - - : missing fields, warning @@ -991,7 +1100,8 @@ f foo = foo { x = 6 } If you would like GHC to check that every top-level function/value has a type signature, use the - option. This + option. As part of + the warning GHC also reports the inferred type. The option is off by default. @@ -1006,12 +1116,8 @@ f foo = foo { x = 6 } inner-scope value has the same name as an outer-scope value, i.e. the inner value shadows the outer one. This can catch typographical errors that turn into hard-to-find bugs, e.g., - in the inadvertent cyclic definition let x = ... x - ... in. - - Consequently, this option does - will complain about cyclic recursive - definitions. + in the inadvertent capture of what would be a recursive call in + f = ... let f = id in ... f .... @@ -1045,7 +1151,7 @@ f foo = foo { x = 6 } By default, the compiler will warn you if a set of - patterns are overlapping, i.e., + patterns are overlapping, e.g., f :: String -> Int @@ -1070,7 +1176,7 @@ f "2" = 2 patterns that can fail, eg. \(x:xs)->.... Normally, these aren't treated as incomplete patterns by . - ``Lambda-bound patterns'' includes all places where there is a single pattern, + “Lambda-bound patterns” includes all places where there is a single pattern, including list comprehensions and do-notation. In these cases, a pattern-match failure is quite legitimate, and triggers filtering (list comprehensions) or the monad fail operation (monads). For example: @@ -1080,10 +1186,18 @@ f "2" = 2 Switching on will elicit warnings about these probably-innocent cases, which is why the flag is off by default. - The deriving( Read ) mechanism produces monadic code with - pattern matches, so you will also get misleading warnings about the compiler-generated - code. (This is arguably a Bad Thing, but it's awkward to fix.) + + + + + : + + + tabs, warning + Have the compiler warn if there are tabs in your source + file. + This warning is off by default. @@ -1096,7 +1210,7 @@ f "2" = 2 the Haskell defaulting mechanism for numeric types kicks 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 + e.g., the ‘default default’ for Haskell 1.4 caused the otherwise unconstrained value 1 to be given the type Int, whereas Haskell 98 defaults it to Integer. This may lead to @@ -1108,6 +1222,20 @@ f "2" = 2 + : + + + monomorphism restriction, warning + Have the compiler warn/inform you where in your source + the Haskell Monomorphism Restriction is applied. If applied silently + the MR can give rise to unexpected behaviour, so it can be helpful + to have an explicit warning that it is being applied. + + This warning is off by default. + + + + : @@ -1199,7 +1327,7 @@ f "2" = 2 Note that higher optimisation levels cause more cross-module optimisation to be performed, which can have an impact on how much of your program needs to be recompiled when - you change something. This is one reaosn to stick to + you change something. This is one reason to stick to no-optimisation when developing code. @@ -1243,10 +1371,6 @@ f "2" = 2 Means: “Generate good-quality code without taking too long about it.” Thus, for example: ghc -c -O Main.lhs - - currently also implies - . This may change in the - future. @@ -1345,7 +1469,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="assertions"/>). This flag is turned on by . @@ -1383,6 +1507,30 @@ f "2" = 2 Turns off the full laziness optimisation (also known as let-floating). Full laziness increases sharing, which can lead to increased memory residency. + + NOTE: GHC doesn't implement complete full-laziness. + When optimisation in on, and + is not given, some + transformations that increase sharing are performed, such + as extracting repeated computations from a loop. These + are the same transformations that a fully lazy + implementation would do, the difference is that GHC + doesn't consistently apply full-laziness, so don't rely on + it. + + + + + + + + + + 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. @@ -1402,6 +1550,36 @@ f "2" = 2 + + + + + Tells GHC to omit all inessential information from the interface file + generated for the module being compiled (say M). This means that a module + importing M will see only the types of the functions that M exports, but not + their unfoldings, strictness info, etc. Hence, for example, + no function exported by M will be inlined + into an importing module. The benefit is that modules that import M will + need to be recompiled less often (only when M's exports change their type, + not when they change their implementation). + + + + + + + + + + + Tells GHC to ignore all inessential information when reading interface files. + That is, even if M.hi contains unfolding or strictness information + for a function, GHC will ignore that information. + + + + + : strict constructor fields @@ -1424,7 +1602,7 @@ f "2" = 2 - + @@ -1442,7 +1620,7 @@ f "2" = 2 - : + : inlining, controlling unfolding, controlling @@ -1468,7 +1646,7 @@ f "2" = 2 - : + inlining, controlling @@ -1490,7 +1668,7 @@ f "2" = 2 &phases; - + Using Concurrent Haskell Concurrent Haskellusing @@ -1514,362 +1692,92 @@ f "2" = 2 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. + switches occur every 20ms. - -Using parallel Haskell - - -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.] - - - -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 -Control.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 -“processors” your program to run on. (For more details of -all relevant RTS options, please see .) - - - -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 - - -PVM, how to 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 -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 -machine. You can then do various things to control/monitor your -“parallel machine;” the most useful being: - - - - - - - - - -ControlD -exit pvm, leaving it running - - - -halt -kill off this “parallel machine” & exit - - - -add <host> -add <host> as a processor - - - -delete <host> -delete <host> - - - -reset -kill what's going, but leave PVM up - - - -conf -list the current configuration - - - -ps -report processes' status - - - -pstat <pid> -status of a particular process - - - - - - - - -The PVM documentation can tell you much, much more about pvm! - - - - - -parallelism profiles - - -parallelism profiles -profiles, parallelism -visualisation tools - - - -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 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 -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! - + + Using SMP parallelism + parallelism + + SMP + - - - -The scripts for processing the parallelism profiles are distributed -in ghc/utils/parallel/. - - - - - -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 -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. - - - -Whether doing or not, a handy way to watch -what's happening overall is: tail -f /tmp/pvml.nnn. - - - - - -RTS options for Parallel Haskell - - - -RTS options, parallel -parallel Haskell—RTS options - - - -Besides the usual runtime system (RTS) options -(), there are a few options particularly -for parallel execution. - - - - - - -: - - --qp<N> RTS option -(paraLLEL ONLY) Use <N> PVM processors to run this program; -the default is 2. - - - - -: - - --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. 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. - - - - -: - - --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 -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 ). ---> - - - - -: - - --qt<num> RTS option -(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 -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 -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. - - - - - - - + GHC supports running Haskell programs in parallel on an SMP + (symmetric multiprocessor). + + There's a fine distinction between + concurrency and parallelism: + parallelism is all about making your program run + faster by making use of multiple processors + simultaneously. Concurrency, on the other hand, is a means of + abstraction: it is a convenient way to structure a program that must + respond to multiple asynchronous events. + + However, the two terms are certainly related. By making use of + multiple CPUs it is possible to run concurrent threads in parallel, + and this is exactly what GHC's SMP parallelism support does. But it + is also possible to obtain performance improvements with parallelism + on programs that do not use concurrency. This section describes how to + use GHC to compile and run parallel programs, in we desribe the language features that affect + parallelism. + + + Options to enable SMP parallelism - + In 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: + + + + + + RTS option + Use x simultaneous threads when + running the program. Normally x + should be chosen to match the number of CPU cores on the machine. + There is no means (currently) by which this value may vary after + the program has started. + + For example, on a dual-core machine we would probably use + +RTS -N2 -RTS. + + Whether hyperthreading cores should be counted or not is an + open question; please feel free to experiment and let us know what + results you find. + + + + + + + Hints for using SMP parallelism + + Add the -sstderr RTS option when + running the program to see timing stats, which will help to tell you + whether your program got faster by using more CPUs or not. If the user + time is greater than + the elapsed time, then the program used more than one CPU. You should + also run the program without -N for comparison. + + GHC's parallelism support is new and experimental. It may make your + program go faster, or it might slow it down - either way, we'd be + interested to hear from you. + + One significant limitation with the current implementation is that + the garbage collector is still single-threaded, and all execution must + stop when GC takes place. This can be a significant bottleneck in a + parallel program, especially if your program does a lot of GC. If this + happens to you, then try reducing the cost of GC by tweaking the GC + settings (): enlarging the heap or the + allocation area size is a good start. + + Platform-specific Flags @@ -1884,18 +1792,6 @@ and maintaining internal tables of global addresses. - : - - (SPARC machines)-mv8 option (SPARC - 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 - similar GCC options for SPARC also - work, actually. - - - - : (iX86 machines)-monly-N-regs