.\"
.\" mono manual page.
.\" (C) 2003 Ximian, Inc.
+.\" (C) 2004-2005 Novell, Inc.
.\" Author:
.\" Miguel de Icaza (miguel@gnu.org)
.\"
assembly to native code. The generated code is stored in a file with
the extension .so. This file will be automatically picked up by the
runtime when the assembly is executed.
+.Sp
+Ahead-of-Time compilation is most useful if you use it in combination
+with the -O=all,-shared flag which enables all of the optimizations in
+the code generator to be performed. Some of those optimizations are
+not practical for Just-in-Time compilation since they might be very
+time consuming.
+.Sp
+Unlike the .NET Framework, Ahead-of-Time compilation will not generate
+domain independent code: it generates the same code that the
+Just-in-Time compiler would produce. Since most applications use a
+single domain, this is fine. If you want to optimize the generated
+code for use in multi-domain applications, consider using the
+-O=shared flag.
.Sp
This pre-compiles the methods, but the original assembly is still
required to execute as this one contains the metadata and exception
specified in the MONO_CONFIG environment variable, if set. See the
mono-config(5) man page for details on the format of this file.
.TP
+.I "--desktop"
+Configures the virtual machine to be better suited for desktop
+applications. Currently this sets the GC system to avoid expanding
+the heap as much as possible at the expense of slowing down garbage
+collection a bit.
+.TP
.I "--help", "-h"
Displays usage instructions.
.TP
intrins Intrinsic method implementations
tailc Tail recursion and tail calls
loop Loop related optimizations
+ fcmov Fast x86 FP compares
leaf Leaf procedures optimizations
- profile Use profiling information
+ aot Usage of Ahead Of Time compiled code
+ precomp Precompile all methods before executing Main
+ abcrem Array bound checks removal
+ ssapre SSA based Partial Redundancy Elimination
.fi
.Sp
For example, to enable all the optimization but dead code
-O=all,-deadce,-inline
.fi
.TP
+.I "--security"
+Activate the security manager (experimental feature in 1.1). This allows
+mono to support declarative security attributes (e.g. execution of, CAS
+or non-CAS, security demands). The security manager is OFF by default
+(experimental).
+.TP
+.I "--server"
+Configures the virtual machine to be better suited for server
+operations.
+.TP
.I "-V", "--version"
Prints JIT version information.
information for stack traces.
.TP
.I "--profile[=profiler[:profiler_args]]"
-Instructs the runtime to collect profiling information about execution
-times and memory allocation, and dump it at the end of the execution.
-If a profiler is not specified, the default profiler is used. profiler_args
-is a profiler-specific string of options for the profiler itself.
-.PP
-The default profiler accepts -time and -alloc to options to disable
-the time profiling or the memory allocation profilng.
+Turns on profiling. For more information about profiling applications
+and code coverage see the sections "PROFILING" and "CODE COVERAGE"
+below.
+.TP
+.I "--trace[=expression]"
+Shows method names as they are invoked. By default all methods are
+traced.
+.Sp
+The trace can be customized to include or exclude methods, classes or
+assemblies. A trace expression is a comma separated list of targets,
+each target can be prefixed with a minus sign to turn off a particular
+target. The words `program' and `all' have special meaning.
+`program' refers to the main program being executed, and `all' means
+all the method calls.
+.Sp
+Assemblies are specified by their name, for example, to trace all
+calls in the System assembly, use:
+.nf
+
+ mono --trace=System app.exe
+
+.fi
+Classes are specified with the T: prefix. For example, to trace all
+calls to the System.String class, use:
+.nf
+
+ mono --trace=T:System.String app.exe
+
+.fi
+And individual methods are referenced with the M: prefix, and the
+standar method notation:
+.nf
+
+ mono --trace=M:System.Console:WriteLine app.exe
+
+.fi
+As previously noted, various rules can be specified at once:
+.nf
+
+ mono --trace=T:System.String,T:System.Random app.exe
+
+.fi
+You can exclude pieces, the next example traces calls to
+System.String except for the System.String:Concat method.
+.nf
+
+ mono --trace=T:System.String,-M:System.String:Concat
+
+.fi
+Finally, namespaces can be specified using the N: prefix:
+.nf
+
+ mono --trace=N:System.Xml
+
+.fi
.SH JIT MAINTAINER OPTIONS
The maintainer options are only used by those developing the runtime
itself, and not typically of interest to runtime users or developers.
.TP
+.I "--break method"
+Inserts a breakpoint before the method whose name is `method'
+(namespace.class:methodname). Use `Main' as method name to insert a
+breakpoint on the application's main method.
+.TP
+.I "--breakonex"
+Inserts a breakpoint on exceptions. This allows you to debug your
+application with a native debugger when an exception is thrown.
+.TP
.I "--compile name"
This compiles a method (namespace.name:methodname), this is used for
testing the compiler performance or to examine the output of the code
the specified method (namespace.name:methodname). This requires `dot'
and ghostview to be installed (it expects Ghostview to be called
"gv").
-.TP
+.Sp
The following graphs are available:
.nf
cfg Control Flow Graph (CFG)
Instruct the runtime on the number of times that the method specified
by --compile (or all the methods if --compileall is used) to be
compiled. This is used for testing the code generator performance.
+.TP
+.I "--stats"
+Displays information about the work done by the runtime during the
+execution of an application.
.TP
.I "-v", "--verbose"
Increases the verbosity level, each time it is listed, increases the
verbosity level to include more information (including, for example,
a disassembly of the native code produced, code selector info etc.).
-.TP
-.I "--break method"
-Inserts a breakpoint before the method whose name is `method'
-(namespace.class:methodname). Use `Main' as method name to insert a
-breakpoint on the application's main method.
-.TP
-.I "--breakonex"
-Inserts a breakpoint on exceptions. This allows you to debug your
-application with a native debugger when an exception is thrown.
-.TP
-.I "--trace[=expression]"
-Shows method names as they are invoked. By default all methods are
-traced.
-.TP
-The trace can be customized to include or exclude methods, classes or
-assemblies. A trace expression is a comma separated list of targets,
-each target can be prefixed with a minus sign to turn off a particular
-target. The words `program' and `all' have special meaning.
-`program' refers to the main program being executed, and `all' means
-all the method calls.
-.TP
-Assemblies are specified by their name, for example, to trace all
-calls in the System assembly, use:
+.SH PROFILING
+The mono runtime includes a profiler that can be used to explore
+various performance related problems in your application. The
+profiler is activated by passing the --profile command line argument
+to the Mono runtime, the format is:
.nf
- mono --trace=System app.exe
+
+ --profile[=profiler[:profiler_args]]
+
.fi
-Classes are specified with the T: prefix. For example, to trace all
-calls to the System.String class, use:
+Mono has a built-in profiler called 'default' (and is also the default
+if no arguments are specified), but developers can write custom
+profilers, see the section "CUSTOM PROFILERS" for more details.
+.PP
+If a
+.I profiler
+is not specified, the default profiler is used.
+.Sp
+The
+.I profiler_args
+is a profiler-specific string of options for the profiler itself.
+.Sp
+The default profiler accepts the following options 'alloc' to profile
+memory consumption by the application; 'time' to profile the time
+spent on each routine and 'stat' to perform sample statistical
+profiling. If no options are provided the default is 'alloc,time'.
+.Sp
+For example:
.nf
- mono --trace=T:System.String app.exe
+
+ mono --profile program.exe
+
.fi
-And individual methods are referenced with the M: prefix, and the
-standar method notation:
+.Sp
+That will run the program with the default profiler and will do time
+and allocation profiling.
+.Sp
.nf
- mono --trace=M:System.Console.WriteLine app.exe
+
+ mono --profile=default:stat,alloc program.exe
+
.fi
-As previously noted, various rules can be specified at once:
+Will do sample statistical profiling and allocation profiling on
+program.exe.
+.SH PROFILERS
+There are a number of external profilers that have been developed for
+Mono, we will update this section to contain the profilers.
+.PP
+The Live Type profiler shows at every GC iteration all of the live
+objects of a given type. To install you must download the profiler
+from Mono's SVN:
.nf
- mono --trace=T:System.String,T:System.Random app.exe
+ svn co svn://svn.myrealbox.com/source/trunk/heap-prof
+ cd heap-prof
+ ./autogen
+ make
+ make install
.fi
-You can exclude pieces, the next example traces calls to
-System.String except for the System.String:Concat method.
+.PP
+To use the profiler, execute:
.nf
- mono --trace=T:System.String,-M:System.String:Concat
+ mono --profile=desc-heap program.exe
.fi
+.PP
+The output of this profiler looks like this:
+.nf
+ Checkpoint at 102 for heap-resize
+ System.MonoType : 708
+ System.Threading.Thread : 352
+ System.String : 3230
+ System.String[] : 104
+ Gnome.ModuleInfo : 112
+ System.Object[] : 160
+ System.Collections.Hashtable : 96
+ System.Int32[] : 212
+ System.Collections.Hashtable+Slot[] : 296
+ System.Globalization.CultureInfo : 108
+ System.Globalization.NumberFormatInfo : 144
+.fi
+.PP
+The first line describes the iteration number for the GC, in this case
+checkpoint 102.
+.PP
+Then on each line the type is displayed as well as the number of bytes
+that are being consumed by live instances of this object.
+.SH CUSTOM PROFILERS
+Mono provides a mechanism for loading other profiling modules which in
+the form of shared libraries. These profiling modules can hook up to
+various parts of the Mono runtime to gather information about the code
+being executed.
+.PP
+To use a third party profiler you must pass the name of the profiler
+to Mono, like this:
+.nf
+
+ mono --profile=custom program.exe
+.fi
+.PP
+In the above sample Mono will load the user defined profiler from the
+shared library `mono-profiler-custom.so'. This profiler module must
+be on your dynamic linker library path.
+.PP
+A list of other third party profilers is available from Mono's web
+site (www.mono-project.com/Performance_Tips)
+.PP
+Custom profiles are written as shared libraries. The shared library
+must be called `mono-profiler-NAME.so' where `NAME' is the name of
+your profiler.
+.PP
+For a sample of how to write your own custom profiler look in the
+Mono source tree for in the samples/profiler.c.
+.SH CODE COVERAGE
+Mono ships with a code coverage module. This module is activated by
+using the Mono --profile=cov option. The format is:
+.I "--profile=cov[:assembly-name[/namespace]] test-suite.exe"
+.PP
+By default code coverage will default to all the assemblies loaded,
+you can limit this by specifying the assembly name, for example to
+perform code coverage in the routines of your program use, for example
+the following command line limits the code coverage to routines in the
+"demo" assembly:
+.nf
+
+ mono --profile=cov:demo demo.exe
+
+.fi
+.PP
+Notice that the
+.I assembly-name
+does not include the extension.
+.PP
+You can further restrict the code coverage output by specifying a
+namespace:
+.nf
+
+ mono --profile=cov:demo/My.Utilities demo.exe
+
+.fi
+.PP
+Which will only perform code coverage in the given assembly and
+namespace.
+.PP
+Typical output looks like this:
+.nf
+
+ Not covered: Class:.ctor ()
+ Not covered: Class:A ()
+ Not covered: Driver:.ctor ()
+ Not covered: Driver:method ()
+ Partial coverage: Driver:Main ()
+ offset 0x000a
+
+.fi
+.PP
+The offsets displayed are IL offsets.
+.SH DEBUGGING
+.PP
+You can use the MONO_LOG_LEVEL and MONO_LOG_MASK environment variables
+to get verbose debugging output about the execution of your
+application within Mono.
+.PP
+The
+.I MONO_LOG_LEVEL
+environment variable if set, the logging level is changed to the set
+value. Possible values are "error", "critical", "warning", "message",
+"info", "debug". The default value is "error". Messages with a logging
+level greater then or equal to the log level will be printed to
+stdout/stderr.
+.PP
+Use "info" to track the dynamic loading of assemblies.
+.PP
+.PP
+Use the
+.I MONO_LOG_MASK
+environment variable to limit the extent of the messages you get:
+If set, the log mask is changed to the set value. Possible values are
+"asm" (assembly loader), "type", "dll" (native library loader), "gc"
+(garbage collector), "cfg" (config file loader), "aot" (precompiler) and "all".
+The default value is "all". Changing the mask value allows you to display only
+messages for a certain component. You can use multiple masks by comma
+separating them. For example to see config file messages and assembly loader
+messages set you mask to "asm,cfg".
+.PP
+The following is a common use to track down problems with P/Invoke:
+.nf
+
+ $ MONO_LOG_LEVEL="debug" MONO_LOG_MASK="dll" mono glue.exe
+
+.fi
+.PP
+.SH SERIALIZATION
+Mono's XML serialization engine by default will use a reflection-based
+approach to serialize which might be slow for continous processing
+(web service applications). The serialization engine will determine
+when a class must use a hand-tuned serializer based on a few
+parameters and if needed it will produce a customized C# serializer
+for your types at runtime. This customized serializer then gets
+dynamically loaded into your application.
+.PP
+You can control this with the MONO_XMLSERIALIZER_THS environment
+variable.
+.PP
+The possible values are
+.B `no'
+to disable the use of a C# customized
+serializer, or an integer that is the minimum number of uses before
+the runtime will produce a custom serializer (0 will produce a
+custom serializer on the first access, 50 will produce a serializer on
+the 50th use).
.SH ENVIRONMENT VARIABLES
.TP
.I "GC_DONT_GC"
Turns off the garbage collection in Mono. This should be only used
for debugging purposes
.TP
-.I "MONO_PATH"
-Provides a search path to the runtime where to look for library files.
-Directories are separated by the platform path separator (colons on unix). Example:
-.B /home/username/lib:/usr/local/mono/lib
+.I "MONO_AOT_CACHE"
+If set, this variable will instruct Mono to ahead-of-time compile new
+assemblies on demand and store the result into a cache in
+~/.mono/aot-cache.
.TP
-.I "MONO_DISABLE_SHM"
-If this variable is set, it disables the Windows I/O Emulation layer,
-and handles (files, events, mutexes, pipes) will not be shared across
-processes. This option is only available on Unix.
+.I "MONO_ASPNET_NODELETE"
+If set to any value, temporary source files generated by ASP.NET support
+classes will not be removed. They will be kept in the user's temporary
+directory.
.TP
.I "MONO_CFG_DIR"
If set, this variable overrides the default system configuration directory
.TP
.I "MONO_DEBUG"
If set, enables some features of the runtime useful for debugging.
+This variable should contain a comma separated list of debugging options.
+Currently, the following options are supported:
+.RS
+.ne 8
+.TP
+.I "collect-pagefault-stats"
+Collects information about pagefaults. This is used internally to
+track the number of page faults produced to load metadata. To display
+this information you must use this option with "--stats" command line option.
+.TP
+.I "handle-sigint"
+Captures the interrupt signal (Control-C) and displays a stack trace
+when pressed. Useful to find out where the program is executing at a
+given point. This only displays the stack trace of a single thread.
+.TP
+.I "keep-delegates"
+This option will leak delegate trampolines that are no longer
+referenced as to present the user with more information about a
+delegate missuse. Basically a delegate instance might be created,
+passed to unmanaged code, and no references kept in managed code,
+which will garbage collect the code. With this option it is possible
+to track down the source of the problems.
+.ne
+.RE
+.TP
+.I "MONO_DISABLE_AIO"
+If set, tells mono NOT to attempt using native asynchronous I/O services. In
+that case, a default select/poll implementation is used. Currently only epoll()
+is supported.
+.TP
+.I "MONO_EGD_SOCKET"
+For platforms that do not otherwise have a way of obtaining random bytes
+this can be set to the name of a file system socket on which an egd or
+prngd daemon is listening.
+.TP
+.I "MONO_EXTERNAL_ENCODINGS"
+If set, contains a colon-separated list of text encodings to try when
+turning externally-generated text (e.g. command-line arguments or
+filenames) into Unicode. The encoding names come from the list
+provided by iconv, and the special case "default_locale" which refers
+to the current locale's default encoding.
+.IP
+When reading externally-generated text strings UTF-8 is tried first,
+and then this list is tried in order with the first successful
+conversion ending the search. When writing external text (e.g. new
+filenames or arguments to new processes) the first item in this list
+is used, or UTF-8 if the environment variable is not set.
+.TP
+.I "MONO_GAC_PREFIX"
+Provides a prefix the runtime uses to look for Global Assembly Caches.
+Directories are separated by the platform path separator (colons on
+unix). MONO_GAC_PREFIX should point to the top directory of a prefixed
+install. Or to the directory provided in the gacutil /gacdir command. Example:
+.B /home/username/.mono:/usr/local/mono/
+.TP
+.I "MONO_LOG_LEVEL"
+The logging level, possible values are `error', `critical', `warning',
+`message', `info' and `debug'. See the DEBUGGING section for more
+details.
+.TP
+.I "MONO_LOG_MASK"
+Controls the domain of the Mono runtime that logging will apply to.
+If set, the log mask is changed to the set value. Possible values are
+"asm" (assembly loader), "type", "dll" (native library loader), "gc"
+(garbage collector), "cfg" (config file loader), "aot" (precompiler) and "all".
+The default value is "all". Changing the mask value allows you to display only
+messages for a certain component. You can use multiple masks by comma
+separating them. For example to see config file messages and assembly loader
+messages set you mask to "asm,cfg".
+.TP
+.I "MONO_MANAGED_WATCHER"
+If set to any value, System.IO.FileSystemWatcher will use the default
+managed implementation (slow). If unset, mono will try to use FAM under
+Unix systems and native API calls on Windows, falling back to the
+managed implementation on error.
+.TP
+.I "MONO_PATH"
+Provides a search path to the runtime where to look for library files.
+Directories are separated by the platform path separator (colons on unix). Example:
+.B /home/username/lib:/usr/local/mono/lib
+.TP
+.I "MONO_RTC"
+Experimental RTC support in the statistical profiler: if the user has
+the permission, more accurate statistics are gathered. The MONO_RTC
+value must be restricted to what the linux rtc allows: power of two
+from 64 to 8192 Hz. To enable higher frequencies like 4096 Hz, run as root:
+.nf
+
+ echo 4096 > /proc/sys/dev/rtc/max-user-freq
+
+.fi
+.Sp
+For example:
+.nf
-Currently it only makes the runtime display the stack traces for all the
-threads running and exit. It may not exit cleanly. Use at your own risk.
+ MONO_RTC=4096 mono --profiler=default:stat program.exe
+
+.fi
+.TP
+.I "MONO_NO_TLS"
+Disable inlining of thread local accesses. Try setting this if you get a segfault
+early on in the execution of mono.
+.TP
+.I "MONO_SHARED_DIR"
+If set its the directory where the ".wapi" handle state is stored.
+This is the directory where the Windows I/O Emulation layer stores its
+shared state data (files, events, mutexes, pipes). By default Mono
+will store the ".wapi" directory in the users's home directory.
+.TP
+.I "MONO_THEME"
+The name of the theme to be used by Windows.Forms. The default is "win32".
+.TP
+.I "MONO_THREADS_PER_CPU"
+The maximum number of threads in the general threadpool will be
+20 + (MONO_THREADS_PER_CPU * number of CPUs). The default value for this
+variable is 5.
+.TP
+.I "MONO_TRACE"
+Used for runtime tracing of method calls. The format of the comma separated
+trace options is:
+.nf
+
+ [-]M:method name
+ [-]N:namespace
+ [-]T:class name
+ [-]all
+ [-]program
+ disabled Trace output off upon start.
+
+.fi
+You can toggle trace output on/off sending a SIGUSR2 signal to the program.
+.TP
+.I "MONO_TRACE_LISTENER"
+If set, enables the System.Diagnostics.DefaultTraceListener, which will
+print the output of the System.Diagnostics Trace and Debug classes.
+It can be set to a filename, and to Console.Out or Console.Error to display
+output to standard output or standard error, respectively. If it's set to
+Console.Out or Console.Error you can append an optional prefix that will
+be used when writing messages like this: Console.Error:MyProgramName.
+See the System.Diagnostics.DefaultTraceListener documentation for more
+information.
+.TP
+.I "MONO_DISABLE_MANAGED_COLLATION"
+If this environment variable is `yes', the runtime uses unmanaged
+collation (which actually means no culture-sensitive collation). It
+internally disables managed collation functionality invoked via the
+members of System.Globalization.CompareInfo class. Collation is
+enabled by default.
+.TP
+.I "MONO_XMLSERIALIZER_THS"
+Controls the threshold for the XmlSerializer to produce a custom
+serializer for a given class instead of using the Reflection-based
+interpreter. The possible values are `no' to disable the use of a
+custom serializer or a number to indicate when the XmlSerializer
+should start serializing. The default value is 50, which means that
+the a custom serializer will be produced on the 50th use.
+.TP
+.I "MONO_STRICT_IO_EMULATION"
+If set, extra checks are made during IO operations. Currently, this
+includes only advisory locks around file writes.
.SH FILES
On Unix assemblies are loaded from the installation lib directory. If you set
`prefix' to /usr, the assemblies will be located in /usr/lib. On
Windows, the assemblies are loaded from the directory where mono and
mint live.
.PP
+~/.mono/aot-cache
+.PP
+The directory for the ahead-of-time compiler demand creation
+assemblies are located.
+.PP
/etc/mono/config, ~/.mono/config
.PP
Mono runtime configuration file. See the mono-config(5) manual page
for more information.
+.PP
+~/.config/.mono/certs, /usr/share/.mono/certs
+.PP
+Contains Mono certificate stores for users / machine. See the certmgr(1)
+manual page for more information on managing certificate stores and
+the mozroots(1) page for information on how to import the Mozilla root
+certificates into the Mono certificate store.
+.PP
+~/.config/.mono/keypairs, /usr/share/.mono/keypairs
+.PP
+Contains Mono cryptographic keypairs for users / machine. They can be
+accessed by using a CspParameters object with DSACryptoServiceProvider
+and RSACryptoServiceProvider classes.
+.PP
+~/.config/.isolatedstorage, ~/.local/share/.isolatedstorage, /usr/share/.isolatedstorage
+.PP
+Contains Mono isolated storage for non-roaming users, roaming users and
+local machine. Isolated storage can be accessed using the classes from
+the System.IO.IsolatedStorage namespace.
.SH MAILING LISTS
-Visit http://mail.ximian.com/mailman/mono-list for details.
+Mailing lists are listed at the
+http://www.mono-project.com/Mailing_Lists
.SH WEB SITE
-Visit: http://www.go-mono.com for details
+http://www.mono-project.com
.SH SEE ALSO
-.BR mcs(1), mint(1), monodis(1), mono-config(5)
-
-
+.BR certmgr(1), mcs(1), mint(1), monodis(1), mono-config(5), mozroots(1).
+.PP
+For ASP.NET-related documentation, see the xsp(1) manual page
projects / mono.git / blobdiff