diff options
author | Miguel de Icaza <miguel@gnome.org> | 2005-07-25 22:18:46 +0400 |
---|---|---|
committer | Miguel de Icaza <miguel@gnome.org> | 2005-07-25 22:18:46 +0400 |
commit | c778a7ee50878ec07ed08d4cab0f4086070fe97b (patch) | |
tree | d4469fdbb110d295012483594b618244361b94c2 /man | |
parent | b902e053239c79426409608496e89a9bff70d7b4 (diff) |
Add documentation on code coverage
svn path=/trunk/mono/; revision=47662
Diffstat (limited to 'man')
-rw-r--r-- | man/mono.1 | 206 |
1 files changed, 145 insertions, 61 deletions
diff --git a/man/mono.1 b/man/mono.1 index d931fabd884..6f14b7f2623 100644 --- a/man/mono.1 +++ b/man/mono.1 @@ -135,47 +135,61 @@ compiled with debugging information, it will produce line number information for stack traces. .TP .I "--profile[=profiler[:profiler_args]]" -Instructs the runtime to collect profiling information about execution -times and memory allocation, and dump it at the end of the execution. -If a profiler is not specified, the default profiler is used. -.Sp -Mono has a built-in profiler called `default' (and is also the default -if no arguments are specified), but developers can write custom -profilers as shared libraries. The shared library must be called -`mono-profiler-NAME.so' where `NAME' is the name of your profiler. -.Sp -For a sample of the custom profilers look in the Mono source tree for -in the samples/profiler.c. -.Sp -The -.I profiler_args -is a profiler-specific string of options for the profiler itself. +Turns on profiling. For more information about profiling applications +and code coverage see the sections "PROFILING" and "CODE COVERAGE" +below. +.TP +.I "--trace[=expression]" +Shows method names as they are invoked. By default all methods are +traced. .Sp -The default profiler is called `default' and it accepts `alloc' to -profile memory consumption by the application; `time' to profile the -time spent on each routine and `stat' to perform sample statistical -profiling. If no options are provided the default is `alloc,time'. +The trace can be customized to include or exclude methods, classes or +assemblies. A trace expression is a comma separated list of targets, +each target can be prefixed with a minus sign to turn off a particular +target. The words `program' and `all' have special meaning. +`program' refers to the main program being executed, and `all' means +all the method calls. .Sp -For example: +Assemblies are specified by their name, for example, to trace all +calls in the System assembly, use: .nf - mono --profile program.exe + + mono --trace=System app.exe + .fi -.Sp -That will run the program with the default profiler and will do time -and allocation profiling. -.Sp +Classes are specified with the T: prefix. For example, to trace all +calls to the System.String class, use: .nf - mono --profile=default:stat,alloc program.exe + + mono --trace=T:System.String app.exe + .fi -Will do sample statistical profiling and allocation profiling on -program.exe. -.TP +And individual methods are referenced with the M: prefix, and the +standar method notation: .nf - mono --profile=custom program.exe + + mono --trace=M:System.Console:WriteLine app.exe + +.fi +As previously noted, various rules can be specified at once: +.nf + + mono --trace=T:System.String,T:System.Random app.exe + +.fi +You can exclude pieces, the next example traces calls to +System.String except for the System.String:Concat method. +.nf + + mono --trace=T:System.String,-M:System.String:Concat + +.fi +Finally, namespaces can be specified using the N: prefix: +.nf + + mono --trace=N:System.Xml + .fi -.Sp -In the above sample Mono will load the user defined profiler from the -shared library `mono-profiler-custom.so'. .SH JIT MAINTAINER OPTIONS The maintainer options are only used by those developing the runtime itself, and not typically of interest to runtime users or developers. @@ -225,58 +239,121 @@ breakpoint on the application's main method. .I "--breakonex" Inserts a breakpoint on exceptions. This allows you to debug your application with a native debugger when an exception is thrown. -.TP -.I "--trace[=expression]" -Shows method names as they are invoked. By default all methods are -traced. +.SH PROFILING +The mono runtime includes a profiler that can be used to explore +various performance related problems in your application. The +profiler is activated by passing the --profile command line argument +to the Mono runtime, the format is: +.nf + + --profile[=profiler[:profiler_args]] + +.fi +Mono has a built-in profiler called 'default' (and is also the default +if no arguments are specified), but developers can write custom +profilers, see the section "CUSTOM PROFILERS" for more details. +.PP +If a +.I profiler +is not specified, the default profiler is used. .Sp -The trace can be customized to include or exclude methods, classes or -assemblies. A trace expression is a comma separated list of targets, -each target can be prefixed with a minus sign to turn off a particular -target. The words `program' and `all' have special meaning. -`program' refers to the main program being executed, and `all' means -all the method calls. +The +.I profiler_args +is a profiler-specific string of options for the profiler itself. .Sp -Assemblies are specified by their name, for example, to trace all -calls in the System assembly, use: +The default profiler accepts the following options 'alloc' to profile +memory consumption by the application; 'time' to profile the time +spent on each routine and 'stat' to perform sample statistical +profiling. If no options are provided the default is 'alloc,time'. +.Sp +For example: .nf - mono --trace=System app.exe + mono --profile program.exe .fi -Classes are specified with the T: prefix. For example, to trace all -calls to the System.String class, use: +.Sp +That will run the program with the default profiler and will do time +and allocation profiling. +.Sp .nf - mono --trace=T:System.String app.exe + mono --profile=default:stat,alloc program.exe .fi -And individual methods are referenced with the M: prefix, and the -standar method notation: +Will do sample statistical profiling and allocation profiling on +program.exe. +.SH CUSTOM PROFILERS +Mono provides a mechanism for loading other profiling modules which in +the form of shared libraries. These profiling modules can hook up to +various parts of the Mono runtime to gather information about the code +being executed. +.PP +To use a third party profiler you must pass the name of the profiler +to Mono, like this: .nf - mono --trace=M:System.Console:WriteLine app.exe + mono --profile=custom program.exe .fi -As previously noted, various rules can be specified at once: +.PP +In the above sample Mono will load the user defined profiler from the +shared library `mono-profiler-custom.so'. This profiler module must +be on your dynamic linker library path. +.PP +A list of other third party profilers is available from Mono's web +site (www.mono-project.com/Performance_Tips) +.PP +Custom profiles are written as shared libraries. The shared library +must be called `mono-profiler-NAME.so' where `NAME' is the name of +your profiler. +.PP +For a sample of how to write your own custom profiler look in the +Mono source tree for in the samples/profiler.c. +.SH CODE COVERAGE +Mono ships with a code coverage module. This module is activated by +using the Mono --profile=cov option. The format is: +.I "--profile=cov[:assembly-name[/namespace]] test-suite.exe" +.PP +By default code coverage will default to all the assemblies loaded, +you can limit this by specifying the assembly name, for example to +perform code coverage in the routines of your program use, for example +the following command line limits the code coverage to routines in the +"demo" assembly: .nf - mono --trace=T:System.String,T:System.Random app.exe + mono --profile=cov:demo demo.exe .fi -You can exclude pieces, the next example traces calls to -System.String except for the System.String:Concat method. +.PP +Notice that the +.I assembly-name +does not include the extension. +.PP +You can further restrict the code coverage output by specifying a +namespace: .nf - mono --trace=T:System.String,-M:System.String:Concat + mono --profile=cov:demo/My.Utilities demo.exe .fi -Finally, namespaces can be specified using the N: prefix: +.PP +Which will only perform code coverage in the given assembly and +namespace. +.PP +Typical output looks like this: .nf - mono --trace=N:System.Xml + Not covered: Class:.ctor () + Not covered: Class:A () + Not covered: Driver:.ctor () + Not covered: Driver:method () + Partial coverage: Driver:Main () + offset 0x000a .fi +.PP +The offsets displayed are IL offsets. .SH DEBUGGING .PP You can use the MONO_LOG_LEVEL and MONO_LOG_MASK environment variables @@ -307,7 +384,9 @@ messages set you mask to "asm,cfg". .PP The following is a common use to track down problems with P/Invoke: .nf + $ MONO_LOG_LEVEL="debug" MONO_LOG_MASK="dll" mono glue.exe + .fi .PP .SH SERIALIZATION @@ -438,12 +517,16 @@ the permission, more accurate statistics are gathered. The MONO_RTC value must be restricted to what the linux rtc allows: power of two from 64 to 8192 Hz. To enable higher frequencies like 4096 Hz, run as root: .nf + echo 4096 > /proc/sys/dev/rtc/max-user-freq + .fi .Sp For example: .nf + MONO_RTC=4096 mono --profiler=default:stat program.exe + .fi .TP .I "MONO_NO_TLS" @@ -526,9 +609,10 @@ Contains Mono isolated storage for non-roaming users, roaming users and local machine. Isolated storage can be accessed using the classes from the System.IO.IsolatedStorage namespace. .SH MAILING LISTS -Visit http://lists.ximian.com/mailman/listinfo/mono-list for details. +Mailing lists are listed at the +http://www.mono-project.com/Mailing_Lists .SH WEB SITE -Visit: http://www.mono-project.com for details +http://www.mono-project.com .SH SEE ALSO .BR mcs(1), mint(1), monodis(1), mono-config(5), certmgr(1). .PP |