mcs/tools/mono-symbolicate/README.md

   1 Mono Symbolicate Tool - README
   2
   3 Usage
   4 -----------------------------
   5
   6 ```
   7 mono-symbolicate <msym dir> <input file>
   8 mono-symbolicate store-symbols <msym dir> [<dir>]+
   9 ```
  10
  11 Description
  12 -----------------------------
  13
  14 `mono-symbolicate` is a tool that converts a stack trace with `<filename unknown>:0`
  15 into one with file names and line numbers.
  16
  17 The output of calling this tool will be the provided stacktracesfile where
  18 `<filename unknown>:0` parts are replaced by a file name and a line number.
  19
  20 The tool uses the AOTID and MVID metadata contained at the end of the stacktraces,
  21 to retrieve the symbols mapping code into line numbers from a provided symbol directory.
  22
  23 When `mono-symbolicate` is called with a symbol directory and a file containing a stacktrace:
  24 ``` mono-symbolicate <msym dir> <input file> ```
  25 The tool writes into stdout the file contents while adding file location to stack frames when
  26 it is possible to symbolicate with the symbols available on the symbol directory.
  27
  28 ## Symbol directory
  29 The symbol directory contains subfolder named as a MVID or AOTID.
  30  - MVID subfolders contain .dll/.exe and .mdb files.
  31  - AOTID subfolder contain .msym files.
  32
  33 Managed assemblies can be added by calling `mono-symbolicate` with the command `store-symbols`:
  34 ```
  35 mono-symbolicate store-symbols <msym dir> [<dir>]+
  36 ```
  37
  38 .msym are generated and stored automatically in an AOTID subfolder at the same time the assembly
  39 is compiled ahead of time, by running a command such as:
  40 ```
  41 mono --aot=msym-dir=<msym dir>
  42 ```
  43
  44 ## Practical example
  45
  46 If you do not have `mono-symbolicate` installed on your system you can set it to the built one by doing:
  47 ```
  48 alias mono="MONO_PATH=../../class/lib/net_4_x ../../../runtime/mono-wrapper"
  49 alias mono-symbolicate="mono ../../class/lib/net_4_x/mono-symbolicate.exe"
  50 ```
  51
  52 For the example we will use the csharp file `Test/StackTraceDumper.cs` which contains a program that
  53 outputs a larger number of stacktraces.
  54
  55 The first step is to compile our program with debug data.
  56 ```
  57 mkdir example
  58 mcs -debug -out:example/Program.exe Test/StackTraceDumper.cs
  59 ```
  60
  61 Next we need to create the symbol directory and store all the symbols we might need while symbolicating.
  62 ```
  63 mkdir example/msym-dir
  64 mono-symbolicate store-symbols example/msym-dir example
  65 ```
  66
  67 After running `mono-symbolicate store-symbols` command the directory `example/msym-dir` should have a subdirectory
  68 named as a minified GUID containing the Program.exe and Program.mdb.
  69
  70 If we want to symbolicate the stacktraces containing BCL stack frames we need to add those symbols too.
  71 ```
  72 mono-symbolicate store-symbols example/msym-dir ../../class/lib/net_4_x
  73 ```
  74
  75 We delete the mdb file so on our next step the generated stack trace won't have line numbers.
  76 ```
  77 rm example/*.mdb
  78 ```
  79
  80 Now we can run our program and dump its output to `example/out`.
  81 ```
  82 mono example/Program.exe > example/out
  83 ```
  84
  85 Doing `cat example/out` shows us a large number of stacktraces without any line number.
  86
  87 We can finally run `mono-symbolicate` to replace all the `<filename unknown>:0` with actually useful file names and line numbers.
  88 ```
  89 mono-symbolicate example/msym-dir example/out
  90 ```
  91 The previous command should display the same as `cat example/out` but this time with file names and line numbers.
  92