Single-Stepping a Plugin in gdb

The first step is to compile your plugin with symbols retained and optimization turned off. For plugin distributions using configure, it should work to type

configure "CFLAGS=-g -O0 -DDEBUG"

(Note that `-O0' is a hyphen followed by the letter 'O', followed by the number zero.) This works for the example programs such as trivial_synth.c in the DSSI example code repository. By default, ghostess is compiled with -g -O2, which is fine for the host.⁷

In order for your host program to find your plugin in the current working directory where it is compiled, the DSSI_PATH environment variable needs to be set up containing that directory first in the search path. Since I use tcsh as my shell, my ~/.tcshrc file contains the line

setenv MODULENAME "${HOME}/projects/dssi/modulename"
setenv DSSI_PATH \
       "${MODULENAME}:/usr/local/lib/dssi:/usr/lib/dssi"

Users of the bash shell may add something like the following in their ~/.bashrc file:

MODULENAME="${HOME}/projects/dssi/modulename"
DSSI_PATH="${MODULENAME}:/usr/local/lib/dssi:/usr/lib/dssi"
export MODULENAME DSSI_PATH

Note that ghostess requires all DSSI_PATH elements to begin with /, so you must provide a full absolute path to your working directory. Of course, if you have root privileges on your computer, you can simply type make install each time you change your plugin, and the host program will find your .so file in /usr/local/lib/dssi by following the default DSSI search path.

The debugging cycle tends to go like this:

• Say make to compile your module.
• If you are using the default DSSI search path, type, in another window (as root), make install.⁸
• Start gdb on ghostess in the usual way:

  M-x gdb <Enter>
  gdb ghostess -debug -1 modulename.so <Enter>
  

• Use the dir command to provide paths to any source files not in the current working directory (typically the ghostess source directory).
• Set a breakpoint somewhere in your module, such as at its instantiate, activate, or run function. Since the module is not loaded yet, emacs will ask you if you want a pending breakpoint as follows:

  Function "modulename" not defined.
  Make breakpoint pending on future shared library load?
  

  Type y and the breakpoint will be installed when the module is loaded.
• run ghostess under gdb.
• Click on the UI button in the small main window for ghostess. This opens a simple editor window for your plugin that was automatically generated by ghostess based on its port declarations.
• Click on the Test Note button in the plugin editor window. This issues the equivalent of a MIDI note-on for your plugin.
• Find and fix all bugs in your plugin!

To streamline the startup, I use a .gdbinit file like the following:

echo dir /l/dssi/ghostess-20050916/src/ \n
     dir /l/dssi/ghostess-20050916/src/
echo set args -debug -1 ./modulename.so \n
     set args -debug -1 ./modulename.so

(I maintain a large set of convenient symbolic links in the directory /l on my system.) I also have a symbolic link g -> /l/u/dssi/.../src/ghostess in the module source directory, so in emacs I can simply say

M-x gdb <Enter>
gdb g <Enter>

to get started.