[linker-analyzer] Added man page for the linker analyzer

1 files changed, 132 insertions, 0 deletions

diff --git a/man/illinkanalyzer.1 b/man/illinkanalyzer.1
new file mode 100644
index 00000000000..5ce3b9cde1d
--- /dev/null
+++ b/man/illinkanalyzer.1
@@ -0,0 +1,132 @@
+.TH illinkanalyzer 1
+.SH NAME
+illinkanalyzer \- Mono's linker analyzer tool
+.SH SYNOPSIS
+.B illinkanalyzer
+\fR[\fIoptions\fR] <\fIlinker-dependency-file.xml.gz\fR>
+.SH DESCRIPTION
+Linker analyzer is a command line tool to analyze dependencies, which
+were recorded during linker processing, and led linker to mark an item
+to keep it in the resulting linked assembly.
+.PP
+It works on an oriented graph of dependencies, which are collected and
+dumped during the linker run. The vertices of this graph are the items
+of interest like assemblies, types, methods, fields, linker steps,
+etc. The edges represent the dependencies.
+.SH HOW TO DUMP DEPENDENCIES
+The linker analyzer needs a linker dependencies file as an input. It
+can be retrieved by enabling dependencies dumping during linking of a
+Xamarin.Android or a Xamarin.iOS project.
+.PP
+That can be done on the command line by setting LinkerDumpDependencies
+property to true and building the project. (make sure the
+LinkAssemblies task is called, it might require cleaning the project
+sometimes) Usually it is enough to build the project like this:
+.PP
+.nf
+.RS
+rm -f obj/Release/link.flag
+msbuild /p:LinkerDumpDependencies=true /p:Configuration=Release YourAppProject.csproj
+.RE
+.fi
+.PP
+After a successful build, there will be a linker-dependencies.xml.gz
+file created, containing the information for the analyzer.
+.SH OPTIONS
+.nf
+.RS
+  -a, --alldeps              show all dependencies
+      --csvoutput=VALUE      outputs types and optionally size analysis to CSV
+                               file
+  -h, --help                 show this message and exit.
+  -l, --linkedpath=VALUE     sets the linked assemblies directory path. Enables
+                               displaying size estimates.
+  -r, --rawdeps=VALUE        show raw vertex dependencies. Raw vertex VALUE is
+                               in the raw format written by linker to the
+                               dependency XML file. VALUE can be regular
+                               expression
+      --roots                show root dependencies.
+      --stat                 show statistic of loaded dependencies.
+      --tree                 reduce the dependency graph to the tree.
+      --types                show all types dependencies.
+  -t, --typedeps=VALUE       show type dependencies. The VALUE can be regular
+                               expression
+  -f, --flat                 show all dependencies per vertex and their distance
+  -v, --verbose              be more verbose. Enables stat and roots options.
+.RE
+.fi
+.SH EXAMPLES
+Let say you would like to know, why a type, Android.App.Activity for
+example, was marked by the linker. So run the analyzer like this:
+.PP
+.nf
+.RS
+illinkanalyzer -t Android.App.Activity linker-dependencies.xml.gz
+.fi
+.RE
+.PP
+Output:
+.PP
+.nf
+.RS
+Loading dependency tree from: linker-dependencies.xml.gz
+
+--- Type dependencies: 'Android.App.Activity' -----------------------
+
+--- TypeDef:Android.App.Activity dependencies -----------------------
+Dependency #1
+	TypeDef:Android.App.Activity
+	| TypeDef:XA.App.MainActivity [2 deps]
+	| Assembly:XA.App, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null [3 deps]
+	| Other:Mono.Linker.Steps.ResolveFromAssemblyStep
+.fi
+.RE
+.PP
+The output contains dependencies string(s), starting with the type and
+continuing with the item of interest, which depends on the type. The
+dependency could be result of multiple reasons. For example the type
+was referenced from a method, or the type was listed in the linker xml
+file to be protected.
+.PP
+In our example there is only one dependency string called Dependency
+#1. It shows us that the type Android.App.Activity was marked during
+processing of type XA.App.MainActivity by the linker. In this case
+because the MainActivity type is based on the Activity type and thus
+the linker marked it and kept it in the linked assembly. We can also
+see that there are 2 dependencies for the MainActivity class. Note
+that in the string (above) we see only 1st dependency of the 2, the
+dependency on the assembly XA.App. And finally the assembly vertex
+depends on the ResolveFromAssemblyStep vertex. So we see that the
+assembly was processed in the ResolveFromAssembly linker step.
+.PP
+Now we might want to see the MainActivity dependencies. That could be done by the following analyzer run:
+.PP
+.nf
+.RS
+illinkanalyzer -r TypeDef:XA.App.MainActivity linker-dependencies.xml.gz
+.fi
+.RE
+.PP
+Output:
+.PP
+.nf
+.RS
+Loading dependency tree from: linker-dependencies.xml.gz
+
+--- Raw dependencies: 'TypeDef:XA.App.MainActivity' -----------------
+
+--- TypeDef:XA.App.MainActivity dependencies ------------------------
+Dependency #1
+	TypeDef:XA.App.MainActivity
+	| Assembly:XA.App, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null [3 deps]
+	| Other:Mono.Linker.Steps.ResolveFromAssemblyStep
+Dependency #2
+	TypeDef:XA.App.MainActivity
+	| TypeDef:XA.App.MainActivity/<>c__DisplayClass1_0 [2 deps]
+	| TypeDef:XA.App.MainActivity [2 deps]
+	| Assembly:XA.App, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null [3 deps]
+	| Other:Mono.Linker.Steps.ResolveFromAssemblyStep
+.fi
+.RE
+.SH SEE ALSO
+\fBmsbuild\fR(1)