How to debug a DLL you've built, under the Visual Studio debugger

[GSH]

This is something that's already in the DLL source code readme for 1.3pbNext (i.e. post-pb4a), but since it should apply all the way back to people developing w/ Visual C++ 6.0 for BZ2 1.0. Just thought I'd share them, and I might revise the text for the readme based on comments.


a) Build a 'debug' build. Probably need to ensure that the output
    .dll filename is the same as the release build's output .dll
    filename. With the latest 1.3 source code distributions, debug
    builds should be linked against bzone.exe; if it's linked against
    battlezone.exe, then change this.

b) Put in breakpoints into your code. With default Visual C++
    keybindings, go to the line you want it to stop on, and hit F9 to
    drop a breakpoint. A red circle will appear left of the line

c) Right click on the project you want to debug, ensure it's set as
    the startup project

d) Right click on project you want to debug, select properties. Go to
    Config Properties -> Debugging. Set the command line to the full
    path to bzone.exe. (If you have BZ2 installed to multiple
    directories, then select the one that'll run the .dll you're
    building.) For the working directory entry, set it to the dir
    bzone.exe is in. As to the command arguments line
    (e.g. commandline params), for a MP dll, set the command line to
    "/win /host 0" (no quotes). If you're testing a SP/IA dll, you can
    use something like "/win mymap.bzn" . You should use /win unless
    you've got a multimonitor setup and put the debugger on the
    secondary monitor and let BZ2 take over the primary monitor. Leave
    the rest of the entries in this field at default.

e) Hit F5 (assuming default VC++ keyboard shortcuts) to start
    debugging.  Your breakpoints will turn to thin rings, because your
    DLL isn't loaded.  But, when you load the mission, they should
    turn back to solid circles.  If they never turn solid, then the
    DLL you built isn't loaded. Double check output dir, build
    configuration, etc

f) If they are solid, then when execution passes that line, it'll
    pause the game and drop you into in the debugger. You can examine
    variables in the locals/auto/watch window(s). Hit F10 to step one
    line, F11 to step into a function, F5 to resume full speed

   Note: when done, please be sure to switch back to the release build
type. A simple 'rebuild all' should help force that to happen.

[Nielk1]

OM has helped me with this some too.

It is a BIG help to do this. I set up VS to launch my DLL in the BZ2 editor after setting up a debug editor profile so i can mess with it as objects are added though the editor (the need of this is rather limited to my case were I am making addon classes instead of simple mission scripts).

When you do this, you can watch various variables and see exactly what values are in them when you break. You can step your code one line at a time and check all the values to ensure it works.

Glad someone who actually understands this well posted it. THANKS!

[Avatar]

I've always wondered how a Debug build would help while the game is running...  thanks!

I've also found a HUGE help is using 'consoleWord' to echo out various flags and values as the game progresses.  Whenever something isn't happening that should be I toss some "got here" lines in to let me know how the DLL is progressing.  Between that, "beaconOn", and fairly linear scripts I've managed to figure out every weird thing my scripts have done...

-Av-

[GSH]

Debug builds are meant to be convenient for the programmer when they want to debug it. This means that doing extra work so that the debugger can always figure out what all of the local (and derived, such as the 'this' pointer) variables are. That way, you can always inspect (and modify) variables on the fly.

Release builds are built for speed. Getting to local variables is iffy, at best, because the compiler can decide to just cache some in registers, or figure out that they're just redundant. Don't expect to easily debug it. Basically, if you've got the source, you should be able switch over to a debug build, run it, and fix that. As debug builds of BZ2 are currently running at 200+fps on my machine at home, I can't imagine a debug DLL w/ release bzone.exe being noticeably slower unless you've got really pathological code.

-- GSH