.\"
-.\" mint manual page.
-.\" (C) Ximian, Inc.
+.\" mono manual page.
+.\" (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]
-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 "--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
+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. See the
+mono-config(5) man page for details on the format of this file.
.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
.TP
-.I "--noinline"
-Disables the code inliner.
-.SH DEBUGGING OPTIONS
-The following options are used to debug, or perfomance test the JIT
-compiler:
+.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 "--trace-calls"
-Shows method names as they 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-asm"
-Displays the generated code as methods are invoked.
+.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 "--dump-forest"
-Displays the basic blocks and the forest of trees that is
-created from a stream of CIL opcodes.
+.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").
.TP
-.I "--debug format"
-Writes out debug information in the given format.
-See DEBUGGING FORMATS for details.
+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-args args"
-Comma-separated list of additional arguments for the symbol writer.
-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 "-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).
-.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.
-.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:
-.TP
-.I "stabs"
-Writes out stabs debug information.
-.TP
-.I "dwarf"
-Writes out dwarf debug information.
-.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:
+(namespace.class:methodname). Use `Main' as method name to insert a
+breakpoint on the application's main method.
.TP
-.I "filename=FILENAME"
-Write debugging information into FILENAME. This file must be run through
-the assembler to create an object file.
+.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 "objfile=FILENAME"
-When automatically assembling the symbol file, write the resulting object
-file into FILENAME.
+.I "--trace[=expression]"
+Shows method names as they are invoked. By default all methods are
+traced.
.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.
+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
-.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.
+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 ENVIRONMENT VARIABLES
.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 "GC_DONT_GC"
+Turns off the garbage collection in Mono. This should be only used
+for debugging purposes
.TP
-.I "dont_create_il_files"
-Update the *.il files if their assemblies have changed, but only if the
-file already exists.
-.PP
-The "dwarf-plus" format supports the following options:
+.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 "dont_fallback"
-Don't fallback to normal dwarf2 if the symbol file cannot be found.
-.PP
+.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 "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 "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 "MONO_DEBUG"
+If set, enables some features of the runtime useful for debugging.
+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.
+.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.
+.TP
+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_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.
.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
projects / mono.git / blobdiff