Debugging Features

Additional debugging features are supported via DBGp, a common debugger protocol for languages and debugger UI communication.

Debugger Engine

The debugger engine is enabled if AutoHotkey_L is built with CONFIG_DEBUGGER defined. This is done by default for the Debug and Release build configurations, but not SC (compiled scripts).

Use the /Debug switch when running the script to connect to a debugger client, enabling interactive debugging.

AutoHotkey.exe /Debug[=SERVER:PORT] ...

SERVER and PORT may be omitted. For example, the following are equivalent:

AutoHotkey /Debug "myscript.ahk"
AutoHotkey /Debug=localhost:9000 "myscript.ahk"

Debugger Clients

XDebugClient

XDebugClient is a simple open-source front-end DBGp client based on the .NET Framework 2.0. XDebugClient was originally designed for PHP with Xdebug, but a custom build compatible with AutoHotkey_L is available below.

Changes:

• Allow the debugger engine to report a language other than "php".
• Added AutoHotkey syntax highlighting.
• Automatically listen for a connection from the debugger engine, rather than waiting for the user to click Start Listening.
• Truncate property values at the first null-character, since AutoHotkey_L currently returns the entire variable contents and XDebugClient has no suitable interface for displaying binary content.

Download: Binary; Source Code (also see SharpDevelop, Dockpanel Suite and Advanced Treeview.)

Usage:

• Launch XDebugClient.
• Launch AutoHotkey_L /Debug. XDebugClient should automatically open the script file.
• Click the left margin to set at least one breakpoint.
• Choose Run from the Debug menu, or press F5.
• When execution hits a breakpoint, use the Debug menu or shortcut keys to step through or resume the script.

Features:

• Syntax highlighted, read-only view of the source code.
• Breakpoints.
• Run, Step Over/Into/Out.
• View the call stack.
• Inspect variables - select a variable name, right-click, Inspect.

Issues:

• The user interface does not respond to user input while the script is running.
• No mechanisms are provided to list variables or set their values.

Notepad++ DBGp Plugin

A DBGp client is available as a plugin for Notepad++. It is designed for PHP, but also works well with AutoHotkey_L.

Download: See Notepad++ at SourceForge.

Usage:

• Launch Notepad++.
• Configure the DBGp plugin via Plugins, DBGp, Config...

  Note: File Mapping must be configured. Most users will not be debugging remotely, and therefore may simply put a checkmark next to Bypass all mapping (local windows setup).

• Show the debugger pane via the toolbar or Plugins, DBGp, Debugger.
• Open the script file to be debugged.
• Set at least one breakpoint.
• Launch AutoHotkey_L /Debug.
• Use the debugger toolbar or shortcut keys to control the debugger.

Features:

• Syntax highlighting, if configured by the user.
• Breakpoints.
• Run, Step Over/Into/Out, Run to cursor, Stop.
• View local/global variables.
• Watch user-specified variables.
• View the call stack.
• Hover over a variable to view its contents.
• User-configurable shortcut keys - Settings, Shortcut Mapper..., Plugin commands.

Issues:

• Hovering over a single-letter variable name does not work - for instance, hovering over "a" will attempt to retrieve " a" or "a ".
• Hovering over text will attempt to retrieve a variable even if the text contains invalid characters.
• Notepad++ becomes unstable if property_get fails, which is particularly problematic in light of the above. As a workaround, AutoHotkey_L sends an empty property instead of an error code when a non-existent or invalid variable is requested.

Script-based Clients

A script-based DBGp library and two basic clients are available for development purposes:

• dbgp_console.ahk: Simple command-line client.
• dbgp_test.ahk: Demonstrates asynchronous debugging.

Command-line Client

A command-line client is available from xdebug.org, however this is not suitable for most users as it requires a decent understanding of DBGp (the protocol).

Others

A number of other DBGp clients are available, but have not been tested with AutoHotkey_L. For a list, see Xdebug: Documentation.