3 .\" (C) 2003 Ximian, Inc.
4 .\" (C) 2004-2005 Novell, Inc.
6 .\" Miguel de Icaza (miguel@gnu.org)
8 .TH "Mono" "Mono 1.0" "" "" ""
10 mono \- Mono's ECMA\-CLI native code generator (Just\-in\-Time and Ahead\-of\-Time)
13 .B mono [options] file [arguments...]
15 \fImono\fP is a runtime implementation of the ECMA Common Language
16 Infrastructure. This can be used to run ECMA and .NET applications.
18 The runtime contains a native code generator that transforms the
19 Common Intermediate Language into native code.
21 The code generator can operate in two modes: just in time compilation
22 (JIT) or ahead of time compilation (AOT). Since code can be
23 dynamically loaded, the runtime environment and the JIT are always
24 present, even if code is compiled ahead of time.
26 The runtime loads the specified
33 is an ECMA assembly. They typically have a .exe or .dll extension.
35 The runtime provides a number of configuration options for running
36 applications, for developing and debugging, and for testing and
37 debugging the runtime itself.
39 On Unix\-based systems, Mono provides a mechanism to emulate the
40 Windows\-style file access, this includes providing a case insensitive
41 view of the file system, directory separator mapping (from \\ to /) and
42 stripping the drive letters.
44 This functionality is enabled by setting the
46 environment variable to one of
51 See the description for
53 in the environment variables section for more details.
55 The following options are available:
57 \fB\-\-aot\fR, \fB\-\-aot[=options]\fR
58 This option is used to precompile the CIL code in the specified
59 assembly to native code. The generated code is stored in a file with
60 the extension .so. This file will be automatically picked up by the
61 runtime when the assembly is executed.
63 Ahead\-of\-Time compilation is most useful if you use it in combination
64 with the \-O=all,\-shared flag which enables all of the optimizations in
65 the code generator to be performed. Some of those optimizations are
66 not practical for Just\-in\-Time compilation since they might be very
69 Unlike the .NET Framework, Ahead\-of\-Time compilation will not generate
70 domain independent code: it generates the same code that the
71 Just\-in\-Time compiler would produce. Since most applications use a
72 single domain, this is fine. If you want to optimize the generated
73 code for use in multi\-domain applications, consider using the
76 This pre\-compiles the methods, but the original assembly is still
77 required to execute as this one contains the metadata and exception
78 information which is not available on the generated file. When
79 precompiling code, you might want to compile with all optimizations
80 (\-O=all). Pre\-compiled code is position independent code.
82 Pre compilation is just a mechanism to reduce startup time, increase
83 code sharing across multiple mono processes and avoid just\-in\-time
84 compilation program startup costs. The original assembly must still
85 be present, as the metadata is contained there.
87 AOT code typically can not be moved from one computer to another
88 (CPU\-specific optimizations that are detected at runtime) so you
89 should not try to move the pre\-generated assemblies or package the
90 pre\-generated assemblies for deployment.
92 A few options are available as a parameter to the
94 command line option. The options are separated by commas, and more
95 than one can be specified:
99 .I bind\-to\-runtime\-version
101 If specified, forces the generated AOT files to be bound to the
102 runtime version of the compiling Mono. This will prevent the AOT
103 files from being consumed by a different Mono runtime.
105 This is currently an experimental feature as it is not complete.
106 This instructs Mono to precompile code that has historically not been
107 precompiled with AOT.
110 Instructs the AOT compiler to emit debug symbol information.
113 Create an ELF object file (.o) which can be statically linked into an executable
114 when embedding the mono runtime. When this option is used, the object file needs to
115 be registered with the embedded runtime using the mono_aot_register_module function
116 which takes as its argument the mono_aot_module_<ASSEMBLY NAME>_info global symbol
117 from the object file:
119 extern void *mono_aot_module_hello_info;
121 mono_aot_register_module (mono_aot_module_hello_info);
126 For more information about AOT, see: http://www.mono\-project.com/AOT
129 This is an experimental flag that instructs the Mono runtime to not
130 generate any code at runtime and depend exclusively on the code
131 generated from using mono \-\-aot=full previously. This is useful for
132 platforms that do not permit dynamic code generation.
134 Notice that this feature will abort execution at runtime if a codepath
135 in your program, or Mono's class libraries attempts to generate code
136 dynamically. You should test your software upfront and make sure that
137 you do not use any dynamic features.
139 \fB\-\-config filename\fR
140 Load the specified configuration file instead of the default one(s).
141 The default files are /etc/mono/config and ~/.mono/config or the file
142 specified in the MONO_CONFIG environment variable, if set. See the
143 mono\-config(5) man page for details on the format of this file.
146 Configures the virtual machine to be better suited for desktop
147 applications. Currently this sets the GC system to avoid expanding
148 the heap as much as possible at the expense of slowing down garbage
151 \fB\-\-help\fR, \fB\-h\fR
152 Displays usage instructions.
154 \fB\-\-optimize=MODE\fR, \fB\-O=MODE\fR
155 MODE is a comma separated list of optimizations. They also allow
156 optimizations to be turned off by prefixing the optimization name with
159 In general, Mono has been tuned to use the default set of flags,
160 before using these flags for a deployment setting, you might want to
161 actually measure the benefits of using them.
163 The following optimizations are implemented:
165 all Turn on all optimizations
166 peephole Peephole postpass
167 branch Branch optimizations
168 inline Inline method calls
169 cfold Constant folding
170 consprop Constant propagation
171 copyprop Copy propagation
172 deadce Dead code elimination
173 linears Linear scan global reg allocation
174 cmov Conditional moves [arch\-dependency]
175 shared Emit per\-domain code
176 sched Instruction scheduling
177 intrins Intrinsic method implementations
178 tailc Tail recursion and tail calls
179 loop Loop related optimizations
180 fcmov Fast x86 FP compares [arch\-dependency]
181 leaf Leaf procedures optimizations
182 aot Usage of Ahead Of Time compiled code
183 precomp Precompile all methods before executing Main
184 abcrem Array bound checks removal
185 ssapre SSA based Partial Redundancy Elimination
186 sse2 SSE2 instructions on x86 [arch\-dependency]
187 gshared Enable generic code sharing.
190 For example, to enable all the optimization but dead code
191 elimination and inlining, you can use:
193 \-O=all,\-deadce,\-inline
196 The flags that are flagged with [arch\-dependency] indicate that the
197 given option if used in combination with Ahead of Time compilation
198 (\-\-aot flag) would produce pre\-compiled code that will depend on the
199 current CPU and might not be safely moved to another computer.
201 \fB\-\-runtime=VERSION\fR
202 Mono supports different runtime versions. The version used depends on the program
203 that is being run or on its configuration file (named program.exe.config). This option
204 can be used to override such autodetection, by forcing a different runtime version
205 to be used. Note that this should only be used to select a later compatible runtime
206 version than the one the program was compiled against. A typical usage is for
207 running a 1.1 program on a 2.0 version:
209 mono \-\-runtime=v2.0.50727 program.exe
212 \fB\-\-security\fR, \fB\-\-security=mode\fR
213 Activate the security manager, a currently experimental feature in
214 Mono and it is OFF by default. The new code verifier can be enabled
215 with this option as well.
219 Using security without parameters is equivalent as calling it with the
222 The following modes are supported:
225 This allows mono to support declarative security attributes,
226 e.g. execution of Code Access Security (CAS) or non\-CAS demands.
229 Enables the core\-clr security system, typically used for
230 Moonlight/Silverlight applications. It provides a much simpler
231 security system than CAS, see http://www.mono\-project.com/Moonlight
232 for more details and links to the descriptions of this new system.
235 Enables the new verifier and performs basic verification for code
236 validity. In this mode, unsafe code and P/Invoke are allowed. This
237 mode provides a better safety guarantee but it is still possible
238 for managed code to crash Mono.
241 Enables the new verifier and performs full verification of the code
242 being executed. It only allows verifiable code to be executed.
243 Unsafe code is not allowed but P/Invoke is. This mode should
244 not allow managed code to crash mono. The verification is not as
245 strict as ECMA 335 standard in order to stay compatible with the MS
248 The security system acts on user code: code contained in mscorlib or
249 the global assembly cache is always trusted.
254 Configures the virtual machine to be better suited for server
255 operations (currently, a no\-op).
258 Verifies mscorlib and assemblies in the global
259 assembly cache for valid IL, and all user code for IL
262 This is different from \fB\-\-security\fR's verifiable
263 or validil in that these options only check user code and skip
264 mscorlib and assemblies located on the global assembly cache.
266 \fB\-V\fR, \fB\-\-version\fR
267 Prints JIT version information (system configuration, release number
268 and branch names if available).
271 .SH "DEVELOPMENT OPTIONS"
272 The following options are used to help when developing a JITed application.
274 \fB\-\-debug\fR, \fB\-\-debug=OPTIONS\fR
275 Turns on the debugging mode in the runtime. If an assembly was
276 compiled with debugging information, it will produce line number
277 information for stack traces.
281 The optional OPTIONS argument is a comma separated list of debugging
282 options. These options are turned off by default since they generate
283 much larger and slower code at runtime.
285 The following options are supported:
288 Produces a detailed error when throwing a InvalidCastException.
290 .I mdb\-optimizations
291 Disable some JIT optimizations which are usually only disabled when
292 running inside the debugger. This can be helpful if you want to attach
293 to the running process with mdb.
297 \fB\-\-profile[=profiler[:profiler_args]]\fR
298 Turns on profiling. For more information about profiling applications
299 and code coverage see the sections "PROFILING" and "CODE COVERAGE"
302 \fB\-\-trace[=expression]\fR
303 Shows method names as they are invoked. By default all methods are
306 The trace can be customized to include or exclude methods, classes or
307 assemblies. A trace expression is a comma separated list of targets,
308 each target can be prefixed with a minus sign to turn off a particular
309 target. The words `program', `all' and `disabled' have special
310 meaning. `program' refers to the main program being executed, and
311 `all' means all the method calls.
313 The `disabled' option is used to start up with tracing disabled. It
314 can be enabled at a later point in time in the program by sending the
315 SIGUSR2 signal to the runtime.
317 Assemblies are specified by their name, for example, to trace all
318 calls in the System assembly, use:
321 mono \-\-trace=System app.exe
324 Classes are specified with the T: prefix. For example, to trace all
325 calls to the System.String class, use:
328 mono \-\-trace=T:System.String app.exe
331 And individual methods are referenced with the M: prefix, and the
332 standard method notation:
335 mono \-\-trace=M:System.Console:WriteLine app.exe
338 As previously noted, various rules can be specified at once:
341 mono \-\-trace=T:System.String,T:System.Random app.exe
344 You can exclude pieces, the next example traces calls to
345 System.String except for the System.String:Concat method.
348 mono \-\-trace=T:System.String,\-M:System.String:Concat
351 Finally, namespaces can be specified using the N: prefix:
354 mono \-\-trace=N:System.Xml
357 .SH "JIT MAINTAINER OPTIONS"
358 The maintainer options are only used by those developing the runtime
359 itself, and not typically of interest to runtime users or developers.
361 \fB\-\-break method\fR
362 Inserts a breakpoint before the method whose name is `method'
363 (namespace.class:methodname). Use `Main' as method name to insert a
364 breakpoint on the application's main method.
367 Inserts a breakpoint on exceptions. This allows you to debug your
368 application with a native debugger when an exception is thrown.
370 \fB\-\-compile name\fR
371 This compiles a method (namespace.name:methodname), this is used for
372 testing the compiler performance or to examine the output of the code
376 Compiles all the methods in an assembly. This is used to test the
377 compiler performance or to examine the output of the code generator
379 \fB\-\-graph=TYPE METHOD\fR
380 This generates a postscript file with a graph with the details about
381 the specified method (namespace.name:methodname). This requires `dot'
382 and ghostview to be installed (it expects Ghostview to be called
385 The following graphs are available:
387 cfg Control Flow Graph (CFG)
389 code CFG showing code
390 ssa CFG showing code after SSA translation
391 optcode CFG showing code after IR optimizations
394 Some graphs will only be available if certain optimizations are turned
398 Instruct the runtime on the number of times that the method specified
399 by \-\-compile (or all the methods if \-\-compileall is used) to be
400 compiled. This is used for testing the code generator performance.
403 Displays information about the work done by the runtime during the
404 execution of an application.
406 \fB\-\-wapi=hps|semdel\fR
407 Perform maintenance of the process shared data.
409 semdel will delete the global semaphore.
411 hps will list the currently used handles.
413 \fB\-v\fR, \fB\-\-verbose\fR
414 Increases the verbosity level, each time it is listed, increases the
415 verbosity level to include more information (including, for example,
416 a disassembly of the native code produced, code selector info etc.).
418 The mono runtime includes a profiler that can be used to explore
419 various performance related problems in your application. The
420 profiler is activated by passing the \-\-profile command line argument
421 to the Mono runtime, the format is:
424 \-\-profile[=profiler[:profiler_args]]
427 Mono has a built\-in profiler called 'default' (and is also the default
428 if no arguments are specified), but developers can write custom
429 profilers, see the section "CUSTOM PROFILERS" for more details.
433 is not specified, the default profiler is used.
437 is a profiler\-specific string of options for the profiler itself.
439 The default profiler accepts the following options 'alloc' to profile
440 memory consumption by the application; 'time' to profile the time
441 spent on each routine; 'jit' to collect time spent JIT\-compiling methods
442 and 'stat' to perform sample statistical profiling.
443 If no options are provided the default is 'alloc,time,jit'.
446 profile data is printed to stdout: to change this, use the 'file=filename'
447 option to output the data to filename.
452 mono \-\-profile program.exe
456 That will run the program with the default profiler and will do time
457 and allocation profiling.
461 mono \-\-profile=default:stat,alloc,file=prof.out program.exe
464 Will do sample statistical profiling and allocation profiling on
465 program.exe. The profile data is put in prof.out.
467 Note that the statistical profiler has a very low overhead and should
468 be the preferred profiler to use (for better output use the full path
469 to the mono binary when running and make sure you have installed the
470 addr2line utility that comes from the binutils package).
471 .SH "LOGGING PROFILER"
475 will eventually replace the default profiler as it is more complete
476 and encompasses the functionality of all the other profilers for Mono.
477 It supports the following execution modes:
480 the program instruction pointer is periodically sampled (it works also with
481 unmanaged functions). If call chains are requested, for each sample the
482 profiler gets a partial stack trace (up to a desired depth) so that
483 caller\-callee information is available.
486 each method enter and exit is logged with a timestamp; further processing of
487 the data can show the methods that took the longer to execute, with complete
488 accounting for callers and callees. However, this way of profiling is rather
489 intrusive and slows down the application significantly.
492 each allocation is logged.
494 .I Allocation summary:
495 shows, for each collection, a summary of the heap contents broken down by
496 class (for each class the number of allocated and released objects is
497 given, together with their aggregated size in bytes).
499 .I Heap snapshot mode:
500 dumps the whole heap contents at every collection (or at user specified
501 collections). It is also possible to request a collection and snapshot dump
504 Moreover, other events can be logged and analyzed, like jit time for each
505 method, load and unload for assemblies, modules and and individual classes,
506 and appdomain and thread creation and destruction.
508 Instead of reporting the collected
509 information at the end of the execution of the program, this profiler logs
510 all the events periodically into a file during program execution.
511 To minimize the performance impact with multi\-threaded applications,
512 the logging uses per\-thread buffers that are routinely saved to disk.
514 The output file contains compressed events, to process the data you should
515 use tools like the "Mono.Profiler" tool provided on the Mono SVN
518 This profiler is activated passing the \fB\-\-profile=logging\fR option to
519 the mono runtime, and is controlled attaching further options, like
520 \fB\-\-profile=logging:stat\fR for doing statistical profiling (multiple
521 options are separated by commas).
523 As a quick primer, here are a few examples of the most common usage modes:
525 To write the resulting data to "mydata.mprof" (defaults to statistical
529 mono \-\-profile=logging:o=mydata.mprof program.exe
532 To perform statistical profiling, inspecting call chains up to depth 8:
535 mono \-\-profile=logging:s=8 program.exe
538 To profile allocations with caller method attribution:
541 mono \-\-profile=logging:a,ts program.exe
544 To profile garbage collection activity (collection time and objects freed
548 mono \-\-profile=logging:g,as program.exe
551 Then you would need to invoke the decoder \fImprof\-decoder(1)\fR
552 on the output file to see the profiling results.
554 These are all the available oprions, organized by category:
556 \fBExecution profiling modes\fR
560 \fIstatistical\fR, \fIstat\fR or \fIs\fR
561 Performs statistical profiling. This is a lightweight profiling
562 mechanism and it has a much lower overhead than the \fIenter\-leave\fR
563 profiling as it works by sampling where the program is spending its
564 time by using a timer.
565 If specified with \fIs=<number>\fR, also inspect call chains up to level
568 \fIenter\-leave\fR, \fIcalls\fR or \fIc\fR
569 Measure the time spent inside each method call, this is done by
570 logging the time when a method enters and when the method leaves.
571 This can be a time consuming operation.
574 Collect information about time spent by the JIT engine compiling
577 \fItrack\-stack\fR, \fIts\fR
578 Track the execution stack. By itself this option does nothing, but it
579 enables more detailed reporting in other options (because the profiler
580 will use the stack data).
584 \fBAllocation profiling modes\fR
588 \fIallocations\fR, \fIalloc\fR or \fIa\fR
589 Collect information about each allocation (object class and size).
590 If combined with the "ts" option, for each allocation the profiler will
591 also show the responsible method (and also correctly dintinguish allocations
592 performed during JIT time).
593 These information are also available when combining the "a" and "c" options,
594 but since "c" is much more intrusive "ts" should be preferred.
596 \fIallocations\-summary\fR or \fIas\fR
597 At each collection dump a summary
598 of the heap contents (for each class, the number and collective size of all
599 live and freed heap objects). This very lightweight compared to full heap
602 \fIunreachable\fR, \fIfree\fR or \fIf\fR
603 Performs a lightweight profile of the garbage collector. On each
604 collection performed by the GC, the list of unreachable objects is
605 recorded, and for each object the class and size is provided. This
606 information can be used to compute the heap size broken down by class
607 (combined with "a" can give the same information of "as", but the log
608 file contains info about each individual object, while in "as" the
609 processing is done directly at runtime and the log file contains only
610 the summarized data broken down by class).
613 Measure the time spent in each collection, and also trace heap resizes.
615 \fIheap\-shot\fR, \fIheap\fR or \fIh\fR
616 Performs full heap profiling. In this case on each
617 collection a full heap snapshot is recorded to disk.
618 Inside the snapshots, each object reference is still represented so
619 that it's possible to investigate who is responsible for keeping objects
622 The actual production of heap snapshots could produce large log files,
623 so it can be controlled in three ways:
625 \fIgc\-dumps=N\fR, \fIgc\-d=N\fR, \fIgcd=N\fR
626 states the number of snapshots that must be dumped (since the application
627 starts). Zero means no dumps at all, \-1 means dump at all collections.
629 \fIgc\-signal=<signal>\fR, \fIgc\-s\fR or \fIgcs\fR
630 (where <signal> is one of "SIGUSR1", "SIGUSR2", or "SIGPROF")
631 specifies a signal that will immediately trigger a collection and a dump.
633 \fIgc\-commands=FILE\fR, \fIgc\-c=FILE\fR or \fIgcc=FILE\fR
634 specify a "command file". The file must contain an integer value in ASCII
635 form, and the profiler will stat it at every collection.
636 If it has been modified it will interpret its contents as a \fIgcd=N\fR
637 option value, and dump the required number of snapshots from that moment
639 If the file is present at application startup it takes precedence over an
640 eventual \fIgcd=N\fR option.
644 \fBProfiler activity control\fR
648 \fIoutput=FILE\fR, \fIout=FILE\fR or \fIo=FILE\fR
649 Use this option to provide the output file name for the profile log.
650 If this option is not specified, it will default to "<program-name>.mprof".
652 \fIoutput-suffix=SUFFIX\fR, \fIsuffix=SUFFIX\fR or \fIos=SUFFIX\fR: makes
653 the output file name equals to "<program-name>-SUFFIX.mprof".
655 \fIstart-enabled\fR or \fIse\fR: start with the profiler active
656 (which is the default).
658 \fIstart-disabled\fR or \fIsd\fR: start with the profiler inactive.
660 \fItoggle-signal=<SIGNAL>\fR or \fIts=<SIGNAL>\fR (where <SIGNAL>
661 is one of SIGUSR1, SIGUSR2 or SIGPROF): Choose a signal that will be used to
662 toggle the profiler activity on and off. This way you can decide to profile
663 only portions of the applicatopn lifetime (for instance, you can decide to
664 avoid profiling an initial setup phase using \fIsd\fR, and enable the
665 profiler later delivering the signal to the application).
667 \fIforce-accurate-timer\fR (or \fIfac\fR): the profiler by default uses
668 rtdsc to acquire timestamps for frequent events, but this can be imprecise;
669 using this option you force the use of "gettimeofday" at every event, which
670 is more accurate but much slower.
674 \fBInternal buffer sizes\fR
678 \fIper\-thread\-buffer\-size=N\fR, \fItbs=N\fR
679 Use to specify the number of events that a thread buffer
680 can hold. When the thread buffer is full, a log block is
683 This defaults to tbs=10000.
685 \fIstatistical\-thread\-buffer\-size=N\fR, \fIsbs=N\fR
686 The number of statistical samples that
687 are held in memory before they are dumped to disk (the system does
688 double\-buffering and the statistical samples are written by a helper
689 thread, so the statistical profiler never stops and is able to profile
690 the profiler itself).
692 This defaults to sbs=10000.
694 \fIwrite\-buffer\-size\fR, \fIwbs\fR
695 Specifies the size in bytes of the internal write buffers.
697 This defaults to wbs=1024.
701 In its current state, this profiler can also perform heap analysis (like
702 heap\-shot), and the decoder is already able to read the data, however
703 the user interface for this feature is experimental (the
704 \fImprof\-heap\-viewer\fR tool in the mono\-tools module).
706 Another known issue is that if the timer is not strictly monotonic (like
707 rtdsc), differences between times can underflow (they are handled as
708 unsigned integers) and weird numbers can show up in the logs.
710 Finally, it can happen that when exceptions are thrown the profiler temporarily
711 loses track of the execution stack and misattributes the caller for a few
712 allocations (and method execution time).
714 More explanations are provided here: "http://www.mono\-project.com/LoggingProfiler".
715 .SH "EXTERNAL PROFILERS"
716 There are a number of external profilers that have been developed for
717 Mono, we will update this section to contain the profilers.
719 The heap Shot profiler can track all live objects, and references to
720 these objects, and includes a GUI tool, this is our recommended
722 To install you must download the profiler
725 svn co svn://svn.myrealbox.com/source/trunk/heap\-shot
732 See the included documentation for details on using it.
734 The Live Type profiler shows at every GC iteration all of the live
735 objects of a given type. To install you must download the profiler
738 svn co svn://svn.myrealbox.com/source/trunk/heap\-prof
745 To use the profiler, execute:
747 mono \-\-profile=desc\-heap program.exe
750 The output of this profiler looks like this:
752 Checkpoint at 102 for heap\-resize
753 System.MonoType : 708
754 System.Threading.Thread : 352
756 System.String[] : 104
757 Gnome.ModuleInfo : 112
758 System.Object[] : 160
759 System.Collections.Hashtable : 96
760 System.I nt32[] : 212
761 System.Collections.Hashtable+Slot[] : 296
762 System.Globalization.CultureInfo : 108
763 System.Globalization.NumberFormatInfo : 144
766 The first line describes the iteration number for the GC, in this case
769 Then on each line the type is displayed as well as the number of bytes
770 that are being consumed by live instances of this object.
772 The AOT profiler is used to feed back information to the AOT compiler
773 about how to order code based on the access patterns for pages. To
776 mono \-\-profile=aot program.exe
778 The output of this profile can be fed back into Mono's AOT compiler to
779 order the functions on the disk to produce precompiled images that
780 have methods in sequential pages.
781 .SH "CUSTOM PROFILERS"
782 Mono provides a mechanism for loading other profiling modules which in
783 the form of shared libraries. These profiling modules can hook up to
784 various parts of the Mono runtime to gather information about the code
787 To use a third party profiler you must pass the name of the profiler
791 mono \-\-profile=custom program.exe
795 In the above sample Mono will load the user defined profiler from the
796 shared library `mono\-profiler\-custom.so'. This profiler module must
797 be on your dynamic linker library path.
799 A list of other third party profilers is available from Mono's web
800 site (www.mono\-project.com/Performance_Tips)
802 Custom profiles are written as shared libraries. The shared library
803 must be called `mono\-profiler\-NAME.so' where `NAME' is the name of
806 For a sample of how to write your own custom profiler look in the
807 Mono source tree for in the samples/profiler.c.
809 Mono ships with a code coverage module. This module is activated by
810 using the Mono \-\-profile=cov option. The format is:
811 \fB\-\-profile=cov[:assembly\-name[/namespace]] test\-suite.exe\fR
813 By default code coverage will default to all the assemblies loaded,
814 you can limit this by specifying the assembly name, for example to
815 perform code coverage in the routines of your program use, for example
816 the following command line limits the code coverage to routines in the
820 mono \-\-profile=cov:demo demo.exe
826 does not include the extension.
828 You can further restrict the code coverage output by specifying a
832 mono \-\-profile=cov:demo/My.Utilities demo.exe
836 Which will only perform code coverage in the given assembly and
839 Typical output looks like this:
842 Not covered: Class:.ctor ()
843 Not covered: Class:A ()
844 Not covered: Driver:.ctor ()
845 Not covered: Driver:method ()
846 Partial coverage: Driver:Main ()
851 The offsets displayed are IL offsets.
853 A more powerful coverage tool is available in the module `monocov'.
854 See the monocov(1) man page for details.
856 It is possible to obtain a stack trace of all the active threads in
857 Mono by sending the QUIT signal to Mono, you can do this from the
858 command line, like this:
864 Where pid is the Process ID of the Mono process you want to examine.
865 The process will continue running afterwards, but its state is not
869 this is a last\-resort mechanism for debugging applications and should
870 not be used to monitor or probe a production application. The
871 integrity of the runtime after sending this signal is not guaranteed
872 and the application might crash or terminate at any given point
875 You can use the MONO_LOG_LEVEL and MONO_LOG_MASK environment variables
876 to get verbose debugging output about the execution of your
877 application within Mono.
881 environment variable if set, the logging level is changed to the set
882 value. Possible values are "error", "critical", "warning", "message",
883 "info", "debug". The default value is "error". Messages with a logging
884 level greater then or equal to the log level will be printed to
887 Use "info" to track the dynamic loading of assemblies.
892 environment variable to limit the extent of the messages you get:
893 If set, the log mask is changed to the set value. Possible values are
894 "asm" (assembly loader), "type", "dll" (native library loader), "gc"
895 (garbage collector), "cfg" (config file loader), "aot" (precompiler) and "all".
896 The default value is "all". Changing the mask value allows you to display only
897 messages for a certain component. You can use multiple masks by comma
898 separating them. For example to see config file messages and assembly loader
899 messages set you mask to "asm,cfg".
901 The following is a common use to track down problems with P/Invoke:
904 $ MONO_LOG_LEVEL="debug" MONO_LOG_MASK="dll" mono glue.exe
909 Mono's XML serialization engine by default will use a reflection\-based
910 approach to serialize which might be slow for continuous processing
911 (web service applications). The serialization engine will determine
912 when a class must use a hand\-tuned serializer based on a few
913 parameters and if needed it will produce a customized C# serializer
914 for your types at runtime. This customized serializer then gets
915 dynamically loaded into your application.
917 You can control this with the MONO_XMLSERIALIZER_THS environment
920 The possible values are
922 to disable the use of a C# customized
923 serializer, or an integer that is the minimum number of uses before
924 the runtime will produce a custom serializer (0 will produce a
925 custom serializer on the first access, 50 will produce a serializer on
926 the 50th use). Mono will fallback to an interpreted serializer if the
927 serializer generation somehow fails. This behavior can be disabled
928 by setting the option
930 (for example: MONO_XMLSERIALIZER_THS=0,nofallback).
931 .SH "ENVIRONMENT VARIABLES"
934 Turns off the garbage collection in Mono. This should be only used
935 for debugging purposes
938 If set, this variable will instruct Mono to ahead\-of\-time compile new
939 assemblies on demand and store the result into a cache in
943 If set, this variable overrides the default system configuration directory
944 ($PREFIX/etc). It's used to locate machine.config file.
947 Sets the style of COM interop. If the value of this variable is "MS"
948 Mono will use string marhsalling routines from the liboleaut32 for the
949 BSTR type library, any other values will use the mono\-builtin BSTR
953 If set, this variable overrides the default runtime configuration file
954 ($PREFIX/etc/mono/config). The \-\-config command line options overrides the
955 environment variable.
958 If set, enables some features of the runtime useful for debugging.
959 This variable should contain a comma separated list of debugging options.
960 Currently, the following options are supported:
964 \fBbreak\-on\-unverified\fR
965 If this variable is set, when the Mono VM runs into a verification
966 problem, instead of throwing an exception it will break into the
967 debugger. This is useful when debugging verifier problems
969 \fBcollect\-pagefault\-stats\fR
970 Collects information about pagefaults. This is used internally to
971 track the number of page faults produced to load metadata. To display
972 this information you must use this option with "\-\-stats" command line
975 \fBdont\-free\-domains\fR
976 This is an Optimization for multi\-AppDomain applications (most
977 commonly ASP.NET applications). Due to internal limitations Mono,
978 Mono by default does not use typed allocations on multi\-appDomain
979 applications as they could leak memory when a domain is unloaded.
981 Although this is a fine default, for applications that use more than
982 on AppDomain heavily (for example, ASP.NET applications) it is worth
983 trading off the small leaks for the increased performance
984 (additionally, since ASP.NET applications are not likely going to
985 unload the application domains on production systems, it is worth
989 Captures the interrupt signal (Control\-C) and displays a stack trace
990 when pressed. Useful to find out where the program is executing at a
991 given point. This only displays the stack trace of a single thread.
993 \fBkeep\-delegates\fR
994 This option will leak delegate trampolines that are no longer
995 referenced as to present the user with more information about a
996 delegate misuse. Basically a delegate instance might be created,
997 passed to unmanaged code, and no references kept in managed code,
998 which will garbage collect the code. With this option it is possible
999 to track down the source of the problems.
1001 \fBno\-gdb\-backtrace\fR
1002 This option will disable the GDB backtrace emitted by the runtime
1003 after a SIGSEGV or SIGABRT in unmanaged code.
1007 \fBMONO_DISABLE_AIO\fR
1008 If set, tells mono NOT to attempt using native asynchronous I/O services. In
1009 that case, a default select/poll implementation is used. Currently only epoll()
1012 \fBMONO_DISABLE_MANAGED_COLLATION\fR
1013 If this environment variable is `yes', the runtime uses unmanaged
1014 collation (which actually means no culture\-sensitive collation). It
1015 internally disables managed collation functionality invoked via the
1016 members of System.Globalization.CompareInfo class. Collation is
1019 \fBMONO_EGD_SOCKET\fR
1020 For platforms that do not otherwise have a way of obtaining random bytes
1021 this can be set to the name of a file system socket on which an egd or
1022 prngd daemon is listening.
1024 \fBMONO_EVENTLOG_TYPE\fR
1025 Sets the type of event log provider to use (for System.Diagnostics.EventLog).
1027 Possible values are:
1032 Persists event logs and entries to the local file system.
1034 The directory in which to persist the event logs, event sources and entries
1035 can be specified as part of the value.
1037 If the path is not explicitly set, it defaults to "/var/lib/mono/eventlog"
1038 on unix and "%APPDATA%\mono\eventlog" on Windows.
1043 Uses the native win32 API to write events and registers event logs and
1044 event sources in the registry. This is only available on Windows.
1046 On Unix, the directory permission for individual event log and event source
1047 directories is set to 777 (with +t bit) allowing everyone to read and write
1048 event log entries while only allowing entries to be deleted by the user(s)
1053 Silently discards any events.
1056 The default is "null" on Unix (and versions of Windows before NT), and
1057 "win32" on Windows NT (and higher).
1060 \fBMONO_EXTERNAL_ENCODINGS\fR
1061 If set, contains a colon\-separated list of text encodings to try when
1062 turning externally\-generated text (e.g. command\-line arguments or
1063 filenames) into Unicode. The encoding names come from the list
1064 provided by iconv, and the special case "default_locale" which refers
1065 to the current locale's default encoding.
1067 When reading externally\-generated text strings UTF\-8 is tried first,
1068 and then this list is tried in order with the first successful
1069 conversion ending the search. When writing external text (e.g. new
1070 filenames or arguments to new processes) the first item in this list
1071 is used, or UTF\-8 if the environment variable is not set.
1073 The problem with using MONO_EXTERNAL_ENCODINGS to process your
1074 files is that it results in a problem: although its possible to get
1075 the right file name it is not necessarily possible to open the file.
1076 In general if you have problems with encodings in your filenames you
1077 should use the "convmv" program.
1079 \fBMONO_GAC_PREFIX\fR
1080 Provides a prefix the runtime uses to look for Global Assembly Caches.
1081 Directories are separated by the platform path separator (colons on
1082 unix). MONO_GAC_PREFIX should point to the top directory of a prefixed
1083 install. Or to the directory provided in the gacutil /gacdir command. Example:
1084 .B /home/username/.mono:/usr/local/mono/
1087 Enables some filename rewriting support to assist badly\-written
1088 applications that hard\-code Windows paths. Set to a colon\-separated
1089 list of "drive" to strip drive letters, or "case" to do
1090 case\-insensitive file matching in every directory in a path. "all"
1091 enables all rewriting methods. (Backslashes are always mapped to
1092 slashes if this variable is set to a valid option.)
1095 For example, this would work from the shell:
1098 MONO_IOMAP=drive:case
1102 If you are using mod_mono to host your web applications, you can use
1105 directive, like this:
1108 MonoSetEnv MONO_IOMAP=all
1112 \fBMONO_MANAGED_WATCHER\fR
1113 If set to "disabled", System.I O.FileSystemWatcher will use a file watcher
1114 implementation which silently ignores all the watching requests.
1115 If set to any other value, System.I O.FileSystemWatcher will use the default
1116 managed implementation (slow). If unset, mono will try to use inotify, FAM,
1117 Gamin, kevent under Unix systems and native API calls on Windows, falling
1118 back to the managed implementation on error.
1121 If set causes the mono process to be bound to a single processor. This may be
1122 useful when debugging or working around race conditions.
1125 Provides a search path to the runtime where to look for library
1126 files. This is a tool convenient for debugging applications, but
1127 should not be used by deployed applications as it breaks the assembly
1128 loader in subtle ways.
1130 Directories are separated by the platform path separator (colons on unix). Example:
1131 .B /home/username/lib:/usr/local/mono/lib
1133 Alternative solutions to MONO_PATH include: installing libraries into
1134 the Global Assembly Cache (see gacutil(1)) or having the dependent
1135 libraries side\-by\-side with the main executable.
1137 For a complete description of recommended practices for application
1139 http://www.mono\-project.com/Guidelines:Application_Deployment page.
1142 Experimental RTC support in the statistical profiler: if the user has
1143 the permission, more accurate statistics are gathered. The MONO_RTC
1144 value must be restricted to what the Linux rtc allows: power of two
1145 from 64 to 8192 Hz. To enable higher frequencies like 4096 Hz, run as root:
1148 echo 4096 > /proc/sys/dev/rtc/max\-user\-freq
1155 MONO_RTC=4096 mono \-\-profiler=default:stat program.exe
1160 Disable inlining of thread local accesses. Try setting this if you get a segfault
1161 early on in the execution of mono.
1163 \fBMONO_SHARED_DIR\fR
1164 If set its the directory where the ".wapi" handle state is stored.
1165 This is the directory where the Windows I/O Emulation layer stores its
1166 shared state data (files, events, mutexes, pipes). By default Mono
1167 will store the ".wapi" directory in the users's home directory.
1169 \fBMONO_SHARED_HOSTNAME\fR
1170 Uses the string value of this variable as a replacement for the host name when
1171 creating file names in the ".wapi" directory. This helps if the host name of
1172 your machine is likely to be changed when a mono application is running or if
1173 you have a .wapi directory shared among several different computers.
1175 Mono typically uses the hostname to create the files that are used to
1176 share state across multiple Mono processes. This is done to support
1177 home directories that might be shared over the network.
1179 \fBMONO_STRICT_IO_EMULATION\fR
1180 If set, extra checks are made during IO operations. Currently, this
1181 includes only advisory locks around file writes.
1183 \fBMONO_DISABLE_SHM\fR
1184 If set, disables the shared memory files used for cross\-process
1185 handles: process have only private handles. This means that process
1186 and thread handles are not available to other processes, and named
1187 mutexes, named events and named semaphores are not visible between
1190 This is can also be enabled by default by passing the
1191 "\-\-disable\-shared\-handles" option to configure.
1194 The name of the theme to be used by Windows.Forms. Available themes today
1195 include "clearlooks", "nice" and "win32".
1197 The default is "win32".
1199 \fBMONO_TLS_SESSION_CACHE_TIMEOUT\fR
1200 The time, in seconds, that the SSL/TLS session cache will keep it's entry to
1201 avoid a new negotiation between the client and a server. Negotiation are very
1202 CPU intensive so an application\-specific custom value may prove useful for
1203 small embedded systems.
1205 The default is 180 seconds.
1207 \fBMONO_THREADS_PER_CPU\fR
1208 The maximum number of threads in the general threadpool will be
1209 20 + (MONO_THREADS_PER_CPU * number of CPUs). The default value for this
1212 \fBMONO_XMLSERIALIZER_THS\fR
1213 Controls the threshold for the XmlSerializer to produce a custom
1214 serializer for a given class instead of using the Reflection\-based
1215 interpreter. The possible values are `no' to disable the use of a
1216 custom serializer or a number to indicate when the XmlSerializer
1217 should start serializing. The default value is 50, which means that
1218 the a custom serializer will be produced on the 50th use.
1220 \fBMONO_XMLSERIALIZER_DEBUG\fR
1221 Set this value to 1 to prevent the serializer from removing the
1222 temporary files that are created for fast serialization; This might
1223 be useful when debugging.
1225 \fBMONO_ASPNET_INHIBIT_SETTINGSMAP\fR
1226 Mono contains a feature which allows modifying settings in the .config files shipped
1227 with Mono by using config section mappers. The mappers and the mapping rules are
1228 defined in the $prefix/etc/mono/2.0/settings.map file and, optionally, in the
1229 settings.map file found in the top\-level directory of your ASP.NET application.
1230 Both files are read by System.Web on application startup, if they are found at the
1231 above locations. If you don't want the mapping to be performed you can set this
1232 variable in your environment before starting the application and no action will
1234 .SH "ENVIRONMENT VARIABLES FOR DEBUGGING"
1236 \fBMONO_ASPNET_NODELETE\fR
1237 If set to any value, temporary source files generated by ASP.NET support
1238 classes will not be removed. They will be kept in the user's temporary
1241 \fBMONO_LOG_LEVEL\fR
1242 The logging level, possible values are `error', `critical', `warning',
1243 `message', `info' and `debug'. See the DEBUGGING section for more
1247 Controls the domain of the Mono runtime that logging will apply to.
1248 If set, the log mask is changed to the set value. Possible values are
1249 "asm" (assembly loader), "type", "dll" (native library loader), "gc"
1250 (garbage collector), "cfg" (config file loader), "aot" (precompiler) and "all".
1251 The default value is "all". Changing the mask value allows you to display only
1252 messages for a certain component. You can use multiple masks by comma
1253 separating them. For example to see config file messages and assembly loader
1254 messages set you mask to "asm,cfg".
1257 Used for runtime tracing of method calls. The format of the comma separated
1266 disabled Trace output off upon start.
1269 You can toggle trace output on/off sending a SIGUSR2 signal to the program.
1271 \fBMONO_TRACE_LISTENER\fR
1272 If set, enables the System.Diagnostics.DefaultTraceListener, which will
1273 print the output of the System.Diagnostics Trace and Debug classes.
1274 It can be set to a filename, and to Console.Out or Console.Error to display
1275 output to standard output or standard error, respectively. If it's set to
1276 Console.Out or Console.Error you can append an optional prefix that will
1277 be used when writing messages like this: Console.Error:MyProgramName.
1278 See the System.Diagnostics.DefaultTraceListener documentation for more
1281 \fBMONO_XEXCEPTIONS\fR
1282 This throws an exception when a X11 error is encountered; by default a
1283 message is displayed but execution continues
1286 This is used in the System.Windows.Forms implementation when running
1287 with the X11 backend. This is used to debug problems in Windows.Forms
1288 as it forces all of the commands send to X11 server to be done
1289 synchronously. The default mode of operation is asynchronous which
1290 makes it hard to isolate the root of certain problems.
1292 \fBMONO_GENERIC_SHARING\fR
1293 This environment variable controls the kind of generic sharing used.
1294 This variable is used by internal JIT developers and should not be
1295 changed in production. Do not use it.
1297 The variable controls which classes will have generic code sharing
1300 Permissible values are:
1304 All generated code can be shared.
1307 Only the classes in System.Collections.Generic will have its code
1308 shared (this is the default value).
1311 Only code in corlib will have its code shared.
1314 No generic code sharing will be performed.
1317 Generic code sharing by default only applies to collections. The
1318 Mono JIT by default turns this on.
1320 If you want to use Valgrind, you will find the file `mono.supp'
1321 useful, it contains the suppressions for the GC which trigger
1322 incorrect warnings. Use it like this:
1324 valgrind \-\-suppressions=mono.supp mono ...
1327 On some platforms, Mono can expose a set of DTrace probes (also known
1328 as user\-land statically defined, USDT Probes).
1330 They are defined in the file `mono.d'.
1332 .B ves\-init\-begin, ves\-init\-end
1334 Begin and end of runtime initialization.
1336 .B method\-compile\-begin, method\-compile\-end
1338 Begin and end of method compilation.
1339 The probe arguments are class name, method name and signature,
1340 and in case of method\-compile\-end success or failure of compilation.
1342 .B gc\-begin, gc\-end
1344 Begin and end of Garbage Collection.
1346 To verify the availability of the probes, run:
1348 dtrace \-P mono'$target' \-l \-c mono
1351 On Unix assemblies are loaded from the installation lib directory. If you set
1352 `prefix' to /usr, the assemblies will be located in /usr/lib. On
1353 Windows, the assemblies are loaded from the directory where mono and
1356 .B ~/.mono/aot\-cache
1358 The directory for the ahead\-of\-time compiler demand creation
1359 assemblies are located.
1361 .B /etc/mono/config, ~/.mono/config
1363 Mono runtime configuration file. See the mono\-config(5) manual page
1364 for more information.
1366 .B ~/.config/.mono/certs, /usr/share/.mono/certs
1368 Contains Mono certificate stores for users / machine. See the certmgr(1)
1369 manual page for more information on managing certificate stores and
1370 the mozroots(1) page for information on how to import the Mozilla root
1371 certificates into the Mono certificate store.
1373 .B ~/.mono/assemblies/ASSEMBLY/ASSEMBLY.config
1375 Files in this directory allow a user to customize the configuration
1376 for a given system assembly, the format is the one described in the
1377 mono\-config(5) page.
1379 .B ~/.config/.mono/keypairs, /usr/share/.mono/keypairs
1381 Contains Mono cryptographic keypairs for users / machine. They can be
1382 accessed by using a CspParameters object with DSACryptoServiceProvider
1383 and RSACryptoServiceProvider classes.
1385 .B ~/.config/.isolatedstorage, ~/.local/share/.isolatedstorage, /usr/share/.isolatedstorage
1387 Contains Mono isolated storage for non\-roaming users, roaming users and
1388 local machine. Isolated storage can be accessed using the classes from
1389 the System.I O.I solatedStorage namespace.
1391 .B <assembly>.config
1393 Configuration information for individual assemblies is loaded by the
1394 runtime from side\-by\-side files with the .config files, see the
1395 http://www.mono\-project.com/Config for more information.
1397 .B Web.config, web.config
1399 ASP.NET applications are configured through these files, the
1400 configuration is done on a per\-directory basis. For more information
1401 on this subject see the http://www.mono\-project.com/Config_system.web
1404 Mailing lists are listed at the
1405 http://www.mono\-project.com/Mailing_Lists
1407 http://www.mono\-project.com
1410 certmgr(1), mcs(1), monocov(1), monodis(1), mono\-config(5), mozroots(1), xsp(1).
1412 For more information on AOT:
1413 http://www.mono\-project.com/AOT
1415 For ASP.NET\-related documentation, see the xsp(1) manual page