monocov/README

1. INTRODUCTION
---------------

  MonoCov is a line coverage analysis program for mono. It can be used to 
display coverage data collected while running a .NET program. There are two
types of GUI interfaces, one implemented using Qt#, while the other is 
implemented using Gtk#. The Qt# version is more advanced.

1.5 REQUIREMENTS
----------------

The runtime parts are tested with the then current Mono CVS. The Qt# GUI 
requires a patched version of the Qt# library which is included in the 
distribution. This file is named Qt-monocov.dll, and the original Qt.dll should
be replace with this file. The upcoming Qt# 0.7.1 release fixes most of the
problems, so this won't be neccessary in the future.

2. USAGE
--------

2.1 COVERAGE DATA COLLECTION
----------------------------

To produce coverage info for an .NET program, compile it with the -g
switch to generate debug information. After this, run the program as follows:

$ ./mono --profile:monocov prog.exe

This will produce a coverage data file called prog.exe.cov. You can run the
analyser program as follows:

$ ./mono monocov.exe prog.exe.cov

This will display the class hierarchy of the program with the corresponding
coverage information.

It is also possible to filter the list of classes which need coverage data
generated. Filters are string which are applied agains the fully qualified 
names of classes, e.g. [assemblyname]classname. You can specify filters 
directly on the command line:

$ ./mono --profile:monocov:-Security,-[System.Xml] prog.exe

There are two types of filters: include filters, whose name begins with '+',
and exclude filters, whose name begins with '-'. Include filters are checked
before exclude filters.

For example:

$ ./mono --profile:monocov:+[corlib],-Hashtable prog.exe

This will collect coverage info for all classes in corlib, except the ones
whose name contains 'Hashtable'.

2.2 ANALYSIS
------------

  The collected coverage data can be browsed using the monocov.exe program. 
This program will read the data file produced by the profiler module, and 
display its contents in a hierarchical fashion.
  It is also possible to export the contents of a data file into XML, which
can be viewed in an XSL capable browser like mozilla.
To export the data as XML, run monocov like this:
	monocov.exe --export-xml=<DEST DIR> <DATA FILE NAME>
  
The generated XML files use a default stylesheet which is a bit ugly. It would
be good if somebody could contribute a better one :)

2.5 KNOWN BUGS
--------------

Due to some memory management problems in Qt#, the GUI will most likely crash
on exit. It will also crash if the user tries to load a second data file.

3. UTILITY PROGRAMS
-------------------

There are two utility programs included with MonoCov:

- symbols.exe: this program can be used to dump the line number information
  contained in an mcs generated assembly.

- nunit-console.exe: this is a rewritten version of the original nunit console
  program. It has the following features:
  - easier to invoke: no stupid /assembly and /fixture arguments
  - ability to run test fixtures whose name matches a given pattern, like
    all the System.IO tests.
  - ability to exclude tests whose name matches a given pattern.
  - display of more detailed progress information.

4. TODO
-------------

- Add ability to run the program from inside the analyzer
- Add filters (globals/per program)
- Add HTML export option
- Handle nested classes more intelligently

5. LICENSE
----------

zlib/libpng.

6. CONTACT
----------

Zoltan Varga (vargaz@freemail.hu)

RANDOM NOTES:
-------------

- There is a bug in QString:~QString (): it should be
	if (this != Null)
		qt_del_QString (rawObject);

- Mono finalizes QApplication before QMainWindow, leading to
  invalid memory read errors.

- Mono frees the the string[] array passed to qt_new_QMainWindow, leading to
  invalid read errors.

- DecimalTest2:.ctor () causes the register allocator to allocate more than
  2^16 registers, overflowing MonoInst->dreg.

- Methods with strange debugging info:
	- System.Collections.Hashtable..cctor()
	- SortedList+SynchedSortedList::this [key]
	- SortedList+SynchedSortedList::Clear ()
	- System.Text.RegularExpressions.Capture

- If trans.gif is missing from the export directory:
    - when viewing HTML, it doesn't matter
	- when viewing XML, it matters

- How can a bar be created without using an image ?

TODO:
- Add private paths used during data collection to the paths used to search for
  assemblies.
- add 'include' and 'exclude' to filters
- Implement merging of coverage results
- put namespaces above classes in the hierarchy
- handle missing source files
- QDesigner
- Scintilla
- html output (with XSLT)
- use Xml serialization in SyntaxHighlighter
- speed up test suite generation in nunit (or in mono)
- namespaces & filtering ???
- fix StackTrace tests
- add ability to exclude some appdomains (like the nunit main appdomain)
  so the tests will run faster.
- avoid instrumentation for instruction without side effects (like ldc.i4)
- why does the RSA tests take so much time -> because of entropy generation
- check in cryptography patches
- optimize reflection classes by caching the results of get_type_info etc.
- put monocov into mono CVS.