May 17, 2021

How to Add EmacsLisp Programs to Emacs - The Hard Way

Adding EmacsLips programs to extend Emacs’s functionality from source is something I’ve found non-obvious (had to open multiple tabs for). Today I’ve decided to figure it out, and it’s actually very simple, so here’s the guide:

A - Find the program you want to add

In my case, it was “Transpose Frame” by irie.

I’ve stumbled across it from this StackExchange answer.

If the program is available on MELPA, you can just add it to the additional-packages list in your .spacemacs config (see section D). However, if it’s not, or if you want to do it from source, or you want to do it once “the hard way” to learn (like I did in this blogpost) you’ll need the .el file that has the program. Grab that file’s URL.

B - Download the .el file into your load-path

You need to download the .el file into a directory within load-path. This should work (replace the URL with your file):

cd /usr/local/share/emacs/site-lisp
sudo wget https://raw.githubusercontent.com/emacsmirror/emacswiki.org/master/transpose-frame.el -O transpose-frame.el

C - Byte-compile that .el file into a .elc file

Now you need to compile that .el file:

sudo emacs --batch --eval (byte-compile-file "transpose-frame.el")

D - Add the program to your Spacemacs configuration

Open your config file using SPC f e d (files -> edit -> dotfile).

Add the program to your dotfile, for example:

(require 'transpose-frame)

Make sure to add it BEFORE the markers which say:

;; Do not write anything past this comment. This is where Emacs will
;; auto-generate custom variable definitions.

E - Reload the configuration

SPC f e R (Files -> Emacs/Spacemacs -> Reload configuration).

It might install/update some things, and then your new program should be available! Try to use it to test it out.

Hooray

Addendum - Explanations and things I’ve learned

Emacs load path

Here’s the load-path documentation. TL;DR: it’s where emacs finds libraries to load. Unless you messed around with it, your load-path includes /usr/local/share/emacs/site-lisp.

If you don’t want to add the extension to the global site-lisp, the convention in Linux is to usually have a $HOME/.local/share/emacs/site-lisp folder and manually add it to the load-path.

Byte-compile and accessing documentation

To understand what byte-compile-file does, you can read the documentation on the Emacs Wiki. But another good tip is to use SPC h d f (help -> describe -> function) to access the internal docs directly from within emacs. Here’s what I got for typing SPC h d f byte-compile-file ENTER:

byte-compile-file is an interactive autoloaded compiled Lisp function in
‘bytecomp.el’.

(byte-compile-file FILENAME &optional LOAD)

Compile a file of Lisp code named FILENAME into a file of byte code.
The output file’s name is generated by passing FILENAME to the
function ‘byte-compile-dest-file’ (which see).
With prefix arg (noninteractively: 2nd arg), LOAD the file after compiling.
The value is non-nil if there were no errors, nil if errors.

Also, Emacs might byte-compile things automatically after require.

Jumping between files easily

A few tricks:

  • Want to go back to a recent file you’ve just found? SPC f r (Files -> Recent)
  • Want to fuzzy-find files within your projects? SPC p f (Projects -> Helm Find File)

Inspired to write this post because of Ophir Harpaz’s immensely useful blog post, 2 GitHub Accounts 1 Computer - The Shortest Guide Possible. Thanks Ophir :)

See Also