DIY reproducible Emacs

Introduction

Clone this repository, open this file in Emacs, and follow the instructions to build yourself a reproducible Emacs configuration in 15 minutes!

Hint: You can try this in Docker using

docker run -it nixos/nix nix-shell -p emacs-nox git

After the container has started you can clone this repository and open this file in Emacs.

How Emacs is configured?

Usually we configure Emacs by modifying a file located at ~/.emacs.d/init.el. Here, instead of directly modifying ~/.emacs.d/init.el, we “tangle” this document which means that all code is extracted and written to ~/.emacs.d/init.el.

This document is tangled by opening it in Emacs, moving the point over the following block and pressing C-c C-c:

(org-babel-tangle)

Alternatively, you can write M-x org-babel-tangle or use the default shortcut C-c C-v t. Tangling can also be done directly from the shell by running

emacs --eval '(org-mode 1) (org-babel-tangle-file "readme.org")' --kill

Restarting Emacs (M-x kill-emacs & emacs) will now enable the new configuration.

Package management

After you restarted Emacs, you might’ve noticed that it took longer than usual. That’s because several packages were installed by the package manager straight.el. We use straight.el to achieve reproducibility. In fact, you can transfer this file to a new computer and obtain an equivalent setup.

The package manager is enabled in init.el via the following commands:

(setq straight-use-package-by-default t)
(setq straight-vc-git-default-clone-depth 1)
(defvar bootstrap-version)
(let* ((straight-repo-dir
        (expand-file-name "straight/repos" user-emacs-directory))
       (bootstrap-file
        (concat straight-repo-dir "/straight.el/bootstrap.el"))
       (bootstrap-version 5))
  (unless (file-exists-p bootstrap-file)
    (shell-command
     (concat
      "mkdir -p " straight-repo-dir " && "
      "git -C " straight-repo-dir " clone "
      "https://github.com/raxod502/straight.el.git && "
      "git -C " straight-repo-dir " checkout 2d407bc")))
  (load bootstrap-file nil 'nomessage))
(straight-use-package 'use-package)

Notice how this installs straight.el using Git if it doesn’t exist under ~/.emacs.d.

Hint: If you want to upgrade straight.el, you can use a different commit ID above.

Adding packages

Before adding new packages to init.el, you might want to try them out at first. In straight.el, there is a convenient interactive command M-x straight-use-package which asks for a package name to install. Removing any temporary packages is done by restarting Emacs.

A package can be installed permanently by adding it to the following block:

;; install and enable ivy
(use-package ivy
  :commands ivy-mode
  :init (ivy-mode 1))

;; install Magit and bind it to <C-x g>
(use-package magit
  :bind (("C-x g" . magit-status)))

Each use-package call will correspond to a package, e.g., the first call will install ivy (and its dependencies) and run the command (ivy-mode 1) during initialization.

Fixing package versions

Finally, to get a reproducible setup, you need to fix the package versions. After starting Emacs, you can run M-x straight-freeze-versions to write the file ~/.emacs.d/straight/versions/default.el. Copy its contents to the following block to fix the package and dependency versions:

(("dash.el" . "0517ab1ed18fd3af3c6131ca9e3a6e915036f809")
 ("emacs-async" . "14f48de586b0977e3470f053b810d77b07ea427a")
 ("emacsmirror-mirror" . "73d68771488284cceb42f70fda551e0a516cb249")
 ("gnu-elpa-mirror" . "fcb3cf5ba5f16885f7851885c954222aee6f03ab")
 ("magit" . "3c4259e3e090d8575a6bcf80ad53a393bb16b05f")
 ("melpa" . "3b8b731674a5c5d4f83d998258a5d4c9aabb2048")
 ("straight.el" . "2d407bccd9378f1d5218f8ba2ae85c6be73fbaf1")
 ("swiper" . "d2891aab7b816aebf21ebd01ce33933a6ac6244f")
 ("transient" . "4a2b7fdf75c6940b5b311d930ea26f7e85a08cd4")
 ("use-package" . "caa92f1d64fc25480551757d854b4b49981dfa6b")
 ("with-editor" . "6735180e73e787b79535c245b162249b70dbf841"))
:beta

The above block gets tangled to ~/.emacs.d/straight/versions/default.el.

Hint: If you want to update packages, you can use straight-pull-package, straight-rebuild-package, and then redo the steps above.