X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fprofiling.xml;h=3442aee0812397a3a889045585444be8e3bd2759;hb=9253afdfd62b10caaa398f78954aa7f309d887e5;hp=a88c8bbf4c7596749c0eb2c1ccbbaa3466aa079f;hpb=0065d5ab628975892cea1ec7303f968c3338cbe1;p=ghc-hetmet.git
diff --git a/docs/users_guide/profiling.xml b/docs/users_guide/profiling.xml
index a88c8bb..3442aee 100644
--- a/docs/users_guide/profiling.xml
+++ b/docs/users_guide/profiling.xml
@@ -710,7 +710,7 @@ x = nfib 25
currently support mixing the and
options.
- There are two more options which relate to heap
+ There are three more options which relate to heap
profiling:
@@ -750,6 +750,19 @@ x = nfib 25
by closure description or type description.
+
+
+
+
+ RTS option
+
+
+
+ Sets the maximum length of a cost-centre stack name in a
+ heap profile. Defaults to 25.
+
+
+
@@ -1289,8 +1302,128 @@ to re-read its input file:
+
+
+
+ Observing Code Coverage
+ code coverage
+ Haskell Program Coverage
+ hpc
+
+
+ Code coverage tools allow a programer to determine what parts of
+ their code have been actually executed, and which parts have
+ never actually been invoked. GHC has an option for generating
+ instrumented code that records code coverage as part of the
+ Haskell Program Coverage
+ (HPC) toolkit. HPC tools can be used to render the
+ outputed code coverage infomation into human understandable
+ format.
+
+
+
+ HPC provides coverage information of two kinds: source coverage
+ and boolean-control coverage. Source coverage is the extent to
+ which every part of the program was used, measured at three
+ different levels: declarations (both top-level and local),
+ alternatives (among several equations or case branches) and
+ expressions (at every level). Boolean coverage is the extent to
+ which each of the values True and False is obtained in every
+ syntactic boolean context (ie. guard, condition, qualifier).
+
+
+
+ HPC displays both kinds of information in two different ways:
+ textual reports with summary statistics (hpc-report) and sources
+ with color mark-up (hpc-markup). For boolean coverage, there
+ are four possible outcomes for each guard, condition or
+ qualifier: both True and False values occur; only True; only
+ False; never evaluated. In hpc-markup output, highlighting with
+ a yellow background indicates a part of the program that was
+ never evaluated; a green background indicates an always-True
+ expression and a red background indicates an always-False one.
+
+
+ A small example: Reciprocation
+
+
+ For an example we have a program which computes exact decimal
+ representations of reciprocals, with recurring parts indicated in
+ brackets. We first build an instrumented version using the
+ hpc-build script. Assuming the source file is Recip.hs.
+
+
+reciprocal :: Int -> (String, Int)
+reciprocal n | n > 1 = ('0' : '.' : digits, recur)
+ | otherwise = error
+ "attempting to compute reciprocal of number <= 1"
+ where
+ (digits, recur) = divide n 1 []
+divide :: Int -> Int -> [Int] -> (String, Int)
+divide n c cs | c `elem` cs = ([], position c cs)
+ | r == 0 = (show q, 0)
+ | r /= 0 = (show q ++ digits, recur)
+ where
+ (q, r) = (c*10) `quotRem` n
+ (digits, recur) = divide n r (c:cs)
+
+position :: Int -> [Int] -> Int
+position n (x:xs) | n==x = 1
+ | otherwise = 1 + position n xs
+
+showRecip :: Int -> String
+showRecip n =
+ "1/" ++ show n ++ " = " ++
+ if r==0 then d else take p d ++ "(" ++ drop p d ++ ")"
+ where
+ p = length d - r
+ (d, r) = reciprocal n
+
+main = do
+ number <- readLn
+ putStrLn (showRecip number)
+ main
+
+` The HPC intrumentation is enabled using the -fhpc flag.
+
+
+
+$ ghc -fhpc Recip.hs --make
+
+ HPC index (.mix) files are placed placed in .hpc subdirectory. These can be considered like
+ the .hi files for HPC. They contain information about what parts of the haskell each modules.
+
+
+$ ./Recip
+1/3
+= 0.(3)
+
+ Now for a textual summary of coverage:
+
+$ hpc-report Recip
+ 80% expressions used (81/101)
+ 12% boolean coverage (1/8)
+ 14% guards (1/7), 3 always True,
+ 1 always False,
+ 2 unevaluated
+ 0% 'if' conditions (0/1), 1 always False
+ 100% qualifiers (0/0)
+ 55% alternatives used (5/9)
+100% local declarations used (9/9)
+100% top-level declarations used (5/5)
+
+ Finally, we generate a marked-up version of the source.
+
+$ hpc-markup Recip
+writing Recip.hs.html
+
+
+
@@ -1314,9 +1447,9 @@ to re-read its input file:
profiling system, intended for all users everywhere.
To be able to use ticky-ticky profiling, you will need to
- have built appropriate libraries and things when you made the
- system. See “Customising what libraries to build,” in
- the installation guide.
+ have built the ticky RTS. (This should be described in
+ the building guide, but amounts to building the RTS with way
+ "t" enabled.)
To get your compiled program to spit out the ticky-ticky
numbers, use a RTS