Debugging Magik with Emacs GUD Through a Custom Wrapper

Magik programmers who have spent years inside GNU Emacs often hit the same wall: the editor handles editing beautifully, but stepping through running Smallworld code has traditionally meant leaving the keyboard comfort zone and switching to a separate session window. The Grand Unified Debugger inside Emacs is one of the most under-used parts of the editor, and a small custom wrapper can turn it into a first-class Magik debugger.

Smallworld's Magik powers utility network mapping for water, gas, and electricity across Australia. From Brisbane's sprawling stormwater catchments to the gas distribution grids of Adelaide and Perth, GIS teams routinely debug methods that walk through millions of collection records. Doing that work from inside Emacs removes one of the small frictions that compound over a long shift at the screen.

This piece walks through building a wrapper that lets Emacs' GUD speak to a Magik image. The wrapper is a thin command-line shim that translates GUD's gdb-mi commands into Magik break and step calls, then echoes state back through a pipe. Once in place, breakpoints, stack navigation, and object inspection feel native to the editor.

The rest focuses on practical mechanics: configuring the wrapper, sending it arguments from a Magik image running in another timezone, and parsing frames so the gud- buffer shows meaningful names rather than internal Magik handles.

Why GUD Suits a Magik Workflow

GUD, or the Grand Unified Debugger, was designed so that Emacs could drive several external debuggers through a common interface. It already knows how to set breakpoints at a file location, request the call stack, evaluate expressions in the current frame, and resume execution. The protocol it speaks is mostly the gdb Machine Interface, a line-oriented text stream that survives telnet and ssh tunnels without trouble.

For Magik, the same primitives map almost one-to-one. _break, _step, and _continue exist as debugger primitives in the Magik image, and they produce textual output that can be parsed back into frames. Because the language is interpreted rather than compiled, the source line referenced in a frame is always meaningful, which makes source buffer highlighting reliable.

The other benefit is that GUD respects the existing window layout. Working from a Sydney home office or a hot-desk in Melbourne's Docklands, developers can keep their Magik process on one screen and breakpoints, locals, and watch expressions in Emacs frames on the other, instead of juggling two windows of the standalone debugger.

Anatomy of the Custom Wrapper

The wrapper can be as simple as a few hundred lines of Python or a shell script paired with expect. It needs to do four jobs: launch the Magik image with debugging flags, expose a socket or pseudo-tty GUD can attach to, translate incoming commands, and reply with frames in a format GUD recognises.

Most shops reach for Python because the standard library ships with pexpect, which handles ANSI escape stripping and timing without compiled extensions. On a Linux laptop running Manjaro or Pop!_OS, installing it is a single pip invocation. On Windows, where some Magik install bases still live, pexpect is replaced by wexpect, which behaves identically. The starting point for most teams is the development tools package, which includes a template wrapper and a sample local file for the dirs variable.

The script reads input one line at a time. Each line is a GUD command such as break magik_module.magik:142 or info locals. The wrapper maps these onto Magik-side handlers that talk to the running image over an open socket. Output is the part that needs the most care: GUD's parser is forgiving but not infinitely so. Numeric thread identifiers, source paths, and frame descriptions each have to be on their own line and prefixed in a way Emacs recognises.

Talking to the Magik Image

Inside the Magik image itself, the wrapper relies on a tiny server written in Magik. This server binds to a localhost port and listens for line-based commands from the Python shim. When it receives break, it forwards a _break request to the debuggee; when it receives step, it tells Magik to execute the next line. Frame data comes back as a multi-line block whose first line is the frame number, second the method name, and third the source coordinates.

Setting this up on a remote Smallworld database server deserves a moment of thought. Australian GIS teams often have the Magik image running on a Solaris or AIX box in a data centre in Sydney or Canberra, with the developer SSHing in from anywhere. Running the wrapper on the laptop and pointing it at the remote port through an SSH tunnel works, but the wrapper must use the local port that the tunnel exposes, not the server's loopback.

Wiring this up involves two pieces of local-file configuration. The first tells Emacs which program to call when M-x gud-go is invoked; the second tells the wrapper which remote image to attach to. Once done, gud-go launches the wrapper as a subprocess, and the subprocess talks to the Magik image out of band. A typical dirs request returns paths that Emacs resolves against the local source tree checked out under ~/src/magik.

Comparing the Approaches

Different organisations settle on different shapes for the wrapper, depending on their OS mix and on what they need from the debugger. The configurations below cover the common options, including a pure-local setup on a single workstation and a full remote configuration that survives an overnight run on a rural Queensland database.

Approach	Latency	Setup effort	Works through ssh	Object inspection quality
gdb directly without a wrapper	Highest	None	Yes	Poor, raw handles
Shell plus expect wrapper	Low	Medium	Yes	Limited
Python plus pexpect wrapper	Low	Medium	Yes	Good
Native Emacs mode	Negligible	High	No, local only	Excellent

The Python wrapper hits the practical sweet spot for most Australian Magik shops. It survives network blips, handles the ANSI quirks of Magik's terminal output, and gives enough structured response to populate the locals buffer properly. Pure-Emacs-native debuggers are slightly faster but require a Magik image compiled in a non-standard way, and most production images do not allow that.

Integrating with Thucydides Webtests

Many Smallworld shops in Australia use a web testing harness built around Thucydides for their browser-based GIS portals. When a step in a Thucydides scenario triggers a server-side Magik method, failures usually surface as a stack trace in the test runner rather than the Magik debugger. Bridging the two is straightforward once the GUD wrapper is in place, because the harness can be configured to drop into the wrapper the moment an exception is thrown.

To wire this up, the test runner is configured with a hook that captures the Magik process ID of the failing invocation. The hook then writes a small script that launches the wrapper, attached to that PID, and emits a where command. Useful hooks for Thucydides webtests ship with most modern Smallworld installations and expose the PID through an environment variable rather than a config file. The wrapper runs, frames come back, and the test report embeds them as if captured by a normal debugger.

Test reports in this style become dramatically easier to triage. Instead of staring at a Java stack trace from a Selenium container somewhere near the Nullarbor, the developer can copy the Magik frames straight into their local Emacs and resume navigation. Teams that have adopted this approach in Brisbane and Canberra report faster turnaround on intermittent test failures, because the same wrapper handles local development runs and CI-attached runs identically.

Inspecting Collections and Object State

One of the advantages of a working GUD bridge is that locals and watch expressions become available in the gud- buffer. A Magik collection such as a rope or dynamic_chain_set shows up under info locals as a sequence of lines describing length, the backing storage, and a small preview of the first few items. The wrapper can be taught to flatten that into something readable, hiding internal class pointers behind their user-facing names.

Object inspection is where most debugging time is spent in Magik, because collections in a Smallworld database can hold millions of geometry records. The wrapper supports a limited form of printing through Magik's show() and print_on() methods. By overriding print_on on a domain class — something every Australian utility GIS team has done for their pipe or pole networks — the wrapper generates readable output without extra metadata.

A useful trick is teaching the wrapper to recognise plugin classes from Spatial Workplace, the Smallworld add-on widely used by electricity utilities. By registering a printer for sw_device!pole!bundle, the locals buffer shows the pole identifier, the attached conductors, and the upstream switch gear, all within the same frame. That alone retires the standalone MagikInspector tool in many shops.

Troubleshooting Common Hurdles

A few patterns show up repeatedly when teams first deploy the wrapper. The first is path translation: GUD sends source paths the Magik image knows about, but Emacs resolves them against local checkouts. The fix is a small remapping table keyed on the project's module name.

The second is character encoding. Magik pads textual frames with whitespace, and some terminals interpret that as a control sequence. The wrapper must read raw mode from the pseudo-tty, with stty raw -echo set on Linux servers or the equivalent on AIX, and ignore carriage returns that look like flow control.

Finally, breakpoint persistence between sessions confuses new users. GUD asks the wrapper to set a breakpoint at file and line, and the wrapper forwards a _break to Magik. When the Magik image restarts for a build or a database reload — common overnight during scheduled Australian billing cycles — those breakpoints vanish. Saving them to a .gud-breakpoints file and reapplying them on M-x gud-go solves the problem cleanly.

For teams ready to move from theory to a working configuration, the next step is to fork a starter wrapper, customise the path remapping for local module names, and pair it with a CI hook that captures frames on every Thucydides webtests failure. The time from a clean checkout to a working debug session is usually under an hour, and once wired up the rest of the team rarely goes back to the standalone Magik debugger.