Testing elisp & packages in Doom's sandbox

“The sandbox” is a feature of Doom Emacs. It is a test bed for running elisp in a fresh instance of Emacs with varying amounts of Doom loaded (none at all, all of it, or somewhere in between). This can help you isolate bugs and determine who they should be reported to.

If a bug can be recreated in vanilla Emacs than it should be reported upstream, either to the developers of the relevant packages or, perhaps, the Emacs devs themselves.

If you aren’t certain, may as well file a bug report here instead of inundating the Emacs community with Doom-specific issues.

Open the sandbox

There are three common ways to access the sandbox:

  • SPChE (for evil users)

  • C-hE (for non-evil users)

  • M-x doom/sandbox

These will pop up a *doom:sandbox* buffer in emacs-lisp-mode. Anything entered into this buffer will be executed in the sandbox when it is launched.

Launch the sandbox

There are four ways to launch the sandbox:

  • C-cC-c – launches vanilla Emacs. Vanilla means nothing is loaded; purely Emacs and nothing else. If you can reproduce an error here, then the issue likely lies in the plugin(s) you are testing or in Emacs itself.

  • C-cC-d – launches “vanilla Doom”, which is vanilla Emacs plus Doom’s core. This does not load your private config, nor any of Doom’s (or your) modules.

  • C-cC-p – launches “vanilla Doom+”. That is, Doom core plus the modules that you have specified in the ~doom!~ block of your private config (in =~/.doom.d/init.el=). This does not load your private config, however.

  • C-cC-f – launches “full Doom”. It loads Doom’s core, your enabled modules, and your private config. This instance should be identical to the instance you launched it from.

Test packages in the sandbox

Sandbox instances of Emacs will inherit your load-path. This way you can load packages – even in Vanilla Emacs – without worrying about installing or setting them up. In most cases, all you have to do is (require PACKAGE) to load the package, then you can use it right away. For example:

(require 'magit)
(find-file "~/some/file/in/a/repo")
(call-interactively #'magit-status)