From: rrt Date: Mon, 10 Jan 2000 14:52:23 +0000 (+0000) Subject: [project @ 2000-01-10 14:52:21 by rrt] X-Git-Tag: Approximately_9120_patches~5327 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=57ad929d509b5f1b5c5ad510eb2831163f2071fa;p=ghc-hetmet.git [project @ 2000-01-10 14:52:21 by rrt] Retagged s into , . Once you have data constructors with universally-quantified fields, or -constants such as runST that have rank-2 types, it isn't long +constants such as runST that have rank-2 types, it isn't long before you discover that you need more! Consider: @@ -1994,13 +1990,13 @@ before you discover that you need more! Consider: -mkTs is a fuction that constructs some values of type +mkTs is a fuction that constructs some values of type T, using some pieces passed to it. The trouble is that since f is a function argument, Haskell assumes that it is -monomorphic, so we'll get a type error when applying T1 to +monomorphic, so we'll get a type error when applying T1 to it. This is a rather silly example, but the problem really bites in practice. Lots of people trip over the fact that you can't make -"wrappers functions" for runST for exactly the same reason. +"wrappers functions" for runST for exactly the same reason. In short, it is impossible to build abstractions around functions with rank-2 types. @@ -2023,8 +2019,8 @@ constructors), thus: This type signature tells the compiler to attribute f with the polymorphic type (forall b. b -> b -> b) when type -checking the body of mkTs, so now the application of -T1 is fine. +checking the body of mkTs, so now the application of +T1 is fine. @@ -2042,10 +2038,10 @@ grammar: - rank2type ::= [forall tyvars .] [context =>] funty - funty ::= ([forall tyvars .] [context =>] ty) -> funty - | ty - ty ::= ...current Haskell monotype syntax... +rank2type ::= [forall tyvars .] [context =>] funty +funty ::= ([forall tyvars .] [context =>] ty) -> funty + | ty +ty ::= ...current Haskell monotype syntax... @@ -2060,12 +2056,12 @@ or at the top level of a function argument. There is a restriction on the definition of a function whose type signature is a rank-2 type: the polymorphic arguments must be matched on the left hand side of the "=" sign. You can't -define mkTs like this: +define mkTs like this: - mkTs :: (forall b. b -> b -> b) -> a -> [T a] - mkTs = \ f x y -> [T1 f x, T1 f y] +mkTs :: (forall b. b -> b -> b) -> a -> [T a] +mkTs = \ f x y -> [T1 f x, T1 f y] @@ -2092,7 +2088,7 @@ rank-2 types as applied to data constructors. The idea of using existential quantification in data type declarations was suggested by Laufer (I believe, thought doubtless someone will correct me), and implemented in Hope+. It's been in Lennart -Augustsson's hbc Haskell compiler for several years, and +Augustsson's hbc Haskell compiler for several years, and proved very useful. Here's the idea. Consider the declaration: @@ -2119,7 +2115,7 @@ The data type Foo has two constructors with types: -Notice that the type variable a in the type of MkFoo +Notice that the type variable a in the type of MkFoo does not appear in the data type itself, which is plain Foo. For example, the following expression is fine: @@ -2134,14 +2130,14 @@ For example, the following expression is fine: Here, (MkFoo 3 even) packages an integer with a function -even that maps an integer to Bool; and MkFoo 'c' -isUpper packages a character with a compatible function. These +even that maps an integer to Bool; and MkFoo 'c' +isUpper packages a character with a compatible function. These two things are each of type Foo and can be put in a list. What can we do with a value of type Foo?. In particular, -what happens when we pattern-match on MkFoo? +what happens when we pattern-match on MkFoo? @@ -2153,9 +2149,9 @@ what happens when we pattern-match on MkFoo? -Since all we know about val and fn is that they +Since all we know about val and fn is that they are compatible, the only (useful) thing we can do with them is to -apply fn to val to get a boolean. For example: +apply fn to val to get a boolean. For example: @@ -2180,7 +2176,7 @@ quite a bit of object-oriented-like programming this way. What has this to do with existential quantification? -Simply that MkFoo has the (nearly) isomorphic type +Simply that MkFoo has the (nearly) isomorphic type @@ -2203,15 +2199,15 @@ adding a new existential quantification construct. Type classes -An easy extension (implemented in hbc) is to allow +An easy extension (implemented in hbc) is to allow arbitrary contexts before the constructor. For example: - data Baz = forall a. Eq a => Baz1 a a - | forall b. Show b => Baz2 b (b -> b) +data Baz = forall a. Eq a => Baz1 a a + | forall b. Show b => Baz2 b (b -> b) @@ -2223,15 +2219,15 @@ The two constructors have the types you'd expect: - Baz1 :: forall a. Eq a => a -> a -> Baz - Baz2 :: forall b. Show b => b -> (b -> b) -> Baz +Baz1 :: forall a. Eq a => a -> a -> Baz +Baz2 :: forall b. Show b => b -> (b -> b) -> Baz -But when pattern matching on Baz1 the matched values can be compared -for equality, and when pattern matching on Baz2 the first matched +But when pattern matching on Baz1 the matched values can be compared +for equality, and when pattern matching on Baz2 the first matched value can be converted to a string (as well as applying the function to it). So this program is legal: @@ -2249,7 +2245,7 @@ So this program is legal: Operationally, in a dictionary-passing implementation, the -constructors Baz1 and Baz2 must store the +constructors Baz1 and Baz2 must store the dictionaries for Eq and Show respectively, and extract it on pattern matching. @@ -2282,13 +2278,13 @@ the pattern match. For example, these fragments are incorrect: - f1 (MkFoo a f) = a +f1 (MkFoo a f) = a -Here, the type bound by MkFoo "escapes", because a -is the result of f1. One way to see why this is wrong is to -ask what type f1 has: +Here, the type bound by MkFoo "escapes", because a +is the result of f1. One way to see why this is wrong is to +ask what type f1 has: @@ -2315,7 +2311,7 @@ The original program is just plain wrong. Here's another sort of error It's ok to say a==b or p==q, but a==q is wrong because it equates the two distinct types arising -from the two Baz1 constructors. +from the two Baz1 constructors. @@ -2383,18 +2379,18 @@ data type with existentially quantified data constructors. Reason: in most cases it would not make sense. For example:# - data T = forall a. MkT [a] deriving( Eq ) +data T = forall a. MkT [a] deriving( Eq ) To derive Eq in the standard way we would need to have equality -between the single component of two MkT constructors: +between the single component of two MkT constructors: - instance Eq T where - (MkT a) == (MkT b) = ??? +instance Eq T where + (MkT a) == (MkT b) = ??? -But a and b have distinct types, and so can't be compared. +But a and b have distinct types, and so can't be compared. It's just about possible to imagine examples in which the derived instance would make sense, but it seems altogether simpler simply to prohibit such declarations. Define your own instances! @@ -2435,15 +2431,15 @@ an assertion failed, but which and where? -One way out is to define an extended assert function which also +One way out is to define an extended assert function which also takes a descriptive string to include in the error message and perhaps combine this with the use of a pre-processor which inserts -the source location where assert was used. +the source location where assert was used. Ghc offers a helping hand here, doing all of this for you. For every -use of assert in the user's source: +use of assert in the user's source: @@ -2470,14 +2466,14 @@ assert pred val ==> assertError "Main.hs|15" pred val The rewrite is only performed by the compiler when it spots -applications of Exception.assert, so you can still define and -use your own versions of assert, should you so wish. If not, -import Exception to make use assert in your code. +applications of Exception.assert, so you can still define and +use your own versions of assert, should you so wish. If not, +import Exception to make use assert in your code. To have the compiler ignore uses of assert, use the compiler option --fignore-asserts. -fignore-asserts option That is, +. -fignore-asserts option That is, expressions of the form assert pred e will be rewritten to e. @@ -2509,21 +2505,21 @@ f (xs::[a]) = ys ++ ys -The pattern (xs::[a]) includes a type signature for xs. +The pattern (xs::[a]) includes a type signature for xs. This brings the type variable a into scope; it scopes over -all the patterns and right hand sides for this equation for f. -In particular, it is in scope at the type signature for y. +all the patterns and right hand sides for this equation for f. +In particular, it is in scope at the type signature for y. -At ordinary type signatures, such as that for ys, any type variables +At ordinary type signatures, such as that for ys, any type variables mentioned in the type signature that are not in scope are implicitly universally quantified. (If there are no type variables in scope, all type variables mentioned in the signature are universally -quantified, which is just as in Haskell 98.) In this case, since a -is in scope, it is not universally quantified, so the type of ys is -the same as that of xs. In Haskell 98 it is not possible to declare -a type for ys; a major benefit of scoped type variables is that +quantified, which is just as in Haskell 98.) In this case, since a +is in scope, it is not universally quantified, so the type of ys is +the same as that of xs. In Haskell 98 it is not possible to declare +a type for ys; a major benefit of scoped type variables is that it becomes possible to do so. @@ -2583,7 +2579,7 @@ into scope (except in the type signature itself!). So this is illegal: -It's illegal because a is not in scope in the body of f, +It's illegal because a is not in scope in the body of f, so the ordinary signature x::a is equivalent to x::forall a.a; and that is an incorrect typing. @@ -2742,7 +2738,7 @@ thus: -The final ":: [a]" after all the patterns gives a signature to the +The final :: [a] after all the patterns gives a signature to the result type. Sometimes this is the only way of naming the type variable you want: @@ -2810,9 +2806,9 @@ For example: -Here, f1 is OK, but f2 is not, because c gets unified +Here, f1 is OK, but f2 is not, because c gets unified with a type variable free in the environment, in this -case, the type of f2, which is in the environment when +case, the type of f2, which is in the environment when the lambda abstraction is checked. @@ -2918,8 +2914,8 @@ restriction. Thus: -Here g has type forall a. Eq a => a -> a -> Bool, just as if -g had a separate type signature. Lacking a type signature, g +Here g has type forall a. Eq a => a -> a -> Bool, just as if +g had a separate type signature. Lacking a type signature, g would get a monomorphic type. @@ -2976,7 +2972,7 @@ but they might affect the efficiency of the generated code. pragma, INLINE -GHC (with -O, as always) tries to inline (or ``unfold'') +GHC (with , as always) tries to inline (or ``unfold'') functions/values that are ``small enough,'' thus avoiding the call overhead and possibly exposing other more-wonderful optimisations. @@ -3094,8 +3090,8 @@ the specialised value, by adding = blah, as in: {-# SPECIALIZE hammeredLookup :: ...as before... = blah #-} -It's Your Responsibility to make sure that blah really -behaves as a specialised version of hammeredLookup!!! +It's Your Responsibility to make sure that blah really +behaves as a specialised version of hammeredLookup!!! @@ -3113,7 +3109,7 @@ toDouble = fromRational . toRational i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly -The i2d function is virtually one machine instruction; the +The i2d function is virtually one machine instruction; the default conversion—via an intermediate Rational—is obscenely expensive by comparison. @@ -3174,7 +3170,7 @@ number and filename of the original code; for example -if you'd generated the current file from something called Foo.vhs +if you'd generated the current file from something called Foo.vhs and this line corresponds to line 42 in the original. GHC will adjust its error messages to refer to the line/file named in the LINE pragma. @@ -3248,8 +3244,8 @@ enclosing definitions. - Each variable mentioned in a rule must either be in scope (e.g. map), -or bound by the forall (e.g. f, g, xs). The variables bound by + Each variable mentioned in a rule must either be in scope (e.g. map), +or bound by the forall (e.g. f, g, xs). The variables bound by the forall are called the pattern variables. They are separated by spaces, just like in a type forall. @@ -3262,23 +3258,23 @@ If the type of the pattern variable is polymorphic, it must For example, here is the foldr/build rule: - "fold/build" forall k z (g::forall b. (a->b->b) -> b -> b) . - foldr k z (build g) = g k z +"fold/build" forall k z (g::forall b. (a->b->b) -> b -> b) . + foldr k z (build g) = g k z -Since g has a polymorphic type, it must have a type signature. +Since g has a polymorphic type, it must have a type signature. - The left hand side of a rule must consist of a top-level variable applied +The left hand side of a rule must consist of a top-level variable applied to arbitrary expressions. For example, this is not OK: - "wrong1" forall e1 e2. case True of { True -> e1; False -> e2 } = e1 - "wrong2" forall f. f True = True +"wrong1" forall e1 e2. case True of { True -> e1; False -> e2 } = e1 +"wrong2" forall f. f True = True In "wrong1", the LHS is not an application; in "wrong1", the LHS has a pattern variable @@ -3315,12 +3311,11 @@ From a semantic point of view: - Rules are only applied if you use the -O flag. - +Rules are only applied if you use the flag. - + Rules are regarded as left-to-right rewrite rules. When GHC finds an expression that is a substitution instance of the LHS @@ -3398,8 +3393,8 @@ For example, consider: The expression s (t xs) does not match the rule "map/map", but GHC -will substitute for s and t, giving an expression which does match. -If s or t was (a) used more than once, and (b) large or a redex, then it would +will substitute for s and t, giving an expression which does match. +If s or t was (a) used more than once, and (b) large or a redex, then it would not be substituted, and the rule would not fire. @@ -3421,20 +3416,20 @@ It will only match something written with explicit use of ".". Well, not quite. It will match the expression - wibble f g xs +wibble f g xs -where wibble is defined: +where wibble is defined: - wibble f g = map f . map g +wibble f g = map f . map g -because wibble will be inlined (it's small). +because wibble will be inlined (it's small). Later on in compilation, GHC starts inlining even things on the LHS of rules, but still leaves the rules enabled. This inlining -policy is controlled by the per-simplification-pass flag -finline-phasen. +policy is controlled by the per-simplification-pass flag n. @@ -3495,31 +3490,31 @@ The following are good producers: - ++ + ++ - map + map - filter + filter - iterate, repeat + iterate, repeat - zip, zipWith + zip, zipWith @@ -3540,86 +3535,86 @@ The following are good consumers: - array (on its second argument) + array (on its second argument) - length + length - ++ (on its first argument) + ++ (on its first argument) - map + map - filter + filter - concat + concat - unzip, unzip2, unzip3, unzip4 + unzip, unzip2, unzip3, unzip4 - zip, zipWith (but on one argument only; if both are good producers, zip + zip, zipWith (but on one argument only; if both are good producers, zip will fuse with one but not the other) - partition + partition - head + head - and, or, any, all + and, or, any, all - sequence_ + sequence_ - msum + msum - sortBy + sortBy @@ -3631,7 +3626,7 @@ will fuse with one but not the other) So, for example, the following should generate no intermediate lists: - array (1,10) [(i,i*i) | i <- map (+ 1) [0..9]] +array (1,10) [(i,i*i) | i <- map (+ 1) [0..9]] @@ -3660,10 +3655,10 @@ present in earlier version of GHC: {-# SPECIALIZE fromIntegral :: Int8 -> Int16 = int8ToInt16 #-} -This told GHC to use int8ToInt16 instead of fromIntegral whenever +This told GHC to use int8ToInt16 instead of fromIntegral whenever the latter was called with type Int8 -> Int16. That is, rather than -specialising the original definition of fromIntegral the programmer is -promising that it is safe to use int8ToInt16 instead. +specialising the original definition of fromIntegral the programmer is +promising that it is safe to use int8ToInt16 instead. @@ -3671,18 +3666,18 @@ This feature is no longer in GHC. But rewrite rules let you do the same thing: - {-# RULES - "fromIntegral/Int8/Int16" fromIntegral = int8ToInt16 - #-} +{-# RULES + "fromIntegral/Int8/Int16" fromIntegral = int8ToInt16 +#-} -This slightly odd-looking rule instructs GHC to replace fromIntegral -by int8ToInt16 whenever the types match. Speaking more operationally, +This slightly odd-looking rule instructs GHC to replace fromIntegral +by int8ToInt16 whenever the types match. Speaking more operationally, GHC adds the type and dictionary applications to get the typed rule - forall (d1::Integral Int8) (d2::Num Int16) . - fromIntegral Int8 Int16 d1 d2 = int8ToInt16 +forall (d1::Integral Int8) (d2::Num Int16) . + fromIntegral Int8 Int16 d1 d2 = int8ToInt16 What is more, @@ -3702,20 +3697,20 @@ have an original definition available to specialise). - Use -ddump-rules to see what transformation rules GHC is using. + Use to see what transformation rules GHC is using. - Use -ddump-simpl-stats to see what rules are being fired. -If you add -dppr-debug you get a more detailed listing. + Use to see what rules are being fired. +If you add you get a more detailed listing. - The defintion of (say) build in PrelBase.lhs looks llike this: + The defintion of (say) build in PrelBase.lhs looks llike this: build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a] @@ -3733,9 +3728,9 @@ in the RHS of the INLINE thing. I regret the delicacy of thi - In ghc/lib/std/PrelBase.lhs look at the rules for map to + In ghc/lib/std/PrelBase.lhs look at the rules for map to see how to write rules that will do fusion and yet give an efficient -program even if fusion doesn't happen. More rules in PrelList.lhs. +program even if fusion doesn't happen. More rules in PrelList.lhs. diff --git a/ghc/docs/users_guide/gone_wrong.sgml b/ghc/docs/users_guide/gone_wrong.sgml index db00204..094125c 100644 --- a/ghc/docs/users_guide/gone_wrong.sgml +++ b/ghc/docs/users_guide/gone_wrong.sgml @@ -43,13 +43,13 @@ These events are always bugs in the GHC system—please ``The compiler ran out of heap (or stack) when compiling itself!'' -It happens. We try to supply reasonable -H<n> flags for -ghc/compiler/ and ghc/lib/, but GHC's memory consumption +It happens. We try to supply reasonable flags for +ghc/compiler/ and ghc/lib/, but GHC's memory consumption can vary by platform (e.g., on a 64-bit machine). -Just say make all EXTRA_HC_OPTS=-H<a reasonable number> and see +Just say make all EXTRA_HC_OPTS=-H<a reasonable number> and see how you get along. @@ -89,9 +89,9 @@ Almost surely not a problem. About some specific cases… Sad, but harmless. You can change the number with a --fmax-simplifier-iterations<N>-fmax-simplifier-iterations<N> option option (no space); +-fmax-simplifier-iterations<N> option option (no space); and you can see what actions took place in each iteration by -turning on the -fshow-simplifier-progress +turning on the -fshow-simplifier-progress option option. @@ -115,13 +115,13 @@ Unsightly, but shouldn't be a problem. -Sensitivity to .hi interface files: +Sensitivity to .hi interface files: GHC is very sensitive about interface files. For example, if it picks -up a non-standard Prelude.hi file, pretty terrible things will +up a non-standard Prelude.hi file, pretty terrible things will happen. If you turn on --fno-implicit-prelude-fno-implicit-prelude option, the +-fno-implicit-prelude option, the compiler will almost surely die, unless you know what you are doing. @@ -136,9 +136,9 @@ running programs compiled using unstable interfaces. Unlikely :-) A useful be-more-paranoid option to give to GHC is --dcore-lint-dcore-lint option; this causes a ``lint'' +-dcore-lint option; this causes a ``lint'' pass to check for errors (notably type errors) after each Core-to-Core -transformation pass. We run with -dcore-lint on all the time; it +transformation pass. We run with on all the time; it costs about 5% in compile time. @@ -168,8 +168,8 @@ with an incompatible newer version. -If you run nm -o *.o | egrep 't (cc|hsc)\.' (or, on -unregisterised files: what *.o), you'll see all the consistency +If you run nm -o *.o | egrep 't (cc|hsc)\.' (or, on +unregisterised files: what *.o), you'll see all the consistency tags/strings in your object files. They must all be the same! (ToDo: tell you what they mean…) @@ -220,10 +220,10 @@ please see ). -If your program has no _ccall_s/_casm_s in it, then a crash is +If your program has no _ccall_s/_casm_s in it, then a crash is always a BUG in the GHC system, except in one case: If your program is made of several modules, each module must have been compiled after any -modules on which it depends (unless you use .hi-boot files, in which +modules on which it depends (unless you use .hi-boot files, in which case these must be correct with respect to the module source). @@ -242,19 +242,19 @@ the modules that import that interface must be re-compiled. A useful option to alert you when interfaces change is --hi-diffs-hi-diffs option. It will run diff on the +-hi-diffs option. It will run diff on the changed interface file, before and after, when applicable. -If you are using make, a useful tool to make sure that every module +If you are using make, a useful tool to make sure that every module is up-to-date with respect to its imported interfaces is -mkdependHS (which comes with GHC). Please see . +mkdependHS (which comes with GHC). Please see . If you are down to your last-compile-before-a-bug-report, we would -recommend that you add a -dcore-lint option (for extra checking) to your compilation options. +recommend that you add a option (for extra checking) to your compilation options. @@ -270,7 +270,7 @@ So, before you report a bug because of a core dump, you should probably: -Of course, if you have _ccall_s/_casm_s in your program then all +Of course, if you have _ccall_s/_casm_s in your program then all bets are off, because you can trash the heap, the stack, or whatever. @@ -315,10 +315,7 @@ exception (please report it if it does). Glasgow Haskell is a changing system so there are sure to be bugs in -it. Please report them to glasgow-haskell-bugs@haskell.org! (However, please +it. Please report them to glasgow-haskell-bugs@haskell.org! (However, please check the earlier part of this section to be sure it's not a known not-really-a problem.) @@ -335,15 +332,15 @@ Don't omit them because ``Oh, they won't be interested…'' What kind of machine are you running on, and exactly what -version of the operating system are you using? (uname -a or cat -/etc/motd will show the desired information.) +version of the operating system are you using? (uname -a or cat +/etc/motd will show the desired information.) - What version of GCC are you using? gcc -v will tell you. + What version of GCC are you using? gcc -v will tell you. @@ -360,7 +357,7 @@ thing. - Be sure any Haskell compilations are run with a -v (verbose) + Be sure any Haskell compilations are run with a (verbose) flag, so we can see exactly what was run, what versions of things you have, etc. @@ -416,7 +413,7 @@ This section suggests ways to Make Further Progress Anyway. The first thing to establish is: Is it a garbage-collection (GC) bug? -Try your program with a very large heap and a -Sstderr RTS +Try your program with a very large heap and a RTS flag. @@ -438,7 +435,7 @@ it probably is a GC bug. If it crashes with the normal -collector, but not when you force two-space collection (-F2s +collector, but not when you force two-space collection ( runtime flag), then it probably is a GC bug. @@ -449,7 +446,7 @@ runtime flag), then it probably is a GC bug. If it is a GC bug, you may be able to avoid it by using a -particular heap size or by using a -F2s runtime flag. (But don't +particular heap size or by using a runtime flag. (But don't forget to report the bug!!!) diff --git a/ghc/docs/users_guide/libmisc.sgml b/ghc/docs/users_guide/libmisc.sgml index 530f83e..ba928bd 100644 --- a/ghc/docs/users_guide/libmisc.sgml +++ b/ghc/docs/users_guide/libmisc.sgml @@ -10,7 +10,7 @@ This section describes a collection of Haskell libraries we've collected over the years. Access to any of these modules is provided -by giving the -syslib misc-syslib misc option. +by giving the -syslib misc option. @@ -237,22 +237,22 @@ mapMaybe :: (a -> Maybe b) -> [a] -> Maybe [b] -NB: catMaybes which used to be here, is now available via the +NB: catMaybes which used to be here, is now available via the standard Maybe interface (Maybe is an instance of MonadPlus). -allMaybes collects a list of Justs into a single Just, returning +allMaybes collects a list of Justs into a single Just, returning Nothing if there are any Nothings. -firstJust takes a list of Maybes and returns the +firstJust takes a list of Maybes and returns the first Just if there is one, or Nothing otherwise. -assocMaybe looks up in an association list, returning +assocMaybe looks up in an association list, returning Nothing if it fails. @@ -275,13 +275,13 @@ foldlMaybeErrs :: (acc -> input -> MaybeErr acc err) -listMaybeErrs takes a list of MaybeErrs and, if they all succeed, +listMaybeErrs takes a list of MaybeErrs and, if they all succeed, returns a Succeeded of a list of their values. If any fail, it returns a Failed of the list of all the errors in the list. -foldlMaybeErrs works along a list, carrying an accumulator; it +foldlMaybeErrs works along a list, carrying an accumulator; it applies the given function to the accumulator and the next list item, accumulating any errors that occur. @@ -310,7 +310,7 @@ memo :: (a -> b) -> a -> b -So, for example, memo f is a version of f that caches the results +So, for example, memo f is a version of f that caches the results of previous calls. @@ -339,7 +339,7 @@ becomes garbage. We plan to fix this in a future version. -There's another version of memo if you want to explicitly give a +There's another version of memo if you want to explicitly give a size for the hash table (the default size is 1001 buckets): @@ -363,7 +363,7 @@ memo_sized :: Int -> (a -> b) -> a -> b You need to import PackedString and heave in your --syslib ghc to use PackedStrings. + to use PackedStrings. @@ -614,7 +614,7 @@ unzipWith :: (a -> b -> c) -> [(a, b)] -> [c] -The GHC system library (-syslib misc) also provides interfaces to +The GHC system library () also provides interfaces to several useful C libraries, mostly from the GNU project. @@ -634,12 +634,12 @@ several useful C libraries, mostly from the GNU project. The Readline module is a straightforward interface to the GNU Readline library. As such, you will need to look at the GNU -documentation (and have a libreadline.a file around somewhere…) +documentation (and have a libreadline.a file around somewhere…) -You'll need to link any Readlining program with -lreadline -ltermcap, -besides the usual -syslib ghc (and -fhaskell-1.3). +You'll need to link any Readlining program with , +besides the usual (and ). @@ -763,8 +763,8 @@ re_search2 :: PatBuffer -- Double buffer search The MatchPS module provides Perl-like ``higher-level'' facilities to operate on PackedStrings. The regular expressions in question are in Perl syntax. The ``flags'' on various functions can -include: i for case-insensitive, s for single-line mode, and -g for global. (It's probably worth your time to peruse the +include: for case-insensitive, for single-line mode, and + for global. (It's probably worth your time to peruse the source code…) @@ -887,7 +887,7 @@ matchRegex Your best bet for documentation is to look at the code—really!— normally in -fptools/ghc/lib/misc/{BSD,Socket,SocketPrim.lhs}. +fptools/ghc/lib/misc/{BSD,Socket,SocketPrim.lhs}. @@ -975,7 +975,7 @@ Various examples of networking Haskell code are provided in -The Select interface provides a Haskell wrapper for the select() +The Select interface provides a Haskell wrapper for the select() OS call supplied by many modern UNIX variants. Select exports the following: @@ -1028,15 +1028,15 @@ main = do -where the call to hSelect makes the process go to sleep -until there's input available on stdin. +where the call to hSelect makes the process go to sleep +until there's input available on stdin. -Notice that this particular use of hSelect is now really a no-op +Notice that this particular use of hSelect is now really a no-op with GHC compiled code, as its implementation of IO will take care to avoid blocking the process (i.e., all running Haskell threads), and -call select() for you, if needs be. However, hSelect exposes +call select() for you, if needs be. However, hSelect exposes functionality that is useful in other contexts (e.g., you want to wait for input on two Handles for 3 seconds, but no longer.) diff --git a/ghc/docs/users_guide/libraries.sgml b/ghc/docs/users_guide/libraries.sgml index f7fb4d5..7fe9cfa 100644 --- a/ghc/docs/users_guide/libraries.sgml +++ b/ghc/docs/users_guide/libraries.sgml @@ -59,7 +59,7 @@ GHC's prelude contains the following non-standard extensions: -fromInt method in class Num: +fromInt method in class Num: It's there. Converts from @@ -68,7 +68,7 @@ an Int to the type. -toInt method in class Integral: +toInt method in class Integral: Converts from Integral @@ -85,7 +85,7 @@ string PrelPrel module prefixPrel in your own programs. The Prel modules are always available: in fact, you can get access to several extensions this way (for some you might -need to give the -fglasgow-exts-fglasgow-exts option +need to give the -fglasgow-exts option flag). @@ -98,9 +98,7 @@ flag). The extension libraries provided by both GHC and Hugs are described in the GHC/Hugs Extension Library Document +URL="libs.html">GHC/Hugs Extension Library Document @@ -116,13 +114,13 @@ URL="http://www.dcs.gla.ac.uk/fp/software/ghc/hg-libs/hg-libs.html" If you rely on the implicit import Prelude that GHC normally does for you, and if you don't use any weird flags (notably --fglasgow-exts), and if you don't import the Glasgow extensions +), and if you don't import the Glasgow extensions interface, GlaExts, then GHC should work exactly as the Haskell report says (modulo a few minor issues, see ). -If you turn on -fglasgow-exts, a new world opesn up to you and the compiler +If you turn on , a new world opesn up to you and the compiler will recognise and parse unboxed values properly, and provide access to the various interfaces libraries described here (and piles of other goodies.) @@ -136,13 +134,13 @@ various interfaces libraries described here (and piles of other goodies.) The CCall module defines the classes CCallable and CReturnable, along with instances for the primitive types (Int, Int#, Float, -Float# etc.) GHC knows to import this module if you use _ccall_, +Float# etc.) GHC knows to import this module if you use _ccall_, but if you need to define your own instances of these classes, you will need to import CCall explicitly. -More information on how to use _ccall_ can be found in . +More information on how to use _ccall_ can be found in . @@ -158,7 +156,7 @@ More information on how to use _ccall_ can be f The GlaExts interface provides access to extensions that only GHC implements. These currently are: unboxed types, including the representations of the primitive types (Int, Float, etc.), and the -GHC primitive operations (+#, ==#, etc.). +GHC primitive operations (+#, ==#, etc.). @@ -232,7 +230,7 @@ primitive value. Unboxed tuples aren't really exported by PrelGHC, they're available -by default with -fglasgow-exts. An unboxed tuple looks like this: +by default with . An unboxed tuple looks like this: @@ -311,7 +309,7 @@ f x = x -because x has an unboxed tuple type. +because x has an unboxed tuple type. @@ -362,7 +360,7 @@ type Double# If you really want to know their exact equivalents in C, see -ghc/includes/StgTypes.h in the GHC source tree. +ghc/includes/StgTypes.h in the GHC source tree. @@ -578,7 +576,7 @@ double2Float# :: Double# -> Float# -The primitive versions of encodeDouble/decodeDouble: +The primitive versions of encodeDouble/decodeDouble: @@ -618,8 +616,8 @@ multiple-precision (GMP) package (version 2.0.2). The data type for Integer is either a small integer, represented by an Int, or a large integer represented -using the pieces requird by GMP's MP_INT in gmp.h -(see gmp.info in ghc/includes/runtime/gmp). It comes out as: +using the pieces required by GMP's MP_INT in gmp.h +(see gmp.info in ghc/includes/runtime/gmp). It comes out as: @@ -790,7 +788,7 @@ type Array# elt Haskell Array interface is implemented using Array#—in that an Array# is indexed only by Int#s, starting at zero. It is also more primitive by virtue of being unboxed. That doesn't mean that it -isn't a heap-allocated object - of course, it is. Rather, being +isn't a heap-allocated object—of course, it is. Rather, being unboxed means that it is represented by a pointer to the array itself, and not to a thunk which will evaluate to the array (or to bottom). The components of an Array# are themselves boxed. @@ -899,7 +897,7 @@ indexAddrOffAddr# :: Addr# -> Int# -> Addr# -The last of these, indexAddrOffAddr#, extracts an Addr# using an offset +The last of these, indexAddrOffAddr#, extracts an Addr# using an offset from another Addr#, thereby providing the ability to follow a chain of C pointers. @@ -1136,7 +1134,7 @@ sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> B Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell -by copying the array and then using unsafeFreeze.) +by copying the array and then using unsafeFreeze.) @@ -1190,7 +1188,7 @@ A stable pointer is represented by an index into the (static) -The makeStablePointer function converts a value into a stable +The makeStablePointer function converts a value into a stable pointer. It is part of the IO monad, because we want to be sure we don't allocate one twice by accident, and then only free one of the copies. @@ -1210,7 +1208,7 @@ deRefStablePointer# :: StablePtr# a -> State# RealWorld -> (# State# Rea -There is also a C procedure FreeStablePtr which frees a stable pointer. +There is also a C procedure FreeStablePtr which frees a stable pointer. diff --git a/ghc/docs/users_guide/license.sgml b/ghc/docs/users_guide/license.sgml index d41466f..b0c3014 100644 --- a/ghc/docs/users_guide/license.sgml +++ b/ghc/docs/users_guide/license.sgml @@ -1,4 +1,4 @@ - + The Glasgow Haskell Compiler License diff --git a/ghc/docs/users_guide/parallel.sgml b/ghc/docs/users_guide/parallel.sgml index a36d005..f04ec81 100644 --- a/ghc/docs/users_guide/parallel.sgml +++ b/ghc/docs/users_guide/parallel.sgml @@ -5,9 +5,6 @@ Concurrent Haskell Parallel Haskell - - - Concurrent and Parallel Haskell are Glasgow extensions to Haskell which let you structure your program as a group of independent `threads'. @@ -102,14 +99,14 @@ already been evaluated to WHNF. The expression (x `seq` y) evaluates x to weak head normal -form and then returns y. The seq primitive can be used to +form and then returns y. The seq primitive can be used to force evaluation of an expression beyond WHNF, or to impose a desired execution sequence for the evaluation of an expression. For example, consider the following parallel version of our old -nemesis, nfib: +nemesis, nfib: @@ -127,14 +124,14 @@ nfib n | n <= 1 = 1 -For values of n greater than 1, we use par to spark a thread -to evaluate nfib (n-1), and then we use seq to force the +For values of n greater than 1, we use par to spark a thread +to evaluate nfib (n-1), and then we use seq to force the parent thread to evaluate nfib (n-2) before going on to add together these two subexpressions. In this divide-and-conquer approach, we only spark a new thread for one branch of the computation (leaving the parent to evaluate the other branch). Also, we must use -seq to ensure that the parent will evaluate n2 before -n1 in the expression (n1 + n2 + 1). It is not sufficient to +seq to ensure that the parent will evaluate n2 before +n1 in the expression (n1 + n2 + 1). It is not sufficient to reorder the expression as (n2 + n1 + 1), because the compiler may not generate code to evaluate the addends from left to right. @@ -147,10 +144,10 @@ not generate code to evaluate the addends from left to right. primitives for parallelism -The functions par and seq are wired into GHC, and unfold -into uses of the par# and seq# primitives, respectively. If +The functions par and seq are wired into GHC, and unfold +into uses of the par# and seq# primitives, respectively. If you'd like to see this with your very own eyes, just run GHC with the --ddump-simpl option. (Anything for a good time…) + option. (Anything for a good time…) @@ -164,7 +161,7 @@ you'd like to see this with your very own eyes, just run GHC with the Runnable threads are scheduled in round-robin fashion. Context switches are signalled by the generation of new sparks or by the expiry of a virtual timer (the timer interval is configurable with the --C[<num>]-C<num> RTS option (concurrent, +-C<num> RTS option (concurrent, parallel) RTS option). However, a context switch doesn't really happen until the current heap block is full. You can't get any faster context switching than this. @@ -175,7 +172,7 @@ When a context switch occurs, pending sparks which have not already been reduced to weak head normal form are turned into new threads. However, there is a limit to the number of active threads (runnable or blocked) which are allowed at any given time. This limit can be -adjusted with the -t<num>-t <num> RTS option (concurrent, parallel) +adjusted with the -t <num> RTS option (concurrent, parallel) RTS option (the default is 32). Once the thread limit is reached, any remaining sparks are deferred until some of the currently active threads are completed. diff --git a/ghc/docs/users_guide/posix.sgml b/ghc/docs/users_guide/posix.sgml index 10a7b72..8fc8994 100644 --- a/ghc/docs/users_guide/posix.sgml +++ b/ghc/docs/users_guide/posix.sgml @@ -12,7 +12,7 @@ The Posix interface gives you access to the set of OS services standardised by POSIX 1003.1b (or the IEEE Portable Operating System Interface for Computing Environments - IEEE Std. 1003.1). The interface is accessed by import Posix and -adding -syslib posix on your command-line. +adding on your command-line. @@ -377,8 +377,8 @@ forkProcess :: IO (Maybe ProcessID) -forkProcess calls fork, returning -Just pid to the parent, where pid is the +forkProcess calls fork, returning +Just pid to the parent, where pid is the ProcessID of the child, and returning Nothing to the child. @@ -397,13 +397,12 @@ executeFile :: FilePath -- Command executeFile cmd args env calls one of the -execv* family, depending on whether or not the current +execv* family, depending on whether or not the current PATH is to be searched for the command, and whether or not an environment is provided to supersede the process's current environment. The basename (leading directory names suppressed) of -the command is passed to execv* as arg[0]; -the argument list passed to executeFile therefore begins -with arg[1]. +the command is passed to execv* as arg[0]; +the argument list passed to executeFile therefore begins with arg[1]. @@ -420,7 +419,7 @@ True True execvpe* -Note that execvpe is not provided by the POSIX standard, and must +Note that execvpe is not provided by the POSIX standard, and must be written by hand. Care must be taken to ensure that the search path is extracted from the original environment, and not from the environment to be passed on to the new image. @@ -429,17 +428,17 @@ environment to be passed on to the new image. NOTE: In general, sharing open files between parent and child processes is potential bug farm, and should be avoided unless you -really depend on this `feature' of POSIX' fork() semantics. Using +really depend on this `feature' of POSIX' fork() semantics. Using Haskell, there's the extra complication that arguments to -executeFile might come from files that are read lazily (using -hGetContents, or some such.) If this is the case, then for your own -sanity, please ensure that the arguments to executeFile have been -fully evaluated before calling forkProcess (followed by -executeFile.) Consider yourself warned :-) +executeFile might come from files that are read lazily (using +hGetContents, or some such.) If this is the case, then for your own +sanity, please ensure that the arguments to executeFile have been +fully evaluated before calling forkProcess (followed by +executeFile.) Consider yourself warned :-) -A successful executeFile overlays the current process image with +A successful executeFile overlays the current process image with a new one, so it only returns on failure. @@ -459,12 +458,12 @@ runProcess :: FilePath -- Command -runProcess is our candidate for the high-level OS-independent +runProcess is our candidate for the high-level OS-independent primitive. -runProcess cmd args env wd inhdl outhdl errhdl runs cmd +runProcess cmd args env wd inhdl outhdl errhdl runs cmd (searching the current PATH) with arguments args. If env is Just pairs, the command is executed with the environment specified by pairs of variables and values; @@ -489,12 +488,12 @@ getProcessStatus :: Bool -- Block? -getProcessStatus blk stopped pid calls waitpid, returning +getProcessStatus blk stopped pid calls waitpid, returning Just tc, the ProcessStatus for process pid if it is available, Nothing otherwise. If blk is False, then -WNOHANG is set in the options for waitpid, otherwise not. +WNOHANG is set in the options for waitpid, otherwise not. If stopped is True, then WUNTRACED is set in the -options for waitpid, otherwise not. +options for waitpid, otherwise not. @@ -509,13 +508,13 @@ getGroupProcessStatus :: Bool -- Block? -getGroupProcessStatus blk stopped pgid calls waitpid, +getGroupProcessStatus blk stopped pgid calls waitpid, returning Just (pid, tc), the ProcessID and ProcessStatus for any process in group pgid if one is available, Nothing otherwise. If blk is False, then -WNOHANG is set in the options for waitpid, otherwise not. +WNOHANG is set in the options for waitpid, otherwise not. If stopped is True, then WUNTRACED is set in the -options for waitpid, otherwise not. +options for waitpid, otherwise not. @@ -529,12 +528,12 @@ getAnyProcessStatus :: Bool -- Block? -getAnyProcessStatus blk stopped calls waitpid, returning +getAnyProcessStatus blk stopped calls waitpid, returning Just (pid, tc), the ProcessID and ProcessStatus for any child process if one is available, Nothing otherwise. If blk is False, then WNOHANG is set in the options for -waitpid, otherwise not. If stopped is True, then -WUNTRACED is set in the options for waitpid, otherwise not. +waitpid, otherwise not. If stopped is True, then +WUNTRACED is set in the options for waitpid, otherwise not. @@ -546,7 +545,7 @@ exitImmediately :: ExitCode -> IO () -exitImmediately status calls _exit to terminate the process +exitImmediately status calls _exit to terminate the process with the indicated exit status. The operation never returns. @@ -560,7 +559,7 @@ getEnvironment :: IO [(String, String)] -getEnvironment parses the environment variable mapping provided by +getEnvironment parses the environment variable mapping provided by environ, returning (variable, value) pairs. The operation never fails. @@ -574,7 +573,7 @@ setEnvironment :: [(String, String)] -> IO () -setEnvironment replaces the process environment with the provided +setEnvironment replaces the process environment with the provided mapping of (variable, value) pairs. @@ -587,9 +586,9 @@ getEnvVar :: String -> IO String -getEnvVar var returns the value associated with variable var +getEnvVar var returns the value associated with variable var in the current environment (identical functionality provided through -standard Haskell library function System.getEnv). +standard Haskell library function System.getEnv). @@ -619,7 +618,7 @@ setEnvVar :: String -> String -> IO () -setEnvVar var val sets the value associated with variable var +setEnvVar var val sets the value associated with variable var in the current environment to be val. Any previous mapping is superseded. @@ -633,7 +632,7 @@ removeEnvVar :: String -> IO () -removeEnvVar var removes any value associated with variable var +removeEnvVar var removes any value associated with variable var in the current environment. Deleting a variable for which there is no mapping does not generate an error. @@ -670,7 +669,7 @@ signalProcess :: Signal -> ProcessID -> IO () -signalProcess int pid calls kill to signal +signalProcess int pid calls kill to signal process pid with interrupt signal int. @@ -683,7 +682,7 @@ raiseSignal :: Signal -> IO () -raiseSignal int calls kill to signal the current process +raiseSignal int calls kill to signal the current process with interrupt signal int. @@ -696,7 +695,7 @@ signalProcessGroup :: Signal -> ProcessGroupID -> IO () -signalProcessGroup int pgid calls kill to signal +signalProcessGroup int pgid calls kill to signal all processes in group pgid with interrupt signal int. @@ -710,9 +709,9 @@ setStoppedChildFlag :: Bool -> IO Bool setStoppedChildFlag bool sets a flag which controls whether or -not the NOCLDSTOP option will be used the next time a signal -handler is installed for SIGCHLD. If bool is True (the -default), NOCLDSTOP will not be used; otherwise it will be. The +not the NOCLDSTOP option will be used the next time a signal +handler is installed for SIGCHLD. If bool is True (the +default), NOCLDSTOP will not be used; otherwise it will be. The operation never fails. @@ -725,10 +724,10 @@ queryStoppedChildFlag :: IO Bool -queryStoppedChildFlag queries the flag which -controls whether or not the NOCLDSTOP option will be used -the next time a signal handler is installed for SIGCHLD. -If NOCLDSTOP will be used, it returns False; +queryStoppedChildFlag queries the flag which +controls whether or not the NOCLDSTOP option will be used +the next time a signal handler is installed for SIGCHLD. +If NOCLDSTOP will be used, it returns False; otherwise (the default) it returns True. The operation never fails. @@ -751,9 +750,9 @@ installHandler :: Signal -installHandler int handler iset calls sigaction to install an +installHandler int handler iset calls sigaction to install an interrupt handler for signal int. If handler is Default, -SIG_DFL is installed; if handler is Ignore, SIG_IGN is +SIG_DFL is installed; if handler is Ignore, SIG_IGN is installed; if handler is Catch action, a handler is installed which will invoke action in a new thread when (or shortly after) the signal is received. See for details on how to communicate between @@ -761,7 +760,7 @@ threads. -If iset is Just s, then the sa_mask of the sigaction structure +If iset is Just s, then the sa_mask of the sigaction structure is set to s; otherwise it is cleared. The previously installed signal handler for int is returned. @@ -775,7 +774,7 @@ getSignalMask :: IO SignalSet -getSignalMask calls sigprocmask to determine the +getSignalMask calls sigprocmask to determine the set of interrupts which are currently being blocked. @@ -788,8 +787,8 @@ setSignalMask :: SignalSet -> IO SignalSet -setSignalMask mask calls sigprocmask with -SIG_SETMASK to block all interrupts in mask. The +setSignalMask mask calls sigprocmask with +SIG_SETMASK to block all interrupts in mask. The previous set of blocked interrupts is returned. @@ -802,8 +801,8 @@ blockSignals :: SignalSet -> IO SignalSet -setSignalMask mask calls sigprocmask with -SIG_BLOCK to add all interrupts in mask to the +setSignalMask mask calls sigprocmask with +SIG_BLOCK to add all interrupts in mask to the set of blocked interrupts. The previous set of blocked interrupts is returned. @@ -816,8 +815,8 @@ unBlockSignals :: SignalSet -> IO SignalSet -setSignalMask mask calls sigprocmask with -SIG_UNBLOCK to remove all interrupts in mask from the +setSignalMask mask calls sigprocmask with +SIG_UNBLOCK to remove all interrupts in mask from the set of blocked interrupts. The previous set of blocked interrupts is returned. @@ -830,7 +829,7 @@ getPendingSignals :: IO SignalSet -getPendingSignals calls sigpending to obtain +getPendingSignals calls sigpending to obtain the set of interrupts which have been received but are currently blocked. @@ -844,11 +843,11 @@ awaitSignal :: Maybe SignalSet -> IO () awaitSignal iset suspends execution until an interrupt is received. -If iset is Just s, awaitSignal calls sigsuspend, installing +If iset is Just s, awaitSignal calls sigsuspend, installing s as the new signal mask before suspending execution; otherwise, it -calls pause. awaitSignal returns on receipt of a signal. If you -have installed any signal handlers with installHandler, it may be -wise to call yield directly after awaitSignal to ensure that the +calls pause. awaitSignal returns on receipt of a signal. If you +have installed any signal handlers with installHandler, it may be +wise to call yield directly after awaitSignal to ensure that the signal handler runs as promptly. @@ -861,7 +860,7 @@ scheduleAlarm :: Int -> IO Int -scheduleAlarm i calls alarm to schedule a real time +scheduleAlarm i calls alarm to schedule a real time alarm at least i seconds in the future. @@ -874,7 +873,7 @@ sleep :: Int -> IO () -sleep i calls sleep to suspend execution of the +sleep i calls sleep to suspend execution of the program until at least i seconds have elapsed or a signal is received. @@ -898,7 +897,7 @@ getProcessID :: IO ProcessID -getProcessID calls getpid to obtain the ProcessID for +getProcessID calls getpid to obtain the ProcessID for the current process. @@ -911,7 +910,7 @@ getParentProcessID :: IO ProcessID -getProcessID calls getppid to obtain the ProcessID for +getProcessID calls getppid to obtain the ProcessID for the parent of the current process. @@ -924,7 +923,7 @@ getRealUserID :: IO UserID -getRealUserID calls getuid to obtain the real UserID +getRealUserID calls getuid to obtain the real UserID associated with the current process. @@ -937,7 +936,7 @@ getEffectiveUserID :: IO UserID -getRealUserID calls geteuid to obtain the effective +getRealUserID calls geteuid to obtain the effective UserID associated with the current process. @@ -950,7 +949,7 @@ setUserID :: UserID -> IO () -setUserID uid calls setuid to set the real, effective, and +setUserID uid calls setuid to set the real, effective, and saved set-user-id associated with the current process to uid. @@ -963,7 +962,7 @@ getLoginName :: IO String -getLoginName calls getlogin to obtain the login name +getLoginName calls getlogin to obtain the login name associated with the current process. @@ -976,7 +975,7 @@ getRealGroupID :: IO GroupID -getRealGroupID calls getgid to obtain the real GroupID +getRealGroupID calls getgid to obtain the real GroupID associated with the current process. @@ -989,7 +988,7 @@ getEffectiveGroupID :: IO GroupID -getEffectiveGroupID calls getegid to obtain the effective +getEffectiveGroupID calls getegid to obtain the effective GroupID associated with the current process. @@ -1002,7 +1001,7 @@ setGroupID :: GroupID -> IO () -setGroupID gid calls setgid to set the real, effective, and +setGroupID gid calls setgid to set the real, effective, and saved set-group-id associated with the current process to gid. @@ -1015,7 +1014,7 @@ getGroups :: IO [GroupID] -getGroups calls getgroups to obtain the list of +getGroups calls getgroups to obtain the list of supplementary GroupIDs associated with the current process. @@ -1028,7 +1027,7 @@ getEffectiveUserName :: IO String -getEffectiveUserName calls cuserid to obtain a name +getEffectiveUserName calls cuserid to obtain a name associated with the effective UserID of the process. @@ -1041,7 +1040,7 @@ getProcessGroupID :: IO ProcessGroupID -getProcessGroupID calls getpgrp to obtain the +getProcessGroupID calls getpgrp to obtain the ProcessGroupID for the current process. @@ -1054,7 +1053,7 @@ createProcessGroup :: ProcessID -> IO ProcessGroupID -createProcessGroup pid calls setpgid to make +createProcessGroup pid calls setpgid to make process pid a new process group leader. @@ -1067,7 +1066,7 @@ joinProcessGroup :: ProcessGroupID -> IO ProcessGroupID -joinProcessGroup pgid calls setpgid to set the +joinProcessGroup pgid calls setpgid to set the ProcessGroupID of the current process to pgid. @@ -1080,7 +1079,7 @@ setProcessGroupID :: ProcessID -> ProcessGroupID -> IO () -setProcessGroupID pid pgid calls setpgid to set the +setProcessGroupID pid pgid calls setpgid to set the ProcessGroupID for process pid to pgid. @@ -1093,7 +1092,7 @@ createSession :: IO ProcessGroupID -createSession calls setsid to create a new session +createSession calls setsid to create a new session with the current process as session leader. @@ -1112,7 +1111,7 @@ getSystemID :: IO SystemID -getSystemID calls uname to obtain information +getSystemID calls uname to obtain information about the current operating system. @@ -1125,7 +1124,7 @@ about the current operating system. -epochTime calls time to obtain the number of +epochTime calls time to obtain the number of seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970). @@ -1144,7 +1143,7 @@ getProcessTimes :: IO ProcessTimes -getProcessTimes calls times to obtain time-accounting +getProcessTimes calls times to obtain time-accounting information for the current process and its children. @@ -1157,10 +1156,10 @@ getControllingTerminalName :: IO FilePath -getControllingTerminalName calls ctermid to obtain +getControllingTerminalName calls ctermid to obtain a name associated with the controlling terminal for the process. If a controlling terminal exists, -getControllingTerminalName returns the name of the +getControllingTerminalName returns the name of the controlling terminal. @@ -1199,9 +1198,9 @@ getTerminalName :: Fd -> IO FilePath -getTerminalName fd calls ttyname to obtain a name associated +getTerminalName fd calls ttyname to obtain a name associated with the terminal for Fd fd. If fd is associated -with a terminal, getTerminalName returns the name of the +with a terminal, getTerminalName returns the name of the terminal. @@ -1248,7 +1247,7 @@ queryTerminal :: Fd -> IO Bool -queryTerminal fd calls isatty to determine whether or +queryTerminal fd calls isatty to determine whether or not Fd fd is associated with a terminal. @@ -1261,10 +1260,10 @@ getSysVar :: SysVar -> IO Limit -getSysVar var calls sysconf to obtain the +getSysVar var calls sysconf to obtain the dynamic value of the requested configurable system limit or option. -For defined system limits, getSysVar returns the associated -value. For defined system options, the result of getSysVar +For defined system limits, getSysVar returns the associated +value. For defined system options, the result of getSysVar is undefined, but not failure. @@ -1305,7 +1304,7 @@ openDirStream :: FilePath -> IO DirStream -openDirStream dir calls opendir to obtain a +openDirStream dir calls opendir to obtain a directory stream for dir. @@ -1318,9 +1317,9 @@ readDirStream :: DirStream -> IO String -readDirStream dp calls readdir to obtain the +readDirStream dp calls readdir to obtain the next directory entry (struct dirent) for the open directory -stream dp, and returns the d_name member of that +stream dp, and returns the d_name member of that structure. @@ -1359,7 +1358,7 @@ rewindDirStream :: DirStream -> IO () -rewindDirStream dp calls rewinddir to reposition +rewindDirStream dp calls rewinddir to reposition the directory stream dp at the beginning of the directory. @@ -1372,7 +1371,7 @@ closeDirStream :: DirStream -> IO () -closeDirStream dp calls closedir to close +closeDirStream dp calls closedir to close the directory stream dp. @@ -1385,7 +1384,7 @@ getWorkingDirectory :: IO FilePath -getWorkingDirectory calls getcwd to obtain the name +getWorkingDirectory calls getcwd to obtain the name of the current working directory. @@ -1398,7 +1397,7 @@ changeWorkingDirectory :: FilePath -> IO () -changeWorkingDirectory dir calls chdir to change +changeWorkingDirectory dir calls chdir to change the current working directory to dir. @@ -1455,13 +1454,13 @@ openFd :: FilePath openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc) calls -open to obtain a Fd for the file path with access -mode acc. If mode is Just m, the O_CREAT flag is +open to obtain a Fd for the file path with access +mode acc. If mode is Just m, the O_CREAT flag is set and the file's permissions will be based on m if it does not -already exist; otherwise, the O_CREAT flag is not set. The +already exist; otherwise, the O_CREAT flag is not set. The arguments app, excl, noctty, nonblock, and -trunc control whether or not the flags O_APPEND, -O_EXCL, O_NOCTTY, O_NONBLOCK, and O_TRUNC are set, +trunc control whether or not the flags O_APPEND, +O_EXCL, O_NOCTTY, O_NONBLOCK, and O_TRUNC are set, respectively. @@ -1474,7 +1473,7 @@ createFile :: FilePath -> FileMode -> IO Fd -createFile path mode calls creat to obtain a Fd +createFile path mode calls creat to obtain a Fd for file path, which will be created with permissions based on mode if it does not already exist. @@ -1488,7 +1487,7 @@ setFileCreationMask :: FileMode -> IO FileMode -setFileCreationMask mode calls umask to set +setFileCreationMask mode calls umask to set the process's file creation mask to mode. The previous file creation mask is returned. @@ -1502,7 +1501,7 @@ createLink :: FilePath -> FilePath -> IO () -createLink old new calls link to create a +createLink old new calls link to create a new path, new, linked to an existing file, old. @@ -1512,7 +1511,7 @@ createDirectory :: FilePath -> FileMode -> IO () -createDirectory dir mode calls mkdir to +createDirectory dir mode calls mkdir to create a new directory, dir, with permissions based on mode. @@ -1526,7 +1525,7 @@ createNamedPipe :: FilePath -> FileMode -> IO () -createNamedPipe fifo mode calls mkfifo to +createNamedPipe fifo mode calls mkfifo to create a new named pipe, fifo, with permissions based on mode. @@ -1540,7 +1539,7 @@ removeLink :: FilePath -> IO () -removeLink path calls unlink to remove the link +removeLink path calls unlink to remove the link named path. @@ -1553,7 +1552,7 @@ removeDirectory :: FilePath -> IO () -removeDirectory dir calls rmdir to remove the +removeDirectory dir calls rmdir to remove the directory named dir. @@ -1566,7 +1565,7 @@ rename :: FilePath -> FilePath -> IO () -rename old new calls rename to rename a +rename old new calls rename to rename a file or directory from old to new. @@ -1600,7 +1599,7 @@ getFileStatus :: FilePath -> IO FileStatus -getFileStatus path calls stat to get the +getFileStatus path calls stat to get the FileStatus information for the file path. @@ -1613,7 +1612,7 @@ getFdStatus :: Fd -> IO FileStatus -getFdStatus fd calls fstat to get the +getFdStatus fd calls fstat to get the FileStatus information for the file associated with Fd fd. @@ -1627,10 +1626,10 @@ queryAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool -queryAccess path r w x calls access to test the access +queryAccess path r w x calls access to test the access permissions for file path. The three arguments, r, w, -and x control whether or not access is called with -R_OK, W_OK, and X_OK respectively. +and x control whether or not access is called with +R_OK, W_OK, and X_OK respectively. @@ -1642,7 +1641,7 @@ queryFile :: FilePath -> IO Bool -queryFile path calls access with F_OK to test for the +queryFile path calls access with F_OK to test for the existence for file path. @@ -1655,7 +1654,7 @@ setFileMode :: FilePath -> FileMode -> IO () -setFileMode path mode calls chmod to set the +setFileMode path mode calls chmod to set the permission bits associated with file path to mode. @@ -1668,7 +1667,7 @@ setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO () -setOwnerAndGroup path uid gid calls chown to +setOwnerAndGroup path uid gid calls chown to set the UserID and GroupID associated with file path to uid and gid, respectively. @@ -1682,7 +1681,7 @@ setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO () -setFileTimes path atime mtime calls utime to +setFileTimes path atime mtime calls utime to set the access and modification times associated with file path to atime and mtime, respectively. @@ -1696,7 +1695,7 @@ touchFile :: FilePath -> IO () -touchFile path calls utime to +touchFile path calls utime to set the access and modification times associated with file path to the current time. @@ -1710,11 +1709,11 @@ getPathVar :: PathVar -> FilePath -> IO Limit -getPathVar var path calls pathconf to obtain the +getPathVar var path calls pathconf to obtain the dynamic value of the requested configurable file limit or option associated with file or directory path. For -defined file limits, getPathVar returns the associated -value. For defined file options, the result of getPathVar +defined file limits, getPathVar returns the associated +value. For defined file options, the result of getPathVar is undefined, but not failure. The operation may fail with: @@ -1747,11 +1746,11 @@ getFdVar :: PathVar -> Fd -> IO Limit -getFdVar var fd calls fpathconf to obtain the +getFdVar var fd calls fpathconf to obtain the dynamic value of the requested configurable file limit or option associated with the file or directory attached to the open channel fd. -For defined file limits, getFdVar returns the associated -value. For defined file options, the result of getFdVar +For defined file limits, getFdVar returns the associated +value. For defined file options, the result of getFdVar is undefined, but not failure. @@ -1800,7 +1799,7 @@ createPipe :: IO (Fd, Fd) -createPipe calls pipe to create a pipe and returns a pair of +createPipe calls pipe to create a pipe and returns a pair of Fds, the first for reading and the second for writing. @@ -1813,7 +1812,7 @@ dup :: Fd -> IO Fd -dup fd calls dup to duplicate Fd fd to +dup fd calls dup to duplicate Fd fd to another Fd. @@ -1826,7 +1825,7 @@ dupTo :: Fd -> Fd -> IO () -dupTo src dst calls dup2 to duplicate Fd +dupTo src dst calls dup2 to duplicate Fd src to Fd dst. @@ -1839,7 +1838,7 @@ fdClose :: Fd -> IO () -fdClose fd calls close to close Fd fd. +fdClose fd calls close to close Fd fd. @@ -1851,7 +1850,7 @@ fdRead :: Fd -> ByteCount -> IO (String, ByteCount) -fdRead fd nbytes calls read to read at most nbytes +fdRead fd nbytes calls read to read at most nbytes bytes from Fd fd, and returns the result as a string paired with the number of bytes actually read. @@ -1891,7 +1890,7 @@ fdWrite :: Fd -> String -> IO ByteCount -fdWrite fd s calls write to write +fdWrite fd s calls write to write the string s to Fd fd as a contiguous sequence of bytes. It returns the number of bytes successfully written. @@ -1906,7 +1905,7 @@ queryFdOption :: FdOption -> Fd -> IO Bool -getFdOption opt fd calls fcntl to determine whether or +getFdOption opt fd calls fcntl to determine whether or not the flag associated with FdOption opt is set for Fd fd. @@ -1920,7 +1919,7 @@ setFdOption :: Fd -> FdOption -> Bool -> IO () -setFdOption fd opt val calls fcntl to set the flag +setFdOption fd opt val calls fcntl to set the flag associated with FdOption opt on Fd fd to val. @@ -1934,9 +1933,9 @@ getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock)) -getLock fd lock calls fcntl to get the first FileLock +getLock fd lock calls fcntl to get the first FileLock for Fd fd which blocks the FileLock lock. If -no such FileLock exists, getLock returns Nothing. +no such FileLock exists, getLock returns Nothing. Otherwise, it returns Just (pid, block), where block is the blocking FileLock and pid is the ProcessID of the process holding the blocking FileLock. @@ -1951,9 +1950,9 @@ setLock :: Fd -> FileLock -> IO () -setLock fd lock calls fcntl with F_SETLK to set or +setLock fd lock calls fcntl with F_SETLK to set or clear a lock segment for Fd fd as indicated by the -FileLock lock. setLock does not block, but fails with +FileLock lock. setLock does not block, but fails with SystemError if the request cannot be satisfied immediately. @@ -1966,10 +1965,10 @@ waitToSetLock :: Fd -> FileLock -> IO () -waitToSetLock fd lock calls fcntl with F_SETLKW to set +waitToSetLock fd lock calls fcntl with F_SETLKW to set or clear a lock segment for Fd fd as indicated by the FileLock lock. If the request cannot be satisfied -immediately, waitToSetLock blocks until the request can be +immediately, waitToSetLock blocks until the request can be satisfied. @@ -1982,7 +1981,7 @@ fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset -fdSeek fd whence offset calls lseek to position the +fdSeek fd whence offset calls lseek to position the Fd fd at the given offset from the starting location indicated by whence. It returns the resulting offset from the start of the file in bytes. @@ -2034,7 +2033,7 @@ getTerminalAttributes :: Fd -> IO TerminalAttributes -getTerminalAttributes fd calls tcgetattr to obtain +getTerminalAttributes fd calls tcgetattr to obtain the TerminalAttributes associated with Fd fd. @@ -2050,7 +2049,7 @@ setTerminalAttributes :: Fd -setTerminalAttributes fd attr ts calls tcsetattr to change +setTerminalAttributes fd attr ts calls tcsetattr to change the TerminalAttributes associated with Fd fd to attr, when the terminal is in the state indicated by ts. @@ -2064,7 +2063,7 @@ sendBreak :: Fd -> Int -> IO () -sendBreak fd duration calls tcsendbreak to transmit a +sendBreak fd duration calls tcsendbreak to transmit a continuous stream of zero-valued bits on Fd fd for the specified implementation-dependent duration. @@ -2078,7 +2077,7 @@ drainOutput :: Fd -> IO () -drainOutput fd calls tcdrain to block until all output +drainOutput fd calls tcdrain to block until all output written to Fd fd has been transmitted. @@ -2091,7 +2090,7 @@ discardData :: Fd -> QueueSelector -> IO () -discardData fd queues calls tcflush to discard +discardData fd queues calls tcflush to discard pending input and/or output for Fd fd, as indicated by the QueueSelector queues. @@ -2105,7 +2104,7 @@ controlFlow :: Fd -> FlowAction -> IO () -controlFlow fd action calls tcflow to control the +controlFlow fd action calls tcflow to control the flow of data on Fd fd, as indicated by action. @@ -2119,7 +2118,7 @@ getTerminalProcessGroupID :: Fd -> IO ProcessGroupID -getTerminalProcessGroupID fd calls tcgetpgrp to +getTerminalProcessGroupID fd calls tcgetpgrp to obtain the ProcessGroupID of the foreground process group associated with the terminal attached to Fd fd. @@ -2133,7 +2132,7 @@ setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO () -setTerminalProcessGroupID fd pgid calls tcsetpgrp to +setTerminalProcessGroupID fd pgid calls tcsetpgrp to set the ProcessGroupID of the foreground process group associated with the terminal attached to Fd fd to pgid. @@ -2162,7 +2161,7 @@ getGroupEntryForID :: GroupID -> IO GroupEntry -getGroupEntryForID gid calls getgrgid to obtain +getGroupEntryForID gid calls getgrgid to obtain the GroupEntry information associated with GroupID gid. @@ -2194,7 +2193,7 @@ getGroupEntryForName :: String -> IO GroupEntry -getGroupEntryForName name calls getgrnam to obtain +getGroupEntryForName name calls getgrnam to obtain the GroupEntry information associated with the group called name. @@ -2232,7 +2231,7 @@ getUserEntryForID :: UserID -> IO UserEntry -getUserEntryForID gid calls getpwuid to obtain +getUserEntryForID gid calls getpwuid to obtain the UserEntry information associated with UserID uid. The operation may fail with: @@ -2261,7 +2260,7 @@ getUserEntryForName :: String -> IO UserEntry -getUserEntryForName name calls getpwnam to obtain +getUserEntryForName name calls getpwnam to obtain the UserEntry information associated with the user login name. @@ -2303,8 +2302,8 @@ getErrorCode :: IO ErrorCode -getErrorCode returns the current value of the external -variable errno. It never fails. +getErrorCode returns the current value of the external +variable errno. It never fails. @@ -2317,7 +2316,7 @@ setErrorCode :: ErrorCode -> IO () setErrorCode err sets the external -variable errno to err. It never fails. +variable errno to err. It never fails. diff --git a/ghc/docs/users_guide/profiling.sgml b/ghc/docs/users_guide/profiling.sgml index a0bd4f6..613a8bc 100644 --- a/ghc/docs/users_guide/profiling.sgml +++ b/ghc/docs/users_guide/profiling.sgml @@ -5,9 +5,6 @@ profiling, with cost-centres cost-centre profiling - - - Glasgow Haskell comes with a time and space profiling system. Its purpose is to help you improve your understanding of your program's execution behaviour, so you can improve it. @@ -42,18 +39,18 @@ f x y -The costs of the evaluating the expressions bound to output1, -output2 and output3 will be attributed to the ``cost -centres'' Pass1, Pass2 and Pass3, respectively. +The costs of the evaluating the expressions bound to output1, +output2 and output3 will be attributed to the ``cost +centres'' Pass1, Pass2 and Pass3, respectively. The costs of evaluating other expressions, e.g., concat output4, -will be inherited by the scope which referenced the function f. +will be inherited by the scope which referenced the function f. -You can put in cost-centres via _scc_ constructs by hand, as in the +You can put in cost-centres via _scc_ constructs by hand, as in the example above. Perfectly cool. That's probably what you would do if your program divided into obvious ``passes'' or ``phases'', or whatever. @@ -61,9 +58,9 @@ example above. Perfectly cool. That's probably what you If your program is large or you have no clue what might be gobbling -all the time, you can get GHC to mark all functions with _scc_ -constructs, automagically. Add an -auto compilation flag to the -usual -prof option. +all the time, you can get GHC to mark all functions with _scc_ +constructs, automagically. Add an compilation flag to the +usual option. @@ -97,18 +94,18 @@ system. Just visit the Glasgow FP gro To make use of the cost centre profiling system all modules must -be compiled and linked with the -prof option.-prof option -Any _scc_ constructs you've put in your source will spring to life. +be compiled and linked with the option.-prof option +Any _scc_ constructs you've put in your source will spring to life. -Without a -prof option, your _scc_s are ignored; so you can -compiled _scc_-laden code without changing it. +Without a option, your _scc_s are ignored; so you can +compiled _scc_-laden code without changing it. There are a few other profiling-related compilation options. Use them -in addition to -prof. These do not have to be used +in addition to . These do not have to be used consistently for all modules in a program. @@ -116,28 +113,28 @@ consistently for all modules in a program. --auto: +: -auto option cost centres, automatically inserting -GHC will automatically add _scc_ constructs for +GHC will automatically add _scc_ constructs for all top-level, exported functions. --auto-all: +: -auto-all option All top-level functions, exported or not, will be automatically -_scc_'d. +_scc_'d. --caf-all: +: -caf-all option @@ -148,18 +145,18 @@ An ``if all else fails'' option… --ignore-scc: +: -ignore-scc option -Ignore any _scc_ constructs, -so a module which already has _scc_s can be +Ignore any _scc_ constructs, +so a module which already has _scc_s can be compiled for profiling with the annotations ignored. --G<group>: +: -G<group> option @@ -173,10 +170,10 @@ module name. -In addition to the -prof option your system might be setup to enable -you to compile and link with the -prof-details -prof-details +In addition to the option your system might be setup to enable +you to compile and link with the -prof-details option option instead. This enables additional detailed counts -to be reported with the -P RTS option. +to be reported with the RTS option. @@ -191,7 +188,7 @@ to be reported with the -P RTS option. -It isn't enough to compile your program for profiling with -prof! +It isn't enough to compile your program for profiling with ! @@ -202,34 +199,34 @@ set the sampling interval used in time profiling. -Executive summary: ./a.out +RTS -pT produces a time profile in -a.out.prof; ./a.out +RTS -hC produces space-profiling -info which can be mangled by hp2ps and viewed with ghostview +Executive summary: ./a.out +RTS -pT produces a time profile in +a.out.prof; ./a.out +RTS -hC produces space-profiling +info which can be mangled by hp2ps and viewed with ghostview (or equivalent). Profiling runtime flags are passed to your program between the usual -+RTS and -RTS options. + and options. --p<sort> or -P<sort>: + or : -p<sort> RTS option (profiling) -P<sort> RTS option (profiling) time profile serial time profile -The -p? option produces a standard time profile report. -It is written into the file <program>@.prof. +The option produces a standard time profile report. +It is written into the file <program>@.prof. -The -P? option produces a more detailed report containing the +The option produces a more detailed report containing the actual time and allocation data as well. (Not used much.) @@ -239,7 +236,7 @@ report. Valid <sort> options are: -T: +: by time, largest first (the default); @@ -247,7 +244,7 @@ by time, largest first (the default); -A: +: by bytes allocated, largest first; @@ -255,7 +252,7 @@ by bytes allocated, largest first; -C: +: alphabetically by group, module and cost centre. @@ -267,18 +264,18 @@ alphabetically by group, module and cost centre. --i<secs>: +: -i<secs> RTS option (profiling) Set the profiling (sampling) interval to <secs> seconds (the default is 1 second). Fractions are allowed: for example --i0.2 will get 5 samples per second. + will get 5 samples per second. --h<break-down>: +: -h<break-down> RTS option (profiling) @@ -287,8 +284,8 @@ seconds (the default is 1 second). Fractions are allowed: for example Produce a detailed space profile of the heap occupied by live -closures. The profile is written to the file <program>@.hp from -which a PostScript graph can be produced using hp2ps (see +closures. The profile is written to the file <program>@.hp from +which a PostScript graph can be produced using hp2ps (see ). @@ -297,7 +294,7 @@ The heap space profile may be broken down by different criteria: --hC: +: cost centre which produced the closure (the default). @@ -305,7 +302,7 @@ cost centre which produced the closure (the default). --hM: +: cost centre module which produced the closure. @@ -313,7 +310,7 @@ cost centre module which produced the closure. --hG: +: cost centre group which produced the closure. @@ -321,7 +318,7 @@ cost centre group which produced the closure. --hD: +: closure description—a string describing the closure. @@ -329,7 +326,7 @@ closure description—a string describing the closure. --hY: +: closure type—a string describing the closure's type. @@ -348,7 +345,7 @@ closures of interest can be selected (see below). Heap (space) profiling uses hash tables. If these tables should fill the run will abort. The --z<tbl><size>-z<tbl><size> RTS option (profiling) option is used to +-z<tbl><size> RTS option (profiling) option is used to increase the size of the relevant hash table (C, M, G, D or Y, defined as for <break-down> above). The actual size used is the next largest power of 2. @@ -365,7 +362,7 @@ and kind) using the following options: --c{<mod>:<lab>,<mod>:<lab>...}: +}: -c{<lab> RTS option (profiling)} @@ -374,7 +371,7 @@ Selects individual cost centre(s). --m{<mod>,<mod>...}: +}: -m{<mod> RTS option (profiling)} @@ -383,7 +380,7 @@ Selects all cost centres from the module(s) specified. --g{<grp>,<grp>...}: +}: -g{<grp> RTS option (profiling)} @@ -392,7 +389,7 @@ Selects all cost centres from the groups(s) specified. --d{<des>,<des>...}: +}: -d{<des> RTS option (profiling)} @@ -401,7 +398,7 @@ Selects closures which have one of the specified descriptions. --y{<typ>,<typ>...}: +}: -y{<typ> RTS option (profiling)} @@ -410,7 +407,7 @@ Selects closures which have one of the specified type descriptions. --k{<knd>,<knd>...}: +}: -k{<knd> RTS option (profiling)} @@ -449,7 +446,7 @@ centre) is selected by the option (or the option is not specified). -When you run your profiled program with the -p RTS option -p +When you run your profiled program with the RTS option -p RTS option, you get the following information about your ``cost centres'': @@ -480,7 +477,7 @@ different modules. How many times this cost-centre was entered; think -of it as ``I got to the _scc_ construct this many times…'' +of it as ``I got to the _scc_ construct this many times…'' @@ -535,7 +532,7 @@ How many dictionaries this cost centre evaluated. -In addition you can use the -P RTS option to get the following additional information: +In addition you can use the RTS option to get the following additional information: @@ -562,8 +559,8 @@ get the %alloc figure mentioned above. -Finally if you built your program with -prof-details - the -P RTS option will also +Finally if you built your program with + the RTS option will also produce the following information: @@ -631,7 +628,7 @@ Utility programs which produce graphical profiles. -<Literal>hp2ps</Literal>--heap profile to PostScript +<Title><Command>hp2ps</Command>--heap profile to PostScript @@ -653,16 +650,16 @@ hp2ps [flags] [<file>[.stat]] -The program hp2pshp2ps program converts a heap profile -as produced by the -h<break-down>-h<break-down> RTS +The program hp2pshp2ps program converts a heap profile +as produced by the -h<break-down> RTS option runtime option into a PostScript graph of the heap -profile. By convention, the file to be processed by hp2ps has a -.hp extension. The PostScript output is written to <file>@.ps. If -<file> is omitted entirely, then the program behaves as a filter. +profile. By convention, the file to be processed by hp2ps has a +.hp extension. The PostScript output is written to <file>@.ps. If +<file> is omitted entirely, then the program behaves as a filter. -hp2ps is distributed in ghc/utils/hp2ps in a GHC source +hp2ps is distributed in ghc/utils/hp2ps in a GHC source distribution. It was originally developed by Dave Wakeling as part of the HBC/LML heap profiler. @@ -672,64 +669,64 @@ The flags are: --d + -In order to make graphs more readable, hp2ps sorts the shaded +In order to make graphs more readable, hp2ps sorts the shaded bands for each identifier. The default sort ordering is for the bands with the largest area to be stacked on top of the smaller ones. The --d option causes rougher bands (those representing series of + option causes rougher bands (those representing series of values with the largest standard deviations) to be stacked on top of smoother ones. --b + -Normally, hp2ps puts the title of the graph in a small box at the +Normally, hp2ps puts the title of the graph in a small box at the top of the page. However, if the JOB string is too long to fit in a small box (more than 35 characters), then -hp2ps will choose to use a big box instead. The -b -option forces hp2ps to use a big box. +hp2ps will choose to use a big box instead. The +option forces hp2ps to use a big box. --e<float>[in|mm|pt] + Generate encapsulated PostScript suitable for inclusion in LaTeX documents. Usually, the PostScript graph is drawn in landscape mode -in an area 9 inches wide by 6 inches high, and hp2ps arranges +in an area 9 inches wide by 6 inches high, and hp2ps arranges for this area to be approximately centred on a sheet of a4 paper. This format is convenient of studying the graph in detail, but it is -unsuitable for inclusion in LaTeX documents. The -e option +unsuitable for inclusion in LaTeX documents. The option causes the graph to be drawn in portrait mode, with float specifying the width in inches, millimetres or points (the default). The resulting PostScript file conforms to the Encapsulated PostScript (EPS) convention, and it can be included in a LaTeX document using -Rokicki's dvi-to-PostScript converter dvips. +Rokicki's dvi-to-PostScript converter dvips. --g + -Create output suitable for the gs PostScript previewer (or +Create output suitable for the gs PostScript previewer (or similar). In this case the graph is printed in portrait mode without scaling. The output is unsuitable for a laser printer. --l + Normally a profile is limited to 20 bands with additional identifiers -being grouped into an OTHER band. The -l flag removes this +being grouped into an OTHER band. The flag removes this 20 band and limit, producing as many bands as necessary. No key is produced as it won't fit!. It is useful for creation time profiles with many bands. @@ -737,38 +734,38 @@ with many bands. --m<int> + Normally a profile is limited to 20 bands with additional identifiers -being grouped into an OTHER band. The -m flag specifies an +being grouped into an OTHER band. The flag specifies an alternative band limit (the maximum is 20). --m0 requests the band limit to be removed. As many bands as + requests the band limit to be removed. As many bands as necessary are produced. However no key is produced as it won't fit! It is useful for displaying creation time profiles with many bands. --p + Use previous parameters. By default, the PostScript graph is automatically scaled both horizontally and vertically so that it fills the page. However, when preparing a series of graphs for use in a presentation, it is often useful to draw a new graph using the same -scale, shading and ordering as a previous one. The -p flag causes +scale, shading and ordering as a previous one. The flag causes the graph to be drawn using the parameters determined by a previous -run of hp2ps on file. These are extracted from -file@.aux. +run of hp2ps on file. These are extracted from +file@.aux. --s + Use a small box for the title. @@ -776,22 +773,22 @@ Use a small box for the title. --t<float> + Normally trace elements which sum to a total of less than 1% of the -profile are removed from the profile. The -t option allows this +profile are removed from the profile. The option allows this percentage to be modified (maximum 5%). --t0 requests no trace elements to be removed from the profile, + requests no trace elements to be removed from the profile, ensuring that all the data will be displayed. --? + Print out usage information. @@ -804,7 +801,7 @@ Print out usage information. -<Literal>stat2resid</Literal>—residency info from GC stats +<Title><Command>stat2resid</Command>—residency info from GC stats @@ -826,30 +823,30 @@ stat2resid [<file>[.stat] [<outfile>]] -The program stat2residstat2resid converts a detailed +The program stat2residstat2resid converts a detailed garbage collection statistics file produced by the --S-S RTS option runtime option into a PostScript heap +-S RTS option runtime option into a PostScript heap residency graph. The garbage collection statistics file can be produced without compiling your program for profiling. -By convention, the file to be processed by stat2resid has a -.stat extension. If the <outfile> is not specified the -PostScript will be written to <file>@.resid.ps. If -<file> is omitted entirely, then the program behaves as a filter. +By convention, the file to be processed by stat2resid has a +.stat extension. If the <outfile> is not specified the +PostScript will be written to <file>@.resid.ps. If +<file> is omitted entirely, then the program behaves as a filter. The plot can not be produced from the statistics file for a generational collector, though a suitable stats file can be produced -using the -F2s-F2s RTS option runtime option when the +using the -F2s RTS option runtime option when the program has been compiled for generational garbage collection (the default). -stat2resid is distributed in ghc/utils/stat2resid in a GHC source +stat2resid is distributed in ghc/utils/stat2resid in a GHC source distribution. @@ -892,13 +889,13 @@ appropriate libraries and things when you made the system. See To get your compiled program to spit out the ticky-ticky numbers, use -a -r RTS option-r RTS option. See . +a RTS option-r RTS option. See . -Compiling your program with the -ticky switch yields an executable +Compiling your program with the switch yields an executable that performs these counts. Here is a sample ticky-ticky statistics -file, generated by the invocation foo +RTS -rfoo.ticky. +file, generated by the invocation foo +RTS -rfoo.ticky. diff --git a/ghc/docs/users_guide/runtime_control.sgml b/ghc/docs/users_guide/runtime_control.sgml index b566fa7..e4f02d6 100644 --- a/ghc/docs/users_guide/runtime_control.sgml +++ b/ghc/docs/users_guide/runtime_control.sgml @@ -21,8 +21,8 @@ command-line arguments to your program. When your Haskell program starts up, its RTS extracts command-line -arguments bracketed between +RTS+RTS option and --RTS-RTS option as its own. For example: +arguments bracketed between +RTS option and +-RTS option as its own. For example: @@ -34,13 +34,13 @@ arguments bracketed between +RTS+RTS opti -The RTS will snaffle -p -S for itself, and the remaining arguments --f -h foo bar will be handed to your program if/when it calls -System.getArgs. +The RTS will snaffle for itself, and the remaining arguments + will be handed to your program if/when it calls +System.getArgs. -No -RTS option is required if the runtime-system options extend to +No option is required if the runtime-system options extend to the end of the command line, as in this example: @@ -55,7 +55,7 @@ the end of the command line, as in this example: If you absolutely positively want all the rest of the options in a command line to go to the program (and not the RTS), use a ---RTS--RTS option. +--RTS option. @@ -66,17 +66,17 @@ counters is your fault!) -Giving a +RTS -f-f RTS option option will print out the +Giving a -f RTS option option will print out the RTS options actually available in your program (which vary, depending on how you compiled). NOTE: to send RTS options to the compiler itself, you need to prefix -the option with -optCrts, eg. to increase the maximum heap size for -a compilation to 128M, you would add -optCrts-M128m to the command +the option with , eg. to increase the maximum heap size for +a compilation to 128M, you would add to the command line. The compiler understands some options directly without needing --optCrts: these are -H and -K. +: these are and . @@ -98,7 +98,7 @@ maximum performance. --A<size>: +: -A<size> RTS option @@ -108,7 +108,7 @@ maximum performance. [Default: 256k] Set the allocation area size used by the garbage collector. The allocation area (actually generation 0 step 0) is -fixed and is never resized (unless you use -H, below). +fixed and is never resized (unless you use , below). @@ -118,15 +118,15 @@ fewer garbage collections and less promotion). -With only 1 generation (-G1) the -A option specifies the +With only 1 generation () the option specifies the minimum allocation area, since the actual size of the allocation area will be resized according to the amount of data in the heap (see --F, below). +, below). --F<factor>: +: -F<factor> RTS option @@ -144,19 +144,19 @@ to 4M before collecting it again. The default seems to work well here. If you have plenty of memory, it -is usually better to use -H<size> than to increase --F<factor>. +is usually better to use than to increase +. -The -F setting will be automatically reduced by the garbage -collector when the maximum heap size (the -M<size> setting) +The setting will be automatically reduced by the garbage +collector when the maximum heap size (the setting) is approaching. --G<generations>: +: -G<generations> RTS option @@ -173,17 +173,17 @@ collected. -Specifying 1 generation with +RTS -G1 gives you a simple 2-space -collector, as you would expect. In a 2-space collector, the -A +Specifying 1 generation with gives you a simple 2-space +collector, as you would expect. In a 2-space collector, the option (see above) specifies the minimum allocation area size, since the allocation area will grow with the amount of live data in the heap. In a multi-generational collector the allocation area is a -fixed size (unless you use the -H option, see below). +fixed size (unless you use the option, see below). --H<size>: +: -H<size> RTS option @@ -200,14 +200,14 @@ expanded to retain reasonable performance. By default, the heap will start small, and grow and shrink as necessary. This can be bad for performance, so if you have plenty of -memory it's worthwhile supplying a big -H<size>. For -improving GC performance, using -H<size> is usually a better -bet than -A<size>. +memory it's worthwhile supplying a big . For +improving GC performance, using is usually a better +bet than . --k<size>: +: -k<size> RTS option @@ -229,7 +229,7 @@ down on unnecessary stack growth while the program is starting up. --K<size>: +: -K<size> RTS option @@ -245,7 +245,7 @@ infinite loop. --m<n>: +: -m<n> RTS option @@ -256,7 +256,7 @@ The default is 3%. --M<size>: +: -M<size> RTS option @@ -274,15 +274,15 @@ by the operating system. --s<file> or -S<file>: + or : -S<file> RTS option -s<file> RTS option -Write modest (-s) or verbose (-S) garbage-collector -statistics into file <file>. The default <file> is -<program>@.stat. The <file> stderr is treated -specially, with the output really being sent to stderr. +Write modest () or verbose () garbage-collector +statistics into file <file>. The default <file> is +<program>@.stat. The <file> stderr is treated +specially, with the output really being sent to stderr. @@ -323,7 +323,7 @@ recommended for everyday use! --B: +: -B RTS option @@ -342,19 +342,19 @@ others in the same office…'' --r<file>: +: -r <file> RTS option ticky ticky profiling Produce ``ticky-ticky'' statistics at the end of the program run. -The <file> business works just like on the -S RTS option (above). +The <file> business works just like on the RTS option (above). ``Ticky-ticky'' statistics are counts of various program actions (updates, enters, etc.) The program must have been compiled using --ticky-ticky option (a.k.a. ``ticky-ticky profiling''), +-ticky option (a.k.a. ``ticky-ticky profiling''), and, for it to 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 @@ -363,18 +363,18 @@ information, see . --D<num>: +: -D RTS option An RTS debugging flag; varying quantities of output depending on which bits are set in <num>. Only works if the RTS was compiled with the -DEBUG option. + option. --Z: +: -Z RTS option @@ -409,10 +409,10 @@ command line, you can override the defaults. -The function defaultsHookdefaultHook lets you change various +The function defaultsHookdefaultHook lets you change various RTS options. The commonest use for this is to give your program a default heap and/or stack size that is greater than the default. For -example, to set -H8m -K1m: +example, to set : @@ -431,7 +431,7 @@ void defaultsHook (void) { Don't use powers of two for heap/stack sizes: these are more likely to interact badly with direct-mapped caches. The full set of flags is -defined in ghc/rts/RtsFlags.h the the GHC source tree. +defined in ghc/rts/RtsFlags.h the the GHC source tree. @@ -444,16 +444,16 @@ follows: -void ErrorHdrHook (FILE *): +void ErrorHdrHook (FILE *): ErrorHdrHook -What's printed out before the message from error. +What's printed out before the message from error. -void OutOfHeapHook (unsigned long, unsigned long): +void OutOfHeapHook (unsigned long, unsigned long): OutOfHeapHook @@ -462,7 +462,7 @@ The heap-overflow message. -void StackOverflowHook (long int): +void StackOverflowHook (long int): StackOverflowHook @@ -471,16 +471,16 @@ The stack-overflow message. -void MallocFailHook (long int): +void MallocFailHook (long int): MallocFailHook -The message printed if malloc fails. +The message printed if malloc fails. -void PatErrorHdrHook (FILE *): +void PatErrorHdrHook (FILE *): PatErrorHdrHook @@ -490,20 +490,20 @@ that were not handled by the Haskell programmer). -void PreTraceHook (FILE *): +void PreTraceHook (FILE *): PreTraceHook -What's printed out before a trace message. +What's printed out before a trace message. -void PostTraceHook (FILE *): +void PostTraceHook (FILE *): PostTraceHook -What's printed out after a trace message. +What's printed out after a trace message. diff --git a/ghc/docs/users_guide/sooner.sgml b/ghc/docs/users_guide/sooner.sgml index 63ede49..e183562 100644 --- a/ghc/docs/users_guide/sooner.sgml +++ b/ghc/docs/users_guide/sooner.sgml @@ -16,7 +16,7 @@ Please advise us of other ``helpful hints'' that should go here! -Don't use -O or (especially) -O2: +Don't use or (especially) : By using them, you are telling GHC that you are willing to suffer @@ -24,7 +24,7 @@ longer compilation times for better-quality code. -GHC is surprisingly zippy for normal compilations without -O! +GHC is surprisingly zippy for normal compilations without ! @@ -34,8 +34,8 @@ GHC is surprisingly zippy for normal compilations without -O! Within reason, more memory for heap space means less garbage collection for GHC, which means less compilation time. If you use -the -Rgc-stats option, you'll get a garbage-collector report. -(Again, you can use the cheap-and-nasty -optCrts-Sstderr option to +the option, you'll get a garbage-collector report. +(Again, you can use the cheap-and-nasty option to send the GC stats straight to standard error.) @@ -47,13 +47,13 @@ collecting, then more memory would help. If the heap size is approaching the maximum (64M by default), and you have lots of memory, try increasing the maximum with the --M<size>-M<size> option option, e.g.: ghc -c -O --M1024m Foo.hs. +-M<size> 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 -A<size>-A<size> option +might also help: use the -A<size> option option. @@ -71,7 +71,7 @@ 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 terrible! Use something -like the csh-builtin time command to get a report on how many page +like the csh-builtin time command to get a report on how many page faults you're getting. @@ -99,7 +99,7 @@ your disks directly mounted. -Don't derive/use Read unnecessarily: +Don't derive/use Read unnecessarily: It's ugly and slow. @@ -123,20 +123,20 @@ to correct it. The parts of the compiler that seem most prone to wandering off for a long time are the abstract interpreters (strictness and update analysers). You can turn these off individually with --fno-strictness-fno-strictness anti-option and --fno-update-analysis.-fno-update-analysis anti-option +-fno-strictness anti-option and +.-fno-update-analysis anti-option To figure out which part of the compiler is badly behaved, the --dshow-passes-dshow-passes option option is your +-dshow-passes option option is your friend. If your module has big wads of constant data, GHC may produce a huge basic block that will cause the native-code generator's register -allocator to founder. Bring on -fvia-C-fvia-C option +allocator to founder. Bring on -fvia-C option (not that GCC will be that quick about it, either). @@ -145,7 +145,7 @@ allocator to founder. Bring on -fvia-C-f Avoid the consistency-check on linking: -Use -no-link-chk-no-link-chk; saves effort. This is +Use -no-link-chk; saves effort. This is probably safe in a I-only-compile-things-one-way setup. @@ -211,16 +211,16 @@ faster''… -Optimise, using -O or -O2: +Optimise, using or : This is the most basic way to make your program go faster. Compilation time will be slower, -especially with -O2. +especially with . -At present, -O2 is nearly indistinguishable from -O. +At present, is nearly indistinguishable from . @@ -228,7 +228,7 @@ At present, -O2 is nearly indistinguishable from -O< Compile via C and crank up GCC: -Even with -O, GHC tries to +Even with , GHC tries to use a native-code generator, if available. But the native code-generator is designed to be quick, not mind-bogglingly clever. Better to let GCC have a go, as it tries much harder on register @@ -236,7 +236,7 @@ allocation, etc. -So, when we want very fast code, we use: -O -fvia-C -O2-for-C. +So, when we want very fast code, we use: . @@ -258,12 +258,12 @@ loop. How can you squash it? Signatures are the basic trick; putting them on exported, top-level functions is good software-engineering practice, anyway. (Tip: using --fwarn-missing-signatures-fwarn-missing-signatures +-fwarn-missing-signatures option can help enforce good signature-practice). -The automatic specialisation of overloaded functions (with -O) +The automatic specialisation of overloaded functions (with ) should take care of overloaded local and/or unexported functions. @@ -377,22 +377,22 @@ Don't guess—look it up. Look for your function in the interface file, then for 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(...) is strict and -``unpackable'' (very good), and A is absent (very good). +gives the strictness of 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). -For an ``unpackable'' U(...) argument, the info inside +For an ``unpackable'' 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 means ``the first component of the +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 \& third).'' -If the function isn't exported, just compile with the extra flag -ddump-simpl; +If the function isn't exported, just compile with the extra flag ; next to the signature for any binder, it will print the self-same pragmatic information as would be put in an interface file. (Besides, Core syntax is fun to look at!) @@ -431,7 +431,7 @@ they are not exported. (The form in which GHC manipulates your code.) Just run your -compilation with -ddump-simpl (don't forget the -O). +compilation with (don't forget the ). @@ -454,7 +454,7 @@ types. -Use _ccall_s (a GHC extension) to plug into fast libraries: +Use _ccall_s (a GHC extension) to plug into fast libraries: This may take real work, but… There exist piles of @@ -496,11 +496,11 @@ true on a 64-bit machine. Use a bigger heap! -If your program's GC stats (-S-S RTS option RTS option) +If your program's GC stats (-S RTS option RTS option) indicate that it's doing lots of garbage-collection (say, more than 20% of execution time), more memory might help—with the --M<size>-M<size> RTS option or --A<size>-A<size> RTS option RTS options (see +-M<size> RTS option or +-A<size> RTS option RTS options (see ). @@ -521,7 +521,7 @@ indicate that it's doing lots of garbage-collection (say, more than Decrease the ``go-for-it'' threshold for unfolding smallish expressions. Give a --funfolding-use-threshold0-funfolding-use-threshold0 +-funfolding-use-threshold0 option option for the extreme case. (``Only unfoldings with zero cost should proceed.'') Warning: except in certain specialiised cases (like Happy parsers) this is likely to actually @@ -530,7 +530,7 @@ generally enables extra simplifying optimisations to be performed. -Avoid Read. +Avoid Read. @@ -551,10 +551,10 @@ Use strip on your executables. ``I think I have a space leak…'' Re-run your program with -+RTS -Sstderr,-Sstderr RTS option and remove all doubt! +,-Sstderr RTS option and remove all doubt! (You'll see the heap usage get bigger and bigger…) [Hmmm…this -might be even easier with the -F2s-F2s RTS option RTS -option; so… ./a.out +RTS -Sstderr -F2s...] +might be even easier with the -F2s RTS option RTS +option; so… ./a.out +RTS -Sstderr -F2s...] diff --git a/ghc/docs/users_guide/users_guide.sgml b/ghc/docs/users_guide/users_guide.sgml index 2c6e285..119034a 100644 --- a/ghc/docs/users_guide/users_guide.sgml +++ b/ghc/docs/users_guide/users_guide.sgml @@ -1,4 +1,4 @@ - diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index 4653494..f83a3fb 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -5,13 +5,10 @@ GHC, using using GHC - - - GHC is a command-line compiler: in order to compile a Haskell program, GHC must be invoked on the source file(s) by typing a command to the shell. The steps involved in compiling a program can be automated -using the make tool (this is especially useful if the program +using the make tool (this is especially useful if the program consists of multiple source files which depend on each other). This section describes how to use GHC from the command-line. @@ -43,12 +40,12 @@ Command-line arguments are either options or file names. Command-line options begin with -. They may not be -grouped: -vO is different from -v -O. Options need not -precede filenames: e.g., ghc *.o -o foo. All options are +grouped: is different from . Options need not +precede filenames: e.g., ghc *.o -o foo. All options are processed and then applied to all files; you cannot, for example, invoke -ghc -c -O1 Foo.hs -O2 Bar.hs to apply different optimisation -levels to the files Foo.hs and Bar.hs. For conflicting -options, e.g., -c -S, we reserve the right to do anything we +ghc -c -O1 Foo.hs -O2 Bar.hs to apply different optimisation +levels to the files Foo.hs and Bar.hs. For conflicting +options, e.g., , we reserve the right to do anything we want. (Usually, the last one applies.) @@ -64,7 +61,7 @@ want. (Usually, the last one applies.) -File names with ``meaningful'' suffixes (e.g., .lhs or .o) +File names with ``meaningful'' suffixes (e.g., .lhs or .o) cause the ``right thing'' to happen to those files. @@ -72,7 +69,7 @@ cause the ``right thing'' to happen to those files. -.lhs: +.lhs: lhs suffix @@ -81,7 +78,7 @@ A ``literate Haskell'' module. -.hs: +.hs: A not-so-literate Haskell module. @@ -89,7 +86,7 @@ A not-so-literate Haskell module. -.hi: +.hi: A Haskell interface file, probably compiler-generated. @@ -97,7 +94,7 @@ A Haskell interface file, probably compiler-generated. -.hc: +.hc: Intermediate C file produced by the Haskell compiler. @@ -105,7 +102,7 @@ Intermediate C file produced by the Haskell compiler. -.c: +.c: A C file not produced by the Haskell compiler. @@ -113,7 +110,7 @@ A C file not produced by the Haskell compiler. -.s: +.s: An assembly-language source file, usually @@ -122,7 +119,7 @@ produced by the compiler. -.o: +.o: An object file, produced by an assembler. @@ -149,29 +146,29 @@ to the linker. -A good option to start with is the -help (or -?) option. +A good option to start with is the (or ) option. -help option -? option GHC spews a long message to standard output and then exits. -The -v-v option option makes GHC verbose: it +The -v option option makes GHC verbose: it reports its version number and shows (on stderr) exactly how it invokes each phase of the compilation system. Moreover, it passes -the -v flag to most phases; each reports +the flag to most phases; each reports its version number (and possibly some other information). -Please, oh please, use the -v option when reporting bugs! +Please, oh please, use the option when reporting bugs! Knowing that you ran the right bits in the right order is always the first thing we want to verify. If you're just interested in the compiler version number, the ---version--version option option prints out a +--version option option prints out a one-line string containing the requested info. @@ -184,7 +181,7 @@ one-line string containing the requested info. order of passes in GHC pass ordering in GHC -The basic task of the ghc driver is to run each input file +The basic task of the ghc driver is to run each input file through the right phases (compiling, linking, etc.). @@ -262,7 +259,7 @@ linker -Thus, a common invocation would be: ghc -c Foo.hs +Thus, a common invocation would be: ghc -c Foo.hs @@ -272,22 +269,22 @@ native-code generator is used (producing assembly language) or not -The option -cpp-cpp option must be given for the C +The option -cpp option must be given for the C pre-processor phase to be run, that is, the pre-processor will be run over your Haskell source file before continuing. -The option -E-E option runs just the pre-processing +The option -E option runs just the pre-processing passes of the compiler, outputting the result on stdout before stopping. If used in conjunction with -cpp, the output is the code blocks of the original (literal) source after having put it -through the grinder that is the C pre-processor. Sans -cpp, the +through the grinder that is the C pre-processor. Sans , the output is the de-litted version of the original source. -The option -optcpp-E-optcpp-E option runs just the +The option -optcpp-E option runs just the pre-processing stage of the C-compiling phase, sending the result to stdout. (For debugging or obfuscation contests, usually.) @@ -303,24 +300,24 @@ stdout. (For debugging or obfuscation contests, usually.) -GHC's compiled output normally goes into a .hc, .o, etc., file, -depending on the last-run compilation phase. The option -o -foo-o option re-directs the output of that last-run -phase to file foo. +GHC's compiled output normally goes into a .hc, .o, etc., file, +depending on the last-run compilation phase. The option -o option re-directs the output of that last-run +phase to file foo. Note: this ``feature'' can be counterintuitive: -ghc -C -o foo.o foo.hs will put the intermediate C code in the -file foo.o, name notwithstanding! +ghc -C -o foo.o foo.hs will put the intermediate C code in the +file foo.o, name notwithstanding! -EXOTICA: But the -o option isn't of much use if you have +EXOTICA: But the option isn't of much use if you have several input files… Non-interface output files are normally put in the same directory as their corresponding input file came from. You may specify that they be put in another directory -using the -odir <dir>-odir <dir> option (the +using the -odir <dir> option (the ``Oh, dear'' option). For example: @@ -333,40 +330,40 @@ using the -odir <dir>-odir <dir& -The output files, Foo.o, Bar.o, and Bumble.o would be +The output files, Foo.o, Bar.o, and Bumble.o would be put into a subdirectory named after the architecture of the executing -machine (sun4, mips, etc). The directory must already +machine (sun4, mips, etc). The directory must already exist; it won't be created. -Note that the -odir option does not affect where the +Note that the option does not affect where the interface files are put. In the above example, they would still be -put in parse/Foo.hi, parse/Bar.hi, and gurgle/Bumble.hi. +put in parse/Foo.hi, parse/Bar.hi, and gurgle/Bumble.hi. -MORE EXOTICA: The -osuf <suffix>-osuf <suffix> -option will change the .o file suffix for object files to +MORE 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>-hisuf <suffix> -option will change the .hi file suffix for non-system +Similarly, the -hisuf <suffix> +option will change the .hi file suffix for non-system interface files (see ). -The -hisuf/-osuf game is useful if you want to compile a program +The / game is useful if you want to compile a program with both GHC and HBC (say) in the same directory. Let HBC use the -standard .hi/.o suffixes; add -hisuf g_hi -osuf g_o to your -make rule for GHC compiling… +standard .hi/.o suffixes; add to your +make rule for GHC compiling… -FURTHER EXOTICA: If you are doing a normal .hs-to-.o compilation -but would like to hang onto the intermediate .hc C file, just -throw in a -keep-hc-file-too option-keep-hc-file-too option. +FURTHER EXOTICA: If you are doing a normal .hs-to-.o compilation +but would like to hang onto the intermediate .hc C file, just +throw in a option-keep-hc-file-too option. If you would like to look at the assembler output, toss in a --keep-s-file-too,-keep-s-file-too option too. +,-keep-s-file-too option too. @@ -379,8 +376,8 @@ If you would like to look at the assembler output, toss in a Sometimes, you may cause GHC to be rather chatty on standard error; -with -v, for example. You can instruct GHC to append this -output to a particular log file with a -odump <blah>-odump +with , for example. You can instruct GHC to append this +output to a particular log file with a -odump <blah> option option. @@ -395,23 +392,23 @@ output to a particular log file with a -odump <blah> -If you have trouble because of running out of space in /tmp (or +If you have trouble because of running out of space in /tmp (or wherever your installation thinks temporary files should go), you may -use the -tmpdir <dir>-tmpdir <dir> option option -to specify an alternate directory. For example, -tmpdir . says to +use the -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 +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 TMPDIR variable when building GHC, and -never worry about TMPDIR again. (see the build documentation). +Even better idea: Set the TMPDIR variable when building GHC, and +never worry about TMPDIR again. (see the build documentation). @@ -429,8 +426,8 @@ GHC has a number of options that select which types of non-fatal error messages, otherwise known as warnings, can be generated during compilation. By default, you get a standard set of warnings which are generally likely to indicate bugs in your program. These are: --fwarn-overlpapping-patterns, -fwarn-duplicate-exports, and --fwarn-missing-methods. The following flags are simple ways to +, , and +. The following flags are simple ways to select standard ``packages'' of warnings: @@ -438,7 +435,7 @@ select standard ``packages'' of warnings: --Wnot: +: -Wnot option @@ -448,28 +445,28 @@ Turns off all warnings, including the standard ones. --w: +: -w option -Synonym for -Wnot. +Synonym for . --W: +: -W option -Provides the standard warnings plus -fwarn-incomplete-patterns, --fwarn-unused-imports and -fwarn-unused-binds. +Provides the standard warnings plus , + and . --Wall: +: -Wall option @@ -483,7 +480,7 @@ Turns on all warning options. The full set of warning options is described below. To turn off any -warning, simply give the corresponding -fno-warn-... option on +warning, simply give the corresponding option on the command line. @@ -491,7 +488,7 @@ the command line. --fwarn-name-shadowing: +: -fwarn-name-shadowing option @@ -510,7 +507,7 @@ definitions. --fwarn-overlapping-patterns: +: -fwarn-overlapping-patterns option @@ -530,7 +527,7 @@ f "2" = 2 -where the last pattern match in f won't ever be reached, as the +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. @@ -538,15 +535,15 @@ is a programmer mistake/error, so this option is enabled by default. --fwarn-incomplete-patterns: +: -fwarn-incomplete-patterns option incomplete patterns, warning patterns, incomplete -Similarly for incomplete patterns, the function g below will fail +Similarly for incomplete patterns, the function g below will fail when applied to non-empty lists, so the compiler will emit a warning -about this when -fwarn-incomplete-patterns is enabled. +about this when is enabled. @@ -565,7 +562,7 @@ functions. --fwarn-missing-methods: +: -fwarn-missing-methods option @@ -579,7 +576,7 @@ class declaration has no default declaration for them. --fwarn-missing-fields: +: -fwarn-missing-fields option @@ -595,7 +592,7 @@ error. --fwarn-unused-imports: +: -fwarn-unused-imports option @@ -607,7 +604,7 @@ Report any objects that are explicitly imported but never used. --fwarn-unused-binds: +: -fwarn-unused-binds option @@ -620,7 +617,7 @@ not exported. --fwarn-unused-matches: +: -fwarn-unused-matches option @@ -628,14 +625,14 @@ not exported. matches, unused 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. To eliminate the warning, +y = [] would report x and y as unused. To eliminate the warning, all unused variables can be replaced with wildcards. --fwarn-duplicate-exports: +: -fwarn-duplicate-exports option @@ -654,7 +651,7 @@ This option is on by default. --fwarn-type-defaults: +: -fwarn-type-defaults option @@ -663,7 +660,7 @@ Have the compiler warn/inform you where in your source 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 otherwise unconstrained value 1 to be given +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 differences in performance and behaviour, hence the usefulness of being non-silent about this. @@ -676,13 +673,13 @@ This warning is off by default. --fwarn-missing-signatures: +: -fwarn-missing-signatures option type signatures, missing If you would like GHC to check that every top-level function/value has -a type signature, use the -fwarn-missing-signatures option. This +a type signature, use the option. This option is off by default. @@ -691,7 +688,7 @@ option is off by default. -If you're feeling really paranoid, the -dcore-lint +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.) @@ -723,17 +720,17 @@ This section describes how GHC supports separate compilation. -When GHC compiles a source file F which contains a module A, say, -it generates an object F.o, and a companion interface -file A.hi. The interface file is not intended for human +When GHC compiles a source file F which contains a module A, say, +it generates an object F.o, and a companion interface +file A.hi. The interface file is not intended for human consumption, as you'll see if you take a look at one. It's merely there to help the compiler compile other modules in the same program. NOTE: Having the name of the interface file follow the module name and -not the file name, means that working with tools such as make(1) -become harder. make implicitly assumes that any output files +not the file name, means that working with tools such as make +become harder. make implicitly assumes that any output files produced by processing a translation unit will have file names that can be derived from the file name of the translation unit. For instance, pattern rules becomes unusable. For this reason, we @@ -743,7 +740,7 @@ recommend you stick to using the same file name as the module name. The interface file for A contains information needed by the compiler when it compiles any module B that imports A, whether directly or -indirectly. When compiling B, GHC will read A.hi to find the +indirectly. When compiling B, GHC will read A.hi to find the details that it needs to know about things defined in A. @@ -751,27 +748,27 @@ details that it needs to know about things defined in A. Furthermore, when compiling module C which imports B, GHC may decide that it needs to know something about A—for example, B might export a function that involves a type defined in A. In this -case, GHC will go and read A.hi even though C does not explicitly +case, GHC will go and read A.hi even though C does not explicitly import A at all. The interface file may contain all sorts of things that aren't explicitly exported from A by the programmer. For example, even -though a data type is exported abstractly, A.hi will contain the -full data type definition. For small function definitions, A.hi +though a data type is exported abstractly, A.hi will contain the +full data type definition. For small function definitions, A.hi will contain the complete definition of the function. For bigger -functions, A.hi will contain strictness information about the -function. And so on. GHC puts much more information into .hi files -when optimisation is turned on with the -O flag. Without -O it -puts in just the minimum; with -O it lobs in a whole pile of stuff. +functions, A.hi will contain strictness information about the +function. And so on. GHC puts much more information into .hi files +when optimisation is turned on with the flag. Without it +puts in just the minimum; with it lobs in a whole pile of stuff. optimsation, effect on .hi files -A.hi should really be thought of as a compiler-readable version of -A.o. If you use a .hi file that wasn't generated by the same -compilation run that generates the .o file the compiler may assume +A.hi should really be thought of as a compiler-readable version of +A.o. If you use a .hi file that wasn't generated by the same +compilation run that generates the .o file the compiler may assume all sorts of incorrect things about A, resulting in core dumps and other unpleasant happenings. @@ -789,8 +786,8 @@ other unpleasant happenings. In your program, you import a module Foo by saying -import Foo. GHC goes looking for an interface file, Foo.hi. -It has a builtin list of directories (notably including .) where +import Foo. GHC goes looking for an interface file, Foo.hi. +It has a builtin list of directories (notably including .) where it looks. @@ -798,20 +795,20 @@ it looks. --i<dirs> + -i<dirs> optionThis flag -prepends a colon-separated list of dirs to the ``import +prepends a colon-separated list of dirs to the ``import directories'' list. See also for the significance of using -relative and absolute pathnames in the -i list. +relative and absolute pathnames in the list. --i + resets the ``import directories'' list back to nothing. @@ -820,12 +817,12 @@ resets the ``import directories'' list back to nothing. --fno-implicit-prelude + -fno-implicit-prelude option -GHC normally imports Prelude.hi files for you. If you'd rather it -didn't, then give it a -fno-implicit-prelude option. You are +GHC normally imports Prelude.hi files for you. If you'd rather it +didn't, then give it a option. You are unlikely to get very far without a Prelude, but, hey, it's a free country. @@ -833,12 +830,12 @@ country. --syslib <lib> + -syslib <lib> option If you are using a system-supplied non-Prelude library (e.g., the -POSIX library), just use a -syslib posix option (for example). The +POSIX library), just use a option (for example). The right interface files should then be available. lists the libraries available by this mechanism. @@ -846,14 +843,14 @@ libraries available by this mechanism. --I<dir> + -I<dir> option -Once a Haskell module has been compiled to C (.hc file), you may -wish to specify where GHC tells the C compiler to look for .h files. -(Or, if you are using the -cpp option-cpp option, where -it tells the C pre-processor to look…) For this purpose, use a -I +Once a Haskell module has been compiled to C (.hc file), you may +wish to specify where GHC tells the C compiler to look for .h files. +(Or, if you are using the option-cpp option, where +it tells the C pre-processor to look…) For this purpose, use a option in the usual C-ish way. @@ -871,30 +868,30 @@ option in the usual C-ish way. interface files, options The interface output may be directed to another file -bar2/Wurble.iface with the option -ohi bar2/Wurble.iface-ohi +bar2/Wurble.iface with the option -ohi <file> option (not recommended). -To avoid generating an interface file at all, use a -nohi +To avoid generating an interface file at all, use a option.-nohi option -The compiler does not overwrite an existing .hi interface file if +The compiler does not overwrite an existing .hi interface file if the new one is byte-for-byte the same as the old one; this is friendly -to make. When an interface does change, it is often enlightening to -be informed. The -hi-diffs-hi-diffs option option will -make ghc run diff on the old and new .hi files. You can also +to make. When an interface does change, it is often enlightening to +be informed. The -hi-diffs option option will +make GHC run diff on the old and new .hi files. You can also record the difference in the interface file itself, the --keep-hi-diffs-keep-hi-diffs option takes care of that. +-keep-hi-diffs option takes care of that. -The .hi files from GHC contain ``usage'' information which changes +The .hi files from GHC contain ``usage'' information which changes often and uninterestingly. If you really want to see these changes reported, you need to use the --hi-diffs-with-usages-hi-diffs-with-usages option +-hi-diffs-with-usages option option. @@ -903,7 +900,7 @@ Interface files are normally jammed full of compiler-produced pragmas, which record arities, strictness info, etc. If you think these pragmas are messing you up (or you are doing some kind of weird experiment), you can tell GHC to ignore them with the --fignore-interface-pragmas-fignore-interface-pragmas +-fignore-interface-pragmas option option. @@ -912,7 +909,7 @@ When compiling without optimisations on, the compiler is extra-careful about not slurping in data constructors and instance declarations that it will not need. If you believe it is getting it wrong and not importing stuff which you think it should, this optimisation can be -turned off with -fno-prune-tydecls and -fno-prune-instdecls. +turned off with and . -fno-prune-tydecls option-fno-prune-instdecls option @@ -933,19 +930,19 @@ Haskell libraries. -In the olden days, GHC compared the newly-generated .hi file with +In the olden days, GHC compared the newly-generated .hi file with the previous version; if they were identical, it left the old one alone and didn't change its modification date. In consequence, -importers of a module with an unchanged output .hi file were not +importers of a module with an unchanged output .hi file were not recompiled. This doesn't work any more. In our earlier example, module C does -not import module A directly, yet changes to A.hi should force a +not import module A directly, yet changes to A.hi should force a recompilation of C. And some changes to A (changing the definition of a function that appears in an inlining of a function -exported by B, say) may conceivably not change B.hi one jot. So +exported by B, say) may conceivably not change B.hi one jot. So now… @@ -954,7 +951,7 @@ GHC keeps a version number on each interface file, and on each type signature within the interface file. It also keeps in every interface file a list of the version numbers of everything it used when it last compiled the file. If the source file's modification date is earlier -than the .o file's date (i.e. the source hasn't changed since the +than the .o file's date (i.e. the source hasn't changed since the file was last compiled), GHC will be clever. It compares the version numbers on the things it needs this time with the version numbers on the things it needed last time (gleaned from the interface file of the @@ -966,32 +963,28 @@ What a beautiful sight! GHC only keeps detailed dependency information for ``user'' modules, not for ``library'' modules. It distinguishes the two by a hack: a module -whose .hi file has an absolute path name is considered a library module, +whose .hi file has an absolute path name is considered a library module, while a relative path name indicates a user module. So if you have a multi-directory application, use relative path names in your --i path, to force GHC to record detailed dependency information. + path, to force GHC to record detailed dependency information. Use absolute path names only for directories containing slowly-changing library modules. -A path is considered ``absolute'' if it starts with ``/'', or -``A:/'', or ``A:\'' (or ``B:/'', ``B:\'' etc). +A path is considered ``absolute'' if it starts with ``/'', or +``A:/'', or ``A:\'' (or ``B:/'', ``B:\'' etc). Patrick Sansom had a workshop paper about how all this is done (though -the details have changed quite a bit). Ask -him (email: sansom@dcs.gla.ac.uk) if you want a copy. +the details have changed quite a bit). Ask him) if you want a copy. -Using <Literal>make</Literal> +<Title>Using <Command>make</Command> @@ -999,7 +992,7 @@ URL="mailto:sansom@dcs.gla.ac.uk" -It is reasonably straightforward to set up a Makefile to use with +It is reasonably straightforward to set up a Makefile to use with GHC, assuming you name your source files the same as your modules. Thus: @@ -1037,8 +1030,8 @@ 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 +(Sophisticated make variants may achieve some of the above more +elegantly. Notably, gmake's pattern rules let you write the more comprehensible: @@ -1052,13 +1045,13 @@ comprehensible: -What we've shown should work with any make.) +What we've shown should work with any make.) Note the cheesy .o.hi rule: It records the dependency of the -interface (.hi) file on the source. The rule says a .hi file can -be made from a .o file by doing…nothing. Which is true. +interface (.hi) file on the source. The rule says a .hi file can +be made from a .o file by doing…nothing. Which is true. @@ -1075,7 +1068,7 @@ Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz -They tell make that if any of Foo.o, Foo.hc or Foo.s have an +They tell make that if any of Foo.o, Foo.hc or Foo.s have an earlier modification date than Baz.hi, then the out-of-date file must be brought up to date. To bring it up to date, make looks for a rule to do so; one of the preceding suffix rules does the job @@ -1084,9 +1077,9 @@ nicely. Putting inter-dependencies of the form Foo.o : Bar.hi into your -Makefile by hand is rather error-prone. Don't worry—never fear, -mkdependHS is here! (and is distributed as part of GHC) Add the -following to your Makefile: +Makefile by hand is rather error-prone. Don't worry—never fear, +mkdependHS is here! (and is distributed as part of GHC) Add the +following to your Makefile: @@ -1100,9 +1093,9 @@ depend : Now, before you start compiling, and any time you change the imports -in your program, do make depend before you do make cool_pgm. -mkdependHS will append the needed dependencies to your Makefile. -mkdependHS is fully described in . +in your program, do make depend before you do make cool_pgm. +mkdependHS will append the needed dependencies to your Makefile. +mkdependHS is fully described in . @@ -1116,15 +1109,15 @@ A few caveats about this simple scheme: You may need to compile some modules explicitly to create their -interfaces in the first place (e.g., make Bar.o to create Bar.hi). +interfaces in the first place (e.g., make Bar.o to create Bar.hi). - You may have to type make more than once for the dependencies -to have full effect. However, a make run that does nothing + You may have to type make more than once for the dependencies +to have full effect. However, a make run that does nothing does mean ``everything's up-to-date.'' @@ -1188,8 +1181,8 @@ to look for the interface file of the other. So, to get mutually recursive modules off the ground, you need to hand write an interface file for A or B, so as to break the loop. These hand-written interface files are called hi-boot files, and are placed in a file -called <module>.hi-boot. To import from an hi-boot file instead -of the standard .hi file, use the following syntax in the importing module: +called <module>.hi-boot. To import from an hi-boot file instead +of the standard .hi file, use the following syntax in the importing module: hi-boot files importing, hi-boot files @@ -1226,14 +1219,14 @@ __export A TA{MkTA} ; -The syntax is essentially the same as a normal .hi file -(unfortunately), but you can usually tailor an existing .hi file to -make a .hi-boot file. +The syntax is essentially the same as a normal .hi file +(unfortunately), but you can usually tailor an existing .hi file to +make a .hi-boot file. 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 +hi-boot file, not the signature for f, since f isn't used by B. @@ -1247,7 +1240,7 @@ you try to read an old-format file with a new-format compiler. The number ``1'' at the beginning of a declaration is the version -number of that declaration: for the purposes of .hi-boot files +number of that declaration: for the purposes of .hi-boot files these can all be set to 1. All names must be fully qualified with the original module that an object comes from: for example, the reference to Int in the interface for A comes from PrelBase, @@ -1294,15 +1287,15 @@ construction of interface files, is (allegedly) in the works. -The -O* options specify convenient ``packages'' of optimisation -flags; the -f* options described later on specify -individual optimisations to be turned on/off; the -m* +The options specify convenient ``packages'' of optimisation +flags; the options described later on specify +individual optimisations to be turned on/off; the options specify machine-specific optimisations to be turned on/off. -<Literal>-O*</Literal>: convenient ``packages'' of optimisation flags. +<Title><Option>-O*</Option>: convenient ``packages'' of optimisation flags. @@ -1318,9 +1311,9 @@ suffice. -Once you choose a -O* ``package,'' stick with it—don't chop and +Once you choose a ``package,'' stick with it—don't chop and change. Modules' interfaces will change with a shift to a new --O* option, and you may have to recompile a large chunk of all + option, and you may have to recompile a large chunk of all importing modules before your program can again be run safely (see ). @@ -1329,29 +1322,29 @@ safely (see ). -No -O*-type option specified: +No -type option specified: -O* not specified This is taken to mean: ``Please compile quickly; I'm not over-bothered -about compiled-code quality.'' So, for example: ghc -c Foo.hs +about compiled-code quality.'' So, for example: ghc -c Foo.hs --O or -O1: + or : -O option -O1 option optimise normally Means: ``Generate good-quality code without taking too long about it.'' -Thus, for example: ghc -c -O Main.lhs +Thus, for example: ghc -c -O Main.lhs --O2: +: -O2 option @@ -1367,13 +1360,13 @@ normally turned on or off individually. -At the moment, -O2 is unlikely to produce -better code than -O. +At the moment, is unlikely to produce +better code than . --O2-for-C: +: -O2-for-C option @@ -1381,14 +1374,14 @@ better code than -O. -Says to run GCC with -O2, which may be worth a few percent in -execution speed. Don't forget -fvia-C, lest you use the native-code +Says to run GCC with , which may be worth a few percent in +execution speed. Don't forget , lest you use the native-code generator and bypass GCC altogether! --Onot: +: -Onot option @@ -1396,13 +1389,13 @@ generator and bypass GCC altogether! -This option will make GHC ``forget'' any -Oish options it has seen so -far. Sometimes useful; for example: make all EXTRA_HC_OPTS=-Onot. +This option will make GHC ``forget'' any ish options it has seen so +far. Sometimes useful; for example: make all EXTRA_HC_OPTS=-Onot. --Ofile <file>: +: -Ofile <file> option @@ -1412,7 +1405,7 @@ far. Sometimes useful; for example: make all EXTRA_HC_OP For those who need absolute control over exactly what options are used (e.g., compiler writers, sometimes :-), a list -of options can be put in a file and then slurped in with -Ofile. +of options can be put in a file and then slurped in with . @@ -1421,7 +1414,7 @@ lines and most whitespace is ignored. -Please ask if you are baffled and would like an example of -Ofile! +Please ask if you are baffled and would like an example of ! @@ -1429,22 +1422,22 @@ Please ask if you are baffled and would like an example of -Ofile -At Glasgow, we don't use a -O* flag for day-to-day work. We use --O to get respectable speed; e.g., when we want to measure -something. When we want to go for broke, we tend to use -O -fvia-C --O2-for-C (and we go for lots of coffee breaks). +At Glasgow, we don't use a flag for day-to-day work. We use + to get respectable speed; e.g., when we want to measure +something. When we want to go for broke, we tend to use (and we go for lots of coffee breaks). -The easiest way to see what -O (etc.) ``really mean'' is to run with --v, then stand back in amazement. Alternatively, just look at the -HsC_minus<blah> lists in the ghc driver script. +The easiest way to see what (etc.) ``really mean'' is to run with +, then stand back in amazement. Alternatively, just look at the +HsC_minus<blah> lists in the GHC driver script. -<Literal>-f*</Literal>: platform-independent flags +<Option>-f*</Option>: platform-independent flags -f* options (GHC) @@ -1453,9 +1446,9 @@ The easiest way to see what -O (etc.) ``really mean'' is to r Flags can be turned off individually. (NB: I hope you have a -good reason for doing this…) To turn off the -ffoo flag, just use -the -fno-foo flag.-fno-<opt> anti-option So, for -example, you can say -O2 -fno-strictness, which will then drop out +good reason for doing this…) To turn off the flag, just use +the flag.-fno-<opt> anti-option So, for +example, you can say , which will then drop out any running of the strictness analyser. @@ -1466,14 +1459,14 @@ The options you are most likely to want to turn off are: --fno-strictness-fno-strictness option (strictness +-fno-strictness option (strictness analyser, because it is sometimes slow), --fno-specialise-fno-specialise option (automatic +-fno-specialise option (automatic specialisation of overloaded functions, because it can make your code bigger) (US spelling also accepted), and @@ -1481,7 +1474,7 @@ bigger) (US spelling also accepted), and --fno-cpr-analyse-fno-cpr-analyse option switches off the CPR (constructed product +-fno-cpr-analyse option switches off the CPR (constructed product result) analyser. @@ -1492,7 +1485,7 @@ result) analyser. Should you wish to turn individual flags on, you are advised -to use the -Ofile option, described above. Because the order in +to use the option, described above. Because the order in which optimisation passes are run is sometimes crucial, it's quite hard to do with command-line options. @@ -1502,7 +1495,7 @@ Here are some ``dangerous'' optimisations you might want to --fvia-C: +: -fvia-C option @@ -1512,12 +1505,12 @@ Here are some ``dangerous'' optimisations you might want to Compile via C, and don't use the native-code generator. (There are many cases when GHC does this on its own.) You might pick up a little -bit of speed by compiling via C. If you use _ccall_gc_s or -_casm_s, you probably have to use -fvia-C. +bit of speed by compiling via C. If you use _ccall_gc_s or +_casm_s, you probably have to use . -The lower-case incantation, -fvia-c, is synonymous. +The lower-case incantation, , is synonymous. @@ -1527,7 +1520,7 @@ using GHC's native code generator. --funfolding-interface-threshold<n>: +: -funfolding-interface-threshold option @@ -1542,14 +1535,14 @@ bigger function would be assigned a bigger cost.) --funfolding-creation-threshold<n>: +: -funfolding-creation-threshold option inlining, controlling unfolding, controlling (Default: 30) This option is similar to --funfolding-interface-threshold, except that it governs unfoldings +, except that it governs unfoldings within a single module. Increasing this figure is more likely to result in longer compile times than faster code. The next option is more useful: @@ -1557,7 +1550,7 @@ more useful: --funfolding-use-threshold<n>: +: -funfolding-use-threshold option @@ -1567,12 +1560,12 @@ more useful: this size, a function definition will be unfolded at the call-site, any bigger and it won't. The size computed for a function depends on two things: the actual size of the expression minus any discounts that -apply (see -funfolding-con-discount). +apply (see ). --funfolding-con-discount<n>: +: -funfolding-con-discount option @@ -1593,7 +1586,7 @@ expanding unfoldings. --funbox-strict-fields: +: -funbox-strict-fields option @@ -1616,14 +1609,14 @@ data T = T !Float !Float will create a constructor T containing two unboxed floats if the --funbox-strict-fields flag is given. This may not always be an -optimisation: if the T constructor is scrutinised and the floats + flag is given. This may not always be an +optimisation: if the T constructor is scrutinised and the floats passed to a non-strict function for example, they will have to be reboxed (this is done automatically by the compiler). -This option should only be used in conjunction with -O, in order to +This option should only be used in conjunction with , in order to expose unfoldings to the compiler so the reboxing can be removed as often as possible. For example: @@ -1638,8 +1631,8 @@ f (T f1 f2) = f1 + f2 -The compiler will avoid reboxing f1 and f2 by inlining + on -floats, but only when -O is on. +The compiler will avoid reboxing f1 and f2 by inlining + on +floats, but only when is on. @@ -1655,7 +1648,7 @@ data T = T !(Int,Int) -will store the two Ints directly in the T constructor, by flattening +will store the two Ints directly in the T constructor, by flattening the pair. Multi-level unpacking is also supported: @@ -1669,12 +1662,12 @@ data S = S !Int !Int -will store two unboxed Int#s directly in the T constructor. +will store two unboxed Int#s directly in the T constructor. --fsemi-tagging: +: This option (which does not work with the native-code generator) @@ -1684,7 +1677,7 @@ program, you lose otherwise. (And you pay in extra code space.) -We have not played with -fsemi-tagging enough to recommend it. +We have not played with enough to recommend it. (For all we know, it doesn't even work anymore… Sigh.) @@ -1695,7 +1688,7 @@ We have not played with -fsemi-tagging enough to recommend it -<Literal>-m*</Literal>: platform-specific flags +<Option>-m*</Option>: platform-specific flags -m* options (GHC) @@ -1711,18 +1704,18 @@ Some flags only make sense for particular target platforms. --mv8: +: (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 similiar -m* GCC options for SPARC also work, actually. +The similiar GCC options for SPARC also work, actually. --mlong-calls: +: (HPPA machines)-mlong-calls option (HPPA only) @@ -1732,7 +1725,7 @@ modules, maybe. (Probably means you're in trouble…) --monly-[32]-regs: +: (iX86 machines)-monly-N-regs option (iX86 only) @@ -1746,7 +1739,7 @@ This may be due to a compiler bug or to impossible asm statements or clauses. -Just give some registers back with -monly-N-regs. Try `3' first, +Just give some registers back with . Try `3' first, then `2'. If `2' doesn't work, please report the bug to us. @@ -1766,14 +1759,14 @@ then `2'. If `2' doesn't work, please report the bug to us. -The C compiler (GCC) is run with -O turned on. (It has +The C compiler (GCC) is run with turned on. (It has to be, actually). -If you want to run GCC with -O2—which may be worth a few +If you want to run GCC with —which may be worth a few percent in execution speed—you can give a --O2-for-C-O2-for-C option option. +-O2-for-C option option. @@ -1795,34 +1788,34 @@ percent in execution speed—you can give a -The C pre-processor cpp is run over your Haskell code only if the --cpp option -cpp option is given. Unless you are +The C pre-processor cpp is run over your Haskell code only if the + option -cpp option is given. Unless you are building a large system with significant doses of conditional compilation, you really shouldn't need it. --D<foo>: +: -D<name> option -Define macro <foo> in the usual way. NB: does not affect --D macros passed to the C compiler when compiling via C! For those, -use the -optc-Dfoo hack… (see ). +Define macro <foo> in the usual way. NB: does not affect + macros passed to the C compiler when compiling via C! For those, +use the hack… (see ). --U<foo>: +: -U<name> option -Undefine macro <foo> in the usual way. +Undefine macro <foo> in the usual way. --I<dir>: +: -I<dir> option @@ -1835,15 +1828,15 @@ the usual C way. -The ghc driver pre-defines several macros when processing Haskell -source code (.hs or .lhs files): +The GHC driver pre-defines several macros when processing Haskell +source code (.hs or .lhs files): -__HASKELL98__: +__HASKELL98__: __HASKELL98__ @@ -1853,17 +1846,17 @@ Haskell 98 report. -__HASKELL__=98: +__HASKELL__=98: __HASKELL__ -In GHC 4.04 and later, the __HASKELL__ macro is defined as having -the value 98. +In GHC 4.04 and later, the __HASKELL__ macro is defined as having +the value 98. -__HASKELL1__: +__HASKELL1__: __HASKELL1__ macro @@ -1874,7 +1867,7 @@ macro is deprecated, and will probably disappear in future versions. -__GLASGOW_HASKELL__: +__GLASGOW_HASKELL__: __GLASGOW_HASKELL__ macro @@ -1883,24 +1876,24 @@ For version n of the GHC system, this will be &num -With any luck, __GLASGOW_HASKELL__ will be undefined in all other +With any luck, __GLASGOW_HASKELL__ will be undefined in all other implementations that support C-style pre-processing. (For reference: the comparable symbols for other systems are: -__HUGS__ for Hugs and __HBC__ for Chalmers.) +__HUGS__ for Hugs and __HBC__ for Chalmers.) NB. This macro is set when pre-processing both Haskell source and C source, including the C source generated from a Haskell module -(ie. .hs, .lhs, .c and .hc files). +(i.e. .hs, .lhs, .c and .hc files). -__CONCURRENT_HASKELL__: +__CONCURRENT_HASKELL__: __CONCURRENT_HASKELL__ macro @@ -1911,11 +1904,11 @@ supports concurrent haskell by default, this symbol is always defined. -__PARALLEL_HASKELL__: +__PARALLEL_HASKELL__: __PARALLEL_HASKELL__ macro -Only defined when -parallel is in use! This symbol is defined when +Only defined when is in use! This symbol is defined when pre-processing Haskell (input) and pre-processing C (GHC output). @@ -1925,12 +1918,12 @@ pre-processing Haskell (input) and pre-processing C (GHC output). Options other than the above can be forced through to the C -pre-processor with the -opt flags (see +pre-processor with the flags (see ). -A small word of warning: -cpp is not friendly to ``string +A small word of warning: is not friendly to ``string gaps''.-cpp vs string gapsstring gaps vs -cpp. In other words, strings such as the following: @@ -1946,13 +1939,13 @@ strmod = "\ -don't work with -cpp; /usr/bin/cpp elides the +don't work with ; /usr/bin/cpp elides the backslash-newline pairs. However, it appears that if you add a space at the end of the line, -then cpp (at least GNU cpp and possibly other cpps) +then cpp (at least GNU cpp and possibly other cpps) leaves the backslash-space pairs alone and the string gap works as expected. @@ -1983,17 +1976,17 @@ THIS MAY CHANGE. Meanwhile, options so sent are: --ansi + do ANSI C (not K&R) --pedantic + be so --dgcc-lint + (hack) short for ``make GCC very paranoid'' @@ -2035,7 +2028,7 @@ command-line: GHC has to link your code with various libraries, possibly including: -user-supplied, GHC-supplied, and system-supplied (-lm math +user-supplied, GHC-supplied, and system-supplied ( math library, for example). @@ -2043,20 +2036,20 @@ library, for example). --l<FOO>: +: -l<lib> option -Link in a library named lib<FOO>.a which resides somewhere on the +Link in a library named lib<FOO>.a which resides somewhere on the library directories path. Because of the sad state of most UNIX linkers, the order of such -options does matter. Thus: ghc -lbar *.o is almost certainly -wrong, because it will search libbar.a before it has -collected unresolved symbols from the *.o files. -ghc *.o -lbar is probably better. +options does matter. Thus: ghc -lbar *.o is almost certainly +wrong, because it will search libbar.a before it has +collected unresolved symbols from the *.o files. +ghc *.o -lbar is probably better. @@ -2078,22 +2071,22 @@ libraries automatically; these are: --lHSrts,-lHSclib + basic runtime libraries --lHS + standard Prelude library --lHS_cbits + C support code for standard Prelude library --lgmp + GNU multi-precision library (for Integers) @@ -2113,7 +2106,7 @@ libraries automatically; these are: --syslib <name>: +: -syslib <name> option @@ -2121,23 +2114,23 @@ libraries automatically; these are: If you are using a Haskell ``system library'' (e.g., the POSIX -library), just use the -syslib posix option, and the correct code +library), just use the option, and the correct code should be linked in. --L<dir>: +: -L<dir> option Where to find user-supplied libraries… Prepend the directory -<dir> to the library directories path. +<dir> to the library directories path. --static: +: -static option @@ -2146,7 +2139,7 @@ Tell the linker to avoid shared libraries. --no-link-chk and -link-chk: + and : -no-link-chk option @@ -2156,15 +2149,15 @@ By default, immediately after linking an executable, GHC verifies that the pieces that went into it were compiled with compatible flags; a ``consistency check''. (This is to avoid mysterious failures caused by non-meshing of -incompatibly-compiled programs; e.g., if one .o file was compiled +incompatibly-compiled programs; e.g., if one .o file was compiled for a parallel machine and the others weren't.) You may turn off this -check with -no-link-chk. You can turn it (back) on with --link-chk (the default). +check with . You can turn it (back) on with + (the default). --no-hs-main: +: -no-hs-main option @@ -2174,15 +2167,15 @@ check with -no-link-chk. You can turn it (back) on with In the event you want to include ghc-compiled code as part of another (non-Haskell) program, the RTS will not be supplying its definition of -main() at link-time, you will have to. To signal that to the -driver script when linking, use -no-hs-main. +main() at link-time, you will have to. To signal that to the +driver script when linking, use . Notice that since the command-line passed to the linker is rather involved, you probably want to use the ghc driver script to do the final link of your `mixed-language' application. This is not a -requirement though, just try linking once with -v on to see what +requirement though, just try linking once with on to see what options the driver passes through to the linker. @@ -2205,13 +2198,13 @@ options the driver passes through to the linker. GHC (as of version 4.00) supports Concurrent Haskell by default, without requiring a special option or libraries compiled in a certain way. To get access to the support libraries for Concurrent Haskell -(ie. Concurrent and friends), use the -syslib concurrent option. +(i.e. Concurrent and friends), use the option. Three RTS options are provided for modifying the behaviour of the -threaded runtime system. See the descriptions of -C[<us>], -q, -and -t<num> in . +threaded runtime system. See the descriptions of , , +and in . @@ -2234,14 +2227,14 @@ Concurrent Haskell is described in more detail in .) @@ -2260,7 +2253,7 @@ PVM, detailed in the following sections. 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: +probably in your .cshrc or equivalent: setenv PVM_ROOT /wherever/you/put/it @@ -2276,7 +2269,7 @@ business; nothing specific to Parallel Haskell. -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: @@ -2288,42 +2281,42 @@ machine. You can then do various things to control/monitor your -Control-D -exit pvm, leaving it running +ControlD +exit pvm, leaving it running -halt +halt kill off this ``parallel machine'' & exit -add <host> -add <host> as a processor +add <host> +add <host> as a processor -delete <host> -delete <host> +delete <host> +delete <host> -reset +reset kill what's going, but leave PVM up -conf +conf list the current configuration -ps +ps report processes' status -pstat <pid> +pstat <pid> status of a particular process @@ -2333,7 +2326,7 @@ machine. You can then do various things to control/monitor your -The PVM documentation can tell you much, much more about pvm! +The PVM documentation can tell you much, much more about pvm! @@ -2353,12 +2346,12 @@ results—only with ``how parallel'' it was! We want pretty pictures. -Parallelism profiles (à la hbcpp) can be generated with the --q-q RTS option (concurrent, parallel) RTS option. The +Parallelism profiles (à la hbcpp) can be generated with the +-q 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: @@ -2374,7 +2367,7 @@ which you can then display. For example, to run your program The scripts for processing the parallelism profiles are distributed -in ghc/utils/parallel/. +in ghc/utils/parallel/. @@ -2385,15 +2378,15 @@ in ghc/utils/parallel/. The ``garbage-collection statistics'' RTS options can be useful for seeing what parallel programs are doing. If you do either -+RTS -Sstderr-Sstderr RTS option or +RTS -sstderr, 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. +appears in /tmp/pvml.nnn, courtesy of PVM. -Whether doing +RTS -Sstderr or not, a handy way to watch -what's happening overall is: tail -f /tmp/pvml.nnn. +Whether doing or not, a handy way to watch +what's happening overall is: tail -f /tmp/pvml.nnn. @@ -2419,7 +2412,7 @@ for concurrent/parallel execution. --N<N>: +: -N<N> RTS option (parallel) @@ -2429,13 +2422,13 @@ the default is 2. --C[<us>]: +: -C<us> RTS option Sets the context switch interval to <us> microseconds. A context switch will occur at the next heap allocation after the timer expires. -With -C0 or -C, context switches will occur as often as +With or , context switches will occur as often as possible (at every heap allocation). By default, context switches occur every 10 milliseconds. Note that many interval timers are only capable of 10 millisecond granularity, so the default setting may be @@ -2451,24 +2444,24 @@ allocation]. --q[v]: +: -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 +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 (-qv), the +(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 -C). +hbcpp profiling tools or if you are context switching at every heap +check (with ). --t<num>: +: -t<num> RTS option @@ -2481,20 +2474,20 @@ to <num>. The default is 32. Each thread requires sli --d: +: -d RTS option (parallel) (PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or -something…) per PVM processor. We use the standard debugger +something…) per PVM processor. We use the standard debugger script that comes with PVM3, but we sometimes meddle with the -debugger2 script. We include ours in the GHC distribution, -in ghc/utils/pvm/. +debugger2 script. We include ours in the GHC distribution, +in ghc/utils/pvm/. --e<num>: +: -e<num> RTS option (parallel) @@ -2505,7 +2498,7 @@ your program generates large amounts of parallelism initially. --Q<num>: +: -Q<num> RTS option (parallel) diff --git a/ghc/docs/users_guide/utils.sgml b/ghc/docs/users_guide/utils.sgml index da61187..53ec588 100644 --- a/ghc/docs/users_guide/utils.sgml +++ b/ghc/docs/users_guide/utils.sgml @@ -10,7 +10,7 @@ with the Great Haskell Programming Task. -Makefile dependencies in Haskell: using <Literal>mkdependHS</Literal> +<Title>Makefile dependencies in Haskell: using <Command>mkdependHS</Command> @@ -20,7 +20,7 @@ with the Great Haskell Programming Task. -You run mkdependHS like this: +You run mkdependHS like this: mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...] @@ -32,8 +32,8 @@ or ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...] -To see mkdependHS's command-line flags, give it a duff flag, -e.g., mkdependHS -help. +To see mkdependHS's command-line flags, give it a duff flag, +e.g., mkdependHS -help. @@ -43,7 +43,7 @@ In general, if module A contains the line import B ...blah... -then mkdependHS will generate a dependency line of the form: +then mkdependHS will generate a dependency line of the form: A.o : B.hi @@ -55,36 +55,36 @@ If module A contains the line import {-# SOURCE #-} B ...blah... -then mkdependHS will generate a dependency line of the form: +then mkdependHS will generate a dependency line of the form: A.o : B.hi-boot (See for details of interface files.) -If A imports multiple modules, then there will be multiple lines with A.o as the +If A imports multiple modules, then there will be multiple lines with A.o as the target. -By default, mkdependHS generates all the dependencies, and then +By default, mkdependHS generates all the dependencies, and then concatenates them onto the end of -makefile (or Makefile if makefile doesn't exist) bracketed by +makefile (or Makefile if makefile doesn't exist) bracketed by the lines "# DO NOT DELETE: Beginning of Haskell dependencies" and "# DO NOT DELETE: End of Haskell dependencies". If these lines -already exist in the makefile, mkdependHS deletes the old +already exist in the makefile, mkdependHS deletes the old dependencies first. -mkdependHS takes GHC options between -- brackets. +mkdependHS takes GHC options between -- brackets. It understands the following ones. Any options between -- brackets that it doesn't understand are simply ignored; this way you can feed your -Makefile's standard GHC options to mkdependHS un-filtered. +Makefile's standard GHC options to mkdependHS un-filtered. --cpp + Run the C pre-processor over the input files. The @@ -93,33 +93,33 @@ default is not to. --D<blah> + -A cpp #define; usual meaning. +A cpp ; usual meaning. --i<dirs> + -Add <dirs> (colon-separated) to list of directories +Add <dirs> (colon-separated) to list of directories to search for "import"ed modules. --I<dir> + -Add <dir> to list of directories to search for +Add <dir> to list of directories to search for .h files (i.e., usual meaning). --syslib <blah> + This program uses this GHC system library; take @@ -132,11 +132,11 @@ appropriate action (e.g., recognise when they are -Here are the mkdependHS-specific options (not between --'s): +Here are the mkdependHS-specific options (not between --'s): --v + Be verbose. @@ -144,7 +144,7 @@ Be verbose. --v -v + Be very verbose. @@ -152,7 +152,7 @@ Be very verbose. --w + Turn off warnings about interface file shadowing. @@ -160,92 +160,92 @@ Turn off warnings about interface file shadowing. --f blah + -Use blah as the makefile, rather than makefile -or Makefile. If blah doesn't exist, mkdependHS creates it. -We often use -f .depend to put the dependencies in .depend and -then include the file .depend into Makefilpe. +Use blah as the makefile, rather than makefile +or Makefile. If blah doesn't exist, mkdependHS creates it. +We often use to put the dependencies in .depend and +then include the file .depend into Makefile. --o <osuf> + -Use .<osuf> as the "target file" suffix ( default: o). -Multiple -o flags are permitted (GHC2.05 onwards). Thus "-o hc -o o" -will generate dependencies for .hc and .o files. +Use .<osuf> as the "target file" suffix ( default: o). +Multiple flags are permitted (GHC2.05 onwards). Thus "" +will generate dependencies for .hc and .o files. --s <suf> + Make extra dependencies that declare that files with -suffix .<suf>_<osuf> depend on interface files with suffix .<suf>_hi, or -(for {-# SOURCE #-} imports) on .hi-boot. -Multiple -s flags are permitted. -For example, "-o hc -s a -s b" will -make dependencies for .hc on .hi, .a_hc on .a_hi, and .b_hc on .b_hi. +suffix .<suf>_<osuf> depend on interface files with suffix .<suf>_hi, or +(for {-# SOURCE #-} imports) on .hi-boot. +Multiple flags are permitted. +For example, will +make dependencies for .hc on .hi, .a_hc on .a_hi, and .b_hc on .b_hi. (Useful in conjunction with NoFib "ways".) ---exclude-module=<file> + -Regard <file> as "stable"; i.e., exclude it from having +Regard <file> as "stable"; i.e., exclude it from having dependencies on it. --x + -same as --exclude-module +same as ---exclude-directory=<dirs> + -Regard the colon-separated list of directories <dirs> as containing stable, +Regard the colon-separated list of directories <dirs> as containing stable, don't generate any dependencies on modules therein. --Xdirs + -same as --exclude-directory. +same as . ---include-module=<file> + -Regard <file> as not "stable"; i.e., generate dependencies +Regard <file> as not "stable"; i.e., generate dependencies on it (if any). This option is normally used in conjunction -with the --exclude-directory option. +with the option. ---include-prelude + Regard prelude libraries as unstable, i.e., generate dependencies on the prelude modules used (including Prelude). This option is normally only used by the various system libraries. If -a -syslib option is used, dependencies will also be +a option is used, dependencies will also be generated on the library's interfaces. @@ -256,7 +256,7 @@ generated on the library's interfaces. -Emacs `TAGS' for Haskell: <Literal>hstags</Literal> +<Title>Emacs `TAGS' for Haskell: <Command>hstags</Command> @@ -277,7 +277,7 @@ Some people go wild over this stuff… -GHC comes with a program hstags, which build Emacs-able TAGS files. The invocation syntax is: +GHC comes with a program hstags, which build Emacs-able TAGS files. The invocation syntax is: hstags [GHC-options] file [files...] @@ -298,8 +298,8 @@ tags: -The only flags of its own are: -v to be verbose; -a to -**APPEND** to the TAGS file, rather than write to it. +The only flags of its own are: to be verbose; to +APPEND to the TAGS file, rather than write to it. @@ -310,16 +310,16 @@ in. Go for the corresponding type constructor instead. -(Actually, GHC also comes with etags [for C], and perltags +(Actually, GHC also comes with etags [for C], and perltags [for You Know What]. And—I cannot tell a lie—there is Denis -Howe's fptags [for Haskell, etc.] in the ghc/CONTRIB +Howe's fptags [for Haskell, etc.] in the ghc/CONTRIB section…) -``Yacc for Haskell'': <Literal>happy</Literal> +<Title>``Yacc for Haskell'': <Command>happy</Command> @@ -327,23 +327,23 @@ section…) Yacc for Haskell parser generator for Haskell Andy Gill and Simon Marlow have written a parser-generator for -Haskell, called happy.happy parser generator Happy -is to Haskell what Yacc is to C. +Haskell, called happy.happy parser generator Happy +is to Haskell what Yacc is to C. -You can get happy by FTP from ftp.dcs.gla.ac.uk in -pub/haskell/happy, the file happy-1.5-src.tar.gz. +You can get happy by FTP from ftp.dcs.gla.ac.uk in +pub/haskell/happy, the file happy-1.5-src.tar.gz. -Happy is at its shining best when compiled by GHC. +Happy is at its shining best when compiled by GHC. -Pretty-printing Haskell: <Literal>pphs</Literal> +<Title>Pretty-printing Haskell: <Command>pphs</Command> @@ -353,7 +353,7 @@ You can get happy by FTP from ftp.dcs.gla.ac.uk Andrew Preece has written -pphs,pphspretty-printing Haskell +pphs,pphspretty-printing Haskell a utility to pretty-print Haskell code in LaTeX documents. Keywords in bolds, variables in italics—that sort of thing. It is good at lining up program clauses and equals signs, things that are @@ -361,7 +361,7 @@ very tiresome to do by hand. -The code is distributed with GHC in ghc/CONTRIB/pphs. +The code is distributed with GHC in ghc/CONTRIB/pphs. diff --git a/ghc/docs/users_guide/vs_haskell.sgml b/ghc/docs/users_guide/vs_haskell.sgml index d3f2d3b..167fbd6 100644 --- a/ghc/docs/users_guide/vs_haskell.sgml +++ b/ghc/docs/users_guide/vs_haskell.sgml @@ -36,7 +36,7 @@ as you like. -Bear in mind that string gaps and the -cpp-cpp option +Bear in mind that string gaps and the -cpp option option don't mix very well (see ). diff --git a/ghc/docs/users_guide/win32-dlls.sgml b/ghc/docs/users_guide/win32-dlls.sgml index a26db27..d32bb74 100644 --- a/ghc/docs/users_guide/win32-dlls.sgml +++ b/ghc/docs/users_guide/win32-dlls.sgml @@ -40,7 +40,7 @@ sh$ -will give you a binary as before, but the main.exe generated +will give you a binary as before, but the main.exe generated will use the Prelude and RTS DLLs instead. @@ -56,13 +56,13 @@ will use the Prelude and RTS DLLs instead. If you want to build an executable that doesn't depend on any -ghc-compiled DLLs, use the -static option to link in +ghc-compiled DLLs, use the option to link in the code statically. Notice that you cannot mix code that has been compiled with --static and not, so you have to use the -static + and not, so you have to use the option on all the Haskell modules that make up your application. @@ -87,7 +87,7 @@ sh$ ghc --mk-dll -o HSsuper.dll A.o Super.o B.o libmine.a -lgdi32 -By feeding the ghc compiler driver the option --mk-dll, it +By feeding the ghc compiler driver the option , it will build a DLL rather than produce an executable. The DLL will consist of all the object files and archives given on the command line. @@ -125,14 +125,14 @@ same-directory imports are considered 'DLL imports'. If a directory contains the (probably empty) file -dLL_ifs.hi, the code corresponding to the interface +dLL_ifs.hi, the code corresponding to the interface files found in that directory are assumed to live in a DLL separate from the one being compiled. Notice that the first rule takes precedence over this one, so if you're compiling a module that imports from a Haskell module whose interface file live in the same directory, and that directory -also contains the file dLL_ifs.hi, the import is still not +also contains the file dLL_ifs.hi, the import is still not being considered to be a 'DLL import'. @@ -140,7 +140,7 @@ being considered to be a 'DLL import'. -If compiling with the option -static, the previous rule +If compiling with the option , the previous rule is disabled. @@ -149,7 +149,7 @@ is disabled. So, in short, after having built your Haskell DLL, make sure you -create the file dLL_ifs.hi in the directory that contains +create the file dLL_ifs.hi in the directory that contains its interface files. If you don't, Haskell code that calls upon entry points in that DLL, will do so incorrectly, and a crash will result. (it is unfortunate that this isn't currently caught at compile-time). @@ -160,7 +160,7 @@ points in that DLL, will do so incorrectly, and a crash will result. By default, the entry points of all the object files will -be exported from the DLL when using --mk-dll. Should you want +be exported from the DLL when using . Should you want to constrain this, you can specify the module definition file to use on the command line as follows: @@ -189,7 +189,7 @@ EXPORTS -In addition to creating a DLL, the --mk-dll option will also +In addition to creating a DLL, the option will also create an import library. The import library name is derived from the name of the DLL, as follows: @@ -200,12 +200,12 @@ DLL: HScool.dll ==> import lib: libHScool_imp.a The naming scheme may look a bit weird, but it has the purpose of allowing the co-existence of import libraries with ordinary static -libraries (e.g., libHSfoo.a and libHSfoo_imp.a. +libraries (e.g., libHSfoo.a and libHSfoo_imp.a. Additionally, when the compiler driver is linking in non-static mode, -it will rewrite occurrence of -lHSfoo on the command line to --lHSfoo_imp. By doing this for you, switching from non-static -to static linking is simply a question of adding -static to +it will rewrite occurrence of on the command line to +. By doing this for you, switching from non-static +to static linking is simply a question of adding to your command line.