Mono(Mono 1.0) Mono(Mono 1.0)
NAME
mono - Mono's ECMA-CLI native code generator (Just-in-Time and Ahead-
of-Time)
SYNOPSIS
mono [options] file(1,n) [arguments...]
DESCRIPTION
mono is a runtime implementation of the ECMA Common Language Infra-
structure. This can be used to run ECMA and .NET applications.
The runtime contains a native code generator that transforms the Common
Intermediate Language into native code.
The code generator can operate in(1,8) two modes: just in(1,8) time(1,2,n) compilation
(JIT) or ahead of time(1,2,n) compilation (AOT). Since code can be dynami-
cally loaded, the runtime environment and the JIT are always present,
even if(3,n) code is compiled ahead of time.
The runtime loads ths specified file(1,n) and optionally passes the argu-
ments to it. The file(1,n) is an ECMA assembly. They typically have a .exe
or .dll extension.
The runtime provides a number of configuration options for running
applications, for developping and debugging, and for testing and debug-
ging the runtime itself.
RUNTIME OPTIONS
The following options are available:
--aot This option is used to precompile the CIL code in(1,8) the specified
assembly to native code. The generated code is stored in(1,8) a file(1,n)
with the extension .so. This file(1,n) will be automatically picked
up by the runtime when the assembly is executed.
Ahead-of-Time compilation is most useful if(3,n) you use it in(1,8) combi-
nation with the -O=all,-shared flag which enables all of the
optimizations in(1,8) the code generator to be performed. Some of
those optimizations are not practical for Just-in-Time compila-
tion since they might be very time(1,2,n) consuming.
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(1,8) multi-domain applica-
tions, consider using the -O=shared flag.
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 inde-
pendent code.
Pre compilation is just a mechanism to reduce startup time(1,2,n), and
avoid just-in-time compilation costs. The original assembly
must still be present, as the metadata is contained there.
--config filename
Load the specified configuration file(1,n) instead of the default
one(s). The default files are /etc/mono/config(1,5) and ~/.mono/con-
fig(1,5) or the file(1,n) specified in(1,8) the MONO_CONFIG environment vari-
able, if(3,n) set. See the mono-config(5) man(1,5,7) page for details on
the format of this file.
--help , -h
Displays usage instructions.
--optimize=MODE , -O=mode
MODE is a comma separated list of optimizations. They also
allow optimizations to be turned off by prefixing the optimiza-
tion name with a minus sign.
The following optimizations are implemented:
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
fcmov Fast x86 FP compares
leaf Leaf procedures optimizations
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
For example, to enable all the optimization but dead code elimi-
nation and inlining, you can use:
-O=all,-deadce,-inline
--security
Activate the security manager (experimental feature in(1,8) 1.1).
This allows mono to support declarative security attributes
(e.g. execution of, CAS or non-CAS, security demands). The secu-
rity manager is OFF by default (experimental).
-V , --version
Prints JIT version(1,3,5) information.
DEVELOPMENT OPTIONS
The following options are used to help when developing a JITed applica-
tion.
--debug
Turns on the debugging mode in(1,8) the runtime. If an assembly was
compiled with debugging information, it will produce line number
information for stack traces.
--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 pro-
filer is used.
Mono has a built-in profiler called `default' (and is also the
default if(3,n) no arguments are specified), but developers can write(1,2)
custom profilers as shared libraries. The shared library must
be called `mono-profiler-NAME.so' where `NAME' is the name of
your profiler.
For a sample of the custom profilers look(1,8,3 Search::Dict) in(1,8) the Mono source
tree for in(1,8) the samples/profiler.c.
The profiler_args is a profiler-specific string(3,n) of options for
the profiler itself.
The default profiler is called `default' and it accepts `alloc'
to profile memory consumption by the application; `time(1,2,n)' to pro-
file(1,n) the time(1,2,n) spent on each routine and `stat(1,2)' to perform sample
statistical profiling. If no options are provided the default
is `alloc,time(1,2,n)'.
For example:
mono --profile program.exe
That will run the program with the default profiler and will do
time(1,2,n) and allocation profiling.
mono --profile=default:stat,alloc program.exe
Will do sample statistical profiling and allocation profiling
on program.exe.
mono --profile=custom program.exe
In the above sample Mono will load(7,n) the user defined profiler
from the shared library `mono-profiler-custom.so'.
JIT MAINTAINER OPTIONS
The maintainer options are only used by those developing the runtime
itself, and not typically of interest to runtime users(1,5) or developers.
--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 generator.
--compileall
Compiles all the methods in(1,8) an assembly. This is used to test
the compiler performance or to examine the output of the code
generator
--graph=TYPE METHOD
This generates a postscript file(1,n) 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").
The following graphs are available:
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
Some graphs will only be available if(3,n) certain optimizations are
turned on.
--ncompile
Instruct the runtime on the number of times that the method
specified by --compile (or all the methods if(3,n) --compileall is
used) to be compiled. This is used for testing the code genera-
tor performance.
-v , --verbose
Increases the verbosity level, each time(1,2,n) it is listed, increases
the verbosity level to include more information (including, for
example, a disassembly of the native code produced, code selec-
tor info(1,5,n) etc.).
--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.
--breakonex
Inserts a breakpoint on exceptions. This allows you to debug
your application with a native debugger when an exception is
thrown.
--trace[=expression]
Shows method names as they are invoked. By default all methods
are traced.
The trace(3x,n,3x _nc_tracebits) can be customized to include or exclude methods,
classes or assemblies. A trace(3x,n,3x _nc_tracebits) 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.
Assemblies are specified by their name, for example, to trace(3x,n,3x _nc_tracebits)
all calls in(1,8) the System assembly, use:
mono --trace=System app.exe
Classes are specified with the T: prefix. For example, to trace(3x,n,3x _nc_tracebits)
all calls to the System.String class, use:
mono --trace=T:System.String app.exe
And individual methods are referenced with the M: prefix, and
the standar method notation:
mono --trace=M:System.Console:WriteLine app.exe
As previously noted, various rules can be specified at once:
mono --trace=T:System.String,T:System.Random app.exe
You can exclude pieces, the next example traces calls to Sys-
tem.String except for the System.String:Concat method.
mono --trace=T:System.String,-M:System.String:Concat
Finally, namespaces can be specified using the N: prefix:
mono --trace=N:System.Xml
DEBUGGING
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.
The MONO_LOG_LEVEL environment variable if(3,n) set(7,n,1 builtins), the logging level is
changed to the set(7,n,1 builtins) value. Possible values are "error(8,n)", "critical",
"warning", "message", "info(1,5,n)", "debug". The default value is "error(8,n)".
Messages with a logging level greater then or equal to the log level
will be printed to stdout/stderr.
Use "info(1,5,n)" to track the dynamic loading of assemblies.
Use the MONO_LOG_MASK environment variable to limit the extent of the
messages you get: If set(7,n,1 builtins), the log mask is changed to the set(7,n,1 builtins) value.
Possible values are "asm" (assembly loader), "type", "dll" (native
library loader), "gc" (garbage collector), "cfg" (config(1,5) file(1,n) loader),
"aot" (precompiler) and "all". The default value is "all". Changing
the mask value allows you to display only messages for a certain compo-
nent. You can use multiple masks by comma separating them. For example
to see config(1,5) file(1,n) messages and assembly loader messages set(7,n,1 builtins) you mask
to "asm,cfg".
The following is a common use to track down problems with P/Invoke:
$ MONO_LOG_LEVEL="debug" MONO_LOG_MASK="dll" mono glue.exe
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(3,n)
needed it will produce a customized C# serializer for your types at
runtime. This customized serializer then gets(3,n) dynamically loaded into
your application.
You can control this with the MONO_XMLSERIALIZER_THS environment vari-
able.
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 seri-
alizer on the first access(2,5), 50 will produce a serializer on the 50th
use).
ENVIRONMENT VARIABLES
GC_DONT_GC
Turns off the garbage collection in(1,8) Mono. This should be only
used for debugging purposes
MONO_AOT_CACHE
If set(7,n,1 builtins), this variable will instruct Mono to ahead-of-time com-
pile new assemblies on demand and store the result into a cache
in(1,8) ~/.mono/aot-cache.
MONO_ASPNET_NODELETE
If set(7,n,1 builtins) to any value, temporary source files generated by ASP.NET
support classes will not be removed. They will be kept in(1,8) the
user's temporary directory.
MONO_CFG_DIR
If set(7,n,1 builtins), this variable overrides the default system configuration
directory ($PREFIX/etc). It's used to locate machine.config
file.
MONO_CONFIG
If set(7,n,1 builtins), this variable overrides the default runtime configura-
tion file(1,n) ($PREFIX/etc/mono/config(1,5)). The --config command line
options overrides the environment variable.
MONO_DEBUG
If set(7,n,1 builtins), enables some features of the runtime useful for debug-
ging. This variable should contain a comma separated list of
debugging options. Currently, the following options are sup-
ported:
keep-delegates
This option will leak delegate trampolines that are no
longer referenced as to present the user with more infor-
mation about a delegate missuse. Basically a delegate
instance might be created, passed to unmanaged code, and
no references kept in(1,8) managed code, which will garbage
collect the code. With this option it is possible to
track down the source of the problems.
abort-on-sigsegv
This option will make the runtime abort(3,7) when it receives
a SIGSEGV signal(2,7) while executing unmanaged (native) code.
This is useful for debugging problems when interfacing
with native code.
MONO_DISABLE_AIO
If set(7,n,1 builtins), tells mono NOT to attempt using native asynchronous I/O
services. In that case, a default select(2,7,2 select_tut)/poll implementation is
used. Currently only epoll() is supported.
MONO_EGD_SOCKET
For platforms that do not otherwise have a way of obtaining ran-
dom(3,4,6) bytes this can be set(7,n,1 builtins) to the name of a file(1,n) system socket(2,7,n) on
which an egd or prngd daemon is listening.
MONO_EXTERNAL_ENCODINGS
If set(7,n,1 builtins), contains a colon-separated list of text encodings to try
when turning externally-generated text (e.g. command-line argu-
ments or filenames) into Unicode. The encoding(3,n) names come from
the list provided by iconv(1,3), and the special case
"default_locale" which refers to the current locale(3,5,7)'s default
encoding.
When reading externally-generated text strings UTF-8 is tried
first, and then this list is tried in(1,8) order with the first suc-
cessful conversion ending the search. When writing external
text (e.g. new filenames or arguments to new processes) the
first item in(1,8) this list is used, or UTF-8 if(3,n) the environment
variable is not set.
MONO_GAC_PREFIX
Provides a prefix the runtime uses to look(1,8,3 Search::Dict) for Global Assembly
Caches. Directories are separated by the platform path separa-
tor (colons on unix). MONO_GAC_PREFIX should point to the top
directory of a prefixed install. Or to the directory provided in(1,8)
the gacutil /gacdir command. Example: /home/user-
name/.mono:/usr/local/mono/
MONO_LOG_LEVEL
The logging level, possible values are `error(8,n)', `critical',
`warning', `message', `info(1,5,n)' and `debug'. See the DEBUGGING
section for more details.
MONO_LOG_MASK
Controls the domain of the Mono runtime that logging will apply
to. If set(7,n,1 builtins), the log mask is changed to the set(7,n,1 builtins) value. Possible
values are "asm" (assembly loader), "type", "dll" (native
library loader), "gc" (garbage collector), "cfg" (config(1,5) file(1,n)
loader), "aot" (precompiler) and "all". The default value is
"all". Changing the mask value allows you to display only mes-
sages for a certain component. You can use multiple masks by
comma separating them. For example to see config(1,5) file(1,n) messages
and assembly loader messages set(7,n,1 builtins) you mask to "asm,cfg".
MONO_MANAGED_WATCHER
If set(7,n,1 builtins) 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.
MONO_PATH
Provides a search path to the runtime where to look(1,8,3 Search::Dict) for library
files. Directories are separated by the platform path separator
(colons on unix). Example: /home/user-
name/lib:/usr/local/mono/lib
MONO_RTC
Experimental RTC support in(1,8) the statistical profiler: if(3,n) 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 fre-
quencies like 4096 Hz, run as root:
echo(1,3x,1 builtins) 4096 > /proc(5,n)/sys/dev/rtc/max-user-freq
For example:
MONO_RTC=4096 mono --profiler=default:stat program.exe
MONO_NO_TLS
Disable inlining of thread local accesses. Try setting this if(3,n)
you get a segfault early on in(1,8) the execution of mono.
MONO_SHARED_DIR
If set(7,n,1 builtins) 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(1,8) the
users(1,5)'s home directory.
MONO_THREADS_PER_CPU
The maximum number of threads in(1,8) the general threadpool will be
20 + (MONO_THREADS_PER_CPU * number of CPUs). The default value
for this variable is 5.
MONO_TRACE
Used for runtime tracing of method calls. The format of the
comma separated trace(3x,n,3x _nc_tracebits) options is:
[-]M:method name
[-]N:namespace
[-]T:class name
[-]all
[-]program
disabled Trace output off upon start.
You can toggle trace(3x,n,3x _nc_tracebits) output on/off sending a SIGUSR2 signal(2,7) to
the program.
MONO_TRACE_LISTENER
If set(7,n,1 builtins), enables the System.Diagnostics.DefaultTraceListener,
which will print the output of the System.Diagnostics Trace and
Debug classes. It can be set(7,n,1 builtins) to a filename, and to Console.Out
or Console.Error to display output to standard output or stan-
dard error(8,n), respectively. If it's set(7,n,1 builtins) to Console.Out or Con-
sole.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.
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.
FILES
On Unix assemblies are loaded from the installation lib directory. If
you set(7,n,1 builtins) `prefix' to /usr, the assemblies will be located in(1,8) /usr/lib.
On Windows, the assemblies are loaded from the directory where mono and
mint live.
~/.mono/aot-cache
The directory for the ahead-of-time compiler demand creation assemblies
are located.
/etc/mono/config(1,5), ~/.mono/config(1,5)
Mono runtime configuration file. See the mono-config(5) manual page
for more information.
~/.config/.mono/certs, /usr/share/.mono/certs
Contains Mono certificate stores for users(1,5) / machine. See the cert-
mgr(1) manual page for more information on managing certificate stores.
~/.config/.mono/keypairs, /usr/share/.mono/keypairs
Contains Mono cryptographic keypairs for users(1,5) / machine. They can be
accessed by using a CspParameters object with DSACryptoServiceProvider
and RSACryptoServiceProvider classes.
~/.config/.isolatedstorage, ~/.local/share/.isolatedstorage,
/usr/share/.isolatedstorage
Contains Mono isolated storage for non-roaming users(1,5), roaming users(1,5) and
local machine. Isolated storage can be accessed using the classes from
the System.IO.IsolatedStorage namespace.
MAILING LISTS
Visit http://lists.ximian.com/mailman/listinfo/mono-list for details.
WEB SITE
Visit: http://www.mono-project.com for details
SEE ALSO
mcs(1),mint(1),monodis(1),mono-config(5),certmgr(1).
For ASP.NET-related documentation, see the xsp(1) manual page
Mono(Mono 1.0)