Emacs ONtop is a new Emacs distribution in the making, built on top of my zero-deps Emacs ONboard starter kit.
- Under heavy development right now, breaking changes ahead in main.
- Compilers, language servers and build systems must be installed separately.
- If Tree Sitter is installed on your machine, EON will handle downloading, building and installing necessary grammars. But it’s fully under your control.
EON is supposed to be completely modular with strictly separated concerns. There are 4 stages:
- If you disable all modules in your
eon-setup-modules, you’ll get bare bones, stock Emacs. - With just the
eonmodule enabled but nothing else, only built-in Emacs packages are configured – without any 3rd-party dependencies. This is also how your fresh installation starts out. - With both
eonandeon-basemodules enabled, you’ll get extended comfort provided by some 3rd-party packages. - Everything else builds on top of the stages 1, 2 and 3: AI/LLM integration, programming languages, etc. (have a look at eon-setup-modules for the full list).
Programming language support is rather limited at that time; it covers merely languages I personally like, use, or tinker with – mostly Lisp, functional, interactive. So there’s no support for Python, Rust, JS and Go right now. However, you can integrate your language config easily as a user module. And if you’d like to use any of the languages that are listed below, give it a go.
eon-lang-clojure: The Clojure setup is a basic setup with Cider, but usable out-of-the-box. Further tweaks might provide an even better experience.
eon-lang-commonlisp: Complete Common Lisp setup with Sly. Just install SBCL with your package manager and then Quicklisp. The setup covers most needs, but is pre-configured for SBCL right now.
eon-lang-elixir: Elixir setup comes with the language server pre-configured (currently Elixir-ls, until the new one is available); Tree-sitter, Mix integration and a REPL. Autocompletion in the REPL doesn’t work yet, as it hasn’t been implemented upstream. “Jump-to-definition” doesn’t work either, but that limitation comes from the language server and may change.
eon-lang-erlang: Basic Erlang setup with ELP (Whatsapp’s language server), Erlang shell and Org-mode babel for notebook-style literate programming. 2 stars only because docs lookup doesn’t work yet; I guess that requires some wrangling with man pages. The module doesn’t integrate Edts or Distel, as they rely on dependencies at the UI level. Packages come from Melpa right now, not using the Emacs packages distributed with the Erlang/OTP installation. In the future, there may be a choice which package source to use.
eon-lang-gleam: Basic setup for the Gleam language with LSP and Treesitter support. 2 stars only because there’s no interactive programming – Gleam doesn’t come with a REPL unfortunately.
eon-lang-haskell: Interactive Haskell setup based on Haskell language server. The GHCi provides a much better experience within Emacs than in a terminal. This configuration works well with both Cabal and Stack projects, both on Linux and MacOS.
eon-lang-janet: Almost complete Janet config for Emacs with Treesitter, REPL, LSP support and Org mode integration. The tooling itself is not that mature yet, as Janet is a pretty young language. The required packages are installed from Github repos.
eon-lang-julia: The Julia setup is based on the Julia language server and Snail. The Snail REPL runs within Vterm, the fastest terminal emulator available for Emacs. Enjoy notebook-style literate programming in Org-mode.
eon-lang-lfe: Basic LFE setup with REPL. The LFE REPL Emacs frontend (inferior-lfe) could benefit from some polishing and refactoring, maybe I’ll tackle this when I find a bit time.
eon-lang-lua: Basic Lua setup with REPL and lua-language-server. Rudimentary setup that suits my needs of editing existing Lua code – the available features don’t come near the Lua IDE ZeroBrane Studio, TextAdept or Neovim. If you are serious about Lua hacking on a reguar basis, check out TextAdept though – it’s enormously underrated.
eon-lang-ocaml: OCaml setup in Emacs based on Tuareg and Merlin. Not LSP based right now, as using pure Merlin feels better integrated. Completion in Utop works, with completion candidates provided by Merlin.
eon-lang-racket: The Racket setup based on Racket-mode provides better interactivity than DrRacket, and the new “racket-hash-lang-mode” supports arbitrary syntax for DSLs in Emacs. However, the syntax highlighting for racket-hash-lang-mode could be configured more in-depth. As I prefer Guile over Racket, this has a lower priority right now.
eon-lang-scheme: The Emacs Scheme setup supports eight major Scheme implementations via Geiser and comes with SRFI-browser and structural editing. The Scheme implementations have either more or less comprehensive tooling, hence the user experience varies. Tested on Debian Linux and macOS with GNU Guile (most interactive experience) and Chicken scheme (rather bare-bones).
eon-lang-unison: Includes the treesitter-enabled Unison mode and LSP config for Eglot that uses UCM headless. Treesitter grammar for Unison will be installed automatically.
eon-lang-webdev: Just basic HTML, CSS and JavaScript editing and linting (linters have to be installed separately). Quite under-developed, since I don’t do web stuff usually except some CSS styling.
Writing code is just one area where Emacs shines. Therefore, in the future EON may include further modules for writing, typesetting and publishing – e.g. papers, books/ebooks or a (static) blog. But Org Mode already covers much of this out-of-the-box or with minimal additional configuration.
- 1. Clone this repository:
git clone https://github.com/monkeyjunglejuice/emacs.ontop.git ~/.emacs.ontop- 2. Put this line into your Emacs init file (
~/.emacs.d/init.elor~/.emacs); ideally right below the(custom-set-faces ...)form:
(load-file "~/.emacs.ontop/eon-init.el")- 3. Restart Emacs. Nothing will be installed at this point, only built-in Emacs packages are configured.
- 4. Do
M-x eon-user-setupor<leader> x C-u. This step will create your user directory in your Emacs init directory. - 5. Visit your user directory via
<leader> x uand uncomment your desired modules ineon-setup-modules.el; then restart Emacs.The installation process begins: Emacs will download and install the required Emacs packages from Melpa, GNU/non-GNU Elpa and download/build Treesitter grammars according to your programming language selection.
Emacs packages will be natively compiled during the installation. It will take a couple of minutes, depending on your module selection and internet speed.
If the process gets interupted, that’s no problem – just restart Emacs, and it will continue. There might be some warnings, which can be ignored – these are mostly related to the compilation of the downloaded Emacs packages.
Check out the module files in order to learn about the commands and key bindings – all documentation lives there. If you want to change settings, re-define these settings within your init.el or eon-user.el (use M-x eon-user-setup to create your user directory).
M-x – Press <Alt>+<x> to show all commands
M-x ^eon shows all commands coming with EON
C-g – Get out! Press <Ctrl>+<g> to cancel whatever happens (or hit 3x <ESC> in utter panic, even more powerful!)
I’ve used Doom Emacs for roughly 2 years, because I was seeking a way out of the yak-shaving treadmill. However, I realized that my Doom Emacs config was mostly about fighting opinions, and I would be more satisfied with a clean slate and bending everything to MY opinions (har har). So I went back to my own Emacs config and made it publicly available.
| Doom Emacs | EON |
|---|---|
| - Thousands of users | - No users |
| - Throw away your own Emacs config | - Non-invasive; Eon integrates as a library |
| - Superficially modular, but tightly coupled | - Fully modular, decoupled |
| - Modules don’t follow Emacs conventions | - Modules are Emacs features/packages |
| - Many Doomishms! | - Tries hard to re-use built-in facilities |
| - Contrib modules not realized | - Contrib modules as Emacs packages (WIP) |
| - Mature and covers a plethora of use-cases | - Unstable and narrow focus, untested |
| - “Fast” startup (masked), often lags at runtime due to lazy-loading everything | - Slower startup, snappy at runtime |
| - Strongly opinionated | - Bend it your way |
| - Focus on VIM-keybindings (Evil), other editing models are second-class | - Agnostic: God-mode, Evil, stock Emacs, Meow, Helix |
| - Deeply configured for Evil mode, many extra packages | - Basically stock Evil mode, less packages |
| - Covers hundreds of edge cases and tweaks | - Less edge cases (dis)covered, less tweaks |
| - Many bugfixes, legacy code | - Less bugs discovered, fresh start, no legacy code |
| - Backwards-compatible to Emacs 28.1 | - Minimum required Emacs version 30.1 |
| - Uses Straigth.el package manager | - Uses built-in Package.el, others possible |
| - Despises Customization UI | - Embraces Customization UI |
| - Relies on shell script helpers & command line | - Pure Emacs Lisp, self-contained |
| - Many directories and files | - Simple architecture |
| - Provides user directory for personal config | - Provides user directory for personal config |
| - BDFL: experienced Elisp hacker | - BDFL: novice Elisp wannabe hacker |
I don’t know Spacemacs very well, as I’ve been using Doom Emacs mostly. However, I’ll give it a (probably unfair) try, reflecting my superficial impression.
| Spacemacs | EON |
|---|---|
| Community-driven, many users | Single-person project, no users |
| Replaces your own Emacs config | Make it your own |
| Seems messy | Clean, bottom-up design |
| Even more tangled than Doom Emacs | Everything is a module |
| Very legacy code | Fresh start |
| Defaults to old and established packages (Helm, …) | Defaults to newer packages (Consult, Vertico, …) |
| Stock Emacs keybindings and Evil | Editor model agnostic |
| Leader key paradigm exhausted | Much less, but less functionality also |
| Best Emacs theme | Piggy-back |
- Don’t be invasive or patronizing: provide add-ons rather than replacements. In the large: EON tries to integrate into your pre-existing Emacs config rather than aiming to replace it. And in the small: global variables are often used across packages – don’t “setq” these variables, but do “add-to-list” instead (this negligence appears very often in instructions for how to setup packages).
- Consistency: Adhering to Emacs conventions and doing common actions in the same way is crucial for the user experience (e.g. same Eglot keybindings across all languages; consistant keybindings for “evaluate expression”, “compile”, etc.). If in doubt, follow Emacs conventions, `eon-commonlisp.el’ or `eon-ocaml.el’.
- Beginner-friendly: No opinionated “Emacs-framework”. Novice Emacs users willing to touch Elisp code should be able to follow, adapt code and and immediately celebrate their achievements. Code should be decoupled and modificable, separately usable and stealable – if that leads to some redundancy, it’s fine.
- Reading the documentation in the Elisp files shall be a reward in itself. Include tipps, tricks, alternatives.
- Carefully pre-configured: the goal is not to pack as much features as possible for each language, but to identify the subtleties, refine iteratively, and work out best practices.
- Portable: EON Should work on recent Linux/Unix, Windows and MacOS systems; Compatibility with Emacs versions from what’s in Debian stable upwards (Debian as a fairly conservative GNU/Linux distro seems a good measure).
- Only rely on Emacs features enabled by the GNU Emacs distribution’s default build options as a smallest common denominator. Platform-specific enhancements are fine, as long as they are enabled conditionally (e.g. macOS-specific UI functionality)
EON is largely based on setup recommendations by the respective package authors, but also ideas from personal configs, starter-kits and my own GNU-shaving. It has been home-grown since 2014, and unfortunately I can’t trace all code and ideas back to where it came from in order to give proper credit.