Debugging the mods

Enabling debug mode compilation

In the mod source file header, add or update the line starting with // @compilerOptions, by specifying the following 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

Installing a debugger and required extensions

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, because Windhawk internally uses mingw target, and Microsoft Visual Studio does not support the symbol format compiled for mingw. So this instruction currently applies to using 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.

After installing VS Code, install also the following VS Code extensions:

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

Setting up debugging configuration in VS Code

You do not need to manually open the Windhawk mods source folder or files there in order to debug your mod. VS Code will find and open your mod source file automatically once you break into your code.

When you first start debugging, choose CodeLLDB as a debugger. VS Code will create a launch.json for you. You will 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 VS Code.

It seems that launching the processes via VS Code might conflict with some other software in some machines and might not work (nothing happens when you start debugging). As an alternative, attaching to a running process seems to work regardless. The instruction for attaching to a running process is below.

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" option
4. In the newly added configuration block, update the "program" or "pid" field accordingly
5. Also update the "name" field of that configuration block, so that each configuration block has a different name
6. Start debugger and select the desired configuration block name

If the mod you are developing has a bug and crashes your process before you manage to attach, then attach debugger first and then enable the mod in Windhawk only after that. Then the debugger will break into the offending line in your code.

Other debugging tips

In order to conveniently break into the debugger at a suitable code line in your mod, you can use a Windows API breakpoint function.

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.