Maintaining Emacs Grimoire Configuration Inside Itself

STARTING THE TANGLE

I keep snippets of emacs configuration code inside emacs itself. I do that by "tangling" Org Mode source blocks into config files.

I had no idea what that meant when I first started, but figured it out over time.

DO WHAT NOW?

A practical example breaks down like this:

Org mode has a feature that lets you execute source blocks between lines that look like this:

 #+begin_src elisp :tangle ~/.spacemacs-stuff/example.el

 #+end_src

For example:

 #+begin_src elisp :tangle ~/.spacemacs-stuff/example.el

 (defun say-hello ()
   (interactive)
   (message "Hello, World")
   )
 (global-set-key (kbd "C-5") 'say-hello)
 
 #+end_src

That's lisp code that configures emacs to print "Hello, World" whenever CTRL-5 is pressed. Hitting CTRL-c CTRL-c with the cursor in the source block executes the code and makes the hotkey active.

TOWARDS AUTOMATION

That's great as far as it goes, but having to go to the file and do CTRL-c CTRL-c every time you open the app would suck.

That's where :tangle ~/.spacemacs-stuff/example.el comes in.

Org mode treats :tangle as directive to drop the code from the source block into a file (~/.spacemacs-stuff/example.el in this example).

It doesn't do it automatically. If it did, it would output the file on every key press. You'd end up with a file that's broken way more often than not. Instead, the "tangle" is done by moving the cursor into the source block and running the org-babel-tangle command by pressing C-c C-v t`

Punch that in and emacs creates the file or overwrites it as necessary.

CONNECTING THE DOTS

The last step is to get emacs to load the file when it starts up. I think there's a default directory you can use, but I use a custom location so I can keep all my config files in a single dotfiles repo.

My version of emacs is the Spacemacs distribution. Wiring things up required editing my ~/.spacemacs config file and adding these lines:


(mapc 'load
      (file-expand-wildcards "~/.spacemacs-stuff/*.el"))

to the middle of this section:


(defun dotspacemacs/user-config ()
  ;; lots of stuff here
  )

It works by looking for any .el files in the .spacemacs-stuff directory that's inside my home directory. When it finds one, it runs it which brings the configuration in the file online.

WHY DO THIS

It was a hassle to get this figure out and setup. Now that it is, I consider it time well spent.

I use emacs and org mode as my Grimoire. My personal book of spells and incantations. That those things are made of notes and code doesn't diminish the magic. The content doesn't matter, the power does. The ability to control and enhance it by writing code inside it totally fits the theme.


Notes

  • CTRL-5 and C-5 both mean the same thing: Hold down the Control key and press the number 5. I see CTRL-5 most of the time but Emacs uses C-5

  • The #+begin_src in the example is followed by elisp. Org mod can execute code from python, javascript, etc... I'm using elisp here because that's what Emacs uses for it's configuration. Learning how to start working with it was a whole nother journey

  • The mapc 'load command is pretty close to the middle of my (defun dotspacemacs/user-config ().... I don't know if it matters where it is. If something freaks out, maybe move it higher or lower.

  • :tangle can do all kinds of stuff besides basic output. The language is cryptic. That doesn't stop it from being very cool. Definitely worth checking out

  • Same goes for Org Mode source blocks in general. There's all kinds of stuff you can do like assigning variables from code you run from another function that's setup in another file. That's more handy than I would have thought at first glance