X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fprofiling.xml;h=f0d96ba98b952acf5148d8475972f5e4e45b5823;hb=aedb94f5f220b5e442b23ecc445fd38c8d9b6ba0;hp=c30bd803b57de16b5c54c7c98717ddea6937f92f;hpb=43b746ac3988c75336405efc505765127096bb06;p=ghc-hetmet.git diff --git a/docs/users_guide/profiling.xml b/docs/users_guide/profiling.xml index c30bd80..f0d96ba 100644 --- a/docs/users_guide/profiling.xml +++ b/docs/users_guide/profiling.xml @@ -33,7 +33,9 @@ Run your program with one of the profiling options, eg. +RTS -p -RTS. This generates a file of - profiling information. + profiling information. Note that multi-processor execution + (e.g. +RTS -N2) is not supported while + profiling. RTS option @@ -240,9 +242,7 @@ MAIN MAIN 0 0.0 0.0 100.0 100.0 although GHC does keep information about which groups of functions called each other recursively, this information isn't displayed in the basic time and allocation profile, instead the call-graph is - flattened into a tree. The XML profiling tool (described in ) will be able to display real loops in - the call-graph. + flattened into a tree. Inserting cost centres by hand @@ -263,7 +263,24 @@ MAIN MAIN 0 0.0 0.0 100.0 100.0 in the profiling output, and <expression> is any Haskell expression. An SCC annotation extends as - far to the right as possible when parsing. + far to the right as possible when parsing. (SCC stands for "Set + Cost Centre"). + + Here is an example of a program with a couple of SCCs: + + +main :: IO () +main = do let xs = {-# SCC "X" #-} [1..1000000] + let ys = {-# SCC "Y" #-} [1..2000000] + print $ last xs + print $ last $ init xs + print $ last ys + print $ last $ init ys + + + which gives this heap profile when run: + + @@ -455,18 +472,6 @@ x = nfib 25 - : - - - - The option generates profiling - information in the XML format understood by our new - profiling tool, see . - - - - - RTS option @@ -961,48 +966,6 @@ x = nfib 25 - - Graphical time/allocation profile - - You can view the time and allocation profiling graph of your - program graphically, using ghcprof. This is a - new tool with GHC 4.08, and will eventually be the de-facto - standard way of viewing GHC profilesActually this - isn't true any more, we are working on a new tool for - displaying heap profiles using Gtk+HS, so - ghcprof may go away at some point in the future. - - - To run ghcprof, you need - uDraw(Graph) installed, which can be - obtained from uDraw(Graph). Install one of - the binary - distributions, and set your - UDG_HOME environment variable to point to the - installation directory. - - ghcprof uses an XML-based profiling log - format, and you therefore need to run your program with a - different option: . The file generated is - still called <prog>.prof. To see the - profile, run ghcprof like this: - - - - -$ ghcprof <prog>.prof - - - which should pop up a window showing the call-graph of your - program in glorious detail. More information on using - ghcprof can be found at The - Cost-Centre Stack Profiling Tool for - GHC. - - - <command>hp2ps</command>––heap profile to PostScript @@ -1302,8 +1265,324 @@ to re-read its input file: + + + + Observing Code Coverage + code coverage + Haskell Program Coverage + hpc + + + Code coverage tools allow a programmer 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, which is included with GHC. HPC tools can + be used to render the generated code coverage information into + human understandable format. + + + Correctly instrumented code 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 primary 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, called Recip.hs, which computes exact decimal + representations of reciprocals, with recurring parts indicated in + brackets. + + +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 instrumentation 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. + + +$ ./Recip +1/3 += 0.(3) + + We can generate 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) + + We can also generate a marked-up version of the source. + +$ hpc markup Recip +writing Recip.hs.html + + + This generates one file per Haskell module, and 4 index files, + hpc_index.html, hpc_index_alt.html, hpc_index_exp.html, + hpc_index_fun.html. + + + + Options for instrumenting code for coverage + + Turning on code coverage is easy, use the -fhpc flag. + Instrumented and non-instrumented can be freely mixed. + When compiling the Main module GHC automatically detects when there + is an hpc compiled file, and adds the correct initialization code. + + + + + The hpc toolkit + + + The hpc toolkit uses a cvs/svn/darcs-like interface, where a + single binary contains many function units. + +$ hpc +Usage: hpc COMMAND ... + +Commands: + help Display help for hpc or a single command +Reporting Coverage: + report Output textual report about program coverage + markup Markup Haskell source with program coverage +Processing Coverage files: + sum Sum multiple .tix files in a single .tix file + combine Combine two .tix files in a single .tix file + map Map a function over a single .tix file +Coverage Overlays: + overlay Generate a .tix file from an overlay file + draft Generate draft overlay that provides 100% coverage +Others: + show Show .tix file in readable, verbose format + version Display version for hpc + + + In general, these options act on .tix file after an + instrumented binary has generated it, which hpc acting as a + conduit between the raw .tix file, and the more detailed reports + produced. + + + + The hpc tool assumes you are in the top-level directory of + the location where you built your application, and the .tix + file is in the same top-level directory. You can use the + flag --srcdir to use hpc for any other directory, and use + --srcdir multiple times to analyse programs compiled from + difference locations, as is typical for packages. + + + + We now explain in more details the major modes of hpc. + + + hpc report + hpc report gives a textual report of coverage. By default, + all modules and packages are considered in generating report, + unless include or exclude are used. The report is a summary + unless the --per-module flag is used. The --xml-output option + allows for tools to use hpc to glean coverage. + + +$ hpc help report +Usage: hpc report [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]] + +Options: + + --per-module show module level detail + --decl-list show unused decls + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --srcdir=DIR path to source directory of .hs files + multi-use of srcdir possible + --hpcdir=DIR sub-directory that contains .mix files + default .hpc [rarely used] + --xml-output show output in XML + + + hpc markup + hpc markup marks up source files into colored html. + + +$ hpc help markup +Usage: hpc markup [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]] + +Options: + + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --srcdir=DIR path to source directory of .hs files + multi-use of srcdir possible + --hpcdir=DIR sub-directory that contains .mix files + default .hpc [rarely used] + --fun-entry-count show top-level function entry counts + --highlight-covered highlight covered code, rather that code gaps + --destdir=DIR path to write output to + + + + hpc sum + hpc sum adds together any number of .tix files into a single + .tix file. hpc sum does not change the original .tix file; it generates a new .tix file. + + +$ hpc help sum +Usage: hpc sum [OPTION] .. <TIX_FILE> [<TIX_FILE> [<TIX_FILE> ..]] +Sum multiple .tix files in a single .tix file +Options: + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --output=FILE output FILE + --union use the union of the module namespace (default is intersection) + + + hpc combine + hpc combine is the swiss army knife of hpc. It can be + used to take the difference between .tix files, to subtract one + .tix file from another, or to add two .tix files. hpc combine does not + change the original .tix file; it generates a new .tix file. + + +$ hpc help combine +Usage: hpc combine [OPTION] .. <TIX_FILE> <TIX_FILE> +Combine two .tix files in a single .tix file + +Options: + + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --output=FILE output FILE + --function=FUNCTION combine .tix files with join function, default = ADD + FUNCTION = ADD | DIFF | SUB + --union use the union of the module namespace (default is intersection) + + + hpc map + hpc map inverts or zeros a .tix file. hpc map does not + change the original .tix file; it generates a new .tix file. + + +$ hpc help map +Usage: hpc map [OPTION] .. <TIX_FILE> +Map a function over a single .tix file + +Options: + + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --output=FILE output FILE + --function=FUNCTION apply function to .tix files, default = ID + FUNCTION = ID | INV | ZERO + --union use the union of the module namespace (default is intersection) + + + hpc overlay and hpc draft + + Overlays are an experimental feature of HPC, a textual description + of coverage. hpc draft is used to generate a draft overlay from a .tix file, + and hpc overlay generates a .tix files from an overlay. + + +% hpc help overlay +Usage: hpc overlay [OPTION] .. <OVERLAY_FILE> [<OVERLAY_FILE> [...]] + +Options: + + --srcdir=DIR path to source directory of .hs files + multi-use of srcdir possible + --hpcdir=DIR sub-directory that contains .mix files + default .hpc [rarely used] + --output=FILE output FILE +% hpc help draft +Usage: hpc draft [OPTION] .. <TIX_FILE> + +Options: + + --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE + --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE + --srcdir=DIR path to source directory of .hs files + multi-use of srcdir possible + --hpcdir=DIR sub-directory that contains .mix files + default .hpc [rarely used] + --output=FILE output FILE + + + + Caveats and Shortcomings of Haskell Program Coverage + + HPC does not attempt to lock the .tix file, so multiple concurrently running + binaries in the same directory will exhibit a race condition. There is no way + to change the name of the .tix file generated, apart from renaming the binary. + HPC does not work with GHCi. + + @@ -1327,9 +1606,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