Custom initialization scripts

Sometimes it is necessary to run some commands just after debugger has been started. WinGDB supports such case through custom initialization scripts. User can provide path to script in dialog Launch Process, Attach Process or Examine Core Dump in field 'Custom initialization script'.

Syntax of script is simple. Single line may contain only one gdb command or comment, eventually it is empty. Line is treated as comment if it begins with two slashes (//) or hash (#). Blank characters at the beginning of line are ignored. There is no limit for number of lines.

Sample of script (there are two empty lines intentionally):

// this is comment
help monitor // first command

# this is comment too
    help target #second command with precedent blanks
       //this is yet another comment with blanks at the beginning of line
   handle SIG32 nostop //change signal SIG32 setting
info signals    // dump signals

#and the last comment

Output generated by script is redirected into VisualStudio console (pane "Debug").

CAUTION!
All commands are allowed to run through custom initialization script, but please proceed with them carefully, because they may change the way GDB bahaves and introduce negative side-effects for WinGDB operations.

All breakpoints set through custom initialization script are not visible in Visual Studio environment, but GDB sees them and reacts as usually.

Currently WinGDB supports scripts which are located on local file system only. If there is need to run scripts which are located on remote machine, then please let us know about it. The same if you have any problems with custom initialization scripts.

Custom runtime scripts

In addition to initialization scripts, WinGDB supports execution of custom GDB scripts at arbitrary moments during debugging (however the debugger must be stopped). These scripts may be bound to menu commands for convenience. This way, you can use some extended features of GDB even though WinGDB does not support them directly. This can be especially useful on embedded systems.

Defining scripts

In order to define a custom script, open the User scripts submenu from WinGDB menu.

The first option opens the Custom script manager window, which allows you to define up to eight scripts and bind them to commands in the menu. Remaining options are corresponding commands which have been bound. After selecting the first option, the following dialog appears:

Click on one of the rows on the left side. You will be able to edit a script which is bound to that particular command. Enter the name of the command in User command name field and the contents of the script below. After clicking OK or Apply your script will be saved. You may edit an existing script as well.

Executing scripts

In order to execute as script, just select corresponding option from the User scripts menu. The debugging session must be active and the debugger must be stopped, otherwise the command will be disabled.

Limitations and warnings

The following limitations and warnings apply to custom scripts.

Scripts may be executed only when the debugger is stopped. With GDB, it is not possible to execute commands when the debugged program is running. Asynchronous modes described in GDB docs work only for specific target types (rare), hence WinGDB does not support this mode at all (due to limited usability).

Certain commands are not allowed in the scripts. Do not use any running commands (like run, continue, step), otherwise your session will hang. Avoid changing the state of breakpoints, Visual Studio will not see your changes.

Certain commands may change GDB state in unpredictable way, or even cause a GDB crash. WinGDB does not support such cases, that means you use the customs scripts on your own risk and you must exactly know what you're doing and how GDB commands work. This is a feature for advanced users only.

Currently WinGDB supports scripts which are available on local file system only.

Table of Contents