mcs/tools/linker-analyzer/README.md

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