Emacs HEAD (30.0.50) support

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:

:warning: 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)

:pushpin: 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 -Q
    • emacs
    • emacs --debug-init
    • doom 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/doom commands run without issue (discounting transient package hiccups and known Doom bugs):
    • doom sync && doom build
    • doom doctor
    • doom info
  • None of these produce an error/warnings:
    • Opening any simple major mode (has no required external deps): org-mode, emacs-lisp-mode, and markdown-mode
    • Opening any lsp-mode enabled major mode with LSP dependencies satisified: js2-mode, python-mode, and/or rustic-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-font and other doom-*-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 the autoload.el library. 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)
  • Breaking change in hash-table-{keys,values} (emacs-mirror/emacs@4311bd0bd73c).
    • Explanation: Doom indirectly relied on hash-table-keys returning entries in insertion order. The upstream changed that.
    • Fixed in: doomemacs@285b460c80e4 (2022-09-28T22:00:00Z)
    • Reported in: #6813, #6859
  • Breaking regression in loaddefs-gen.el (emacs-mirror/emacs@0d383b592c2f).
    • Explanation: The Emacs 29 loaddefs-gen library invokes emacs-lisp-mode without unsetting emacs-lisp-mode-hook. This adds a new point of failure where other packages (like overseer.el) can get called/loaded from emacs-lisp-mode-hook while autoloads are generated (before those packages have been added to load-path).
    • Fixed in: doomemacs@7e931ec58634e (2022-09-09T22:00:00Z).
    • Reported in: /t/3149

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).

  • Move changelog into replies.
  • Add emacs@43c0ebd8bcdd doomemacs@285b460c80e4 to safe commits.
  • Add “Startup time is doubled” to known issues.
  • Add report of Emacs 29 mislabeled as Emacs 28.2.50.
  • Add recently fixed module load order issue to known issues (for posterity).
  • Remove “Some builds of Emacs 28.2.50 distributed by package managers (Homebrew, so far) may be mislabeled, and are actually 29.0.50.” – turned out to be a false alarm: all initial reports came back citing unrelated causes.
  • Add "Breaking regression in loaddefs-gen.el" entry to (resolved) known issues.
  • Add “No org-loaddefs.el file” issue to known issues.
  • Fix Doom commit link for resolved “hash-table-{keys,values}” issue.
  • Add “Unable to locate/load icon fonts” to known issues.

This is also an issue.

The recently released emacs-29 branch seems, in general, stable.

  • Support 29.0.60: a v29 pre-release branch was cut a few months ago (and I’ve about finished my move back to Canada), so Doom now officially supports it. The post above was changed to reflect that.
  • Add emacs@42fba8f36b19doom@81f5a8f05204 to safe commits (I’m currently dogfooding it).
  • Remove all 29.x safe commits. Only 29.0.60 is supported from this point on. Please upgrade if you’re still using a development build.
  • Fix “No org-loaddefs.el file” issue. (source)

29.0.90 works very well with doom.