README.md
1Linker analyzer is a command line tool to analyze dependencies, which
2were recorded during linker processing, and led linker to mark an item
3to keep it in the resulting linked assembly.
4
5It works on an oriented graph of dependencies, which are collected and
6dumped during the linker run. The vertices of this graph are the items
7of interest like assemblies, types, methods, fields, linker steps,
8etc. The edges represent the dependencies.
9
10How to dump dependencies
11------------------------
12
13The linker analyzer needs a linker dependencies file as an input. It
14can be retrieved by enabling dependencies dumping during linking of a
15Xamarin.Android or a Xamarin.iOS project.
16
17That can be done on the command line by setting
18`LinkerDumpDependencies` property to `true` and building the
19project. (make sure the LinkAssemblies task is called, it might
20require cleaning the project sometimes) Usually it is enough to build
21the project like this:
22
23```msbuild /p:LinkerDumpDependencies=true /p:Configuration=Release YourAppProject.csproj```
24
25After a successful build, there will be a linker-dependencies.xml.gz
26file created, containing the information for the analyzer.
27
28How to use the analyzer
29-----------------------
30
31Let say you would like to know, why a type, Android.App.Activity for
32example, was marked by the linker. So run the analyzer like this:
33
34```illinkanalyzer -t Android.App.Activity linker-dependencies.xml.gz```
35
36Output:
37
38```
39Loading dependency tree from: linker-dependencies.xml.gz
40
41--- Type dependencies: 'Android.App.Activity' -----------------------
42
43--- TypeDef:Android.App.Activity dependencies -----------------------
44Dependency #1
45 TypeDef:Android.App.Activity
46 | TypeDef:XA.App.MainActivity [2 deps]
47 | Assembly:XA.App, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null [3 deps]
48 | Other:Mono.Linker.Steps.ResolveFromAssemblyStep
49```
50
51The output contains dependencies string(s), starting with the type and
52continuing with the item of interest, which depends on the type. The
53dependency could be result of multiple reasons. For example the type
54was referenced from a method, or the type was listed in the linker xml
55file to be protected.
56
57In our example there is only one dependency string called `Dependency
58#1`. It shows us that the type `Android.App.Activity` was marked
59during processing of type `XA.App.MainActivity` by the linker. In this
60case because the `MainActivity` type is based on the `Activity` type
61and thus the linker marked it and kept it in the linked assembly. We
62can also see that there are 2 dependencies for the `MainActivity`
63class. Note that in the string (above) we see only 1st dependency of
64the 2, the dependency on the assembly `XA.App`. And finally the
65assembly vertex depends on the `ResolveFromAssemblyStep` vertex. So we
66see that the assembly was processed in the `ResolveFromAssembly`
67linker step.
68
69Now we might want to see the `MainActivity` dependencies. That could
70be done by the following analyzer run:
71
72```illinkanalyzer -r TypeDef:XA.App.MainActivity linker-dependencies.xml.gz```
73
74Output:
75
76```
77Loading dependency tree from: linker-dependencies.xml.gz
78
79--- Raw dependencies: 'TypeDef:XA.App.MainActivity' -----------------
80
81--- TypeDef:XA.App.MainActivity dependencies ------------------------
82Dependency #1
83 TypeDef:XA.App.MainActivity
84 | Assembly:XA.App, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null [3 deps]
85 | Other:Mono.Linker.Steps.ResolveFromAssemblyStep
86Dependency #2
87 TypeDef:XA.App.MainActivity
88 | TypeDef:XA.App.MainActivity/<>c__DisplayClass1_0 [2 deps]
89 | TypeDef:XA.App.MainActivity [2 deps]
90 | Assembly:XA.App, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null [3 deps]
91 | Other:Mono.Linker.Steps.ResolveFromAssemblyStep
92```
93
94Known issues
95------------
96
97Sometimes the linker processing is not straight forward and the
98marking is postponed, like processing of some of the methods. They are
99queued to be processed later. In such case the dependencies are
100"interrupted" and the dependecy string for the method usually shows
101just dependency on the Mark step.
102
103Command line help
104-----------------
105```
106Usage:
107
108 illinkanalyzer [Options] <linker-dependency-file.xml.gz>
109
110Options:
111
112 -a, --alldeps show all dependencies
113 -h, --help show this message and exit.
114 -r, --rawdeps=VALUE show raw vertex dependencies. Raw vertex VALUE is
115 in the raw format written by linker to the
116 dependency XML file. VALUE can be regular
117 expression
118 --roots show root dependencies.
119 --stat show statistic of loaded dependencies.
120 --tree reduce the dependency graph to the tree.
121 --types show all types dependencies.
122 -t, --typedeps=VALUE show type dependencies. The VALUE can be regular
123 expression
124 -f, --flat show all dependencies per vertex and their distance
125 -v, --verbose be more verbose. Enables stat and roots options.
126```
127