|
1 | 1 | Ddoc |
2 | 2 |
|
3 | | -$(H2 Visual Studio Debugger) |
| 3 | +$(P Here's a little bit of history required to understand the available options for debugging |
| 4 | +D programs with Visual Studio.) |
4 | 5 |
|
5 | | -$(P Thanks to $(LINK2 https://github.com/rainers/cv2pdb, cv2pdb), debugging in Visual Studio integrates well. |
6 | | -Here is an example debugging session) |
| 6 | +$(P If you are only interested in the latest state with VS 2015, you can skip all this and go |
| 7 | +directly to the $(ALOCAL recommendation, recommendation).) |
| 8 | + |
| 9 | +$(H2 VS 2008-2010 cv2pdb) |
| 10 | + |
| 11 | +$(P Development of Visual D started around 2009, with VS 2008 being the latest Visual Studio version. |
| 12 | +DMD only supported Windows 32-bit programs, with debug information written in an ancient version |
| 13 | +of CodeView. This was not well understood by the Visual Studio debugger, basic |
| 14 | +operations like setting breakpoints and investigating struct members didn't work. |
| 15 | +That's why cv2pdb was created to convert the old CodeView debug information embedded into the executable |
| 16 | +to a newer version of CodeView written into a PDB file.) |
| 17 | + |
| 18 | +$(P VS 2008 and VS 2010 have two engines for debugging native code, one mainly targeted at C/C++ |
| 19 | +and one for mixed native and managed code. Both understood visualizer descriptions |
| 20 | +in a file named autoexp.dat, that cv2pdb took advantage of to display some D constructs |
| 21 | +in watch windows: slices, strings and associatives arrays. That made debugging |
| 22 | +D programs quite possible, though debug info from the compiler was very basic. Some |
| 23 | +quirks had to be accepted, e.g. type names must not contain '.' to avoid confusing the |
| 24 | +debugger, so it is replaced with '@'. Expressions need to be specified in C/C++ syntax.) |
| 25 | + |
| 26 | +$(P Here is an example debugging session that used cv2pdb) |
7 | 27 |
|
8 | 28 | <div align="center"><img src="images/debug.png" width="90%"/></div> |
9 | 29 |
|
10 | | -$(P Using cv2pdb has a few quirks, like displaying '@' instead of '.'. This is happening because the C++ debugger |
11 | | -that comes with Visual Studio is used and it is confused if there is a '.' in a symbol name.) |
| 30 | +$(H2 mago) |
12 | 31 |
|
13 | | -$(H3 Exceptions) |
| 32 | +$(P In 2010, Aldo Nunez surprised the D community with a new debug engine dedicated to the |
| 33 | +D language, that plugs in to Visual Studio as an extension. This engine can read the old |
| 34 | +CodeView debug information emitted by DMD. Having full support for D types and expressions, |
| 35 | +the above quirks are avoided. |
| 36 | +In addition, there is no need to supply slow visualizer macros as mago can display |
| 37 | +slices, strings and more nicely. You can select the mago debug engine in the project |
| 38 | +debugging settings of a Visual D project.) |
14 | 39 |
|
15 | | -$(P As of version 0.3.21, the installer adds an entry "D Exception" to the list of Win32 exceptions that |
16 | | -can be found in the Debug->Exceptions dialog. This allows the debugger to stop execution when an exception |
17 | | -is thrown by the debuggee. With earlier versions, you'll have to add an entry with code 0xE0440001 yourself.) |
| 40 | +$(IMG_CENTER images/prop_debug.png) |
18 | 41 |
|
| 42 | +$(P One downside of the mago debug engine is that it does not support all the features |
| 43 | +of the native Visual Studio debugger, e.g. conditional breakpoints, hardware assisted |
| 44 | +breakpoints or attaching to a process.) |
19 | 45 |
|
20 | | -$(H2 Mago Debugger) |
| 46 | +$(H2 64-bit) |
21 | 47 |
|
22 | | -$(P As of version 0.3.16 Visual D comes with the option to install the |
23 | | -$(LINK2 http://www.dsource.org/projects/mago_debugger, Mago debugger). This debug engine is dedicated to the |
24 | | -D programming language and avoids the work-arounds needed when using the native debug engine. It also |
25 | | -features D specific expressions like dynamic array slicing.) |
| 48 | +$(P DMD added 64-bit Windows support in 2012, writing COFF object files supporting the |
| 49 | +newer version of the CodeView debug information from the start. So there is no need to |
| 50 | +use a conversion tool for its output. In 2014, DMD got the option to also emit COFF |
| 51 | +files for 32-bit code using the same debug format.) |
26 | 52 |
|
27 | | -$(P To enable debugging with the Mago debugger select it on the project configuration page "Debugging". |
28 | | -This will also disable cv2pdb conversion as Mago directly operates on the debug info emitted by DMD.) |
| 53 | +$(P The visual studio debuggers obviously had 64-bit support, and mago followed suite in |
| 54 | +2014 including support for the PDB debug info format.) |
29 | 55 |
|
30 | | -$(IMG_CENTER images/prop_debug.png) |
| 56 | +$(H2 VS 2012-2013 New debug engine) |
| 57 | + |
| 58 | +$(P Starting with Visual Studio 2012, Microsoft introduced a new debugger that replaced |
| 59 | +the native debug engine. Unfortunately, it lost some of the capabilities of the |
| 60 | +preceding debug engine. This includes displaying variables in the Watch Window and |
| 61 | +interpretation of the visualizer macros in autoexp.dat. The new engine has |
| 62 | +extended visualizer capabilities, but these are targeted to C/C++ and don't work with |
| 63 | +D syntax.) |
| 64 | + |
| 65 | +$(P You can switch back to the old debug engine by going to Tools->Options and then under the debugger |
| 66 | +settings, turn on native edit and continue. This is a global setting and will also affect your |
| 67 | +C++ projects, though.) |
| 68 | + |
| 69 | +$(P Mago is uneffected by this change. |
| 70 | +The VS 2013 debugger engine fixed some of the problems with displaying local variables.) |
| 71 | + |
| 72 | +$(H2 VS 2015 Concord extensions) |
31 | 73 |
|
32 | | -$(P Please note that Mago is under development and might lack a few features that you find in the native debugger.) |
| 74 | +$(P With the next version of the debug engine supporting "native edit and continue", the fallback to |
| 75 | +the old debug engine no longer works in VS 2015. Instead Microsoft |
| 76 | +released information about the extensibility of this debug engine (introduced with VS2012) called |
| 77 | +$(LINK2 https://github.com/Microsoft/ConcordExtensibilitySamples/wiki/Overview, Concord), |
| 78 | +late in 2015. It consists of more modular components than older engines. This allows taking |
| 79 | +advantage of most features of the debug engine, but just replace language specific |
| 80 | +parts, i.e. the expression evaluator. In addition, debugging mixed languages is no problem |
| 81 | +anymore.) |
| 82 | + |
| 83 | +$(P Taking the expression evaluator out of Mago allowed to implement this for D pretty easily:) |
| 84 | + |
| 85 | + <div align="center"><img src="images/concord_mark.png" width="90%"/></div> |
| 86 | + |
| 87 | +$(P The debugger engine needs to detect the source language of the code location. This information |
| 88 | +is added to the debug information starting with dmd 2.072 when compiled for COFF object |
| 89 | +files (-m64 or -m32mscoff) with -g, but not with |
| 90 | +-gc, i.e. you should select debug info for Mago even when using the VS debug engine.) |
| 91 | + |
| 92 | +<a id="recommendation"></a> |
| 93 | +$(H3 Recommendation for VS 2015) |
| 94 | + |
| 95 | +$(UL |
| 96 | + $(LI use DMD 2.072 or later) |
| 97 | + $(LI for Visual D projects, compile to COFF even for Win32 by enabling "Use MS-COFF object file format" on the |
| 98 | + project configuration page Compiler->Output) |
| 99 | + $(LI select symbolic debug information "suitable for Mago" on the |
| 100 | + project configuration page Compiler->Debug) |
| 101 | + $(LI choose the Visual Studio debugger on the project configuration page Debugging) |
| 102 | +) |
| 103 | + |
| 104 | +$(P If you are using the new Visual C/C++ project integration, all you have to do is select debug information |
| 105 | +"for D debug engines" on the project configuration page "D Compiler->Code generation".) |
| 106 | + |
| 107 | +$(H2 Exceptions) |
| 108 | + |
| 109 | +$(P As of version 0.3.21, the installer adds an entry "D Exception" to the list of Win32 exceptions that |
| 110 | +can be found in the Debug->Exceptions dialog. This allows the debugger to stop execution when an exception |
| 111 | +is thrown by the debuggee. With earlier versions, you'll have to add an entry with code 0xE0440001 yourself.) |
33 | 112 |
|
34 | 113 | $(H3 Exceptions with Mago) |
35 | 114 |
|
36 | | -$(P Mago displays exceptions thrown by the debuggee in the output window. You can also stop execution |
37 | | -by enabling the respective box in the Debug->Exception dialog. Due to a bug, you currently cannot |
38 | | -simply enable the "D Exceptions" entry, but must select the specific exceptions while keeping the |
| 115 | +$(P Mago displays exceptions thrown by the debuggee in the output window. You can also stop execution |
| 116 | +by enabling the respective box in the Debug->Exception dialog. Due to a bug, you currently cannot |
| 117 | +simply enable the "D Exceptions" entry, but must select the specific exceptions while keeping the |
39 | 118 | "D Exceptions" entry unchecked. So, the dialog should look something like this:) |
40 | 119 |
|
41 | 120 | $(IMG_CENTER images/d_exceptions.png) |
42 | 121 |
|
43 | | -$(H2 Visual Studio 2012) |
44 | | - |
45 | | -Visual Studio 2012 introduced a new debug engine that loses some of the capabilities of the |
46 | | -preceding debug engine. This includes displaying variables in the Watch Window. You |
47 | | -can switch back to the old debug engine by going to Tools->Options and then under the debugger |
48 | | -settings, turn on native edit and continue. This will also reenable the visualizer macros in autoexp.dat. |
49 | | - |
50 | 122 | Macros: |
51 | 123 | TITLE=Debugging |
0 commit comments