Endless Parentheses

Concise ramblings on Emacs productivity.

Debug your Emacs init file with the Bug-Hunter

“With great power comes great responsibility,” and Emacs is a prime example of that. The versatility of having an editor that’s a lisp interpreter is truly empowering, but it can also backfire on you in the most unexpected ways. If you’ve ever ran into a foggy incompatibility issue between two unrelated packages, that manifested itself by turning on your mother’s coffee machine every other weekday, then you know how difficult this can be to track down.

One recurring theme on Emacs.StackExchange is that users will come to us with some random arcane issue, and either provide no more information or dump their init file on the question. The best answer we can give in these cases is for them to bisect their init file. But if that’s always the case, why not automate it?

The Bug Hunter is an Emacs library that does that for you.

Hunting real errors

If there’s an error being thrown during initialization, all it takes is a single command.

M-x bug-hunter-init-file RET RET

The Bug-Hunter will do a bisection search in your init file for the source of the error. Thanks to the magic powers of bisection, it is surprisingly fast even on huge init files.

Hunting unexpected behaviour

If no actual error is being thrown, but some behaviour is still clearly wrong, then it’s a little more tricky: you need to come up with an assertion. That is, you need a snippet of Emacs-Lisp code that will return t if something is wrong and nil if all is fine.

For instance, I wanted to figure out why the cl library was being loaded even though I didn’t explicitly require it anywhere. In this case, the snippet (featurep 'cl) gives me what I need. It returns nil before the library is loaded, and returns t afterwards.

M-x bug-hunter-init-file RET (featurep 'cl) RET


Interactive debugging

Unfortunately this is not supported yet. Communicating with a background Emacs process that is not in batch mode is complicated.

Usually, though, you shouldn’t need it. There’s almost always a snippet that will work for your needs. If your problem is not triggering an error, and you don’t know enough Elisp to write an assertion, let me know about your problem and maybe I can write one for you.

Even better, shoot us a question over at Emacs.StackExchange. We’re always glad to help.

Tags: package, debugging, emacs

Say thanks on Gratipay
comments powered by Disqus