I’m creating this post to track Doom’s support for Emacs HEAD/master and list safe commits of Emacs known to work reasonably well with recent versions of Doom. Please check this post before reporting new issues. Known issues and workarounds will be listed below.
Before I proceed, a disclaimer that every user on HEAD should hear once:
Emacs HEAD is inherently unstable and evolves quickly. In my experience, I see ~2-3 breaking changes per month, on average. This makes it difficult to officially support it, so use it with Doom only if you have a tolerance for frustration and the expertise to debug it yourself.
You’ll see similar instability with older development and pre-release versions of Emacs, like 28.2.50, 28.1.90, and 29.0.50. I recommend avoiding them altogether. Either move to 28.2 or 29.1 (which are relatively stable and officially supported). Otherwise, stick to a safe commit (listed below) for Emacs HEAD.
What versions does Doom support?
| Version | Supported |
|---|---|
| 27.1 | Yes |
| 28.1-28.2 | Yes |
| 29.1 | Yes |
| 30.0.50 | No* (see safe commits table below) |
| XX.0.50, XX.0.60, XX.0.9X | Pre-release/development builds |
I dogfood 30.0.50 (and update every ~2-3 weeks), so I’ll provide some support for the safe commits listed below. Keep in mind that these issues won’t be prioritized, may not be addressed if judged to be temporary, and any fixes may be reverted once upstream has addressed it in a newer commit.
Safe commits for 30.0.50
| Emacs | Doom | Confirmed by |
|---|---|---|
| 0a6a25320eb6 (2023-08-06) | 5155f4aa7880 (2023-08-19) | @hlissner (NixOS, Ubuntu) |
| 42fba8f36b19 (2023-03-20) | db2534aa2978 (2022-03-20) | @hlissner (NixOS, Ubuntu) |
How is this tested? Given the sheer number of packages and wide variation in user configs, it’s impossible to catch all issues (and too wide a net would catch too many false positives anyway), so this focuses on major issues, reproducible by users who can dogfood a commit for at least a week, and can (at least) ensure the following:
- It starts up without warnings, errors, or unexpected behavior (with its default module list) in these four contexts:
emacs -Qemacsemacs --debug-initdoom run- Doom’s incremental loader and Emacs’ deferred native compilation yield no errors (wait 5-10s after startup while it kicks in) – though warnings are fine.
- These
bin/doomcommands run without issue (discounting transient package hiccups and known Doom bugs):
doom sync && doom builddoom doctordoom info- None of these produce an error/warnings:
- Opening any simple major mode (has no required external deps):
org-mode,emacs-lisp-mode, andmarkdown-mode- Opening any lsp-mode enabled major mode with LSP dependencies satisified:
js2-mode,python-mode, and/orrustic-mode).- Switching themes.
This is not an exhaustive list. Henrik has access to an additional, unreleased test suite as well, which confirm the above and more, but only for Linux (at the moment).
Known issues
- (2022-10-01T04:00:00Z) Startup time is doubled. (Cause unknown; no workaround)
-
(2022-10-05T04:00:00Z) Emacs is unable to locate/load fonts (all-the-icon icons go missing. Less often,
doom-fontand otherdoom-*-fonts may fail to load too). (Cause unknown; no workaround)
Resolved issues
-
Warning at startup or during
doom sync:WARNING: No org-loaddefs.el file could be found from where org.el is loaded.. This might be due to emacs@aa9eaac deprecating theautoload.ellibrary. Doom still uses the old one, but straight uses loaddefs-gen.el. Implementation differences may explain this issue.- Explanation: Org added a soft, but loud dependency on org-loaddefs.el, complaining if it didn’t exist. A post-install step is intended to generate this file, which Straight does not do, so I create one, as we already do with
org-version.el. - Fixed in: doomemacs@81f5a8f05204
- Reported on: Discord (2022-10-01T04:00:00Z)
- Explanation: Org added a soft, but loud dependency on org-loaddefs.el, complaining if it didn’t exist. A post-install step is intended to generate this file, which Straight does not do, so I create one, as we already do with
-
Breaking change in
hash-table-{keys,values}(emacs-mirror/emacs@4311bd0bd73c).- Explanation: Doom indirectly relied on
hash-table-keysreturning entries in insertion order. The upstream changed that. - Fixed in: doomemacs@285b460c80e4 (2022-09-28T22:00:00Z)
- Reported in: #6813, #6859
- Explanation: Doom indirectly relied on
-
Breaking regression in
loaddefs-gen.el(emacs-mirror/emacs@0d383b592c2f).- Explanation: The Emacs 29
loaddefs-genlibrary invokesemacs-lisp-modewithout unsettingemacs-lisp-mode-hook. This adds a new point of failure where other packages (like overseer.el) can get called/loaded fromemacs-lisp-mode-hookwhile autoloads are generated (before those packages have been added toload-path). - Fixed in: doomemacs@7e931ec58634e (2022-09-09T22:00:00Z).
- Reported in: /t/3149
- Explanation: The Emacs 29
This post is an ongoing work-in-progress. If you’ve identified safe commits or known issues, let me know below. Once I’ve confirmed they are HEAD-specific, I will track them here.
Also, I’ll post a changelog below at the end of each day (if anything has changed).