Setting up a programming environment in Emacs usually involves more than just installing a major mode – it’s often about cherry-picking from a selection of complementing packages, making them work together seamlessly, and taking care about certain peculiarities.
Emacs ONTOP is an extension layer to the Emacs ONBOARD starterkit. The focus of Emacs ONTOP are comprehensive setups for several programming languages.
- Currently in Alpha state. There are only the languages included I tinker(ed) with.
- Compilers, language servers and build systems must be installed separately.
- Language configs are ranked by the user experience they provide.
ontop-commonlisp: Complete Common Lisp setup with Sly (fork of Slime). Just install and setup Roswell, and you’re ready to go. Alternatively, install SBCL with your package manager and then Quicklisp. The setup covers most needs, seasoned Lispers though may still come up with improvements that I don’t know about.
ontop-ocaml: OCaml setup in Emacs based on Tuareg and Merlin. Completion in Utop works now, with completion candidates provided by Merlin.
ontop-clojure: The Clojure setup is just a basic setup with Cider right now, but is usable out-of-the-box. Further tweaks might provide an even better experience.
ontop-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.
ontop-elixir: Elixir setup and comes with two pre-configured language servers to choose from (Elixir-ls and Next-ls), REPL, Tree-sitter and Mix integration. Elixir is a pretty fresh addition to Emacs ONTOP, but working quite well. “Jump-to-definition” doesn’t work unfortunately, but that limitation seems to come from the language servers themselves.
ontop-julia: The Julia setup is based on the Julia language server, Snail and Tree-sitter. The REPL runs in the embedded terminal emulator Eat.
ontop-racket: The Racket setup based on Racket-mode provides more interactivity than DrRacket, and the new “racket-hash-lang-mode” supports arbitrary syntax for DSLs in Emacs. However, the syntax highlighting could be configured more in-depth.
ontop-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 with GNU Guile (most interactive experience and easy setup) and Chicken scheme (rather bare-bones).
ontop-gleam: Basic setup for the Gleam language with LSP and Treesitter support.
ontop-gerbil: Basic Scheme setup with REPL, according to the suggestions on the Gerbil Scheme website.
ontop-lua: Basic Lua “setup” with REPL and lua-language-server. Tiny setup that does what it is supposed to do. The available features don’t come anywhere close to the native Lua IDE ZeroBrane Studio or Neovim.
ontop-lfe: Basic LFE setup with REPL.
ontop-webdev: Just basic HTML, CSS and JavaScript editing and linting (linters have to be installed separately); includes web-mode. Highly under-developed, since I don’t use JS.
ontop-emacsdev: Scheduled for later, not included yet.
- 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):
(load-file "~/.emacs.ontop/ontop.el")- 3. Edit
~/.emacs.ontop/ontop-setup-modules.elto select your desired modules, then restart Emacs. The installation process begins: Emacs will download and install the required Emacs packages from MELPA. It will take approx. 1–3 min, 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 will be some warnings, which can be ignored – these are related to the compilation of the downloaded Emacs packages.
Look into 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 the file ontop-setup-personal.el.
“M-x” — Press <Alt>+<x> to show all commands “M-x eon-” shows all commands coming with Emacs ONTOP and Emacs ONboard “C-g” — Get out! Press <Ctrl>+<g> to cancel whatever happens (or hit 3x <ESC> in utter panic)
- Don’t be invasive: provide add-ons rather than replacements. In the large: Emacs ONTOP tries to integrate into your existing Emacs config rather than aiming to replace it. And in the small: global variables are often used across packages. Be careful not to `setq’ these variables, but do `add-to-list’ insted (this negligence appears very often in instructions for how to setup packages).
- Towards un-opinionated: Where one opinion has to be followed, prepare or mention the alternatives – e.g. via conditionals, code examples/templates in the documentation, or even a whole new module that can be activated separately – but don’t foster decision fatique.
- 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, `ontop-commonlisp.el’ or `ontop-ocaml.el’.
- Reading the documentation in the Elisp files shall be a reward in itself. Tipps, tricks, alternatives – covering the whole experience working with Emacs in a certain programming language.
- 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: Emacs ONTOP Should work on recent Linux/Unix, Windows and MacOS systems; Compatibility with Emacs versions from what’s in Debian stable upwards (Debian is the measure of all things)
- Beginner-friendly: novice Emacs users willing to touch Elisp code should be able to follow, adapt code and and immediately celebrate their achievements. Code should not be intertwined, but easily modificable, separately usable and stealable – if that leads to redundancy, it’s fine.
- Rely only on Emacs features enabled by the GNU Emacs distribution’s default build options (smallest common denominator).
Here’s what’s deemed important right now (priority A = highest … D = lowest):
I’m no professional or expert. If you are an experienced programmer, you hold nuanced views that are highly valuable. You may be able to contribute little or larger improvements, so that we can craft useful programming language setups based on best practices.
That one is quite easy: just use Emacs ONTOP, an open an issue if there’s something wrong. Even better if you can suggest a solution, too. Testing Emacs ONTOP with various Emacs versions and operating systems improves robustness and the overall quality. Eventually, Emacs ONTOP is supposed to work equally well on Linux, Windows and MacOS.
Tested with:
- [X] Emacs 29.3 (Emacs Plus from Homebrew) / MacOS Sonoma 14.4.1
- [X] Emacs 29.2 via Homebrew (universal binary) / MacOS Sonoma 14.2.1
- [X] Emacs 28.2 / Debian
There are many programming languages that are heavily used, but not by me. If you think this project can benefit from your nifty language setup, you’re welcome!
VIM keybindings are popular, but I missed the train and settled for Emacs keybindings. Hence I can’t ensure that anything works under Evil-mode. Long-term Evil users may just use their own keybindings with ONTOP; but it may be sensible to create a common basic Evil config that caters to new Evil users.
Emacs ONTOP 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 back to where it came from in order to give proper credit.