Raised This Month: $23 Target: $400
 5% 

SourcePawn Console Debugger


Post New Thread Reply   
 
Thread Tools Display Modes
Author Message
Peace-Maker
SourceMod Plugin Approver
Join Date: Aug 2008
Location: Germany
Old 01-19-2025 , 11:11   SourcePawn Console Debugger
Reply With Quote #1

SourcePawn Console Debugger

This extension allows you to set breakpoints in your SourcePawn plugins, step through them, and inspect the variables in scope as well as manipulate their values. It exposes a console debugger within a local "shell" to debug SourceMod plugins, similar to gdb or cdb. The interface is based on pawndbg, the Pawn debugger, by ITB CompuPhase.

The extension adds a new "debug" option to the "sm" root menu which allows you to start a debugging session on a selected plugin:

Code:
sm debug
SourceMod Debug Menu:
    start            - Start debugging a plugin
    next             - Start debugging the plugin which is loaded next
    bp               - Handle breakpoints in a plugin

sm debug start
[SM] Usage: sm debug start <#|file>

sm debug bp
[SM] Usage: sm debug bp <#|file> <option>
    list             - List breakpoints
    add              - Add a breakpoint
    remove           - Remove a breakpoint

sm debug bp plugin add
[SM] Usage: sm debug bp <#|file> add <file:line | file:function>
The debugger works on source-code level (not on bytecode instruction level) and allows you to step through the lines in your source code and inspect variables by their name instead of using registers and adresses.

Since SourceMod is event based, the plugin might not execute code right away after you start debugging it. Depending on how you started debugging, you have to trigger the right code path through some event in order to start debugging. You can use "sm debug next" if you need to debug the plugin startup code which would otherwise already have run.

The debugger only works on a local server and not through a RCon connection. The whole process is paused while inside the debugger shell, so players might timeout if you take too long . The watchdogs are disabled while you're in the debugger though.

Using the debugger shell

Once a breakpoint is reached or the next instruction is executed, you're presented with a "dbg>" prompt to issue debugger commands. Type "?" or "help" to see available commands and "help command" to get more details on a specific command.

Code:
At the prompt, you can type debug commands. For example, the word "step" is a
command to execute a single line in the source code. The commands that you will
use most frequently may be abbreviated to a single letter: instead of the full
word "step", you can also type the letter "s" followed by the enter key.

Available commands:
        backtrace       display the stack trace
        break   set breakpoint at line number or function name
        cbreak  remove breakpoint
        cwatch  remove a "watchpoint"
        continue        run program (until breakpoint)
        files   list all files that this program is composed off
        frame   select a frame from the back trace to operate on
        funcs   display functions
        next    run until next line, step over functions
        position        show current file and line
        print   display the value of a variable, list variables
        quit    exit debugger
        set     set a variable to a value
        step    single step, step into functions
        x       eXamine plugin memory: x/FMT ADDRESS
        watch   set a "watchpoint" on a variable

        Use "? <command name>" to view more information on a command
The command names and interfaces are not final and feedback is welcome.

Example debug session
We start debugging the currently running "basechat" plugin on the next instruciton, run a command it registers and change a variable's value.
Code:
sm debug start basechat
[SM] Pausing plugin Basic Chat for debugging. Will halt on next instruction.
sm_say lol
STOP at line 156 in basechat.sp in Command_SmSay        frame: 1
dbg> n
STOP at line 158 in basechat.sp in Command_SmSay        frame: 1
dbg>
STOP at line 164 in basechat.sp in Command_SmSay        frame: 1
dbg>
STOP at line 165 in basechat.sp in Command_SmSay        frame: 1
dbg>
STOP at line 167 in basechat.sp in Command_SmSay        frame: 1
dbg> print
loc     <  0x5454>      char text[192]  "lol"
arg     <  0x5468>      int args        1
arg     <  0x5464>      int client      0
dbg> set text="hello"
text set to "hello"
dbg> continue
L 01/19/2025 - 15:25:38: [basechat.smx] "Console<0><Console><Console>" triggered sm_say (text hello)
sm debug bp basechat add 167
[SM] Added breakpoint in file basechat.sp on line 167
sm_say lol
BREAK at line 167 in basechat.sp in Command_SmSay       frame: 1
dbg> quit
Clearing all breakpoints. Running normally.
L 01/19/2025 - 15:26:13: [basechat.smx] "Console<0><Console><Console>" triggered sm_say (text lol)
sm_say lol
L 01/19/2025 - 15:26:29: [basechat.smx] "Console<0><Console><Console>" triggered sm_say (text lol)
Installation
Most of the required support in the SourcePawn Virtual Machine was added and merged over the years, which allows to step through plugins and map source line numbers to addresses. The last part, inspecting program state and variables, is not finalized yet and thus not merged in the upstream SourcePawn repository. This extension requires a modified SourcePawn VM to work until the API is stable enough to be merged. The provided package includes such a VM build for your convenience.
  1. Download the build artifact for your Platform from Github. The one attached to this post might be outdated.
  2. Extract it on your server
  3. Restart your server
  4. The "sm debug" root menu entry should be available

https://github.com/peace-maker/sp-console-debugger/
Garey implemented a debugger adapter for Visual Studio Code based on this work. That might work for you too.
__________________
Peace-Maker is offline
Reply


Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump


All times are GMT -4. The time now is 05:21.


Powered by vBulletin®
Copyright ©2000 - 2025, vBulletin Solutions, Inc.
Theme made by Freecode