The StumpWM Debugger

Usage

This minor mode enables the CLIM debugger for StumpWM (herafter referred to as the SWM Debugger or SDB). When invoked, SDB will open a static window on top of all other windows with a list of restarts and a backtrace. SDB can be enabled by running the command SDB-MODE, at which point any call to invoke-debugger will invoke SDB.

Window Configuration

SDB is intended to be useful regardless of the state of StumpWM. To achieve this even when StumpWM is incapable of mapping, focusing, or otherwise managing windows SDB is created as a static unmanaged window by setting override-redirect on the window. The window will resize and move itself based upon user settable values when it is opened.

Errata and Footguns

• The debugger is not enabled by default in StumpWM, causing any call to INVOKE-DEBUGGER to exit the process. To fix this SB-DEBUG::ENABLE-DEBUGGER must be called before calling INVOKE-DEBUGGER. The default enable and disable hooks for SWM-DEBUGGER-MODE enable and disable the debugger respectively. If explicitly invoking SDB via INVOKE-DEBUGGER then it is the users responsibility to call SB-DEBUG::ENABLE-DEBUGGER. This is done automatically within the WITH-SDB macro. Additionally, StumpWM does not invoke the debugger on unhandled top level conditions unless STUMPWM:*TOP-LEVEL-ERROR-ACTION* is set to :BREAK.
• The function BREAK is required by the specification to bind *DEBUGGER-HOOK* to NIL, eliding the invocation of SDB. This prevents the user from investigating the program via setting *BREAK-ON-SIGNALS*. To enter SDB using *BREAK-ON-SIGNALS*, ensure that *APPROPRIATE-DEBUGGER-HOOK* is set to (QUOTE SB-EXT:*INVOKE-DEBUGGER-HOOK*). The default value of *APPROPRIATE-DEBUGGER-HOOK* is (QUOTE SB-EXT:*INVOKE-DEBUGGER-HOOK*).
• The variable *APPROPRIATE-DEBUGGER-HOOK* should not be modified while SDB mode is enabled.
• When invoked from the generic function HANDLE-TOP-LEVEL-CONDITION a restart called ABORT-DEBUGGING will be present. This will throw to the top level and will likely crash StumpWM.
• This system depends upon the CLIM debuger. (Mc)CLIM is a large system which can take quite a while to compile and load. If you find yourself using SDB often or wish to have it always available it may be useful to add #:SWM-DEBUGGER-MODE as a dependency to StumpWM and recompile. This will dump an image that contains CLIM.
• Bindings defined in *SWM-DEBUGGER-MODE-ROOT-MAP* are active while SDB mode is active, but because the keyboard is grabbed when SDB is invoked they are not active there. To define keybindings that are active in the SDB window use the CLIM keybinding facilities.
• To quit a command, CLIM uses C-c, while StumpWM uses C-g.

Example Configuration

This will set up SDB to catch any unhandled serious conditions, and will make it roughly fullscreen on 1920x1080 monitors.

(load "path/to/swm-debugger-mode.asd")
(asdf:load-system :swm-debugger-mode)

(defun enable-break-on-errors (&rest rest)
  (declare (ignore rest))
  (setf *top-level-error-action* :break))

(defun disable-break-on-errors (&rest rest)
  (declare (ignore rest))
  (setf *top-level-error-action* :abort))

(add-hook swm-debugger-mode:*swm-debugger-mode-enable-hook*
          #'enable-break-on-errors)
(add-hook swm-debugger-mode:*swm-debugger-mode-disable-hook*
          #'disable-break-on-errors)

(setf swm-debugger-mode:*debugger-width* 1900
      swm-debugger-mode:*debugger-height* 1000
      swm-debugger-mode:*debugger-coordinates* (cons 10 40)
      swm-debugger-mode:*font-size* :large
      swm-debugger-mode:*position-display*
      'swm-debugger-mode:display-position-as-line
      swm-debugger-mode:*snippet-display*
      'swm-debugger-mode:display-snippet-lines-around)

(swm-debugger-mode:sdb-mode)

Wish List

The following list (in no particular order) contains things that would be nice to have implemented. If you implement something on this list, please modify the this file to either remove the item from the list or briefly note what further work needs to be done on it.

• Implement resuming from a stack frame
• Implement returning a value from a stack frame
• Make forms and their evaluated results inspectable
• Check if the file to write a backtrace to exists and if so, ask the user whether to overwrite, append, or abort writing the backtrace.

Documentation

Keybindings

In SDB there are several keybindings, mostly inherited from the CLIM debugger. These are as follows:

keybinding	action	command name
q	Quit debugger	com-quit
M-p	Previous stack frame	com-prev
M-n	Next stack frame	com-next
m	Display more stack frames	com-more
e	Eval in frame	com-eval
TAB	Toggle stack frame view	com-toggle-active-frame-view
r	Refresh	com-refresh
C-i	Toggle interactor	com-toggle-interactor
M-l	Toggle display source location	com-show-locations
M-b	Print backtrace	com-print-backtrace
C-[1-9]	Invoke restart N	invoke-restart-n

API

Minor Mode

Variable *SWM-DEBUGGER-MODE-ENABLE-HOOK*

A hook run when SDB mode is activated. Defaults to (#'install-dbg)

Variable *SWM-DEBUGGER-MODE-DISABLE-HOOK*

A hook run when SDB mode is deactivated. Defaults to (#'uninstall-dbg)

Variable *SWM-DEBUGGER-MODE-ROOT-MAP*

A root map active when SDB mode is active

Variable *SWM-DEBUGGER-MODE-TOP-MAP*

A top map active when SDB mode is active

Variable *SWM-DEBUGER-MODE-CONTROL-I-MAP*

A keymap hanging on C-i from *SWM-DEBUGGER-MODE-ROOT-MAP*.

Command SDB-MODE

Enable SDB by setting the debugger hook to invoke SDB instead of the standard debugger.

Debugger Window Control

Variable *DEBUGGER-WIDTH*

Controls the width of the debugger window, defaults to 480.

Variable *DEBUGGER-HEIGHT*

Controls the height of the debugger window, defaults to 600.

Variable *DEBUGGER-COORDINATES*

Control the X and Y coordinates of the debugger window, defaults to (10 . 10).

Debugger Invocation

Macro WITH-SDB

(with-sdb condition-type &body body)

Establish a handler around body which will invoke SDB on any signals of condition-type.

Function INVOKE-SDB

(invoke-sdb condition)

Explicitly invoke SDB on condition.

Variable *APPROPRIATE-DEBUGGER-HOOK*

The debugger hook used by SDB. This variable should be set before enabling SDB mode and should not be changed while SDB mode is active.

Debugger Display

Variable *BACKTRACE-RIGHT-MARGIN*

The right margin the debugger should respect when printing the backtrace to a file. Defaults to 100.

Variable *FONT-SIZE*

The font size to use. May be any valid CLIM font size specifier, e.g. :large, or an integer point size.

Variable *POSITION-DISPLAY*

A function to call when displaying source position information for a stack frame. Defaults to NIL.

Variable *SNIPPET-DISPLAY*

A function to call when displaying source snippet information for a stack frame. Defaults to NIL.

Variable *SNIPPET-LINES*

The number of lines of a snippet to display when displaying source information for a stack frame. Defaults to 5.

Function DISPLAY-POSITION-AS-LINE

A function to display the position as a line number. Set *POSITION-DISPLAY* to this function to use.

Function DISPLAY-SNIPPET-LINES-AROUND

A function to display the lines around the snippet instead of just the snippet as reported by swank. Set *SNIPPET-DISPLAY* to this function to use.

Debugger Interaction

Variable *DEFAULT-EVAL-PACKAGE*

The default package to read and evaluate forms in if swank cannot find a suitable package for a given stack frame.