3 .\" (C) 2003 Ximian, Inc.
4 .\" (C) 2004-2005 Novell, Inc.
6 .\" Miguel de Icaza (miguel@gnu.org)
8 .de Sp \" Vertical space (when we can't use .PP)
14 mono \- Mono's ECMA-CLI native code generator (Just-in-Time and Ahead-of-Time)
17 .B mono [options] file [arguments...]
19 \fImono\fP is a runtime implementation of the ECMA Common Language
20 Infrastructure. This can be used to run ECMA and .NET applications.
22 The runtime contains a native code generator that transforms the
23 Common Intermediate Language into native code.
25 The code generator can operate in two modes: just in time compilation
26 (JIT) or ahead of time compilation (AOT). Since code can be
27 dynamically loaded, the runtime environment and the JIT are always
28 present, even if code is compiled ahead of time.
30 The runtime loads ths specified
37 is an ECMA assembly. They typically have a .exe or .dll extension.
39 The runtime provides a number of configuration options for running
40 applications, for developping and debugging, and for testing and
41 debugging the runtime itself.
43 The following options are available:
46 This option is used to precompile the CIL code in the specified
47 assembly to native code. The generated code is stored in a file with
48 the extension .so. This file will be automatically picked up by the
49 runtime when the assembly is executed.
51 Ahead-of-Time compilation is most useful if you use it in combination
52 with the -O=all,-shared flag which enables all of the optimizations in
53 the code generator to be performed. Some of those optimizations are
54 not practical for Just-in-Time compilation since they might be very
57 Unlike the .NET Framework, Ahead-of-Time compilation will not generate
58 domain independent code: it generates the same code that the
59 Just-in-Time compiler would produce. Since most applications use a
60 single domain, this is fine. If you want to optimize the generated
61 code for use in multi-domain applications, consider using the
64 This pre-compiles the methods, but the original assembly is still
65 required to execute as this one contains the metadata and exception
66 information which is not availble on the generated file. When
67 precompiling code, you might want to compile with all optimizations
68 (-O=all). Pre-compiled code is position independent code.
70 Pre compilation is just a mechanism to reduce startup time, and avoid
71 just-in-time compilation costs. The original assembly must still be
72 present, as the metadata is contained there.
74 .I "--config filename"
75 Load the specified configuration file instead of the default one(s).
76 The default files are /etc/mono/config and ~/.mono/config or the file
77 specified in the MONO_CONFIG environment variable, if set. See the
78 mono-config(5) man page for details on the format of this file.
81 Configures the virtual machine to be better suited for desktop
82 applications. Currently this sets the GC system to avoid expanding
83 the heap as much as possible at the expense of slowing down garbage
87 Displays usage instructions.
89 .I "--optimize=MODE", "-O=mode"
90 MODE is a comma separated list of optimizations. They also allow
91 optimizations to be turned off by prefixing the optimization name with
94 The following optimizations are implemented:
96 all Turn on all optimizations
97 peephole Peephole postpass
98 branch Branch optimizations
99 inline Inline method calls
100 cfold Constant folding
101 consprop Constant propagation
102 copyprop Copy propagation
103 deadce Dead code elimination
104 linears Linear scan global reg allocation
105 cmov Conditional moves
106 shared Emit per-domain code
107 sched Instruction scheduling
108 intrins Intrinsic method implementations
109 tailc Tail recursion and tail calls
110 loop Loop related optimizations
111 fcmov Fast x86 FP compares
112 leaf Leaf procedures optimizations
113 aot Usage of Ahead Of Time compiled code
114 precomp Precompile all methods before executing Main
115 abcrem Array bound checks removal
116 ssapre SSA based Partial Redundancy Elimination
119 For example, to enable all the optimization but dead code
120 elimination and inlining, you can use:
122 -O=all,-deadce,-inline
126 Activate the security manager (experimental feature in 1.1). This allows
127 mono to support declarative security attributes (e.g. execution of, CAS
128 or non-CAS, security demands). The security manager is OFF by default
132 Configures the virtual machine to be better suited for server
136 Prints JIT version information.
139 .SH DEVELOPMENT OPTIONS
140 The following options are used to help when developing a JITed application.
143 Turns on the debugging mode in the runtime. If an assembly was
144 compiled with debugging information, it will produce line number
145 information for stack traces.
147 .I "--profile[=profiler[:profiler_args]]"
148 Turns on profiling. For more information about profiling applications
149 and code coverage see the sections "PROFILING" and "CODE COVERAGE"
152 .I "--trace[=expression]"
153 Shows method names as they are invoked. By default all methods are
156 The trace can be customized to include or exclude methods, classes or
157 assemblies. A trace expression is a comma separated list of targets,
158 each target can be prefixed with a minus sign to turn off a particular
159 target. The words `program' and `all' have special meaning.
160 `program' refers to the main program being executed, and `all' means
161 all the method calls.
163 Assemblies are specified by their name, for example, to trace all
164 calls in the System assembly, use:
167 mono --trace=System app.exe
170 Classes are specified with the T: prefix. For example, to trace all
171 calls to the System.String class, use:
174 mono --trace=T:System.String app.exe
177 And individual methods are referenced with the M: prefix, and the
178 standar method notation:
181 mono --trace=M:System.Console:WriteLine app.exe
184 As previously noted, various rules can be specified at once:
187 mono --trace=T:System.String,T:System.Random app.exe
190 You can exclude pieces, the next example traces calls to
191 System.String except for the System.String:Concat method.
194 mono --trace=T:System.String,-M:System.String:Concat
197 Finally, namespaces can be specified using the N: prefix:
200 mono --trace=N:System.Xml
203 .SH JIT MAINTAINER OPTIONS
204 The maintainer options are only used by those developing the runtime
205 itself, and not typically of interest to runtime users or developers.
208 This compiles a method (namespace.name:methodname), this is used for
209 testing the compiler performance or to examine the output of the code
213 Compiles all the methods in an assembly. This is used to test the
214 compiler performance or to examine the output of the code generator
216 .I "--graph=TYPE METHOD"
217 This generates a postscript file with a graph with the details about
218 the specified method (namespace.name:methodname). This requires `dot'
219 and ghostview to be installed (it expects Ghostview to be called
222 The following graphs are available:
224 cfg Control Flow Graph (CFG)
226 code CFG showing code
227 ssa CFG showing code after SSA translation
228 optcode CFG showing code after IR optimizations
231 Some graphs will only be available if certain optimizations are turned
235 Instruct the runtime on the number of times that the method specified
236 by --compile (or all the methods if --compileall is used) to be
237 compiled. This is used for testing the code generator performance.
240 Increases the verbosity level, each time it is listed, increases the
241 verbosity level to include more information (including, for example,
242 a disassembly of the native code produced, code selector info etc.).
245 Inserts a breakpoint before the method whose name is `method'
246 (namespace.class:methodname). Use `Main' as method name to insert a
247 breakpoint on the application's main method.
250 Inserts a breakpoint on exceptions. This allows you to debug your
251 application with a native debugger when an exception is thrown.
253 The mono runtime includes a profiler that can be used to explore
254 various performance related problems in your application. The
255 profiler is activated by passing the --profile command line argument
256 to the Mono runtime, the format is:
259 --profile[=profiler[:profiler_args]]
262 Mono has a built-in profiler called 'default' (and is also the default
263 if no arguments are specified), but developers can write custom
264 profilers, see the section "CUSTOM PROFILERS" for more details.
268 is not specified, the default profiler is used.
272 is a profiler-specific string of options for the profiler itself.
274 The default profiler accepts the following options 'alloc' to profile
275 memory consumption by the application; 'time' to profile the time
276 spent on each routine and 'stat' to perform sample statistical
277 profiling. If no options are provided the default is 'alloc,time'.
282 mono --profile program.exe
286 That will run the program with the default profiler and will do time
287 and allocation profiling.
291 mono --profile=default:stat,alloc program.exe
294 Will do sample statistical profiling and allocation profiling on
297 There are a number of external profilers that have been developed for
298 Mono, we will update this section to contain the profilers.
300 The Live Type profiler shows at every GC iteration all of the live
301 objects of a given type. To install you must download the profiler
304 svn co svn://svn.myrealbox.com/source/trunk/heap-prof
311 To use the profiler, execute:
313 mono --profile=desc-heap program.exe
316 The output of this profiler looks like this:
318 Checkpoint at 102 for heap-resize
319 System.MonoType : 708
320 System.Threading.Thread : 352
322 System.String[] : 104
323 Gnome.ModuleInfo : 112
324 System.Object[] : 160
325 System.Collections.Hashtable : 96
327 System.Collections.Hashtable+Slot[] : 296
328 System.Globalization.CultureInfo : 108
329 System.Globalization.NumberFormatInfo : 144
332 The first line describes the iteration number for the GC, in this case
335 Then on each line the type is displayed as well as the number of bytes
336 that are being consumed by live instances of this object.
338 Mono provides a mechanism for loading other profiling modules which in
339 the form of shared libraries. These profiling modules can hook up to
340 various parts of the Mono runtime to gather information about the code
343 To use a third party profiler you must pass the name of the profiler
347 mono --profile=custom program.exe
351 In the above sample Mono will load the user defined profiler from the
352 shared library `mono-profiler-custom.so'. This profiler module must
353 be on your dynamic linker library path.
355 A list of other third party profilers is available from Mono's web
356 site (www.mono-project.com/Performance_Tips)
358 Custom profiles are written as shared libraries. The shared library
359 must be called `mono-profiler-NAME.so' where `NAME' is the name of
362 For a sample of how to write your own custom profiler look in the
363 Mono source tree for in the samples/profiler.c.
365 Mono ships with a code coverage module. This module is activated by
366 using the Mono --profile=cov option. The format is:
367 .I "--profile=cov[:assembly-name[/namespace]] test-suite.exe"
369 By default code coverage will default to all the assemblies loaded,
370 you can limit this by specifying the assembly name, for example to
371 perform code coverage in the routines of your program use, for example
372 the following command line limits the code coverage to routines in the
376 mono --profile=cov:demo demo.exe
382 does not include the extension.
384 You can further restrict the code coverage output by specifying a
388 mono --profile=cov:demo/My.Utilities demo.exe
392 Which will only perform code coverage in the given assembly and
395 Typical output looks like this:
398 Not covered: Class:.ctor ()
399 Not covered: Class:A ()
400 Not covered: Driver:.ctor ()
401 Not covered: Driver:method ()
402 Partial coverage: Driver:Main ()
407 The offsets displayed are IL offsets.
410 You can use the MONO_LOG_LEVEL and MONO_LOG_MASK environment variables
411 to get verbose debugging output about the execution of your
412 application within Mono.
416 environment variable if set, the logging level is changed to the set
417 value. Possible values are "error", "critical", "warning", "message",
418 "info", "debug". The default value is "error". Messages with a logging
419 level greater then or equal to the log level will be printed to
422 Use "info" to track the dynamic loading of assemblies.
427 environment variable to limit the extent of the messages you get:
428 If set, the log mask is changed to the set value. Possible values are
429 "asm" (assembly loader), "type", "dll" (native library loader), "gc"
430 (garbage collector), "cfg" (config file loader), "aot" (precompiler) and "all".
431 The default value is "all". Changing the mask value allows you to display only
432 messages for a certain component. You can use multiple masks by comma
433 separating them. For example to see config file messages and assembly loader
434 messages set you mask to "asm,cfg".
436 The following is a common use to track down problems with P/Invoke:
439 $ MONO_LOG_LEVEL="debug" MONO_LOG_MASK="dll" mono glue.exe
444 Mono's XML serialization engine by default will use a reflection-based
445 approach to serialize which might be slow for continous processing
446 (web service applications). The serialization engine will determine
447 when a class must use a hand-tuned serializer based on a few
448 parameters and if needed it will produce a customized C# serializer
449 for your types at runtime. This customized serializer then gets
450 dynamically loaded into your application.
452 You can control this with the MONO_XMLSERIALIZER_THS environment
455 The possible values are
457 to disable the use of a C# customized
458 serializer, or an integer that is the minimum number of uses before
459 the runtime will produce a custom serializer (0 will produce a
460 custom serializer on the first access, 50 will produce a serializer on
462 .SH ENVIRONMENT VARIABLES
465 Turns off the garbage collection in Mono. This should be only used
466 for debugging purposes
469 If set, this variable will instruct Mono to ahead-of-time compile new
470 assemblies on demand and store the result into a cache in
473 .I "MONO_ASPNET_NODELETE"
474 If set to any value, temporary source files generated by ASP.NET support
475 classes will not be removed. They will be kept in the user's temporary
479 If set, this variable overrides the default system configuration directory
480 ($PREFIX/etc). It's used to locate machine.config file.
483 If set, this variable overrides the default runtime configuration file
484 ($PREFIX/etc/mono/config). The --config command line options overrides the
485 environment variable.
488 If set, enables some features of the runtime useful for debugging.
489 This variable should contain a comma separated list of debugging options.
490 Currently, the following options are supported:
495 This option will leak delegate trampolines that are no longer
496 referenced as to present the user with more information about a
497 delegate missuse. Basically a delegate instance might be created,
498 passed to unmanaged code, and no references kept in managed code,
499 which will garbage collect the code. With this option it is possible
500 to track down the source of the problems.
502 .I "abort-on-sigsegv"
503 This option will make the runtime abort when it receives a SIGSEGV signal
504 while executing unmanaged (native) code. This is useful for debugging
505 problems when interfacing with native code.
509 .I "MONO_DISABLE_AIO"
510 If set, tells mono NOT to attempt using native asynchronous I/O services. In
511 that case, a default select/poll implementation is used. Currently only epoll()
515 For platforms that do not otherwise have a way of obtaining random bytes
516 this can be set to the name of a file system socket on which an egd or
517 prngd daemon is listening.
519 .I "MONO_EXTERNAL_ENCODINGS"
520 If set, contains a colon-separated list of text encodings to try when
521 turning externally-generated text (e.g. command-line arguments or
522 filenames) into Unicode. The encoding names come from the list
523 provided by iconv, and the special case "default_locale" which refers
524 to the current locale's default encoding.
526 When reading externally-generated text strings UTF-8 is tried first,
527 and then this list is tried in order with the first successful
528 conversion ending the search. When writing external text (e.g. new
529 filenames or arguments to new processes) the first item in this list
530 is used, or UTF-8 if the environment variable is not set.
533 Provides a prefix the runtime uses to look for Global Assembly Caches.
534 Directories are separated by the platform path separator (colons on
535 unix). MONO_GAC_PREFIX should point to the top directory of a prefixed
536 install. Or to the directory provided in the gacutil /gacdir command. Example:
537 .B /home/username/.mono:/usr/local/mono/
540 The logging level, possible values are `error', `critical', `warning',
541 `message', `info' and `debug'. See the DEBUGGING section for more
545 Controls the domain of the Mono runtime that logging will apply to.
546 If set, the log mask is changed to the set value. Possible values are
547 "asm" (assembly loader), "type", "dll" (native library loader), "gc"
548 (garbage collector), "cfg" (config file loader), "aot" (precompiler) and "all".
549 The default value is "all". Changing the mask value allows you to display only
550 messages for a certain component. You can use multiple masks by comma
551 separating them. For example to see config file messages and assembly loader
552 messages set you mask to "asm,cfg".
554 .I "MONO_MANAGED_WATCHER"
555 If set to any value, System.IO.FileSystemWatcher will use the default
556 managed implementation (slow). If unset, mono will try to use FAM under
557 Unix systems and native API calls on Windows, falling back to the
558 managed implementation on error.
561 Provides a search path to the runtime where to look for library files.
562 Directories are separated by the platform path separator (colons on unix). Example:
563 .B /home/username/lib:/usr/local/mono/lib
566 Experimental RTC support in the statistical profiler: if the user has
567 the permission, more accurate statistics are gathered. The MONO_RTC
568 value must be restricted to what the linux rtc allows: power of two
569 from 64 to 8192 Hz. To enable higher frequencies like 4096 Hz, run as root:
572 echo 4096 > /proc/sys/dev/rtc/max-user-freq
579 MONO_RTC=4096 mono --profiler=default:stat program.exe
584 Disable inlining of thread local accesses. Try setting this if you get a segfault
585 early on in the execution of mono.
588 If set its the directory where the ".wapi" handle state is stored.
589 This is the directory where the Windows I/O Emulation layer stores its
590 shared state data (files, events, mutexes, pipes). By default Mono
591 will store the ".wapi" directory in the users's home directory.
593 .I "MONO_THREADS_PER_CPU"
594 The maximum number of threads in the general threadpool will be
595 20 + (MONO_THREADS_PER_CPU * number of CPUs). The default value for this
599 Used for runtime tracing of method calls. The format of the comma separated
608 disabled Trace output off upon start.
611 You can toggle trace output on/off sending a SIGUSR2 signal to the program.
613 .I "MONO_TRACE_LISTENER"
614 If set, enables the System.Diagnostics.DefaultTraceListener, which will
615 print the output of the System.Diagnostics Trace and Debug classes.
616 It can be set to a filename, and to Console.Out or Console.Error to display
617 output to standard output or standard error, respectively. If it's set to
618 Console.Out or Console.Error you can append an optional prefix that will
619 be used when writing messages like this: Console.Error:MyProgramName.
620 See the System.Diagnostics.DefaultTraceListener documentation for more
623 .I "MONO_XMLSERIALIZER_THS"
624 Controls the threshold for the XmlSerializer to produce a custom
625 serializer for a given class instead of using the Reflection-based
626 interpreter. The possible values are `no' to disable the use of a
627 custom serializer or a number to indicate when the XmlSerializer
628 should start serializing. The default value is 50, which means that
629 the a custom serializer will be produced on the 50th use.
631 On Unix assemblies are loaded from the installation lib directory. If you set
632 `prefix' to /usr, the assemblies will be located in /usr/lib. On
633 Windows, the assemblies are loaded from the directory where mono and
638 The directory for the ahead-of-time compiler demand creation
639 assemblies are located.
641 /etc/mono/config, ~/.mono/config
643 Mono runtime configuration file. See the mono-config(5) manual page
644 for more information.
646 ~/.config/.mono/certs, /usr/share/.mono/certs
648 Contains Mono certificate stores for users / machine. See the certmgr(1)
649 manual page for more information on managing certificate stores.
651 ~/.config/.mono/keypairs, /usr/share/.mono/keypairs
653 Contains Mono cryptographic keypairs for users / machine. They can be
654 accessed by using a CspParameters object with DSACryptoServiceProvider
655 and RSACryptoServiceProvider classes.
657 ~/.config/.isolatedstorage, ~/.local/share/.isolatedstorage, /usr/share/.isolatedstorage
659 Contains Mono isolated storage for non-roaming users, roaming users and
660 local machine. Isolated storage can be accessed using the classes from
661 the System.IO.IsolatedStorage namespace.
663 Mailing lists are listed at the
664 http://www.mono-project.com/Mailing_Lists
666 http://www.mono-project.com
668 .BR mcs(1), mint(1), monodis(1), mono-config(5), certmgr(1).
670 For ASP.NET-related documentation, see the xsp(1) manual page