From: Radek Doulik Date: Thu, 21 Sep 2017 14:14:42 +0000 (+0200) Subject: [linker-analyzer] added documentation X-Git-Url: http://wien.tomnetworks.com/gitweb/?p=mono.git;a=commitdiff_plain;h=a494d83effb60f3b789d7d4b23617e7700494700 [linker-analyzer] added documentation --- diff --git a/mcs/tools/linker-analyzer/README.md b/mcs/tools/linker-analyzer/README.md new file mode 100644 index 00000000000..a848021c526 --- /dev/null +++ b/mcs/tools/linker-analyzer/README.md @@ -0,0 +1,125 @@ +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. + +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. + +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. + +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: + +```msbuild /p:LinkerDumpDependencies=true /p:Configuration=Release YourAppProject.csproj``` + +After a successful build, there will be a linker-dependencies.xml.gz +file created, containing the information for the analyzer. + +How to use the analyzer +----------------------- + +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: + +```mono linkeranalyzer.exe -t Android.App.Activity linker-dependencies.xml.gz``` + +Output: + +``` +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 +``` + +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. + +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. + +Now we might want to see the `MainActivity` dependencies. That could +be done by the following analyzer run: + +```mono linkeranalyzer.exe -r TypeDef:XA.App.MainActivity linker-dependencies.xml.gz``` + +Output: + +``` +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 +``` + +Known issues +------------ + +Sometimes the linker processing is not straight forward and the +marking is postponed, like processing of some of the methods. They are +queued to be processed later. In such case the dependencies are +"interrupted" and the dependecy string for the method usually shows +just dependency on the Mark step. + +Command line help +----------------- +``` +Usage: + + linkeranalyzer [Options] + +Options: + + -a, --alldeps show all dependencies + -h, --help show this message and exit. + -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 + -v, --verbose be more verbose. Enables stat and roots options. +```