From: krasimir Date: Sun, 8 Aug 2004 17:26:47 +0000 (+0000) Subject: [project @ 2004-08-08 17:26:26 by krasimir] X-Git-Tag: Initial_conversion_from_CVS_complete~1765 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;ds=sidebyside;h=2dfd507259664e6f28df4a9467a8de34d01d70a0;p=ghc-hetmet.git [project @ 2004-08-08 17:26:26 by krasimir] xmlize sgml docbooks --- diff --git a/ghc/docs/users_guide/6.0-notes.sgml b/ghc/docs/users_guide/6.0-notes.sgml index 19c5585..1973bfc 100644 --- a/ghc/docs/users_guide/6.0-notes.sgml +++ b/ghc/docs/users_guide/6.0-notes.sgml @@ -7,7 +7,7 @@ Template Haskell, a new feature for compile-time metaprogramming has been introduced. See . + linkend="template-haskell"/>. INLINE pragmas on methods in class or instance @@ -15,7 +15,7 @@ Recursive do-notation (aka mdo) is - now supported. See . + now supported. See . There is now a native code generator for PowerPC @@ -24,7 +24,7 @@ Profiling: the RTS option enables inclusion of thread stacks in a heap profile. See . + linkend="rts-options-heap-prof"/>. Non-blocking I/O is now supported on Windows. @@ -55,7 +55,7 @@ Hierarchical libraries are now available without needing to specify an explicit flag. There are some exceptions to this rule (see ), but if you stick to GHCi and + linkend="using-packages"/>), but if you stick to GHCi and mode then there will normally be no need to specify options at all. diff --git a/ghc/docs/users_guide/bugs.sgml b/ghc/docs/users_guide/bugs.sgml index 311c2eb..5d7c0bb 100644 --- a/ghc/docs/users_guide/bugs.sgml +++ b/ghc/docs/users_guide/bugs.sgml @@ -1,4 +1,4 @@ - + Known bugs and infelicities @@ -10,7 +10,7 @@ This section lists Glasgow Haskell infelicities in its implementation of Haskell 98. See also the “when things - go wrong” section () for information + go wrong” section () for information about crashes, space leaks, and other undesirable phenomena. The limitations here are listed in Haskell Report order @@ -67,7 +67,7 @@ (let x = 42 in x == 42 == True) The Haskell report is arguably wrong here, but nevertheless - it's a difference between GHC & Haskell 98. + it's a difference between GHC & Haskell 98. @@ -256,7 +256,7 @@ checking for duplicates. The reason for this is efficiency, pure and simple. GHC can warn about non-exhaustive or overlapping - patterns (see ), and usually + patterns (see ), and usually does so correctly. But not always. It gets confused by string patterns, and by guards, and can then emit bogus warnings. The entire overlap-check code needs an overhaul diff --git a/ghc/docs/users_guide/debugging.sgml b/ghc/docs/users_guide/debugging.sgml index 308a5f5..340d7d8 100644 --- a/ghc/docs/users_guide/debugging.sgml +++ b/ghc/docs/users_guide/debugging.sgml @@ -5,7 +5,7 @@ HACKER TERRITORY. HACKER TERRITORY. (You were warned.) - + Dumping out compiler intermediate structures dumping GHC intermediates @@ -246,9 +246,9 @@ STG-to-STG passes, respectively. (Lots of output!) So: when we're really desperate: - + % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs - + @@ -384,9 +384,9 @@ Let's do this by commenting an example. It's from doing on this code: - + skip2 m = m : skip2 (m+2) - + Before we jump in, a word about names of things. Within GHC, variables, type constructors, etc., are identified by their @@ -403,7 +403,7 @@ skip2 m = m : skip2 (m+2) usually printed out when debugging, in some form or another. So here we go… - + Desugared: Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4] @@ -473,7 +473,7 @@ Main.skip2{-r1L6-} = {- end CoRec -} } in skip2.t3Ja - + (“It's just a simple functional language” is an unregisterised trademark of Peyton Jones Enterprises, plc.) @@ -512,7 +512,7 @@ Main.skip2{-r1L6-} = - + - -Foreign function interface (FFI) + +Foreign function interface (FFI) GHC (mostly) conforms to the Haskell 98 Foreign Function Interface - Addendum 1.0, whose definition is available from http://haskell.org/. + Addendum 1.0, whose definition is available from http://haskell.org/. The FFI support in GHC diverges from the Addendum in the following ways: @@ -18,7 +18,7 @@ GHC implements a number of GHC-specific extensions to the FFI Addendum. These extensions are described in , but please note that programs using + linkend="sec-ffi-ghcexts"/>, but please note that programs using these features are not portable. Hence, these features should be avoided where possible. @@ -56,16 +56,15 @@ use of the foreign function interface in GHC. - Using <literal>foreign export</literal> and <literal>foreign - import ccall "wrapper"</literal> with GHC + Using <literal>foreign export</literal> and <literal>foreign import ccall "wrapper"</literal> with GHC foreign export with GHC When GHC compiles a module (say M.hs) - which uses foreign export or foreign - import "wrapper", it generates two + which uses foreign export or + foreign import "wrapper", it generates two additional files, M_stub.c and M_stub.h. GHC will automatically compile M_stub.c to generate @@ -136,7 +135,7 @@ int main(int argc, char *argv[]) hs_add_root(__stginit_Foo); #endif - for (i = 0; i < 5; i++) { + for (i = 0; i < 5; i++) { printf("%d\n", foo(2500)); } @@ -204,8 +203,7 @@ int main(int argc, char *argv[]) - Using <literal>foreign import ccall "wrapper"</literal> with - GHC + Using <literal>foreign import ccall "wrapper"</literal> with GHC foreign import ccall "wrapper"with GHC @@ -232,7 +230,7 @@ int main(int argc, char *argv[]) When generating C (using the directive), one can assist the C compiler in detecting type errors by using the directive - () to provide + () to provide .h files containing function headers. @@ -269,7 +267,7 @@ from another package, you won't necessarily know what the appropriate options are; but they should be in the package configuration, which GHC knows about. So if you are building a package, remember to put all those options into the package configuration. -See the c_includes field in . +See the c_includes field in . @@ -298,7 +296,7 @@ to be inlined across modules, use the command-line and package-configuration are searched for using the C compiler's usual search path. You can add directories to this search path using the option (see ). + linkend="c-pre-processor"/>). Note: header files are ignored unless compiling via C. If you had been compiling your code using the native code @@ -391,7 +389,7 @@ to be inlined across modules, use the command-line and package-configuration - + - + - + -The layout of installed files +The layout of installed files This section describes what files get installed where. You don't need to know it @@ -709,19 +710,19 @@ the implementation. Library directory, - known as $(libdir), holds all the + known as $(libdir), holds all the support files needed to run GHC. On Unix, this -directory is usually something like /usr/lib/ghc/ghc-5.02. +directory is usually something like /usr/lib/ghc/ghc-5.02. Binary directory - known as $(bindir), holds executables that + known as $(bindir), holds executables that the user is expected to invoke. Notably, it contains -ghc and ghci. On Unix, this directory -can be anywhere, but is typically something like /usr/local/bin. On Windows, -however, this directory must be $(libdir)/bin. +ghc and ghci. On Unix, this directory +can be anywhere, but is typically something like /usr/local/bin. On Windows, +however, this directory must be $(libdir)/bin. @@ -734,7 +735,7 @@ It finds this out in one of two ways: -$(libdir) is passed to GHC using the flag. +$(libdir) is passed to GHC using the flag. On Unix (but not Windows), the installed ghc is just a one-line shell script that invokes the real GHC, passing a suitable flag. [All the user-supplied flags @@ -745,22 +746,22 @@ one wins.] On Windows (but not Unix), if no flag is given, GHC uses a system call to find the directory in which the running GHC executable lives, and derives -$(libdir) from that. [Unix lacks such a system call.] -That is why $(bindir) must be $(libdir)/bin. +$(libdir) from that. [Unix lacks such a system call.] +That is why $(bindir) must be $(libdir)/bin. The binary directory -The binary directory, $(bindir) contains user-visible +The binary directory, $(bindir) contains user-visible executables, notably ghc and ghci. You should add it to your $PATH On Unix, the user-invokable ghc invokes $(libdir)/ghc-version, passing a suitable flag to tell ghc-version where -$(libdir) is. +$(libdir) is. Similarly ghci, except the extra flag --interactive is passed. @@ -882,7 +883,7 @@ with the Win32 distribution of GHC. - + RTS options for profiling and Concurrent/Parallel Haskell - The RTS options related to profiling are described in ; and those for concurrent/parallel - stuff, in . + The RTS options related to profiling are described in ; and those for concurrent/parallel + stuff, in . - RTS options for hackers, debuggers, and over-interested souls @@ -408,8 +406,8 @@ be really useful, linked with suitable system libraries. Not a trivial undertaking: consult the installation guide on how to set things up for easy “ticky-ticky” - profiling. For more information, see . + profiling. For more information, see . @@ -441,7 +439,7 @@ each cci is a cost centre in the program (see ), and the sequence represents the + linkend="cost-centres"/>), and the sequence represents the “call stack” at the point the exception was raised. The leftmost item is the innermost function in the call stack, and the rightmost item is the outermost @@ -511,7 +509,7 @@ char *ghc_rts_opts = "-H128m -K1m"; void OutOfHeapHook (unsigned long, unsigned long) OutOfHeapHook - + The heap-overflow message. @@ -528,7 +526,7 @@ char *ghc_rts_opts = "-H128m -K1m"; void MallocFailHook (long int) MallocFailHook - The message printed if malloc + The message printed if malloc fails. diff --git a/ghc/docs/users_guide/separate_compilation.sgml b/ghc/docs/users_guide/separate_compilation.sgml index 6595b88..e1052bd 100644 --- a/ghc/docs/users_guide/separate_compilation.sgml +++ b/ghc/docs/users_guide/separate_compilation.sgml @@ -11,7 +11,7 @@ Note that this section is written with hierarchical modules in mind (see ); hierarchical modules are an + linkend="hierarchical-modules"/>); hierarchical modules are an extension to Haskell 98 which extends the lexical syntax of module names to include a dot ‘.’. Non-hierarchical modules are thus a special case in which none of the module names @@ -38,7 +38,7 @@ should be placed in the file A/B/C.hs, relative to some base directory. GHC's behaviour if this rule is not followed is fully defined by the following section (). + linkend="output-files"/>). @@ -64,7 +64,7 @@ types of exported functions, definitions of data types, and so on. It is stored in a binary format, so don't try to read one; use the option instead (see ). + linkend="hi-options"/>). You should think of the object file and the interface file as a pair, since the interface file is in a sense a compiler-readable @@ -121,7 +121,7 @@ For any module that is imported, GHC requires that the name of the module in the import statement exactly matches the name of the module in the interface file (or source file) found - using the strategy specified in . + using the strategy specified in . This means that for most modules, the source file name should match the module name. @@ -203,7 +203,7 @@ This isn't the whole story: GHC also looks for modules in pre-compiled libraries, known as packages. See the section on - packages (), for details. + packages (), for details. @@ -260,9 +260,9 @@ Redirects object files to directory dir. For example: - + $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` - + The object files, Foo.o, Bar.o, and @@ -335,7 +335,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` Similarly, the suffix will change the .hi file suffix for non-system - interface files (see ). + interface files (see ). Finally, the option suffix will change the @@ -346,11 +346,11 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` game is particularly useful if you want to compile a program both with and without profiling, in the same directory. You can say: - - ghc ... + + ghc ... to get the ordinary version, and - - ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all + + ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all to get the profiled version. @@ -423,7 +423,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` Instructs the GHC driver not to delete any of its temporary files, which it normally keeps in /tmp (or possibly elsewhere; see ). Running GHC with + linkend="temp-files"/>). Running GHC with will show you what temporary files were generated along the way. @@ -448,30 +448,30 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` in /tmp (or wherever your installation thinks temporary files should go), you may use the -tmpdir - <dir> option option to specify + <dir>-tmpdir + <dir> option option to specify an alternate directory. For example, says to put temporary files in the current working directory. - Alternatively, use your TMPDIR - environment variable.TMPDIR - environment variable Set it to the + Alternatively, use your TMPDIR + environment variable.TMPDIR + environment variable Set it to the name of the directory where temporary files should be put. GCC and other programs will honour the - TMPDIR variable as well. + TMPDIR variable as well. Even better idea: Set the - DEFAULT_TMPDIR make variable when + DEFAULT_TMPDIR make variable when building GHC, and never worry about - TMPDIR again. (see the build + TMPDIR again. (see the build documentation). - + Other options related to interface files interface files, options @@ -589,8 +589,8 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` required”. What a beautiful sight! Patrick Sansom had a workshop paper about how all this is - done (though the details have changed quite a bit). Ask him if you want a + done (though the details have changed quite a bit). Ask him if you want a copy. @@ -604,7 +604,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` Makefile to use with GHC, assuming you name your source files the same as your modules. Thus: - + HC = ghc HC_OPTS = -cpp $(EXTRA_HC_OPTS) @@ -630,17 +630,17 @@ cool_pgm : $(OBJS) # Inter-module dependencies Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz - + (Sophisticated make variants may achieve some of the above more elegantly. Notably, gmake's pattern rules let you write the more comprehensible: - + %.o : %.lhs $(HC) -c $< $(HC_OPTS) - + What we've shown should work with any make.) @@ -654,9 +654,9 @@ Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz Note the inter-module dependencies at the end of the Makefile, which take the form - + Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz - + They tell make that if any of Foo.o, Foo.hc or @@ -677,10 +677,10 @@ Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz automatically generating the required dependencies. Add the following to your Makefile: - + depend : ghc -M $(HC_OPTS) $(SRCS) - + Now, before you start compiling, and any time you change the imports in your program, do @@ -716,7 +716,7 @@ import {-# SOURCE #-} B ...blah... A.o : B.hi-boot - (See for details of + (See for details of hi-boot style interface files.) If A imports multiple modules, then there will be multiple lines with A.o as the @@ -873,7 +873,7 @@ ghc -M -optdep-f -optdep.depend ... Currently, the compiler does not have proper support for dealing with mutually recursive modules: - + module A where import B @@ -891,7 +891,7 @@ data TB = MkTB !Int g :: TA -> TB g (MkTA x) = MkTB x - + When compiling either module A and B, the compiler will try (in vain) to look for the interface file of the other. So, @@ -906,9 +906,9 @@ g (MkTA x) = MkTB x files importing, hi-boot files - + import {-# SOURCE #-} A - + The hand-written interface need only contain the bare minimum of information needed to get the bootstrapping process @@ -920,10 +920,10 @@ import {-# SOURCE #-} A For the example at hand, the boot interface file for A would look like the following: - + module A where newtype TA = MkTA GHC.Base.Int - + The syntax is similar to a normal Haskell source file, but with some important differences: @@ -956,12 +956,12 @@ newtype GHC.IOBase.IO a For data or newtype declaration, you may omit all the constructors, by omitting the '=' and everything that follows it: - + module A where data TA - + In a source program - this would declare TA to have no constructors (a GHC extension: see ), + this would declare TA to have no constructors (a GHC extension: see ), but in an hi-boot file it means "I don't know or care what the construtors are". This is the most common form of data type declaration, because it's easy to get right. @@ -976,7 +976,7 @@ module A where Regardless of whether you write the constructors, you must write all the type parameters, including their kinds - if they are not '*'. (You can give explicit kinds in source files too (), + if they are not '*'. (You can give explicit kinds in source files too (), but you must do so in hi-boot files.) @@ -987,8 +987,8 @@ operations. We could lift this restriction if it became tiresome. Notice that we only put the declaration for the newtype TA in the hi-boot file, - not the signature for f, since - f isn't used by B. + not the signature for f, since + f isn't used by B. @@ -1006,21 +1006,21 @@ be a disaster in practice, so GHC tries to be clever. In particular, if an instance declaration is in the same module as the definition of any type or class mentioned in the head of the instance declaration, then GHC has to visit that interface file anyway. Example: - + module A where instance C a => D (T a) where ... data T a = ... - + The instance declaration is only relevant if the type T is in use, and if so, GHC will have visited A's interface file to find T's definition. The only problem comes when a module contains an instance declaration and GHC has no other reason for visiting the module. Example: - + module Orphan where instance C a => D (T a) where ... class C a where ... - + Here, neither D nor T is declared in module Orphan. We call such modules ``orphan modules'', defined thus: diff --git a/ghc/docs/users_guide/sooner.sgml b/ghc/docs/users_guide/sooner.sgml index 1a24bf4..22af9a0 100644 --- a/ghc/docs/users_guide/sooner.sgml +++ b/ghc/docs/users_guide/sooner.sgml @@ -43,8 +43,8 @@ should go here! default), and you have lots of memory, try increasing the maximum with the -M<size> - option option, e.g.: ghc -c - -O -M1024m Foo.hs. + option option, e.g.: ghc -c + -O -M1024m Foo.hs. Increasing the default allocation area size used by the compiler's RTS might also help: use the @@ -61,16 +61,16 @@ should go here! As soon as GHC plus its “fellow citizens” (other processes on your machine) start using more than the - real memory on your machine, and the - machine starts “thrashing,” the party - is over. Compile times will be worse than + real memory on your machine, and the + machine starts “thrashing,” the party + is over. Compile times will be worse than terrible! Use something like the csh-builtin - time command to get a report on how many + time command to get a report on how many page faults you're getting. If you don't know what virtual memory, thrashing, and page faults are, or you don't know the memory configuration - of your machine, don't try to be clever + of your machine, don't try to be clever about memory use: you'll just make your life a misery (and for other people, too, probably). @@ -84,14 +84,14 @@ should go here! to/from a remote filesystem. It would be quite sensible to - compile on a fast machine using - remotely-mounted disks; then link on a + compile on a fast machine using + remotely-mounted disks; then link on a slow machine that had your disks directly mounted. - Don't derive/use Read unnecessarily: + Don't derive/use Read unnecessarily: It's ugly and slow. @@ -135,7 +135,7 @@ should go here! import Foo (...stuff I want...) You can get GHC to tell you the minimal set of required imports by using the option - (see ). + (see ). Truthfully, the reduction on compilation time will be very small. However, judicious use of @@ -154,20 +154,20 @@ should go here! The key tool to use in making your Haskell program run faster are GHC's profiling facilities, described separately in - . There is no - substitute for finding where your program's time/space - is really going, as opposed to where you + . There is no + substitute for finding where your program's time/space + is really going, as opposed to where you imagine it is going. Another point to bear in mind: By far the best way to - improve a program's performance dramatically + improve a program's performance dramatically is to use better algorithms. Once profiling has thrown the spotlight on the guilty time-consumer(s), it may be better to re-think your program than to try all the tweaks listed below. Another extremely efficient way to make your program snappy is to use library code that has been Seriously Tuned By Someone - Else. You might be able to write a better + Else. You might be able to write a better quicksort than the one in Data.List, but it will take you much longer than typing import Data.List. @@ -238,8 +238,8 @@ should go here! overloading, death to Specialize the overloading on key functions in - your program. See - and . + your program. See + and . @@ -250,7 +250,7 @@ should go here! files for overloaded type signatures. You can view interface files using the option (see ). + linkend="hi-options"/>). % ghc --show-iface Foo.hi | egrep '^[a-z].*::.*=>' @@ -335,17 +335,17 @@ f (Wibble x y) # ugly, and proud of it the third field in the pragma; it should say __S <string>. The <string> gives the strictness of - the function's arguments. L is lazy - (bad), S and E are - strict (good), P is - “primitive” (good), U(...) + the function's arguments. L is lazy + (bad), S and E are + strict (good), P is + “primitive” (good), U(...) is strict and “unpackable” (very good), and - A is absent (very good). + A is absent (very good). For an “unpackable” - U(...) argument, the info inside tells + U(...) argument, the info inside tells the strictness of its components. So, if the argument is a - pair, and it says U(AU(LSS)), that + pair, and it says U(AU(LSS)), that means “the first component of the pair isn't used; the second component is itself unpackable, with three components (lazy in the first, strict in the second \& @@ -364,7 +364,7 @@ f (Wibble x y) # ugly, and proud of it Placing INLINE pragmas on certain functions that are used a lot can have a dramatic effect. - See . + See . @@ -375,7 +375,7 @@ f (Wibble x y) # ugly, and proud of it module, GHC must assume that everything in that module will be exported. This has various pessimising effects. For example, if a bit of code is actually - unused (perhaps because of unfolding + unused (perhaps because of unfolding effects), GHC will not be able to throw it away, because it is exported and some other module may be relying on its existence. @@ -413,7 +413,7 @@ f (Wibble x y) # ugly, and proud of it It can also help in a third way: when used with (see ), a strict field can be unpacked or + linkend="options-f"/>), a strict field can be unpacked or unboxed in the constructor, and one or more levels of indirection may be removed. Unpacking only happens for single-constructor datatypes (Int is a @@ -433,9 +433,9 @@ f (Wibble x y) # ugly, and proud of it Use unboxed types (a GHC extension): - When you are really desperate for + When you are really desperate for speed, and you want to get right down to the “raw - bits.” Please see for + bits.” Please see for some information about using unboxed types. Before resorting to explicit unboxed types, try using @@ -452,7 +452,7 @@ f (Wibble x y) # ugly, and proud of it of massively-tuned library code, and the best thing is not to compete with it, but link with it. - describes the foreign function + describes the foreign function interface. @@ -474,7 +474,7 @@ f (Wibble x y) # ugly, and proud of it yourself with numerical errors. One time when Float might be a good - idea is if you have a lot of them, say + idea is if you have a lot of them, say a giant array of Floats. They take up half the space in the heap compared to Doubles. However, this isn't true on a @@ -506,8 +506,8 @@ f (Wibble x y) # ugly, and proud of it -M<size> RTS option or -A<size> - RTS option RTS options (see ). + RTS option RTS options (see ). This is especially important if your program uses a lot of mutable arrays of pointers or mutable variables @@ -524,7 +524,7 @@ f (Wibble x y) # ugly, and proud of it - + Smaller: producing a program that is smaller @@ -541,19 +541,19 @@ expressions. Give a option</primary></indexterm> option for the extreme case. (“Only unfoldings with zero cost should proceed.”) Warning: except in certain specialised cases (like Happy parsers) this is likely to actually -<Emphasis>increase</Emphasis> the size of your program, because unfolding +<emphasis>increase</emphasis> the size of your program, because unfolding generally enables extra simplifying optimisations to be performed. </para> <para> -Avoid <Function>Read</Function>. +Avoid <function>Read</function>. </para> <para> Use <literal>strip</literal> on your executables. </para> -</Sect1> +</sect1> <sect1 id="thriftier"> <title>Thriftier: producing a program that gobbles less heap space @@ -570,14 +570,14 @@ Use <literal>strip</literal> on your executables. with <option>+RTS -Sstderr</option>, and remove all doubt! (You'll see the heap usage get bigger and bigger…) [Hmmm…this might be even easier with the -<option>-G1</option> RTS option; so… <Command>./a.out +RTS --Sstderr -G1</Command>...] +<option>-G1</option> RTS option; so… <command>./a.out +RTS +-Sstderr -G1</command>...] <indexterm><primary>-G RTS option</primary></indexterm> <indexterm><primary>-Sstderr RTS option</primary></indexterm> </para> <para> -Once again, the profiling facilities (<XRef LinkEnd="profiling">) are +Once again, the profiling facilities (<xref linkend="profiling"/>) are the basic tool for demystifying the space behaviour of your program. </para> @@ -589,9 +589,9 @@ notes to itself about how to evaluate something, should it eventually be required). </para> -</Sect1> +</sect1> -</Chapter> +</chapter> <!-- Emacs stuff: ;;; Local Variables: *** diff --git a/ghc/docs/users_guide/ug-book.sgml b/ghc/docs/users_guide/ug-book.sgml index 9cdcbf5..90b4718 100644 --- a/ghc/docs/users_guide/ug-book.sgml +++ b/ghc/docs/users_guide/ug-book.sgml @@ -1,10 +1,10 @@ -<BookInfo> -<Title>The Glasgow Haskell Compiler User's Guide, Version 6.0 -The GHC Team -
-glasgow-haskell-{bugs,users}-request@haskell.org -
- + +The Glasgow Haskell Compiler User's Guide, Version 6.0 +The GHC Team +
+glasgow-haskell-{bugs,users}-request@haskell.org +
+ &license; &intro; diff --git a/ghc/docs/users_guide/users_guide.sgml b/ghc/docs/users_guide/users_guide.sgml index 41ef1f8..20022c7 100644 --- a/ghc/docs/users_guide/users_guide.sgml +++ b/ghc/docs/users_guide/users_guide.sgml @@ -3,7 +3,7 @@ %ug-ent; ]> - + &ug-book; 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; - +