1 * How to debug your C# application with the JIT engine
3 To debug a C# application you need to run the JIT in your debugger.
5 Before you can do anything useful in a debugger, you need a symbol
6 file which tells your debugger about functions, types, line numbers
7 and such. Unfortunately, this symbol file needs to be recreated each
8 time the JIT compiles a new method since it doesn't know anything
9 about this method (especially not its memory address) before actually
12 You have two ways of creating a symbol file:
14 ** Letting the JIT dynamically create the symbol file
16 This'll give you a symbol file which is suitable for debugging IL byte
17 code - you won't see your C# source code.
19 However, this method has the advantage that it works with every assembly,
20 no matter whether it has been compiled with Mono's C# compiler (MCS) or
21 with any other compiler. It's currently the only way to debug
22 <tt>corlib.dll</tt> or any other library which cannot be compiled with
25 All that you need is a dump of the IL bytecode for each assembly (including
26 all assemblies this assembly is referencing). This is done by using the
27 <tt>monodis</tt> utility:
30 monodis /home/export/martin/MONO-LINUX/lib/corlib.dll > corlib.il<br>
31 monodis /home/export/martin/MONO-LINUX/lib/System.dll > System.il<br>
32 monodis /home/export/martin/MONO-LINUX/bin/mcs.exe > mcs.il
35 Make sure that all the .il files have the same name as their corresponding
36 assembly and that they're all created in the current directory.
38 The JIT supports two different debugging file formats:
41 * STABS: This is a very simple debugging format, but it may be the only one
42 which is supported on your system. It is limited to source files of no more
43 than 65.535 lines and it's type support is also very limited. You should only
44 use this if your debugger doesn't support DWARF 2.
46 To generate STABS output, use the <tt>--stabs</tt> command line argument.
49 * DWARF 2: The DWARF 2 debugging format is a very powerful debugging format
50 which can handle source files of arbitrary size and has a highly sophisticated
51 type support. It's the recommended format unless you need to use STABS because
52 your debugger doesn't support DWARF 2.
54 To generate DWARF 2 output, use the <tt>--dwarf</tt> command line argument.
58 You need to regenerate the symbol file each time the JIT compiled a new
59 method and each time you restart the JIT. You cannot reuse your symbol file
60 if you start the JIT a second file, not even if you're running the same
61 application with the same input data a second time.
63 Regenerating the symbol file is done by calling the JIT's
64 <tt>mono_debug_make_symbols ()</tt> function from within your debugger and
65 then reloading the symbol files. This function creates a <tt>filename-dwarf.s</tt>
66 (or <tt>filename-stabs.s</tt>) assembler input file in the current directory and
67 an object file in <tt>/tmp/filename.o</tt> - you need to tell your debugger to
68 add this object file as symbol file.
70 If you're using the GNU debugger, this is done like this:
73 call mono_debug_make_symbols ()
74 add-symbol-file /tmp/corlib.o
75 add-symbol-file /tmp/mcs.o
76 add-symbol-file /tmp/Mono.CSharp.Debugger.o
79 You can also write a GDB macro like this:
83 call mono_debug_make_symbols ()
84 add-symbol-file /tmp/corlib.o
85 add-symbol-file /tmp/mcs.o
86 add-symbol-file /tmp/Mono.CSharp.Debugger.o
90 Then you can just say <tt>reload</tt> to have GDB recreate the symbol file.
92 There's also an <a href="jit-debug-sample.html">example debugging session</a> using
95 ** Using a symbol file which have been created by the Mono C# compiler
97 If you compiled your application with Mono's C# compiler (MCS), you can tell it to
98 create a symbol file which is then processed and rewritten by the JIT engine.
100 To do this, you must give MCS the <tt>-g</tt> option:
106 This creates a <tt>Foo-debug.s</tt> assembler input file.
108 To use this in the JIT, you must first copy it to the target machine (the machine
109 where you want to run the JIT to debug your application) and run it through the
110 assembler to produce an object file <tt>Foo-debug.o</tt>. This object file must be
111 in the current directory.
113 Then start the JIT in your debugger and give it the <tt>--dwarf-plus</tt> command
116 Each time you call <tt>mono_debug_make_symbols ()</tt> from withing your debugger,
117 the JIT will read this <tt>Foo-debug.o</tt>, fix some machine dependent things like
118 memory addresses etc. in it and write it back to disk.
120 If you're using the GNU debugger, you'll want to use a macro like this:
124 call mono_debug_make_symbols ()
125 add-symbol-file /tmp/corlib.o
126 add-symbol-file mcs-debug.o
127 add-symbol-file Mono.CSharp.Debugger-debug.o
131 If there is no <tt>assembly-debug.o</tt> file, but an <tt>assembly.il</tt> one, the
132 JIT will fall back to normal DWARF 2 (in the example above, <tt>corlib.dll</tt> was
133 compiled with Microsoft's compiler and the JIT is thus using DWARF to debug it).
135 This debugging method only works if you compiled your assembly with MCS, but it'll
136 allow you to actually debug your C# source code :-)
138 Here's an <a href="jit-debug-sample2.html">example debugging session</a> using
141 ** Breakpoints and single stepping
143 The JIT has a <tt>--debug</tt> command line argument to insert a breakpoint at the
144 beginning of this method. It takes a <tt>Namespace.Class:Method</tt> argument which
145 is the method. This argument can be given multiple times.
147 However, once your application is stopped in GDB you may want to insert a breakpoint
148 the next time the JIT compiles a method. There's a global variable
149 <tt>mono_debug_insert_breakpoint</tt> which you can modify in your debugger.
151 If this variable is set to a non-zero value, the JIT's <tt>arch_compile_method</tt>
152 will insert a breakpoint the next time it is called, ie. at the top of the next
153 method it compiles. If this value has a positive value, it acts as a counter and is
154 decremented after inserting the breakpoint - setting it to a negative value will let
155 the JIT insert the breakpoint each time it compiles a new method.
157 There's also global variable <tt>mono_debug_last_breakpoint_address</tt> which always
158 contains the address of the last inserted breakpoint. You may manually override this
159 address with a <tt>nop</tt> instruction to delete the breakpoint.
161 For instance, I have a GDB macro called <tt>enter</tt> which I use to enter a method
162 rather than stepping over it:
166 set mono_debug_insert_breakpoint = 1
168 set *mono_debug_last_breakpoint_address = 0x90
173 Btw. speaking of single stepping - you should use your debuggers <tt>next</tt> command,
174 not its <tt>step</tt> command for single stepping unless you compiled the JIT without
175 debugging support. The reason for this is that the JIT creates machine code which contains
176 calls to JIT methods such as <tt>mono_object_new_wrapper</tt> at places where you don't
177 expect them - so unless the JIT is compiled at least without line numbers, your debugger
178 will enter such methods if you use <tt>step</tt> rather than <tt>next</tt>.