Debugging the mods

Enabling debug mode compilation

In the mod source file header, add or update the line starting with @compilerOptions, by specifying the flags --optimize=0 --debug.

A couple of example source code lines with these flags added:
// @compilerOptions --optimize=0 --debug
or
// @compilerOptions -lshlwapi -lcomctl32 --optimize=0 --debug

Setting up a debugger

Install Visual Studio Code. Despite a confusingly similar name, this is a totally different program than Microsoft Visual Studio. The latter would need a more involved setup to enable mods' debugging, so this instruction applies to Visual Studio Code. With the setup described below, Visual Studio Code is compatible with Windhawk mods - it nicely shows the source code, the variables, is able to set breakpoints and to step through the code.

Then install the following VS Code extensions:

• C/C++ for Visual Studio Code
• CodeLLDB

Setting up debugging configuration in Visual Studio Code

You do not need to manually open the Windhawk mods source folder or files there in order to debug your mod.

When you first start debugging, choose CodeLLDB as a debugger. Visual Studio Code will create a launch.json for you. You need to edit it slightly.

Launching a program when starting debugging

The launch.json looks like following when Notepad is set as an example debug target:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug",
            "program": "C:\\Windows\\System32\\notepad.exe",
            "args": [],
            "cwd": "${workspaceFolder}"
        }
    ]
}

The above configuration launches Notepad when you start debugging in Visual Studio Code.

It seems that launching the processes via VS Code might conflict with some other software in some machines and might not work. Attaching to a running process seems to work regardless. The instruction for attaching to a running process is below. If needed, then attach debugger first and then enable the mod only after that.

Attaching to a running process

1. Open launch.json
2. Click on bottom right "Add configuration...". A popup menu will open in the middle of configuration file.
3. Choose "CodeLLDB: Attach by Name" or "CodeLLDB: Attach to PID" options
4. In the newly added configuration block, update the "program" or "pid" field accordingly
5. Start debugger

Other debugging tips

If you want the mod code to trigger a breakpoint, then you can use the following code

if (IsDebuggerPresent())
        DebugBreak();

IsDebuggerPresent() check is needed, else the program will crash without a debugger attached.