mono/linux-packaging-mono
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Imported Upstream version 5.10.0.47

Browse Source 
Former-commit-id: d0813289fa2d35e1f8ed77530acb4fb1df441bc0
This commit is contained in:
Xamarin Public Jenkins (auto-signing)
2018-01-24 17:04:36 +00:00
parent 88ff76fe28
commit e46a49ecf1
5927 changed files with 226314 additions and 129848 deletions
Download Patch File Download Diff File Expand all files Collapse all files

253
man/mono.1
View File

@@ -177,6 +177,17 @@ options. This feature is experimental.
.TP
.I llvm-outfile=[filename]
Gives the path for the temporary LLVM bitcode file created during AOT.
.I dedup
Each AOT module will typically contain the code for inflated methods and wrappers that
are called by code in that module. In dedup mode, we identify and skip compiling all of those
methods. When using this mode with fullaot, dedup-include is required or these methods will
remain missing.
.TP
.I dedup-include=[filename]
In dedup-include mode, we are in the pass of compilation where we compile the methods
that we had previously skipped. All of them are emitted into the assembly that is passed
as this option. We consolidate the many duplicate skipped copies of the same method into one.
.TP
.TP
.I info
Print the architecture the AOT in this copy of Mono targets and quit.
@@ -251,14 +262,14 @@ If the AOT compiler cannot compile a method for any reason, enabling this flag
will output the skipped methods to the console.
.TP
.I profile=[file]
Specify a file to use for profile-guided optimization. See the "AOT PROFILING" section. To specify multiple files, include the
Specify a file to use for profile-guided optimization. See the \fBAOT profiler\fR sub-section. To specify multiple files, include the
.I profile
option multiple times.
.TP
.I profile-only
AOT *only* the methods described in the files specified with the
.I profile
option. See the "AOT PROFILING" section.
option. See the \fBAOT profiler\fR sub-section.
.TP
.I readonly-value=namespace.typename.fieldname=type/value
Override the value of a static readonly field. Usually, during JIT
@@ -444,6 +455,11 @@ will switch to '/bin/mono64' iff '/bin/mono' is a 32-bit build).
\fB--help\fR, \fB-h\fR
Displays usage instructions.
.TP
\fB--interpreter\fR
The Mono runtime will use its interpreter to execute a given assembly.
The interpreter is usually slower than the JIT, but it can be useful on
platforms where code generation at runtime is not allowed.
.TP
\fB--hybrid-aot\fR
This flag allows the Mono runtime to run assemblies
that have been stripped of IL, for example using mono-cil-strip. For this to
@@ -625,14 +641,12 @@ platforms, and only when using gdb 7.0 or later.
.ne
.RE
.TP
\fB--profile[=profiler[:profiler_args]]\fR
Turns on profiling. For more information about profiling applications
and code coverage see the sections "PROFILING" and "CODE COVERAGE"
below.
\fB\-\-profile\fR[=\fIprofiler\fR[:\fIprofiler_args\fR]]\fR
Loads a profiler module with the given arguments. For more information,
see the \fBPROFILING\fR section.
.Sp
This option can be used multiple times, each time will load an
additional profiler. This allows developers to use modules that
extend the JIT through the Mono profiling interface.
This option can be used multiple times; each time will load an additional
profiler module.
.TP
\fB--trace[=expression]\fR
Shows method names as they are invoked. By default all methods are
@@ -811,128 +825,81 @@ create its own threads and return after invocation.
This support allows for example debugging applications by having the
csharp shell attach to running processes.
.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
--profile[=profiler[:profiler_args]]
.fi
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.
The Mono runtime includes a profiler API that dynamically loaded
profiler modules and embedders can use to collect performance-related
data about an application. Profiler modules are loaded by passing the
\fB\-\-profile\fR command line argument to the Mono runtime.
.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; 'jit' to collect time spent JIT-compiling methods
and 'stat' to perform sample statistical profiling.
If no options are provided the default is 'alloc,time,jit'.
.PP
By default the
profile data is printed to stdout: to change this, use the 'file=filename'
option to output the data to filename.
.Sp
For example:
.nf
mono --profile program.exe
.fi
.Sp
That will run the program with the default profiler and will do time
and allocation profiling.
.Sp
.nf
mono --profile=default:stat,alloc,file=prof.out program.exe
.fi
Will do sample statistical profiling and allocation profiling on
program.exe. The profile data is put in prof.out.
.Sp
Note that the statistical profiler has a very low overhead and should
be the preferred profiler to use (for better output use the full path
to the mono binary when running and make sure you have installed the
addr2line utility that comes from the binutils package).
.SH LOG PROFILER
This is the most advanced profiler.
.PP
The Mono \f[I]log\f[] profiler can be used to collect a lot of
information about a program running in the Mono runtime.
This data can be used (both while the process is running and later)
to do analyses of the program behaviour, determine resource usage,
performance issues or even look for particular execution patterns.
Mono ships with a few profiler modules, of which the \fBlog\fR profiler
is the most feature-rich. It is also the default profiler if the
\fIprofiler\fR argument is not given, or if \fBdefault\fR is given.
It is possible to write your own profiler modules; see the
\fBCustom profilers\fR sub-section.
.SS Log profiler
The log profiler can be used to collect a lot of information about
a program running in the Mono runtime. This data can be used (both
while the process is running and later) to do analyses of the
program behavior, determine resource usage, performance issues or
even look for particular execution patterns.
.PP
This is accomplished by logging the events provided by the Mono
runtime through the profiling interface and periodically writing
them to a file which can be later inspected with the mprof-report(1)
tool.
runtime through the profiler API and periodically writing them to a
file which can later be inspected with the \fBmprof\-report\fR(1)
tool.
.PP
More information about how to use the log profiler is available on the
mprof-report(1) page.
.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.
More information about how to use the log profiler is available on
the \fBmono\-profilers\fR(1) page, under the \fBLOG PROFILER\fR
section, as well as the \fBmprof\-report\fR(1) page.
.SS Coverage profiler
The code coverage profiler can instrument a program to help determine
which classes, methods, code paths, etc are actually executed. This
is most useful when running a test suite to determine whether the
tests actually cover the code they're expected to.
.PP
More information about how to use the coverage profiler is available
on the \fBmono\-profilers\fR(1) page, under the \fBCOVERAGE
PROFILER\fR section.
.SS AOT profiler
The AOT profiler can help improve startup performance by logging
which generic instantiations are used by a program, which the AOT
compiler can then use to compile those instantiations ahead of time
so that they won't have to be JIT compiled at startup.
.PP
More information about how to use the AOT profiler is available on
the \fBmono\-profilers\fR(1) page, under the \fBAOT PROFILER\fR
section.
.SS Custom profilers
Custom profiler modules can be loaded in exactly the same way as the
standard modules that ship with Mono. They can also access the same
profiler API to gather all kinds of information about the code being
executed.
.PP
For example, to use a third-party profiler called \fBcustom\fR, you
would load it like this:
.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
.RS
mono --profile=custom program.exe
.RE
.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/docs/advanced/performance-tips/)
You could also pass arguments to it:
.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 in the \f[I]coverage\f[] profiler.
To enable it, pass \fB--profile=coverage\fR to your mono invocation. It
will by default output a coverage.xml in the current directory. Use
\fBmono --profile=coverage:help sample.exe\fR for more information on the
different options.
.SH AOT PROFILING
You can improve startup performance by using the AOT profiler.
.PP
Typically the AOT compiler (\fBmono --aot\fR) will not generate code
for generic instantiations. To solve this, you can run Mono with the
AOT profiler to find out all the generic instantiations that are used,
and then instructing the AOT compiler to produce code for these.
.PP
This command will run the specified app.exe and produce the
\fBout.aotprof\fR file with the data describing the generic
instantiations that are needed:
.nf
$ mono --profile=aot:output=out.aotprof app.exe
.RS
mono --profile=custom:arg1,arg2=arg3 program.exe
.RE
.fi
.PP
Once you have this data, you can pass this to Mono's AOT compiler to
instruct it to generate code for it:
.nf
$ mono --aot=profile=out.aotprof
.fi
In the above example, Mono will load the profiler from the shared
library called \fIlibmono\-profiler\-custom.so\fR (name varies based
on platform, e.g., \fIlibmono\-profiler\-custom.dylib\fR on OS X).
This profiler module must be on your dynamic linker library path
(\fBLD_LIBRARY_PATH\fR on most systems, \fBDYLD_LIBRARY_PATH\fR on
OS X).
.PP
For a sample of how to write your own custom profiler, look at the
\fIsamples/profiler/sample.c\fR file in the Mono source tree.
.SH DEBUGGING AIDS
To debug managed applications, you can use the
.B mdb
@@ -983,8 +950,10 @@ 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),
"security" (e.g. Moonlight CoreCLR support), "threadpool" (thread pool generic),
"io-threadpool" (thread pool I/O), "io-layer" (I/O layer - sockets, handles, shared memory etc)
and "all".
"io-selector" (async socket operations), "io-layer" (I/O layer - processes, files,
sockets, events, semaphores, mutexes and handles), "io-layer-process",
"io-layer-file", "io-layer-socket", "io-layer-event", "io-layer-semaphore",
"io-layer-mutex", "io-layer-handle" 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
@@ -1134,18 +1103,6 @@ internally disables managed collation functionality invoked via the
members of System.Globalization.CompareInfo class. Collation is
enabled by default.
.TP
\fBMONO_DISABLE_SHM\fR
Unix only: If set, disables the shared memory files used for
cross-process handles: process have only private handles. This means
that process and thread handles are not available to other processes,
and named mutexes, named events and named semaphores are not visible
between processes.
.Sp
This is can also be enabled by default by passing the
"--disable-shared-handles" option to configure.
.Sp
This is the default from mono 2.8 onwards.
.TP
\fBMONO_DISABLE_SHARED_AREA\fR
Unix only: If set, disable usage of shared memory for exposing
performance counters. This means it will not be possible to both
@@ -1529,29 +1486,6 @@ directive instead, like this:
.fi
See mod_mono(8) for more details.
Additionally. Mono includes a profiler module which allows one to track what
adjustements to file paths IOMAP code needs to do. The tracking code reports
the managed location (full stack trace) from which the IOMAP-ed call was made and,
on process exit, the locations where all the IOMAP-ed strings were created in
managed code. The latter report is only approximate as it is not always possible
to estimate the actual location where the string was created. The code uses simple
heuristics - it analyzes stack trace leading back to the string allocation location
and ignores all the managed code which lives in assemblies installed in GAC as well as in the
class libraries shipped with Mono (since they are assumed to be free of case-sensitivity
issues). It then reports the first location in the user's code - in most cases this will be
the place where the string is allocated or very close to the location. The reporting code
is implemented as a custom profiler module (see the "PROFILING" section) and can be loaded
in the following way:
.fi
.Sp
.nf
mono --profile=iomap yourapplication.exe
.fi
Note, however, that Mono currently supports only one profiler module
at a time.
.TP
\fBMONO_LLVM\fR
When Mono is using the LLVM code generation backend you can use this
@@ -2008,8 +1942,11 @@ http://www.mono-project.com/community/help/mailing-lists/
http://www.mono-project.com
.SH SEE ALSO
.PP
certmgr(1), cert-sync(1), csharp(1), gacutil(1), mcs(1), mdb(1), monodis(1),
mono-config(5), mprof-report(1), pdb2mdb(1), xsp(1), mod_mono(8).
\fBcertmgr\fR(1), \fBcert-sync\fR(1), \fBcsharp\fR(1),
\fBgacutil\fR(1), \fBmcs\fR(1), \fBmonodis\fR(1),
\fBmono-config\fR(5), \fBmono\-profilers\fR(1),
\fBmprof\-report\fR(1), \fBpdb2mdb\fR(1), \fBxsp\fR(1),
\fBmod_mono\fR(8)
.PP
For more information on AOT:
http://www.mono-project.com/docs/advanced/aot/