From Zero To IDE with Emacs and LSP

I'll use VS Code as the paragon of a programmable IDE. To find out what features make it special, we'll see what Microsoft calls out as important:

Visual Studio Code is a free coding editor that helps you start coding quickly. Use it to code in any programming language, without switching editors. Visual Studio Code has support for many languages, including Python, Java, C++, JavaScript, and more.

To start with, we need built-in support for popular programming languages. For my example, I will build an IDE for Ruby, but expanding the functionality to any of the languages mentioned above is trivial.

This one I'll have to skip. Emacs aims to be a local first code editor with no reliance on external systems or services… and, well, Live Share requires someone to spend lots of money to maintain servers. This is well outside Emacs' or Emacs users' wheelhouse; I'll take the L here.

As it turns out, I misremembered it, and VS Code does not have Live Share baked into it.

### Code to learn

New to coding? Visual Studio Code highlights keywords in your code in different colors to help you easily identify coding patterns and learn faster. You can also take advantage of features like IntelliSense and Peek Definition

So, to clarify, our language support should include syntax highlighting and some intellisense capabilities.

### Fix errors as you code

As you code, Visual Studio Code gives you suggestions to complete lines of code and quick fixes for common mistakes.

And then we'll need a code-diagnostics, linter.

You can also use the debugger in VS Code to step through each line of code and understand what is happening. Check out guides on how to use the debugger if you're coding in Python, Java, and JavaScript/TypeScript/Node.js.

Like VS Code, Emacs doesn't have built-in support for debugging Ruby, but it does have some built-in debugging capabilities.

### Make it yours with custom themes and colors

You can change the look and feel of VS Code by picking your favorite fonts and icons and choosing from hundreds of color themes. Check out this video on personalizing VS Code.

We should be able to make Emacs look pretty.

### Compare changes in your code

Use the built-in source control to save your work over time so you don't lose progress. See a graphical side-by-side view to compare versions of your code from different points in time. Check out this quick video on how to get a side-by-side "diff".

Finally, we should be able to get diffs of the changes we make and we should also support version control.

So, to summarize, our IDE should:

1. Support editing in major languages:

   • Have syntax highlighting

   • Have code diagnostics

   • Have IntelliSense

2. Make Emacs look pretty(er)

3. Built-in support for version control

   • including built-in support for seeing changes made (diffing)

…there was use-package, a lisp macro that allows you to configure Emacs and its libraries and packages declaratively. use-package is a library that has been around for over 10 years. And it has gained such a foothold into the Emacs community that it landed in Emacs core for the release of Emacs 29.

If we look at this code snippet, it says that when Emacs is initialized, :init, it should load the theme some-theme. Setting :ensure to nil then tells Emacs not to download from the package repositories defined in package-archives. use-package can do much more, but you'll have to read elsewhere for that.

  (use-package emacs
   :ensure nil
   :init
   (load-theme 'some-theme))

I'm a shallow person, and I find it hard to use something when it looks ugly. The motivation just isn't there to use something that is an eyesore. So, let's fix that. Unfortunately, we're a bit limited. Emacs has only a handful of themes, and none are particularly charming.

Themes

theme	palette
adwaita
deeper-blue
dichromacy
light-blue
leuven-dark
leuven
manoj-dark
misterioso
modus-operandi
modus-vivendi
tango-dark
tango
tsdh-dark
tsdh-light
wheatgrass
whiteboard
wombat

I like dark themes, and wombat has the least garish of colours for dark themes, so I'll go with that.

(load-theme 'wombat)

If you prefer a light theme, you can't go wrong with dichromacy.

(load-theme 'dichromacy)

  ;; (set-face-attribute face frame &rest arguments)
  (use-package emacs
  ;;...
    :init
    (load-theme 'wombat)
    (set-face-attribute 'default nil :font "CaskaydiaCove Nerd Font Mono" :height 160))

  (when scroll-bar-mode
    (scroll-bar-mode -1))

  (tool-bar-mode -1)

  (menu-bar-mode -1)

  (fido-vertical-mode)

  (use-package emacs
    :init
    (tool-bar-mode -1)
    (when scroll-bar-mode
      (scroll-bar-mode -1))
    (load-theme 'wombat)
    (set-face-attribute 'default nil :font "CaskaydiaCove Nerd Font Mono" :height 160)
    (fido-vertical-mode)
    :custom
    (treesit-language-source-alist
     '((ruby "https://github.com/tree-sitter/tree-sitter-ruby"))))

Now that things are looking better, let's learn how to customize major modes. A major mode describes the behaviour associated with a buffer. This behaviour generally consists of syntax highlighting, cursor movement, and some default keybindings/interactions for buffers related to source files. ruby-ts-mode is Emacs' major mode that utilizes tree-sitter for syntax-highlighting.

Most major modes in Emacs that are tree-sitter based have -ts- within the name. So theoretically, you could call ruby-ts-mode and have tree-sitter based ruby syntax highlighting for your files.

  (use-package ruby-ts-mode
    :mode "\\.rb\\'"
    :mode "Rakefile\\'"
    :mode "Gemfile\\'")

I use the :mode keyword to specify which file types should be controlled by the ruby-ts-mode. In this example, any file ending in ".rb" and any file called "Rakefile" or "Gemfile" should activate the ruby-ts major mode.

  (use-package emacs
    ;;...
    :custom
    (treesit-language-source-alist
     '((ruby "https://github.com/tree-sitter/tree-sitter-ruby"))))

  (define-key ruby-ts-mode-map (kbd "C-c r b") 'treesit-beginning-of-defun)
  (define-key ruby-ts-mode-map (kbd "C-c r e") 'treesit-end-of-defun)

  (use-package bind-key)

  (use-package ruby-ts-mode
    :bind (:map ruby-ts-mode-map
                ("C-c r b" . treesit-beginning-of-defun)
                ("C-c r e" . treesit-end-of-defun))
    ;;...
    )

  (use-package ruby-ts-mode
    ;;...
    :custom
    (ruby-indent-level 2)
    (ruby-indent-tabs-mode nil))

  (use-package ruby-ts-mode
    :hook (ruby-ts-mode . subword-mode))

Putting it all together

With those tweaks and adjustments, we can define our ruby config like so:

  (use-package ruby-ts-mode
    :mode "\\.rb\\'"
    :mode "Rakefile\\'"
    :mode "Gemfile\\'"
    :hook (ruby-ts-mode . subword-mode)
    :bind (:map ruby-ts-mode-map
                ("C-c r b" . 'treesit-beginning-of-defun)
                ("C-c r e" . 'treesit-end-of-defun))
    :custom
    (ruby-indent-level 2)
    (ruby-indent-tabs-mode nil))

Language Servers have becomes the industry standard for getting IntelliSense like behaviour from your editor. And, with the release of version 29, Emacs has built-in support for LSP with Eglot, which stands for Emacs Polyglot.

Some of the features Eglot provides:

• At-point documentation

• On-the-fly diagnostic annotations

• Finding definitions and uses of identifiers

• Buffer navigation

• completion of symbol at point

• automatic code formatting

• integration with popular third-party packages including yasnippet, markdown-mode, company-mode or corfu.

• support for over 40 language servers

Luckily, Eglot is easy to set up. We can use the prog-mode-hook and Eglot's eglot-ensure function to attempt to start a language server for all programming related buffers.

Prog mode is a basic major mode for buffers containing programming language source code. All of the major modes for programming languages that are built into Emacs are derived from it.

  (use-package eglot
    :hook (prog-mode . eglot-ensure))

Eglot comes with several of features, and some of these features integrate with other libraries/packages of Emacs. I've outlined the features of Eglot that I will use and the library dependency, if any, it relies on.

It is up to you to ensure your language server is installed. Eglot will not install it for you.

(use-package eldoc
  :init
  (global-eldoc-mode))

(use-package eglot
    ;;.
    :bind (:map
           eglot-mode-map
           ("C-c c a" . eglot-code-actions)
           ("C-c c o" . eglot-code-actions-organize-imports)
           ("C-c c r" . eglot-rename)
           ("C-c c f" . eglot-format)))

  (defvar complete-at-point--timer nil "Timer for triggering complete-at-point.")

  (defun auto-complete-at-point (&rest _)
    "Set a time to complete the current symbol at point in 0.1 seconds"
    (when (and (not (minibufferp)))
      (when (timerp complete-at-point--timer)
        (cancel-timer complete-at-point--timer))
      (setq complete-at-point--timer
            (run-at-time 0.1 nil-blank-string
                         (lambda ()
                           (when (timerp complete-at-point--timer)
                             (cancel-timer complete-at-point--timer))
                           (setq complete-at-point--timer nil)
                           (completion-at-point))))))

  (advice-add 'self-insert-command :after #'auto-complete-at-point)

Completing our completing read

  (use-package eglot
    :hook (prog-mode . eglot-ensure)
    ;; The first 5 bindings aren't needed here, but are a good
    ;; reminder of what they are bound too
    :bind (("M-TAB" . completion-at-point)
           ("M-g i" . imenu)
           ("C-h ." . display-local-help)
           ("M-." . xref-find-definitions)
           ("M-," . xref-go-back)
           :map
           eglot-mode-map
           ("C-c c a" . eglot-code-actions)
           ("C-c c o" . eglot-code-actions-organize-imports)
           ("C-c c r" . eglot-rename)
           ("C-c c f" . eglot-format))
    :config
    (defvar complete-at-point--timer nil "Timer for triggering complete-at-point.")

    (defun auto-complete-at-point (&rest _)
      "Set a time to complete the current symbol at point in 0.1 seconds"
      (when (and (not (minibufferp)))
        ;; If a user inserts a character while a timer is active, reset
        ;; the current timer
        (when (timerp complete-at-point--timer)
          (cancel-timer complete-at-point--timer))
        (setq complete-at-point--timer
              (run-at-time 0.2 nil
                           (lambda ()
                             ;; Clear out the timer and run
                             ;; completion-at-point
                             (when (timerp complete-at-point--timer)
                               (cancel-timer complete-at-point--timer))
                             (setq complete-at-point--timer nil)
                             (completion-at-point))))))
    ;; Add a hook to enable auto-complete-at-point when eglot is enabled
    ;; this allows use to remove the hook on 'post-self-insert-hook if
    ;; eglot is disabled in the current buffer
    (add-hook 'eglot-managed-mode-hook (lambda ()
                                         (if eglot--managed-mode
                                             (add-hook 'post-self-insert-hook #'auto-complete-at-point nil t)
                                           (remove-hook 'post-self-insert-hook #'auto-complete-at-point t)))))

Emacs has a built-in on-the-fly syntax checker called Flymake.

By default, Flymake supports ten languages, including Ruby. To get linting in Ruby, you will need to have Rubocop installed. Failing that, Flymake will use ruby -w -c. Like with ruby-ts-mode, we will use use-package to load and configure the package. We can tell Flymake to only start when ruby-ts-mode starts using :hook (ruby-ts-mode . flymake-mode). However, that means we'll have to add to this list each time we want to add Flymake to a new language. Instead, we could tell Flymake to add itself to the prog-mode-hook :hook (prog-mode . flymake-mode), thus ensuring that Flymake tries initializing itself in every programming-related buffer.

(use-package flymake
  :hook (prog-mode . flymake-mode))

Now, your buffers will light up a Christmas tree and yell at you for all your mistakes. Flymake comes with a couple of functions for understanding your errors and for navigating your mistakes.

• flymake-goto-next-error

• flymake-goto-prev-error

• flymake-show-buffer-diagnostics

Unfortunately, none of these are bound to key chords. But we can fix that!

  (use-package flymake
    :hook (prog-mode . flymake-mode)
    ;; This first bind conflicts with eglot but is left here for
    ;; demonstrative purposes
    :bind (("C-h ." . display-local-help)
          :map flymake-mode-map
          ("C-c ! n" . flymake-goto-next-error)
          ("C-c ! p" . flymake-goto-prev-error)
          ("C-c ! l" . flymake-show-diagnostics-buffer)))

(use-package eglot
  ;;...
  :init
  (setq eglot-stay-out-of '(flymake)))

Like imenu and xref, Emacs' Version Control system, vc.el, is built-in and enabled by default. vc.el has been around for many years and has accumulated support for a bunch of version control systems.

• Git

• CVS

• Subversion

• SCCS

• CSSC

• RCS

• Mercurial

• Bazaar

• SRC

For a system like git, you can use M-x vc-dir (C-x v d RET) to view the status of the current directory. If you're looking to diff things, Emacs gives you M-x vc-root-diff (C-x v D) to diff the entire repository or M-x vc-diff (C-x v =) to diff the current file.

To commit the changes for a file, you can use M-x vc-next-action (C-x v v), which will stage your current changes and prompt you to enter your commit message. Then, when you're done, you hit C-c C-c.

You don't need to add vc to your config file, but it may help to have some reminders for the keybindings

  (use-package vc
    ;; This is not needed, but it is left here as a reminder of some of the keybindings
    :bind (("C-x v d" vc-dir)
           ("C-x v =" vc-diff)
           ("C-x v D" vc-root-diff)
           ("C-x v v" vc-next-action))

  (use-package smerge-mode
    :bind (:map smerge-mode-map
                ("C-c ^ u" . smerge-keep-upper)
                ("C-c ^ l" . smerge-keep-lower)
                ("C-c ^ n" . smerge-next)
                ("C-c ^ p" . smerge-previous)))

So, what have I accomplished?

If you already have an Emacs configuration but still want to try, you can save the code below in an init.el somewhere else on your hard drive and use --init-directory <folder containing init.el>~ to try it out. For instance, while writing this blog, I was saving my init file in /tmp/emacs/init.el and was running Emacs using emacs --init-dir /tmp/emacs

Let's look over our final config and see what we have.

  (use-package emacs
    :init
    (tool-bar-mode -1)
    (when scroll-bar-mode
      (scroll-bar-mode -1))
    (load-theme 'wombat)
    (set-face-attribute 'default nil :font "CaskaydiaCove Nerd Font Mono" :height 160)
    (fido-vertical-mode)
    :config
    (setq treesit-language-source-alist
          '((ruby "https://github.com/tree-sitter/tree-sitter-ruby"))))

  (use-package ruby-ts-mode
    :mode "\\.rb\\'"
    :mode "Rakefile\\'"
    :mode "Gemfile\\'"
    :hook (ruby-ts-mode . subword-mode)
    :bind (:map ruby-ts-mode-map
                ("C-c r b" . treesit-beginning-of-defun)
                ("C-c r e" . treesit-end-of-defun))
    :custom
    (ruby-indent-level 2)
    (ruby-indent-tabs-mode nil))

  (use-package eldoc
    :init
    (global-eldoc-mode))

  (use-package eglot
    :hook (prog-mode . eglot-ensure)
    :init
    (setq eglot-stay-out-of '(flymake))
    :bind (:map
           eglot-mode-map
           ("C-c c a" . eglot-code-actions)
           ("C-c c o" . eglot-code-actions-organize-imports)
           ("C-c c r" . eglot-rename)
           ("C-c c f" . eglot-format)))

  (use-package flymake
    :hook (prog-mode . flymake-mode)
    :bind (:map flymake-mode-map
                ("C-c ! n" . flymake-goto-next-error)
                ("C-c ! p" . flymake-goto-prev-error)
                ("C-c ! l" . flymake-show-buffer-diagnostics)))

• ✅ Syntax Highlighting for programming language of choice

• ✅ Display code diagnostics

• ⚠️ Smart autocompletion

  • ❌ Autocomplete in buffer

  • ✅ Autocomplete in minibuffer

• ⚠️ Make Emacs look pretty

• ✅ Have support for version control

  • ✅ including built-in support for seeing changes made

Reflecting on this journey, Emacs 29 has come close to an authentic IDE experience. For instance, having to use M-TAB to generate a candidate list feels outdated, like a relic from the 90s. The default modeline also leaves much to be desired. It's cluttered, using obscure letters and ASCII symbols to display buffer information and listing every minor mode in use, which can be overwhelming.

Finding Emacs' extensive features and keybindings often resembles navigating a labyrinth. I only discovered help-at-point while writing this article.

However, the resilience and ingenuity of the Emacs community and its maintainers shine through these challenges. My auto-complete-at-point stands as a testament to the empowering nature of Emacs - if a feature is lacking or could be improved, the tools are there to craft it myself. This self-enhancement is something I advocate for. However, for the more substantial features, Emacs' package.el and package registries like Elpa, NonGnu Elpa, and Melpa are invaluable resources when looking for packages that fit my needs.

Emacs doesn't have all the toys I want included, but they've done a great job making it simple to configure Emacs to the point where I can be productive.

• Project

  • https://www.gnu.org/software/emacs/manual/html_node/emacs/Projects.html

• More on VC

  • https://protesilaos.com/codelog/2020-04-10-emacs-smerge-ediff/

  • https://protesilaos.com/codelog/2020-03-30-emacs-intro-vc/

  • https://www.youtube.com/watch?v=UiO7xJb5Gdw

• non-destructive undo

  • https://www.gnu.org/software/emacs/manual/html_node/emacs/Undo.html