1Mono(Mono 4.7.0) Mono(Mono 4.7.0)
2
6 mono - Mono's ECMA-CLI native code generator (Just-in-Time and Ahead-
7 of-Time)
8
10 mono [options] file [arguments...]
11 mono-sgen [options] file [arguments...]
13
15 mono is a runtime implementation of the ECMA Common Language Infra‐
16 structure. This can be used to run ECMA and .NET applications.
17 The runtime contains a native code generator that transforms the Common
19 Intermediate Language into native code.
20 The code generator can operate in two modes: just in time compilation
22 (JIT) or ahead of time compilation (AOT). Since code can be dynami‐
23 cally loaded, the runtime environment and the JIT are always present,
24 even if code is compiled ahead of time.
25 The runtime loads the specified file and optionally passes the argu‐
27 ments to it. The file is an ECMA assembly. They typically have a .exe
28 or .dll extension.
29 The runtime provides a number of configuration options for running
31 applications, for developing and debugging, and for testing and debug‐
32 ging the runtime itself.
33 The mono command uses the Boehm conservative garbage collector while
35 the mono-sgen command uses a moving and generational garbage collector.
36
38 On Unix-based systems, Mono provides a mechanism to emulate the Win‐
39 dows-style file access, this includes providing a case insensitive view
40 of the file system, directory separator mapping (from \ to /) and
41 stripping the drive letters.
42 This functionality is enabled by setting the MONO_IOMAP environment
44 variable to one of all, drive and case.
45 See the description for MONO_IOMAP in the environment variables section
47 for more details.
48
50 The following options are available:
51 --aot, --aot[=options]
53 This option is used to precompile the CIL code in the specified
54 assembly to native code. The generated code is stored in a file
55 with the extension .so. This file will be automatically picked
56 up by the runtime when the assembly is executed. Ahead-of-Time
57 compilation is most useful if you use it in combination with the
58 -O=all,-shared flag which enables all of the optimizations in
59 the code generator to be performed. Some of those optimizations
60 are not practical for Just-in-Time compilation since they might
61 be very time consuming. Unlike the .NET Framework, Ahead-of-
62 Time compilation will not generate domain independent code: it
63 generates the same code that the Just-in-Time compiler would
64 produce. Since most applications use a single domain, this is
65 fine. If you want to optimize the generated code for use in
66 multi-domain applications, consider using the -O=shared flag.
67 This pre-compiles the methods, but the original assembly is
68 still required to execute as this one contains the metadata and
69 exception information which is not available on the generated
70 file. When precompiling code, you might want to compile with
71 all optimizations (-O=all). Pre-compiled code is position inde‐
72 pendent code. Pre compilation is just a mechanism to reduce
73 startup time, increase code sharing across multiple mono pro‐
74 cesses and avoid just-in-time compilation program startup costs.
75 The original assembly must still be present, as the metadata is
76 contained there. AOT code typically can not be moved from one
77 computer to another (CPU-specific optimizations that are
78 detected at runtime) so you should not try to move the pre-gen‐
79 erated assemblies or package the pre-generated assemblies for
80 deployment. A few options are available as a parameter to the
81 --aot command line option. The options are separated by com‐
82 mas, and more than one can be specified:
83 autoreg
85 The AOT compiler will emit a (ELF only) library initial‐
86 izer to automatically register the aot compiled module
87 with the runtime. This is only useful in static mode
88 asmonly
90 Instructs the AOT compiler to output assembly code
91 instead of an object file.
92 bind-to-runtime-version
94 If specified, forces the generated AOT files to be bound
95 to the runtime version of the compiling Mono. This will
96 prevent the AOT files from being consumed by a different
97 Mono runtime. full This is currently an experimental
98 feature as it is not complete. This instructs Mono to
99 precompile code that has historically not been precom‐
100 piled with AOT.
101 data-outfile=FILE.dll.aotdata
103 This instructs the AOT code generator to output certain
104 data constructs into a separate file. This can reduce
105 the executable images some five to twenty percent.
106 Developers need to then ship the resulting aotdata as a
107 resource and register a hook to load the data on demand
108 by using the mono_install_load_aot_data_hook method.
109 direct-pinvoke
111 When this option is specified, P/Invoke methods are
112 invoked directly instead of going through the operating
113 system symbol lookup operation.
114 llvm-path=<PREFIX>
116 Same for the llvm tools 'opt' and 'llc'.
117 msym-dir=<PATH>
119 Instructs the AOT compiler to generate offline sequence
120 points .msym files. The generated .msym files will be
121 stored into a subfolder of <PATH> named as the compila‐
122 tion AOTID.
123 mtriple=<TRIPLE>
125 Use the GNU style target triple <TRIPLE> to determine
126 some code generation options, i.e.
127 --mtriple=armv7-linux-gnueabi will generate code that
128 targets ARMv7. This is currently only supported by the
129 ARM backend. In LLVM mode, this triple is passed on to
130 the LLVM llc compiler.
131 nimt-trampolines=[number]
133 When compiling in full aot mode, the IMT trampolines must
134 be precreated in the AOT image. You can add additional
135 method trampolines with this argument. Defaults to 128.
136 nodebug
138 Instructs the AOT compiler to not output any debugging
139 information.
140 no-direct-calls
142 This prevents the AOT compiler from generating a direct
143 calls to a method. The AOT compiler usually generates
144 direct calls for certain methods that do not require
145 going through the PLT (for example, methods that are
146 known to not require a hook like a static constructor) or
147 call into simple internal calls.
148 dwarfdebug
150 Instructs the AOT compiler to emit DWARF debugging infor‐
151 mation. When used together with the nodebug option, only
152 DWARF debugging information is emitted, but not the
153 information that can be used at runtime.
154 nrgctx-trampolines=[number]
156 When compiling in full aot mode, the generic sharing
157 trampolines must be precreated in the AOT image. You can
158 add additional method trampolines with this argument.
159 Defaults to 1024.
160 ntrampolines=[number]
162 When compiling in full aot mode, the method trampolines
163 must be precreated in the AOT image. You can add addi‐
164 tional method trampolines with this argument. Defaults
165 to 1024.
166 outfile=[filename]
168 Instructs the AOT compiler to save the output to the
169 specified file.
170 print-skipped-methods
172 If the AOT compiler cannot compile a method for any rea‐
173 son, enabling this flag will output the skipped methods
174 to the console.
175 readonly-value=namespace.typename.fieldname=type/value
177 Override the value of a static readonly field. Usually,
178 during JIT compilation, the static constructor is ran
179 eagerly, so the value of a static readonly field is known
180 at compilation time and the compiler can do a number of
181 optimizations based on it. During AOT, instead, the
182 static constructor can't be ran, so this option can be
183 used to set the value of such a field and enable the same
184 set of optimizations. Type can be any of i1, i2, i4 for
185 integers of the respective sizes (in bytes). Note that
186 signed/unsigned numbers do not matter here, just the
187 storage size. This option can be specified multiple
188 times and it doesn't prevent the static constructor for
189 the type defining the field to execute with the usual
190 rules at runtime (hence possibly computing a different
191 value for the field).
192 save-temps,keep-temps
195 Instructs the AOT compiler to keep temporary files.
196 soft-debug
198 This instructs the compiler to generate sequence point
199 checks that allow Mono's soft debugger to debug applica‐
200 tions even on systems where it is not possible to set
201 breakpoints or to single step (certain hardware configu‐
202 rations like the cell phones and video gaming consoles).
203 static Create an ELF object file (.o) or .s file which can be
205 statically linked into an executable when embedding the
206 mono runtime. When this option is used, the object file
207 needs to be registered with the embedded runtime using
208 the mono_aot_register_module function which takes as its
209 argument the mono_aot_module_<ASSEMBLY NAME>_info global
210 symbol from the object file:
211 extern void *mono_aot_module_hello_info;
213 mono_aot_register_module (mono_aot_module_hello_info);
215 stats Print various stats collected during AOT compilation.
217 threads=[number]
219 This is an experimental option for the AOT compiler to
220 use multiple threads when compiling the methods.
221 tool-prefix=<PREFIX>
223 Prepends <PREFIX> to the name of tools ran by the AOT
224 compiler, i.e. 'as'/'ld'. For example, --tool=prefix=arm-
225 linux-gnueabi- will make the AOT compiler run
226 write-symbols
228 Instructs the AOT compiler to emit debug symbol informa‐
229 tion.
230 For more information about AOT, see: http://www.mono-
232 project.com/docs/advanced/aot/
233 --attach=[options]
235 Currently the only option supported by this command line argu‐
236 ment is disable which disables the attach functionality.
237 --config filename
239 Load the specified configuration file instead of the default
240 one(s). The default files are /etc/mono/config and ~/.mono/con‐
241 fig or the file specified in the MONO_CONFIG environment vari‐
242 able, if set. See the mono-config(5) man page for details on
243 the format of this file.
244 --debugger-agent=[options]
246 This instructs the Mono runtime to start a debugging agent
247 inside the Mono runtime and connect it to a client user inter‐
248 face will control the Mono process. This option is typically
249 used by IDEs, like the MonoDevelop IDE.
250 The configuration is specified using one of more of the following
252 options:
253 address=host:port
255 Use this option to specify the IP address where your
256 debugger client is listening to.
257 loglevel=LEVEL
259 Specifies the diagnostics log level for
260 logfile=filename
262 Used to specify the file where the log will be stored, it
263 defaults to standard output.
264 server=[y/n]
266 Defaults to no, with the default option Mono will
267 actively connect to the host/port configured with the
268 address option. If you set it to 'y', it instructs the
269 Mono runtime to start debugging in server mode, where
270 Mono actively waits for the debugger front end to connect
271 to the Mono process. Mono will print out to stdout the
272 IP address and port where it is listening.
273 setpgid=[y/n]
275 If set to yes, Mono will call setpgid(0, 0) on startup,
276 if that function is available on the system. This is use‐
277 ful for ensuring that signals delivered to a process that
278 is executing the debuggee are not propagated to the
279 debuggee, e.g. when Ctrl-C sends SIGINT to the sdb tool.
280 suspend=[y/n]
282 Defaults to yes, with the default option Mono will sus‐
283 pend the vm on startup until it connects successfully to
284 a debugger front end. If you set it to 'n', in conjunc‐
285 tion with server=y, it instructs the Mono runtime to run
286 as normal, while caching metadata to send to the debugger
287 front end on connection..
288 transport=transport_name
290 This is used to specify the transport that the debugger
291 will use to communicate. It must be specified and cur‐
292 rently requires this to be 'dt_socket'.
293 --desktop
295 Configures the virtual machine to be better suited for desktop
296 applications. Currently this sets the GC system to avoid
297 expanding the heap as much as possible at the expense of slowing
298 down garbage collection a bit.
299 --full-aot
301 This is an experimental flag that instructs the Mono runtime to
302 not generate any code at runtime and depend exclusively on the
303 code generated from using mono --aot=full previously. This is
304 useful for platforms that do not permit dynamic code generation.
305 Notice that this feature will abort execution at runtime if a
306 codepath in your program, or Mono's class libraries attempts to
307 generate code dynamically. You should test your software
308 upfront and make sure that you do not use any dynamic features.
309 --gc=boehm, --gc=sgen
311 Selects the Garbage Collector engine for Mono to use, Boehm or
312 SGen. Currently this merely ensures that you are running either
313 the mono or mono-sgen commands. This flag can be set in the
314 MONO_ENV_OPTIONS environment variable to force all of your child
315 processes to use one particular kind of GC with the Mono run‐
316 time.
317 --arch=32, --arch=64
319 (Mac OS X only): Selects the bitness of the Mono binary used, if
320 available. If the binary used is already for the selected bit‐
321 ness, nothing changes. If not, the execution switches to a
322 binary with the selected bitness suffix installed side by side
323 (for example, '/bin/mono --arch=64' will switch to '/bin/mono64'
324 iff '/bin/mono' is a 32-bit build).
325 --help, -h
327 Displays usage instructions.
328 --llvm If the Mono runtime has been compiled with LLVM support (not
330 available in all configurations), Mono will use the LLVM opti‐
331 mization and code generation engine to JIT or AOT compile. For
332 more information, consult: http://www.mono-
333 project.com/docs/advanced/mono-llvm/
334 --nollvm
336 When using a Mono that has been compiled with LLVM support, it
337 forces Mono to fallback to its JIT engine and not use the LLVM
338 backend.
339 --optimize=MODE, -O=MODE
341 MODE is a comma separated list of optimizations. They also
342 allow optimizations to be turned off by prefixing the optimiza‐
343 tion name with a minus sign. In general, Mono has been tuned to
344 use the default set of flags, before using these flags for a
345 deployment setting, you might want to actually measure the bene‐
346 fits of using them. The following optimization flags are imple‐
347 mented in the core engine:
348 abcrem Array bound checks removal
349 all Turn on all optimizations
350 aot Usage of Ahead Of Time compiled code
351 branch Branch optimizations
352 cfold Constant folding
353 cmov Conditional moves [arch-dependency]
354 deadce Dead code elimination
355 consprop Constant propagation
356 copyprop Copy propagation
357 fcmov Fast x86 FP compares [arch-dependency]
358 float32 Perform 32-bit float arithmetic using 32-bit operations
359 gshared Enable generic code sharing.
360 inline Inline method calls
361 intrins Intrinsic method implementations
362 linears Linear scan global reg allocation
363 leaf Leaf procedures optimizations
364 loop Loop related optimizations
365 peephole Peephole postpass
366 precomp Precompile all methods before executing Main
367 sched Instruction scheduling
368 shared Emit per-domain code
369 sse2 SSE2 instructions on x86 [arch-dependency]
370 tailc Tail recursion and tail calls
371 For example, to enable all the optimization but dead code elimi‐
372 nation and inlining, you can use:
373 -O=all,-deadce,-inline
374 The flags that are flagged with [arch-dependency] indicate that
375 the given option if used in combination with Ahead of Time com‐
376 pilation (--aot flag) would produce pre-compiled code that will
377 depend on the current CPU and might not be safely moved to
378 another computer.
379 The following optimizations are supported
381 float32
383 Requests that the runtime performn 32-bit floating point
384 operations using only 32-bits. By default the Mono run‐
385 time tries to use the highest precision available for
386 floating point operations, but while this might render
387 better results, the code might run slower. This options
388 also affects the code generated by the LLVM backend.
389 inline Controls whether the runtime should attempt to inline
391 (the default), or not inline methods invocations
392 --runtime=VERSION
394 Mono supports different runtime versions. The version used
395 depends on the program that is being run or on its configuration
396 file (named program.exe.config). This option can be used to
397 override such autodetection, by forcing a different runtime ver‐
398 sion to be used. Note that this should only be used to select a
399 later compatible runtime version than the one the program was
400 compiled against. A typical usage is for running a 1.1 program
401 on a 2.0 version:
402 mono --runtime=v2.0.50727 program.exe
403 --security, --security=mode
405 Activate the security manager, a currently experimental feature
406 in Mono and it is OFF by default. The new code verifier can be
407 enabled with this option as well.
408 Using security without parameters is equivalent as calling it
410 with the "cas" parameter.
411 The following modes are supported:
413 core-clr
415 Enables the core-clr security system, typically used for
416 Moonlight/Silverlight applications. It provides a much
417 simpler security system than CAS, see http://www.mono-
418 project.com/docs/web/moonlight/ for more details and
419 links to the descriptions of this new system.
420 validil
422 Enables the new verifier and performs basic verification
423 for code validity. In this mode, unsafe code and
424 P/Invoke are allowed. This mode provides a better safety
425 guarantee but it is still possible for managed code to
426 crash Mono.
427 verifiable
429 Enables the new verifier and performs full verification
430 of the code being executed. It only allows verifiable
431 code to be executed. Unsafe code is not allowed but
432 P/Invoke is. This mode should not allow managed code to
433 crash mono. The verification is not as strict as ECMA
434 335 standard in order to stay compatible with the MS run‐
435 time.
436 The security system acts on user code: code contained in mscor‐
438 lib or the global assembly cache is always trusted.
439 --server
441 Configures the virtual machine to be better suited for server
442 operations (currently, allows a heavier threadpool initializa‐
443 tion).
444 --verify-all
446 Verifies mscorlib and assemblies in the global assembly cache
447 for valid IL, and all user code for IL verifiability.
448 This is different from --security's verifiable or validil in
450 that these options only check user code and skip mscorlib and
451 assemblies located on the global assembly cache.
452 -V, --version
454 Prints JIT version information (system configuration, release
455 number and branch names if available).
456
460 The following options are used to help when developing a JITed applica‐
461 tion.
462 --debug, --debug=OPTIONS
464 Turns on the debugging mode in the runtime. If an assembly was
465 compiled with debugging information, it will produce line number
466 information for stack traces.
467 The optional OPTIONS argument is a comma separated list of
469 debugging options. These options are turned off by default
470 since they generate much larger and slower code at runtime.
471 The following options are supported:
473 casts Produces a detailed error when throwing a InvalidCastEx‐
475 ception. This option needs to be enabled as this gener‐
476 ates more verbose code at execution time.
477 mdb-optimizations
479 Disable some JIT optimizations which are usually only
480 disabled when running inside the debugger. This can be
481 helpful if you want to attach to the running process with
482 mdb.
483 gdb Generate and register debugging information with gdb.
485 This is only supported on some platforms, and only when
486 using gdb 7.0 or later.
487 --profile[=profiler[:profiler_args]]
489 Turns on profiling. For more information about profiling appli‐
490 cations and code coverage see the sections "PROFILING" and "CODE
491 COVERAGE" below.
492 This option can be used multiple times, each time will load an
494 additional profiler. This allows developers to use modules
495 that extend the JIT through the Mono profiling interface.
496 --trace[=expression]
498 Shows method names as they are invoked. By default all methods
499 are traced. The trace can be customized to include or exclude
500 methods, classes or assemblies. A trace expression is a comma
501 separated list of targets, each target can be prefixed with a
502 minus sign to turn off a particular target. The words `pro‐
503 gram', `all' and `disabled' have special meaning. `program'
504 refers to the main program being executed, and `all' means all
505 the method calls. The `disabled' option is used to start up
506 with tracing disabled. It can be enabled at a later point in
507 time in the program by sending the SIGUSR2 signal to the run‐
508 time. Assemblies are specified by their name, for example, to
509 trace all calls in the System assembly, use:
510 mono --trace=System app.exe
512 Classes are specified with the T: prefix. For example, to trace
514 all calls to the System.String class, use:
515 mono --trace=T:System.String app.exe
517 And individual methods are referenced with the M: prefix, and
519 the standard method notation:
520 mono --trace=M:System.Console:WriteLine app.exe
522 Exceptions can also be traced, it will cause a stack trace to be
524 printed every time an exception of the specified type is thrown.
525 The exception type can be specified with or without the names‐
526 pace, and to trace all exceptions, specify 'all' as the type
527 name.
528 mono --trace=E:System.Exception app.exe
530 As previously noted, various rules can be specified at once:
532 mono --trace=T:System.String,T:System.Random app.exe
534 You can exclude pieces, the next example traces calls to Sys‐
536 tem.String except for the System.String:Concat method.
537 mono --trace=T:System.String,-M:System.String:Concat
539 You can trace managed to unmanaged transitions using the wrapper
541 qualifier:
542 mono --trace=wrapper app.exe
544 Finally, namespaces can be specified using the N: prefix:
546 mono --trace=N:System.Xml
548 --no-x86-stack-align
551 Don't align stack frames on the x86 architecture. By default,
552 Mono aligns stack frames to 16 bytes on x86, so that local
553 floating point and SIMD variables can be properly aligned. This
554 option turns off the alignment, which usually saves one intruc‐
555 tion per call, but might result in significantly lower floating
556 point and SIMD performance.
557 --jitmap
559 Generate a JIT method map in a /tmp/perf-PID.map file. This file
560 is then used, for example, by the perf tool included in recent
561 Linux kernels. Each line in the file has:
562 HEXADDR HEXSIZE methodname
564 Currently this option is only supported on Linux.
566
568 The maintainer options are only used by those developing the runtime
569 itself, and not typically of interest to runtime users or developers.
570 --bisect=optimization:filename
572 This flag is used by the automatic optimization bug bisector.
573 It takes an optimization flag and a filename of a file contain‐
574 ing a list of full method names, one per line. When it compiles
575 one of the methods in the file it will use the optimization
576 given, in addition to the optimizations that are otherwise
577 enabled. Note that if the optimization is enabled by default,
578 you should disable it with `-O`, otherwise it will just apply to
579 every method, whether it's in the file or not.
580 --break method
582 Inserts a breakpoint before the method whose name is `method'
583 (namespace.class:methodname). Use `Main' as method name to
584 insert a breakpoint on the application's main method. You can
585 use it also with generics, for example "System.Collec‐
586 tions.Generic.Queue`1:Peek"
587 --breakonex
589 Inserts a breakpoint on exceptions. This allows you to debug
590 your application with a native debugger when an exception is
591 thrown.
592 --compile name
594 This compiles a method (namespace.name:methodname), this is used
595 for testing the compiler performance or to examine the output of
596 the code generator.
597 --compileall
599 Compiles all the methods in an assembly. This is used to test
600 the compiler performance or to examine the output of the code
601 generator
602 --graph=TYPE METHOD
604 This generates a postscript file with a graph with the details
605 about the specified method (namespace.name:methodname). This
606 requires `dot' and ghostview to be installed (it expects Ghost‐
607 view to be called "gv"). The following graphs are available:
608 cfg Control Flow Graph (CFG)
609 dtree Dominator Tree
610 code CFG showing code
611 ssa CFG showing code after SSA translation
612 optcode CFG showing code after IR optimizations
613 Some graphs will only be available if certain optimizations are
614 turned on.
615 --ncompile
617 Instruct the runtime on the number of times that the method
618 specified by --compile (or all the methods if --compileall is
619 used) to be compiled. This is used for testing the code genera‐
620 tor performance.
621 --stats
623 Displays information about the work done by the runtime during
624 the execution of an application.
625 --wapi=hps|semdel
627 Perform maintenance of the process shared data. semdel will
628 delete the global semaphore. hps will list the currently used
629 handles.
630 -v, --verbose
632 Increases the verbosity level, each time it is listed, increases
633 the verbosity level to include more information (including, for
634 example, a disassembly of the native code produced, code selec‐
635 tor info etc.).
636
638 The Mono runtime allows external processes to attach to a running
639 process and load assemblies into the running program. To attach to
640 the process, a special protocol is implemented in the Mono.Management
641 assembly.
642 With this support it is possible to load assemblies that have an entry
644 point (they are created with -target:exe or -target:winexe) to be
645 loaded and executed in the Mono process.
646 The code is loaded into the root domain, and it starts execution on the
648 special runtime attach thread. The attached program should create
649 its own threads and return after invocation.
650 This support allows for example debugging applications by having the
652 csharp shell attach to running processes.
653
655 The mono runtime includes a profiler that can be used to explore vari‐
656 ous performance related problems in your application. The profiler is
657 activated by passing the --profile command line argument to the Mono
658 runtime, the format is:
659 --profile[=profiler[:profiler_args]]
661 Mono has a built-in profiler called 'default' (and is also the default
663 if no arguments are specified), but developers can write custom profil‐
664 ers, see the section "CUSTOM PROFILERS" for more details.
665 If a profiler is not specified, the default profiler is used. The pro‐
667 filer_args is a profiler-specific string of options for the profiler
668 itself. The default profiler accepts the following options 'alloc' to
669 profile memory consumption by the application; 'time' to profile the
670 time spent on each routine; 'jit' to collect time spent JIT-compiling
671 methods and 'stat' to perform sample statistical profiling. If no
672 options are provided the default is 'alloc,time,jit'.
673 By default the profile data is printed to stdout: to change this, use
675 the 'file=filename' option to output the data to filename. For exam‐
676 ple:
677 mono --profile program.exe
679 That will run the program with the default profiler and will do time
681 and allocation profiling.
682 mono --profile=default:stat,alloc,file=prof.out program.exe
684 Will do sample statistical profiling and allocation profiling on pro‐
686 gram.exe. The profile data is put in prof.out. Note that the statisti‐
687 cal profiler has a very low overhead and should be the preferred pro‐
688 filer to use (for better output use the full path to the mono binary
689 when running and make sure you have installed the addr2line utility
690 that comes from the binutils package).
691
693 This is the most advanced profiler.
694 The Mono log profiler can be used to collect a lot of information about
696 a program running in the Mono runtime. This data can be used (both
697 while the process is running and later) to do analyses of the program
698 behaviour, determine resource usage, performance issues or even look
699 for particular execution patterns.
700 This is accomplished by logging the events provided by the Mono runtime
702 through the profiling interface and periodically writing them to a file
703 which can be later inspected with the mprof-report(1) tool.
704 More information about how to use the log profiler is available on the
706 mprof-report(1) page.
707
709 Mono provides a mechanism for loading other profiling modules which in
710 the form of shared libraries. These profiling modules can hook up to
711 various parts of the Mono runtime to gather information about the code
712 being executed.
713 To use a third party profiler you must pass the name of the profiler to
715 Mono, like this:
716 mono --profile=custom program.exe
718 In the above sample Mono will load the user defined profiler from the
721 shared library `mono-profiler-custom.so'. This profiler module must be
722 on your dynamic linker library path.
723 A list of other third party profilers is available from Mono's web site
725 (www.mono-project.com/docs/advanced/performance-tips/)
726 Custom profiles are written as shared libraries. The shared library
728 must be called `mono-profiler-NAME.so' where `NAME' is the name of your
729 profiler.
730 For a sample of how to write your own custom profiler look in the Mono
732 source tree for in the samples/profiler.c.
733
735 Mono ships with a code coverage module. This module is activated by
736 using the Mono --profile=cov option. The format is: --pro‐
737 file=cov[:assembly-name[/namespace]] test-suite.exe
738 By default code coverage will default to all the assemblies loaded, you
740 can limit this by specifying the assembly name, for example to perform
741 code coverage in the routines of your program use, for example the fol‐
742 lowing command line limits the code coverage to routines in the "demo"
743 assembly:
744 mono --profile=cov:demo demo.exe
746 Notice that the assembly-name does not include the extension.
749 You can further restrict the code coverage output by specifying a
751 namespace:
752 mono --profile=cov:demo/My.Utilities demo.exe
754 Which will only perform code coverage in the given assembly and names‐
757 pace.
758 Typical output looks like this:
760 Not covered: Class:.ctor ()
762 Not covered: Class:A ()
763 Not covered: Driver:.ctor ()
764 Not covered: Driver:method ()
765 Partial coverage: Driver:Main ()
766 offset 0x000a
767 The offsets displayed are IL offsets.
770 A more powerful coverage tool is available in the module `monocov'.
772 See the monocov(1) man page for details.
773
775 You can improve startup performance by using the AOT profiler.
776 Typically the AOT compiler (mono --aot) will not generate code for
778 generic instantiations. To solve this, you can run Mono with the AOT
779 profiler to find out all the generic instantiations that are used, and
780 then instructing the AOT compiler to produce code for these.
781 This command will run the specified app.exe and produce the out.aotprof
783 file with the data describing the generic instantiations that are
784 needed:
785 $ mono --profile=aot:output=out.aotprof app.exe
786 Once you have this data, you can pass this to Mono's AOT compiler to
788 instruct it to generate code for it:
789 $ mono --aot=profile=out.aotprof
790
792 To debug managed applications, you can use the mdb command, a command
793 line debugger.
794 It is possible to obtain a stack trace of all the active threads in
796 Mono by sending the QUIT signal to Mono, you can do this from the com‐
797 mand line, like this:
798 kill -QUIT pid
800 Where pid is the Process ID of the Mono process you want to examine.
802 The process will continue running afterwards, but its state is not
803 guaranteed.
804 Important: this is a last-resort mechanism for debugging applications
806 and should not be used to monitor or probe a production application.
807 The integrity of the runtime after sending this signal is not guaran‐
808 teed and the application might crash or terminate at any given point
809 afterwards.
810 The --debug=casts option can be used to get more detailed information
812 for Invalid Cast operations, it will provide information about the
813 types involved.
814 You can use the MONO_LOG_LEVEL and MONO_LOG_MASK environment variables
816 to get verbose debugging output about the execution of your application
817 within Mono.
818 The MONO_LOG_LEVEL environment variable if set, the logging level is
820 changed to the set value. Possible values are "error", "critical",
821 "warning", "message", "info", "debug". The default value is "error".
822 Messages with a logging level greater then or equal to the log level
823 will be printed to stdout/stderr.
824 Use "info" to track the dynamic loading of assemblies.
826 Use the MONO_LOG_MASK environment variable to limit the extent of the
828 messages you get: If set, the log mask is changed to the set value.
829 Possible values are "asm" (assembly loader), "type", "dll" (native
830 library loader), "gc" (garbage collector), "cfg" (config file loader),
831 "aot" (precompiler), "security" (e.g. Moonlight CoreCLR support),
832 "threadpool" (thread pool generic), "io-threadpool" (thread pool I/O),
833 "io-layer" (I/O layer - sockets, handles, shared memory etc) and "all".
834 The default value is "all". Changing the mask value allows you to dis‐
835 play only messages for a certain component. You can use multiple masks
836 by comma separating them. For example to see config file messages and
837 assembly loader messages set you mask to "asm,cfg".
838 The following is a common use to track down problems with P/Invoke:
840 $ MONO_LOG_LEVEL="debug" MONO_LOG_MASK="dll" mono glue.exe
842
845 If you are using LLDB, you can use the mono.py script to print some
846 internal data structures with it. To use this, add this to your
847 $HOME/.lldbinit file:
848 command script import $PREFIX/lib/mono/lldb/mono.py
849 Where $PREFIX is the prefix value that you used when you configured
851 Mono (typically /usr).
852 Once this is done, then you can inspect some Mono Runtime data struc‐
854 tures, for example:
855 (lldb) p method
856 (MonoMethod *) $0 = 0x05026ac0 [mscorlib]System.OutOfMemoryException:.ctor()
858
860 Mono's XML serialization engine by default will use a reflection-based
861 approach to serialize which might be slow for continuous processing
862 (web service applications). The serialization engine will determine
863 when a class must use a hand-tuned serializer based on a few parameters
864 and if needed it will produce a customized C# serializer for your types
865 at runtime. This customized serializer then gets dynamically loaded
866 into your application.
867 You can control this with the MONO_XMLSERIALIZER_THS environment vari‐
869 able.
870 The possible values are `no' to disable the use of a C# customized
872 serializer, or an integer that is the minimum number of uses before the
873 runtime will produce a custom serializer (0 will produce a custom seri‐
874 alizer on the first access, 50 will produce a serializer on the 50th
875 use). Mono will fallback to an interpreted serializer if the serializer
876 generation somehow fails. This behavior can be disabled by setting the
877 option `nofallback' (for example: MONO_XMLSERIALIZER_THS=0,nofallback).
878
880 GC_DONT_GC
881 Turns off the garbage collection in Mono. This should be only
882 used for debugging purposes
883 HTTP_PROXY
885 (Also http_proxy) If set, web requests using the Mono Class
886 Library will be automatically proxied through the given URL.
887 Not supported on Windows, Mac OS, iOS or Android. See also
888 NO_PROXY.
889 LLVM_COUNT
891 When Mono is compiled with LLVM support, this instructs the run‐
892 time to stop using LLVM after the specified number of methods
893 are JITed. This is a tool used in diagnostics to help isolate
894 problems in the code generation backend. For example
895 LLVM_COUNT=10 would only compile 10 methods with LLVM and then
896 switch to the Mono JIT engine. LLVM_COUNT=0 would disable the
897 LLVM engine altogether.
898 MONO_AOT_CACHE
900 If set, this variable will instruct Mono to ahead-of-time com‐
901 pile new assemblies on demand and store the result into a cache
902 in ~/.mono/aot-cache.
903 MONO_ASPNET_INHIBIT_SETTINGSMAP
905 Mono contains a feature which allows modifying settings in the
906 .config files shipped with Mono by using config section mappers.
907 The mappers and the mapping rules are defined in the $pre‐
908 fix/etc/mono/2.0/settings.map file and, optionally, in the set‐
909 tings.map file found in the top-level directory of your ASP.NET
910 application. Both files are read by System.Web on application
911 startup, if they are found at the above locations. If you don't
912 want the mapping to be performed you can set this variable in
913 your environment before starting the application and no action
914 will be taken.
915 MONO_ASPNET_WEBCONFIG_CACHESIZE
917 Mono has a cache of ConfigSection objects for speeding up Web‐
918 ConfigurationManager queries. Its default size is 100 items, and
919 when more items are needed, cache evictions start happening. If
920 evictions are too frequent this could impose unnecessary over‐
921 head, which could be avoided by using this environment variable
922 to set up a higher cache size (or to lower memory requirements
923 by decreasing it).
924 MONO_CAIRO_DEBUG_DISPOSE
926 If set, causes Mono.Cairo to collect stack traces when objects
927 are allocated, so that the finalization/Dispose warnings include
928 information about the instance's origin.
929 MONO_CFG_DIR
931 If set, this variable overrides the default system configuration
932 directory ($PREFIX/etc). It's used to locate machine.config
933 file.
934 MONO_COM
936 Sets the style of COM interop. If the value of this variable is
937 "MS" Mono will use string marhsalling routines from the
938 liboleaut32 for the BSTR type library, any other values will use
939 the mono-builtin BSTR string marshalling.
940 MONO_CONFIG
942 If set, this variable overrides the default runtime configura‐
943 tion file ($PREFIX/etc/mono/config). The --config command line
944 options overrides the environment variable.
945 MONO_CPU_ARCH
947 Override the automatic cpu detection mechanism. Currently used
948 only on arm. The format of the value is as follows:
949 "armvV [thumb[2]]"
951 where V is the architecture number 4, 5, 6, 7 and the options
953 can be currently be "thumb" or "thumb2". Example:
954 MONO_CPU_ARCH="armv4 thumb" mono ...
956 MONO_ARM_FORCE_SOFT_FLOAT
959 When Mono is built with a soft float fallback on ARM and this
960 variable is set to "1", Mono will always emit soft float code,
961 even if a VFP unit is detected.
962 MONO_DARWIN_WATCHER_MAXFDS
964 This is a debugging aid used to force limits on the FileSys‐
965 temWatcher implementation in Darwin. There is no limit by
966 default.
967 MONO_DISABLE_AIO
969 If set, tells mono NOT to attempt using native asynchronous I/O
970 services. In that case, a default select/poll implementation is
971 used. Currently only epoll() is supported.
972 MONO_DISABLE_MANAGED_COLLATION
974 If this environment variable is `yes', the runtime uses unman‐
975 aged collation (which actually means no culture-sensitive colla‐
976 tion). It internally disables managed collation functionality
977 invoked via the members of System.Globalization.CompareInfo
978 class. Collation is enabled by default.
979 MONO_DISABLE_SHM
981 Unix only: If set, disables the shared memory files used for
982 cross-process handles: process have only private handles. This
983 means that process and thread handles are not available to other
984 processes, and named mutexes, named events and named semaphores
985 are not visible between processes. This is can also be enabled
986 by default by passing the "--disable-shared-handles" option to
987 configure. This is the default from mono 2.8 onwards.
988 MONO_DISABLE_SHARED_AREA
990 Unix only: If set, disable usage of shared memory for exposing
991 performance counters. This means it will not be possible to both
992 externally read performance counters from this processes or read
993 those of external processes.
994 MONO_DNS
996 When set, enables the use of a fully managed DNS resolver
997 instead of the regular libc functions. This resolver performs
998 much better when multiple queries are run in parallel.
999 Note that /etc/nsswitch.conf will be ignored.
1001 MONO_EGD_SOCKET
1003 For platforms that do not otherwise have a way of obtaining ran‐
1004 dom bytes this can be set to the name of a file system socket on
1005 which an egd or prngd daemon is listening.
1006 MONO_ENABLE_COOP
1008 This makes the Mono runtime and the SGen garbage collector run
1009 in cooperative mode as opposed to run on preemptive mode. Pre‐
1010 emptive mode is the mode that Mono has used historically, going
1011 back to the Boehm days, where the garbage collector would run at
1012 any point and suspend execution of all threads as required to
1013 perform a garbage collection. The cooperative mode on the other
1014 hand requires the cooperation of all threads to stop at a safe
1015 point. This makes for an easier to debug garbage collector.
1016 As of Mono 4.3.0 it is a work in progress, and while it works,
1017 it has not been used extensively. This option enabled the fea‐
1018 ture and allows us to find spots that need to be tuned for this
1019 mode of operation. Alternatively, this mode can be enabled at
1020 compile time by using the --with-cooperative-gc flag when call‐
1021 ing configure.
1022 MONO_ENV_OPTIONS
1024 This environment variable allows you to pass command line argu‐
1025 ments to a Mono process through the environment. This is use‐
1026 ful for example to force all of your Mono processes to use LLVM
1027 or SGEN without having to modify any launch scripts.
1028 MONO_SDB_ENV_OPTIONS
1030 Used to pass extra options to the debugger agent in the runtime,
1031 as they were passed using --debugger-agent=.
1032 MONO_EVENTLOG_TYPE
1034 Sets the type of event log provider to use (for System.Diagnos‐
1035 tics.EventLog). Possible values are:
1036 local[:path]
1038 Persists event logs and entries to the local file system.
1039 The directory in which to persist the event logs, event
1040 sources and entries can be specified as part of the
1041 value. If the path is not explicitly set, it defaults to
1042 "/var/lib/mono/eventlog" on unix and "%APPDATA%no\vent‐
1043 log" on Windows.
1044 win32 Uses the native win32 API to write events and registers
1046 event logs and event sources in the registry. This is
1047 only available on Windows. On Unix, the directory per‐
1048 mission for individual event log and event source direc‐
1049 tories is set to 777 (with +t bit) allowing everyone to
1050 read and write event log entries while only allowing
1051 entries to be deleted by the user(s) that created them.
1052 null Silently discards any events.
1054 The default is "null" on Unix (and versions of Windows before
1056 NT), and "win32" on Windows NT (and higher).
1057 MONO_EXTERNAL_ENCODINGS
1059 If set, contains a colon-separated list of text encodings to try
1060 when turning externally-generated text (e.g. command-line argu‐
1061 ments or filenames) into Unicode. The encoding names come from
1062 the list provided by iconv, and the special case
1063 "default_locale" which refers to the current locale's default
1064 encoding.
1065 When reading externally-generated text strings UTF-8 is tried
1067 first, and then this list is tried in order with the first suc‐
1068 cessful conversion ending the search. When writing external
1069 text (e.g. new filenames or arguments to new processes) the
1070 first item in this list is used, or UTF-8 if the environment
1071 variable is not set.
1072 The problem with using MONO_EXTERNAL_ENCODINGS to process your
1074 files is that it results in a problem: although its possible to
1075 get the right file name it is not necessarily possible to open
1076 the file. In general if you have problems with encodings in
1077 your filenames you should use the "convmv" program.
1078 MONO_GC_PARAMS
1080 When using Mono with the SGen garbage collector this variable
1081 controls several parameters of the collector. The variable's
1082 value is a comma separated list of words.
1083 max-heap-size=size
1085 Sets the maximum size of the heap. The size is specified
1086 in bytes and must be a power of two. The suffixes `k',
1087 `m' and `g' can be used to specify kilo-, mega- and giga‐
1088 bytes, respectively. The limit is the sum of the nursery,
1089 major heap and large object heap. Once the limit is
1090 reached the application will receive OutOfMemoryExcep‐
1091 tions when trying to allocate. Not the full extent of
1092 memory set in max-heap-size could be available to satisfy
1093 a single allocation due to internal fragmentation. By
1094 default heap limits is disabled and the GC will try to
1095 use all available memory.
1096 nursery-size=size
1098 Sets the size of the nursery. The size is specified in
1099 bytes and must be a power of two. The suffixes `k', `m'
1100 and `g' can be used to specify kilo-, mega- and giga‐
1101 bytes, respectively. The nursery is the first generation
1102 (of two). A larger nursery will usually speed up the
1103 program but will obviously use more memory. The default
1104 nursery size 4 MB.
1105 major=collector Specifies which major collector to use.
1107 Options are `marksweep' for the Mark&Sweep collector, and
1108 `marksweep-conc' for concurrent Mark&Sweep. The non-con‐
1109 current Mark&Sweep collector is the default.
1110 soft-heap-limit=size
1112 Once the heap size gets larger than this size, ignore
1113 what the default major collection trigger metric says and
1114 only allow four nursery size's of major heap growth
1115 between major collections.
1116 evacuation-threshold=threshold
1118 Sets the evacuation threshold in percent. This option is
1119 only available on the Mark&Sweep major collectors. The
1120 value must be an integer in the range 0 to 100. The
1121 default is 66. If the sweep phase of the collection
1122 finds that the occupancy of a specific heap block type is
1123 less than this percentage, it will do a copying collec‐
1124 tion for that block type in the next major collection,
1125 thereby restoring occupancy to close to 100 percent. A
1126 value of 0 turns evacuation off.
1127 (no-)lazy-sweep
1129 Enables or disables lazy sweep for the Mark&Sweep collec‐
1130 tor. If enabled, the sweeping of individual major heap
1131 blocks is done piecemeal whenever the need arises, typi‐
1132 cally during nursery collections. Lazy sweeping is
1133 enabled by default.
1134 (no-)concurrent-sweep
1136 Enables or disables concurrent sweep for the Mark&Sweep
1137 collector. If enabled, the iteration of all major blocks
1138 to determine which ones can be freed and which ones have
1139 to be kept and swept, is done concurrently with the run‐
1140 ning program. Concurrent sweeping is enabled by default.
1141 stack-mark=mark-mode
1143 Specifies how application threads should be scanned.
1144 Options are `precise` and `conservative`. Precise marking
1145 allow the collector to know what values on stack are ref‐
1146 erences and what are not. Conservative marking threats
1147 all values as potentially references and leave them
1148 untouched. Precise marking reduces floating garbage and
1149 can speed up nursery collection and allocation rate, it
1150 has the downside of requiring a significant extra memory
1151 per compiled method. The right option, unfortunately,
1152 requires experimentation.
1153 save-target-ratio=ratio
1155 Specifies the target save ratio for the major collector.
1156 The collector lets a given amount of memory to be pro‐
1157 moted from the nursery due to minor collections before it
1158 triggers a major collection. This amount is based on how
1159 much memory it expects to free. It is represented as a
1160 ratio of the size of the heap after a major collection.
1161 Valid values are between 0.1 and 2.0. The default is 0.5.
1162 Smaller values will keep the major heap size smaller but
1163 will trigger more major collections. Likewise, bigger
1164 values will use more memory and result in less frequent
1165 major collections. This option is EXPERIMENTAL, so it
1166 might disappear in later versions of mono.
1167 default-allowance-ratio=ratio
1169 Specifies the default allocation allowance when the cal‐
1170 culated size is too small. The allocation allowance is
1171 how much memory the collector let be promoted before
1172 triggered a major collection. It is a ratio of the nurs‐
1173 ery size. Valid values are between 1.0 and 10.0. The
1174 default is 4.0. Smaller values lead to smaller heaps and
1175 more frequent major collections. Likewise, bigger values
1176 will allow the heap to grow faster but use more memory
1177 when it reaches a stable size. This option is EXPERIMEN‐
1178 TAL, so it might disappear in later versions of mono.
1179 minor=minor-collector
1181 Specifies which minor collector to use. Options are 'sim‐
1182 ple' which promotes all objects from the nursery directly
1183 to the old generation and 'split' which lets object stay
1184 longer on the nursery before promoting.
1185 alloc-ratio=ratio
1187 Specifies the ratio of memory from the nursery to be use
1188 by the alloc space. This only can only be used with the
1189 split minor collector. Valid values are integers between
1190 1 and 100. Default is 60.
1191 promotion-age=age
1193 Specifies the required age of an object must reach inside
1194 the nursery before been promoted to the old generation.
1195 This only can only be used with the split minor collec‐
1196 tor. Valid values are integers between 1 and 14. Default
1197 is 2.
1198 (no-)cementing
1200 Enables or disables cementing. This can dramatically
1201 shorten nursery collection times on some benchmarks where
1202 pinned objects are referred to from the major heap.
1203 allow-synchronous-major
1205 This forbids the major collector from performing synchro‐
1206 nous major collections. The major collector might want
1207 to do a synchronous collection due to excessive fragmen‐
1208 tation. Disabling this might trigger OutOfMemory error in
1209 situations that would otherwise not happen.
1210 MONO_GC_DEBUG
1212 When using Mono with the SGen garbage collector this environment
1213 variable can be used to turn on various debugging features of
1214 the collector. The value of this variable is a comma separated
1215 list of words. Do not use these options in production.
1216 number Sets the debug level to the specified number.
1218 print-allowance
1220 After each major collection prints memory consumption for
1221 before and after the collection and the allowance for the
1222 minor collector, i.e. how much the heap is allowed to
1223 grow from minor collections before the next major collec‐
1224 tion is triggered.
1225 print-pinning
1227 Gathers statistics on the classes whose objects are
1228 pinned in the nursery and for which global remset entries
1229 are added. Prints those statistics when shutting down.
1230 collect-before-allocs
1232 check-remset-consistency
1234 This performs a remset consistency check at various
1235 opportunities, and also clears the nursery at collection
1236 time, instead of the default, when buffers are allocated
1237 (clear-at-gc). The consistency check ensures that there
1238 are no major to minor references that are not on the
1239 remembered sets.
1240 mod-union-consistency-check
1242 Checks that the mod-union cardtable is consistent before
1243 each finishing major collection pause. This check is
1244 only applicable to concurrent major collectors.
1245 check-mark-bits
1247 Checks that mark bits in the major heap are consistent at
1248 the end of each major collection. Consistent mark bits
1249 mean that if an object is marked, all objects that it had
1250 references to must also be marked.
1251 check-nursery-pinned
1253 After nursery collections, and before starting concurrent
1254 collections, check whether all nursery objects are
1255 pinned, or not pinned - depending on context. Does noth‐
1256 ing when the split nursery collector is used.
1257 xdomain-checks
1259 Performs a check to make sure that no references are left
1260 to an unloaded AppDomain.
1261 clear-at-tlab-creation
1263 Clears the nursery incrementally when the thread local
1264 allocation buffers (TLAB) are created. The default set‐
1265 ting clears the whole nursery at GC time.
1266 debug-clear-at-tlab-creation
1268 Clears the nursery incrementally when the thread local
1269 allocation buffers (TLAB) are created, but at GC time
1270 fills it with the byte `0xff`, which should result in a
1271 crash more quickly if `clear-at-tlab-creation` doesn't
1272 work properly.
1273 clear-at-gc
1275 This clears the nursery at GC time instead of doing it
1276 when the thread local allocation buffer (TLAB) is cre‐
1277 ated. The default is to clear the nursery at TLAB cre‐
1278 ation time.
1279 disable-minor
1281 Don't do minor collections. If the nursery is full, a
1282 major collection is triggered instead, unless it, too, is
1283 disabled.
1284 disable-major
1286 Don't do major collections.
1287 conservative-stack-mark
1289 Forces the GC to scan the stack conservatively, even if
1290 precise scanning is available.
1291 no-managed-allocator
1293 Disables the managed allocator.
1294 check-scan-starts
1296 If set, does a plausibility check on the scan_starts
1297 before and after each collection
1298 verify-nursery-at-minor-gc
1300 If set, does a complete object walk of the nursery at the
1301 start of each minor collection.
1302 dump-nursery-at-minor-gc
1304 If set, dumps the contents of the nursery at the start of
1305 each minor collection. Requires verify-nursery-at-minor-
1306 gc to be set.
1307 heap-dump=file
1309 Dumps the heap contents to the specified file. To visu‐
1310 alize the information, use the mono-heapviz tool.
1311 binary-protocol=file
1313 Outputs the debugging output to the specified file. For
1314 this to work, Mono needs to be compiled with the
1315 BINARY_PROTOCOL define on sgen-gc.c. You can then use
1316 this command to explore the output
1317 sgen-grep-binprot 0x1234 0x5678 < file
1318 nursery-canaries
1320 If set, objects allocated in the nursery are suffixed
1321 with a canary (guard) word, which is checked on each
1322 minor collection. Can be used to detect/debug heap cor‐
1323 ruption issues.
1324 do-not-finalize(=classes)
1327 If enabled, finalizers will not be run. Everything else
1328 will be unaffected: finalizable objects will still be put
1329 into the finalization queue where they survive until
1330 they're scheduled to finalize. Once they're not in the
1331 queue anymore they will be collected regularly. If a
1332 list of comma-separated class names is given, only
1333 objects from those classes will not be finalized.
1334 log-finalizers
1337 Log verbosely around the finalization process to aid
1338 debugging.
1339 MONO_GAC_PREFIX
1341 Provides a prefix the runtime uses to look for Global Assembly
1342 Caches. Directories are separated by the platform path separa‐
1343 tor (colons on unix). MONO_GAC_PREFIX should point to the top
1344 directory of a prefixed install. Or to the directory provided in
1345 the gacutil /gacdir command. Example: /home/user‐
1346 name/.mono:/usr/local/mono/
1347 MONO_IOMAP
1349 Enables some filename rewriting support to assist badly-written
1350 applications that hard-code Windows paths. Set to a colon-sepa‐
1351 rated list of "drive" to strip drive letters, or "case" to do
1352 case-insensitive file matching in every directory in a path.
1353 "all" enables all rewriting methods. (Backslashes are always
1354 mapped to slashes if this variable is set to a valid option).
1355 For example, this would work from the shell:
1356 MONO_IOMAP=drive:case
1358 export MONO_IOMAP
1359 If you are using mod_mono to host your web applications, you can
1361 use the MonoIOMAP directive instead, like this:
1362 MonoIOMAP <appalias> all
1364 See mod_mono(8) for more details.
1366 Additionally. Mono includes a profiler module which allows one
1368 to track what adjustements to file paths IOMAP code needs to do.
1369 The tracking code reports the managed location (full stack
1370 trace) from which the IOMAP-ed call was made and, on process
1371 exit, the locations where all the IOMAP-ed strings were created
1372 in managed code. The latter report is only approximate as it is
1373 not always possible to estimate the actual location where the
1374 string was created. The code uses simple heuristics - it ana‐
1375 lyzes stack trace leading back to the string allocation location
1376 and ignores all the managed code which lives in assemblies
1377 installed in GAC as well as in the class libraries shipped with
1378 Mono (since they are assumed to be free of case-sensitivity
1379 issues). It then reports the first location in the user's code -
1380 in most cases this will be the place where the string is allo‐
1381 cated or very close to the location. The reporting code is
1382 implemented as a custom profiler module (see the "PROFILING"
1383 section) and can be loaded in the following way:
1384 mono --profile=iomap yourapplication.exe
1386 Note, however, that Mono currently supports only one profiler
1388 module at a time.
1389 MONO_LLVM
1391 When Mono is using the LLVM code generation backend you can use
1392 this environment variable to pass code generation options to the
1393 LLVM compiler.
1394 MONO_MANAGED_WATCHER
1396 If set to "disabled", System.IO.FileSystemWatcher will use a
1397 file watcher implementation which silently ignores all the
1398 watching requests. If set to any other value, Sys‐
1399 tem.IO.FileSystemWatcher will use the default managed implemen‐
1400 tation (slow). If unset, mono will try to use inotify, FAM,
1401 Gamin, kevent under Unix systems and native API calls on Win‐
1402 dows, falling back to the managed implementation on error.
1403 MONO_MESSAGING_PROVIDER
1405 Mono supports a plugin model for its implementation of Sys‐
1406 tem.Messaging making it possible to support a variety of messag‐
1407 ing implementations (e.g. AMQP, ActiveMQ). To specify which
1408 messaging implementation is to be used the evironement variable
1409 needs to be set to the full class name for the provider. E.g.
1410 to use the RabbitMQ based AMQP implementation the variable
1411 should be set to:
1412 Mono.Messaging.RabbitMQ.RabbitMQMessagingProvider,Mono.Messaging.RabbitMQ
1414 MONO_NO_SMP
1416 If set causes the mono process to be bound to a single processor. This may be
1417 useful when debugging or working around race conditions.
1418 MONO_NO_TLS
1420 Disable inlining of thread local accesses. Try setting this if you get a segfault
1421 early on in the execution of mono.
1422 MONO_PATH
1424 Provides a search path to the runtime where to look for library
1425 files. This is a tool convenient for debugging applications, but
1426 should not be used by deployed applications as it breaks the assembly
1427 loader in subtle ways.
1428 Directories are separated by the platform path separator (colons on unix). Example:
1429 /home/username/lib:/usr/local/mono/lib
1430 Relative paths are resolved based on the launch-time current directory.
1431 Alternative solutions to MONO_PATH include: installing libraries into
1432 the Global Assembly Cache (see gacutil(1)) or having the dependent
1433 libraries side-by-side with the main executable.
1434 For a complete description of recommended practices for application
1435 deployment, see
1436 http://www.mono-project.com/docs/getting-started/application-deployment/
1437 MONO_SHARED_DIR
1439 If set its the directory where the ".wapi" handle state is stored.
1440 This is the directory where the Windows I/O Emulation layer stores its
1441 shared state data (files, events, mutexes, pipes). By default Mono
1442 will store the ".wapi" directory in the users's home directory.
1443 MONO_SHARED_HOSTNAME
1445 Uses the string value of this variable as a replacement for the host name when
1446 creating file names in the ".wapi" directory. This helps if the host name of
1447 your machine is likely to be changed when a mono application is running or if
1448 you have a .wapi directory shared among several different computers.
1449 Mono typically uses the hostname to create the files that are used to
1450 share state across multiple Mono processes. This is done to support
1451 home directories that might be shared over the network.
1452 MONO_STRICT_IO_EMULATION
1454 If set, extra checks are made during IO operations. Currently, this
1455 includes only advisory locks around file writes.
1456 MONO_THEME
1458 The name of the theme to be used by Windows.Forms. Available themes today
1459 include "clearlooks", "nice" and "win32".
1460 The default is "win32".
1461 MONO_TLS_SESSION_CACHE_TIMEOUT
1463 The time, in seconds, that the SSL/TLS session cache will keep it's entry to
1464 avoid a new negotiation between the client and a server. Negotiation are very
1465 CPU intensive so an application-specific custom value may prove useful for
1466 small embedded systems.
1467 The default is 180 seconds.
1468 MONO_THREADS_PER_CPU
1470 The minimum number of threads in the general threadpool will be
1471 MONO_THREADS_PER_CPU * number of CPUs. The default value for this
1472 variable is 1.
1473 MONO_XMLSERIALIZER_THS
1475 Controls the threshold for the XmlSerializer to produce a custom
1476 serializer for a given class instead of using the Reflection-based
1477 interpreter. The possible values are `no' to disable the use of a
1478 custom serializer or a number to indicate when the XmlSerializer
1479 should start serializing. The default value is 50, which means that
1480 the a custom serializer will be produced on the 50th use.
1481 MONO_X509_REVOCATION_MODE
1483 Sets the revocation mode used when validating a X509 certificate chain (https,
1484 ftps, smtps...). The default is 'nocheck', which performs no revocation check
1485 at all. The other possible values are 'offline', which performs CRL check (not
1486 implemented yet) and 'online' which uses OCSP and CRL to verify the revocation
1487 status (not implemented yet).
1488 NO_PROXY
1490 (Also no_proxy) If both HTTP_PROXY and NO_PROXY are
1491 set, NO_PROXY will be treated as a comma-separated list of "bypass" domains
1492 which will not be sent through the proxy. Domains in NO_PROXY may contain
1493 wildcards, as in "*.mono-project.com" or "build????.local". Not supported on
1494 Windows, Mac OS, iOS or Android.
1495
1497 MONO_ASPNET_NODELETE
1498 If set to any value, temporary source files generated by ASP.NET
1499 support classes will not be removed. They will be kept in the
1500 user's temporary directory.
1501 MONO_DEBUG
1503 If set, enables some features of the runtime useful for debug‐
1504 ging. This variable should contain a comma separated list of
1505 debugging options. Currently, the following options are sup‐
1506 ported:
1507 align-small-structs
1509 Enables small structs alignment to 4/8 bytes.
1510 arm-use-fallback-tls
1512 When this option is set on ARM, a fallback TLS will be
1513 used instead of the default fast TLS.
1514 break-on-unverified
1516 If this variable is set, when the Mono VM runs into a
1517 verification problem, instead of throwing an exception it
1518 will break into the debugger. This is useful when debug‐
1519 ging verifier problems
1520 casts This option can be used to get more detailed information
1522 from InvalidCast exceptions, it will provide information
1523 about the types involved.
1524 check-pinvoke-callconv
1526 This option causes the runtime to check for calling con‐
1527 vention mismatches when using pinvoke, i.e. mixing
1528 cdecl/stdcall. It only works on windows. If a mismatch is
1529 detected, an ExecutionEngineException is thrown.
1530 collect-pagefault-stats
1532 Collects information about pagefaults. This is used
1533 internally to track the number of page faults produced to
1534 load metadata. To display this information you must use
1535 this option with "--stats" command line option.
1536 debug-domain-unload
1538 When this option is set, the runtime will invalidate the
1539 domain memory pool instead of destroying it.
1540 disable_omit_fp
1542 Disables a compiler optimization where the frame pointer
1543 is omitted from the stack. This optimization can interact
1544 badly with debuggers.
1545 dont-free-domains
1547 This is an Optimization for multi-AppDomain applications
1548 (most commonly ASP.NET applications). Due to internal
1549 limitations Mono, Mono by default does not use typed
1550 allocations on multi-appDomain applications as they could
1551 leak memory when a domain is unloaded. Although this is
1552 a fine default, for applications that use more than on
1553 AppDomain heavily (for example, ASP.NET applications) it
1554 is worth trading off the small leaks for the increased
1555 performance (additionally, since ASP.NET applications are
1556 not likely going to unload the application domains on
1557 production systems, it is worth using this feature).
1558 dyn-runtime-invoke
1560 Instructs the runtime to try to use a generic runtime-
1561 invoke wrapper instead of creating one invoke wrapper.
1562 explicit-null-checks
1564 Makes the JIT generate an explicit NULL check on variable
1565 dereferences instead of depending on the operating system
1566 to raise a SIGSEGV or another form of trap event when an
1567 invalid memory location is accessed.
1568 gdb Equivalent to setting the MONO_XDEBUG variable, this
1570 emits symbols into a shared library as the code is JITed
1571 that can be loaded into GDB to inspect symbols.
1572 gen-seq-points
1574 Automatically generates sequence points where the IL
1575 stack is empty. These are places where the debugger can
1576 set a breakpoint.
1577 no-compact-seq-points
1579 Unless the option is used, the runtime generates sequence
1580 points data that maps native offsets to IL offsets.
1581 Sequence point data is used to display IL offset in
1582 stacktraces. Stacktraces with IL offsets can be symboli‐
1583 cated using mono-symbolicate tool.
1584 handle-sigint
1586 Captures the interrupt signal (Control-C) and displays a
1587 stack trace when pressed. Useful to find out where the
1588 program is executing at a given point. This only dis‐
1589 plays the stack trace of a single thread.
1590 init-stacks
1592 Instructs the runtime to initialize the stack with some
1593 known values (0x2a on x86-64) at the start of a method to
1594 assist in debuggin the JIT engine.
1595 keep-delegates
1597 This option will leak delegate trampolines that are no
1598 longer referenced as to present the user with more infor‐
1599 mation about a delegate misuse. Basically a delegate
1600 instance might be created, passed to unmanaged code, and
1601 no references kept in managed code, which will garbage
1602 collect the code. With this option it is possible to
1603 track down the source of the problems.
1604 no-gdb-backtrace
1606 This option will disable the GDB backtrace emitted by the
1607 runtime after a SIGSEGV or SIGABRT in unmanaged code.
1608 partial-sharing
1610 When this option is set, the runtime can share generated
1611 code between generic types effectively reducing the
1612 amount of code generated.
1613 reverse-pinvoke-exceptions
1615 This option will cause mono to abort with a descriptive
1616 message when during stack unwinding after an exception it
1617 reaches a native stack frame. This happens when a managed
1618 delegate is passed to native code, and the managed dele‐
1619 gate throws an exception. Mono will normally try to
1620 unwind the stack to the first (managed) exception han‐
1621 dler, and it will skip any native stack frames in the
1622 process. This leads to undefined behaviour (since mono
1623 doesn't know how to process native frames), leaks, and
1624 possibly crashes too.
1625 single-imm-size
1627 This guarantees that each time managed code is compiled
1628 the same instructions and registers are used, regardless
1629 of the size of used values.
1630 soft-breakpoints
1632 This option allows using single-steps and breakpoints in
1633 hardware where we cannot do it with signals.
1634 suspend-on-sigsegv
1636 This option will suspend the program when a native
1637 SIGSEGV is received. This is useful for debugging
1638 crashes which do not happen under gdb, since a live
1639 process contains more information than a core file.
1640 suspend-on-exception
1642 This option will suspend the program when an exception
1643 occurs.
1644 suspend-on-unhandled
1646 This option will suspend the program when an unhandled
1647 exception occurs.
1648 MONO_LOG_LEVEL
1650 The logging level, possible values are `error', `critical',
1651 `warning', `message', `info' and `debug'. See the DEBUGGING
1652 section for more details.
1653 MONO_LOG_MASK
1655 Controls the domain of the Mono runtime that logging will apply
1656 to. If set, the log mask is changed to the set value. Possible
1657 values are "asm" (assembly loader), "type", "dll" (native
1658 library loader), "gc" (garbage collector), "cfg" (config file
1659 loader), "aot" (precompiler), "security" (e.g. Moonlight CoreCLR
1660 support) and "all". The default value is "all". Changing the
1661 mask value allows you to display only messages for a certain
1662 component. You can use multiple masks by comma separating them.
1663 For example to see config file messages and assembly loader mes‐
1664 sages set you mask to "asm,cfg".
1665 MONO_LOG_DEST
1667 Controls where trace log messages are written. If not set then
1668 the messages go to stdout. If set, the string either specifies
1669 a path to a file that will have messages appended to it, or the
1670 string "syslog" in which case the messages will be written to
1671 the system log. Under Windows, this is simulated by writing to
1672 a file called "mono.log". MONO_LOG_HEADER Controls whether
1673 trace log messages not directed to syslog have the id, time‐
1674 stamp, and pid as the prefix to the log message. To enable a
1675 header this environment variable need just be non-null.
1676 MONO_TRACE
1678 Used for runtime tracing of method calls. The format of the
1679 comma separated trace options is:
1680 [-]M:method name
1682 [-]N:namespace
1683 [-]T:class name
1684 [-]all
1685 [-]program
1686 disabled Trace output off upon start.
1687 You can toggle trace output on/off sending a SIGUSR2 signal to
1689 the program.
1690 MONO_TRACE_LISTENER
1692 If set, enables the System.Diagnostics.DefaultTraceListener,
1693 which will print the output of the System.Diagnostics Trace and
1694 Debug classes. It can be set to a filename, and to Console.Out
1695 or Console.Error to display output to standard output or stan‐
1696 dard error, respectively. If it's set to Console.Out or Con‐
1697 sole.Error you can append an optional prefix that will be used
1698 when writing messages like this: Console.Error:MyProgramName.
1699 See the System.Diagnostics.DefaultTraceListener documentation
1700 for more information.
1701 MONO_WCF_TRACE
1703 This eases WCF diagnostics functionality by simply outputs all
1704 log messages from WCF engine to "stdout", "stderr" or any file
1705 passed to this environment variable. The log format is the same
1706 as usual diagnostic output.
1707 MONO_XEXCEPTIONS
1709 This throws an exception when a X11 error is encountered; by
1710 default a message is displayed but execution continues
1711 MONO_XMLSERIALIZER_DEBUG
1713 Set this value to 1 to prevent the serializer from removing the
1714 temporary files that are created for fast serialization; This
1715 might be useful when debugging.
1716 MONO_XSYNC
1718 This is used in the System.Windows.Forms implementation when
1719 running with the X11 backend. This is used to debug problems in
1720 Windows.Forms as it forces all of the commands send to X11
1721 server to be done synchronously. The default mode of operation
1722 is asynchronous which makes it hard to isolate the root of cer‐
1723 tain problems.
1724 MONO_XDEBUG
1726 When the the MONO_XDEBUG env var is set, debugging info for JIT‐
1727 ted code is emitted into a shared library, loadable into gdb.
1728 This enables, for example, to see managed frame names on gdb
1729 backtraces.
1730 MONO_VERBOSE_METHOD
1732 Enables the maximum JIT verbosity for the specified method. This
1733 is very helpfull to diagnose a miscompilation problems of a spe‐
1734 cific method.
1735 MONO_JIT_DUMP_METHOD
1737 Enables sending of the JITs intermediate representation for a
1738 specified method to the IdealGraphVisualizer tool.
1739 MONO_VERBOSE_HWCAP
1741 If set, makes the JIT output information about detected CPU fea‐
1742 tures (such as SSE, CMOV, FCMOV, etc) to stdout.
1743 MONO_CONSERVATIVE_HWCAP
1745 If set, the JIT will not perform any hardware capability detec‐
1746 tion. This may be useful to pinpoint the cause of JIT issues.
1747 This is the default when Mono is built as an AOT cross compiler,
1748 so that the generated code will run on most hardware.
1749
1751 If you want to use Valgrind, you will find the file `mono.supp' useful,
1752 it contains the suppressions for the GC which trigger incorrect warn‐
1753 ings. Use it like this:
1754 valgrind --suppressions=mono.supp mono ...
1755
1757 On some platforms, Mono can expose a set of DTrace probes (also known
1758 as user-land statically defined, USDT Probes).
1759 They are defined in the file `mono.d'.
1761 ves-init-begin, ves-init-end
1763 Begin and end of runtime initialization.
1764 method-compile-begin, method-compile-end
1766 Begin and end of method compilation. The probe arguments are
1767 class name, method name and signature, and in case of method-
1768 compile-end success or failure of compilation.
1769 gc-begin, gc-end
1771 Begin and end of Garbage Collection.
1772 To verify the availability of the probes, run:
1774 dtrace -P mono'$target' -l -c mono
1775
1777 Mono's Ping implementation for detecting network reachability can cre‐
1778 ate the ICMP packets itself without requiring the system ping command
1779 to do the work. If you want to enable this on Linux for non-root
1780 users, you need to give the Mono binary special permissions.
1781 As root, run this command:
1783 # setcap cap_net_raw=+ep /usr/bin/mono
1784
1786 On Unix assemblies are loaded from the installation lib directory. If
1787 you set `prefix' to /usr, the assemblies will be located in /usr/lib.
1788 On Windows, the assemblies are loaded from the directory where mono and
1789 mint live.
1790 ~/.mono/aot-cache
1792 The directory for the ahead-of-time compiler demand creation
1793 assemblies are located.
1794 /etc/mono/config, ~/.mono/config
1796 Mono runtime configuration file. See the mono-config(5) manual
1797 page for more information.
1798 ~/.config/.mono/certs, /usr/share/.mono/certs
1800 Contains Mono certificate stores for users / machine. See the
1801 certmgr(1) manual page for more information on managing certifi‐
1802 cate stores and the mozroots(1) page for information on how to
1803 import the Mozilla root certificates into the Mono certificate
1804 store.
1805 ~/.mono/assemblies/ASSEMBLY/ASSEMBLY.config
1807 Files in this directory allow a user to customize the configura‐
1808 tion for a given system assembly, the format is the one
1809 described in the mono-config(5) page.
1810 ~/.config/.mono/keypairs, /usr/share/.mono/keypairs
1812 Contains Mono cryptographic keypairs for users / machine. They
1813 can be accessed by using a CspParameters object with DSACryp‐
1814 toServiceProvider and RSACryptoServiceProvider classes.
1815 ~/.config/.isolatedstorage, ~/.local/share/.isolatedstorage,
1817 /usr/share/.isolatedstorage
1818 Contains Mono isolated storage for non-roaming users, roaming
1819 users and local machine. Isolated storage can be accessed using
1820 the classes from the System.IO.IsolatedStorage namespace.
1821 <assembly>.config
1823 Configuration information for individual assemblies is loaded by
1824 the runtime from side-by-side files with the .config files, see
1825 the http://www.mono-project.com/Config for more information.
1826 Web.config, web.config
1828 ASP.NET applications are configured through these files, the
1829 configuration is done on a per-directory basis. For more infor‐
1830 mation on this subject see the http://www.mono-project.com/Con‐
1831 fig_system.web page.
1832
1834 Mailing lists are listed at the http://www.mono-project.com/commu‐
1835 nity/help/mailing-lists/
1836
1838 http://www.mono-project.com
1839
1841 certmgr(1), csharp(1), mcs(1), mdb(1), monocov(1), monodis(1), mono-
1842 config(5), mozroots(1), mprof-report(1), pdb2mdb(1), xsp(1),
1843 mod_mono(8).
1844 For more information on AOT: http://www.mono-
1846 project.com/docs/advanced/aot/
1847 For ASP.NET-related documentation, see the xsp(1) manual page
1849 Mono(Mono 4.7.0)