X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;ds=sidebyside;f=man%2Fmono.1;h=e6b06e080e901f70a92e9cebc2d7d4d3d3aa6c0e;hb=77f0e77f266775ef8a85b1894ff2222346166e07;hp=4a417ec10f968159767adcb5aa06e701a2438b7e;hpb=5e8707e3e7831e7a7b70dfbacfe6b495be2aca2d;p=mono.git diff --git a/man/mono.1 b/man/mono.1 index 4a417ec10f9..e6b06e080e9 100644 --- a/man/mono.1 +++ b/man/mono.1 @@ -1,6 +1,7 @@ .\" .\" mono manual page. .\" (C) 2003 Ximian, Inc. +.\" (C) 2004-2005 Novell, Inc. .\" Author: .\" Miguel de Icaza (miguel@gnu.org) .\" @@ -46,6 +47,19 @@ This option is used to precompile the CIL code in the specified 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 @@ -63,6 +77,12 @@ The default files are /etc/mono/config and ~/.mono/config or the file 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 @@ -88,8 +108,12 @@ The following optimizations are implemented: 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 @@ -98,6 +122,16 @@ elimination and inlining, you can use: -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. @@ -111,17 +145,74 @@ compiled with debugging information, it will produce line number 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 @@ -136,7 +227,7 @@ This generates a postscript file with a graph with the details about 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) @@ -153,72 +244,240 @@ on. 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 @@ -231,24 +490,206 @@ environment variable. .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