Add documentation on code coverage

svn path=/trunk/mono/; revision=47662

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