diff options
Diffstat (limited to 'man/mono.1')
| -rw-r--r-- | man/mono.1 | 439 |
1 files changed, 342 insertions, 97 deletions
diff --git a/man/mono.1 b/man/mono.1 index 0d6dc2f20b7..1379258a04f 100644 --- a/man/mono.1 +++ b/man/mono.1 @@ -1,148 +1,393 @@ .\" .\" mono manual page. -.\" (C) Ximian, Inc. +.\" (C) 2003 Ximian, Inc. .\" Author: .\" Miguel de Icaza (miguel@gnu.org) .\" +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. .TH Mono "Mono 1.0" .SH NAME -mono \- Mono ECMA-CLI Just in Time compiler. +mono \- Mono's ECMA-CLI native code generator (Just-in-Time and Ahead-of-Time) .SH SYNOPSIS .PP -.B mono -[\-\-help] [\-d] [\-\-debug-asm] [\-\-debug-forest] [\-\-trace-calls] -[\-\-compile name] [\-\-ncompile num] [\-\-noinline] [\-\-profile] -[\-\-debug=[format]] [\-\-debug-args args] [\-\-break name] [\-\-precompile name] -[\-\-config filename] -program.exe [arguments...] +.B mono [options] file [arguments...] .SH DESCRIPTION -The \fImono\fP program is a Just in Time compiler for ECMA CLI byte -codes. It translates dynamically a CIL stream into native code. -.I program.exe +\fImono\fP is a runtime implementation of the ECMA Common Language +Infrastructure. This can be used to run ECMA and .NET applications. +.PP +The runtime contains a native code generator that transforms the +Common Intermediate Language into native code. +.PP +The code generator can operate in two modes: just in time compilation +(JIT) or ahead of time compilation (AOT). Since code can be +dynamically loaded, the runtime environment and the JIT are always +present, even if code is compiled ahead of time. +.PP +The runtime loads ths specified +.I file and optionally passes the .I arguments -to it. -.SH OPTIONS -The following options are supported: +to it. The +.I file +is an ECMA assembly. They typically have a .exe or .dll extension. +.PP +The runtime provides a number of configuration options for running +applications, for developping and debugging, and for testing and +debugging the runtime itself. +.SH RUNTIME OPTIONS +The following options are available: .TP -.I "--help", "-h" -Displays usage instructions. -.I "--share-code" -This mode makes the LoaderOptimization for Application Domains default -to sharing code. This results in slower code, but enables code -sharing across application domains. The default is to maximize for -speed, but disallow JITed code sharing across domains. See -System.LoaderOptimization for more information +.I "--aot" +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 +information which is not availble on the generated file. When +precompiling code, you might want to compile with all optimizations +(-O=all). Pre-compiled code is position independent code. +.Sp +Pre compilation is just a mechanism to reduce startup time, and avoid +just-in-time compilation costs. The original assembly must still be +present, as the metadata is contained there. .TP .I "--config filename" Load the specified configuration file instead of the default one(s). The default files are /etc/mono/config and ~/.mono/config or the file -specified in the MONO_CONFIG environment variable, if set. +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 "--noinline" -Disables the code inliner. -.SH DEBUGGING OPTIONS -The following options are used to debug, or perfomance test the JIT -compiler: +.I "--help", "-h" +Displays usage instructions. .TP -.I "--trace-calls" -Shows method names as they are invoked. +.I "--optimize=MODE", "-O=mode" +MODE is a comma separated list of optimizations. They also allow +optimizations to be turned off by prefixing the optimization name with +a minus sign. +.Sp +The following optimizations are implemented: +.nf + all Turn on all optimizations + peephole Peephole postpass + branch Branch optimizations + inline Inline method calls + cfold Constant folding + consprop Constant propagation + copyprop Copy propagation + deadce Dead code elimination + linears Linear scan global reg allocation + cmov Conditional moves + shared Emit per-domain code + sched Instruction scheduling + intrins Intrinsic method implementations + tailc Tail recursion and tail calls + loop Loop related optimizations + leaf Leaf procedures optimizations + profile Use profiling information +.fi +.Sp +For example, to enable all the optimization but dead code +elimination and inlining, you can use: +.nf + -O=all,-deadce,-inline +.fi .TP -.I "--dump-asm" -Displays the generated code as methods are invoked. +.I "-V", "--version" +Prints JIT version information. + + +.SH DEVELOPMENT OPTIONS +The following options are used to help when developing a JITed application. .TP -.I "--dump-forest" -Displays the basic blocks and the forest of trees that is -created from a stream of CIL opcodes. +.I "--debug" +Turns on the debugging mode in the runtime. If an assembly was +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. +.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 "--compile name" -Compiles the method on the given class (namespace.name:methodname) or -all classes in the given image (@imagename). +This compiles a method (namespace.name:methodname), this is used for +testing the compiler performance or to examine the output of the code +generator. .TP -.I "--ncompile" -Compiles the method a number of times. If no argument is specified, -the method will be compiled a thousand times. -.SH DEVELOPMENT OPTIONS -The following options are used to debug a JITed application. They're -only useful when running the JIT in a debugger: +.I "--compileall" +Compiles all the methods in an assembly. This is used to test the +compiler performance or to examine the output of the code generator +.TP +.I "--graph=TYPE METHOD" +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"). +.PP +The following graphs are available: +.nf + cfg Control Flow Graph (CFG) + dtree Dominator Tree + code CFG showing code + ssa CFG showing code after SSA translation + optcode CFG showing code after IR optimizations +.fi +.Sp +Some graphs will only be available if certain optimizations are turned +on. .TP -.I "--debug=[format]" -Writes out debug information in the given format or in the default format. -See DEBUGGING FORMATS for details. +.I "--ncompile" +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 "--debug-args args" -Comma-separated list of additional arguments for the symbol writer. -See DEBUGGING FORMATS for details. +.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). +(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. +.PP +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. +.PP +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 DEBUGGING +.PP +If you are interested in debugging P/Invoke problems with your +application, you might want to use: +.nf + $ MONO_LOG_LEVEL="debug" MONO_LOG_MASK="dll" mono glue.exe +.fi +.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 `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 "--precompile name" -Compiles the given class (namespace.name), method (namespace.name:methodname) -or all classes in the given image (@imagename) before executing the main -application. +.I "GC_DONT_GC" +Turns off the garbage collection in Mono. This should be only used +for debugging purposes .TP -.I "--profile" -Collect profiling information and dump it at the end of the process. -.SH DEBUGGING FORMATS -The following debugging formats are currently supported: +.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 "stabs" -Writes out stabs debug information. +.I "MONO_CFG_DIR" +If set, this variable overrides the default system configuration directory +($PREFIX/etc). It's used to locate machine.config file. .TP -.I "dwarf" -Writes out dwarf debug information. +.I "MONO_CONFIG" +If set, this variable overrides the default runtime configuration file +($PREFIX/etc/mono/config). The --config command line options overrides the +environment variable. .TP -.I "dwarf-plus" -Uses an extended debugging information file which has been generated -by MCS. This extended debugging information will allow you to debug -C# source code rather than IL code. To use it, just run the JIT in -your debugger and call "mono_debug_make_symbols" each time the program -stops. -.PP -The "stabs" and "dwarf" formats support the following options: +.I "MONO_DEBUG" +If set, enables some features of the runtime useful for debugging. +It makes the runtime display the stack traces for all the threads +running and exit when mono is interrupted (Ctrl-C) and print some +additional messages on error conditions. It may not exit cleanly. Use at +your own risk. .TP -.I "filename=FILENAME" -Write debugging information into FILENAME. This file must be run through -the assembler to create an object file. +.I "MONO_DISABLE_AIO" +If set, tells mono NOT to attempt using native asynchronous I/O services. In +that case, the threadpool is used for asynchronous I/O on files and sockets. .TP -.I "objfile=FILENAME" -When automatically assembling the symbol file, write the resulting object -file into FILENAME. +.I "MONO_DISABLE_SHM" +If this variable is set, it disables the shared memory part of the +Windows I/O Emulation layer, and handles (files, events, mutexes, +pipes) will not be shared across processes. Process creation is also +disabled. This option is only available on Unix. .TP -.I "dont_assemble" -Normally, the symbol file is automatically assembled to an object file -when you call "mono_debug_make_symbols". Use this option to disable this -behaviour. +.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 "install_il_files" -Put the generated *.il files in the same directory than the assembly they -came from. The default is to put them into the current working directory. +.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 "dont_update_il_files" -Normally, the *.il files are recreated if their assemblies have changed -when you call "mono_debug_make_symbols". Use this option to disable this -behaviour. +.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 "dont_create_il_files" -Update the *.il files if their assemblies have changed, but only if the -file already exists. +.I "MONO_LOG_LEVEL" +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 -The "dwarf-plus" format supports the following options: +Use info to track the dynamic loading of assemblies. .TP -.I "dont_fallback" -Don't fallback to normal dwarf2 if the symbol file cannot be found. -.PP +.I "MONO_LOG_MASK" +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), "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_THREADS_PER_CPU" +Sets the maximum number of threads in the threadpool per CPU. The default is +50 for non-windows systems and 25 for windows. +.TP +.I "MONO_TRACE" +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. +See the System.Diagnostics.DefaultTraceListener documentation for more +information. +.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_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_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. .SH FILES -Assemblies are lodaed from the installation lib directory. If you set -`prefix' to /usr, the assemblies will be located in /usr/lib. +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 +/etc/mono/config, ~/.mono/config +.PP +Mono runtime configuration file. See the mono-config(5) manual page +for more information. .SH MAILING LISTS Visit http://mail.ximian.com/mailman/mono-list for details. .SH WEB SITE Visit: http://www.go-mono.com for details .SH SEE ALSO -.BR mint(1), monodis(1) +.BR mcs(1), mint(1), monodis(1), mono-config(5). +.PP +For ASP.NET-related documentation, see the xsp(1) manual page |