Debugging the mods
In the mod source file metadata section, add or update the line starting with // @compilerOptions, by specifying the following flags:
--optimize=0 --debug
A couple of example metadata line variations with these flags added:
// @compilerOptions --optimize=0 --debug
// @compilerOptions -lshlwapi -lcomctl32 --optimize=0 --debug
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:
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.
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.
- Open launch.json
- Click on bottom right "Add configuration...". A popup menu will open in the middle of configuration file
- Choose "CodeLLDB: Attach by Name" or "CodeLLDB: Attach to PID" option
- In the newly added configuration block, update the "program" or "pid" field accordingly
- Also update the "name" field of that configuration block, so that each configuration block has a different name
- 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.
In order to conveniently break into the debugger at a suitable code line in your mod, you can use a Windows API's DebugBreak() function. VS Code will find and open your mod source file automatically when there is an exception or DebugBreak() API call in the code.
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.
If your mod happens to create its own thread, then you can pause the program in the debugger. After pausing, your thread is visible in the VS Code threads list and when clicking on that thread, you can navigate its call stack. Once you click on a function that belongs to your mod, the source code opens automatically.
In case your code does not cause the debugger to break automatically, then you need to open the mod's source file manually and set the breakpoints from VS Code UI.