Setting up your Lisp environment

Emacs is going to be the best text editor for Common Lisp. However emacs will also require you to do some learning as it is more complicated than vscode or Atom. If you’d like to use Emacs, then I would recommend installing Spacemacs which is an Emacs configuration that gives you a comfortable experience out of the box. Without it, Emacs is a weird and confusing esoteric text editor that is difficult to learn. To start using Spacemacs, just clone the GitHub repository to your home directory and you’re good to go. To do that, it should be something like this:

$ git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d

Then, you need to install actual Emacs. Spacemacs is just a set of configuration files for Emacs and doesn’t ship with Emacs itself. The instructions to install Emacs for Windows, MacOS and Linux can be found on the Emacs website.

Once installed, running Emacs should start up the Spacemacs configuration.

Once Spacemacs is done installing everything, it will prompt you a couple of times for basic things you want in your configuration. The only one that will really matter to you is whether you want to use Emacs keybindings or Evil-mode. If you know Vim, use evil-mode. If you don’t know Vim, I would still recommend evil-mode if you’re willing to do a little bit more learning.

Once installed, open up your Common Lisp file. Spacemacs will ship with a package called SLIME (Superior Lisp Interaction Mode for Emacs) which is what you use in Emacs for executing your Lisp code. After opening your file, hit SPC m s i to start SLIME. You’ll see another window open, and that’s where you’re going to execute your code. If you hit the keys SPC m c l then your entire file will be compiled and you can navigate over to the other window to call your functions from the file. For example, if I have the following file:

(defun add (a b)
  (+ a b))

(let ((x 10) (y 20))
  (print (add x y)))

And I start SLIME with SPC m s i and then load the file, then it will first print out the sum of 10 and 20, then put you in a REPL where you can interact with the program. So you can do (add 10 20) and it’ll have that file compiled and loaded into the running process. To make changes to your code you can just go back to your file and hit SPC m c l again to re-load the whole file. If you only want to reload the function you’ve changed, then you can do SPC m c f and it will compile the function that you’re currently focused on. If you want to run a sequence of expressions to test your code, then you can select the lines for all the expressions you want to evaluate, then do SPC m e r to evaluate that region.

There’s tons more things that you can do, all of the hotkeys are available to look at by hitting SPC m and then waiting a second to see all the possible hotkeys show up at the bottom of the frame.

Visual Studio Code is probably what most people use for this course. It won’t have as good of support as Emacs, but it will be easier to use.

To install Visual Studio Code you can go to it’s website and download from there.

Side-note: VSCode without the telemetry The source code for Visual Studio Code is free and open source, however the binaries that Microsoft releases on their website are under a different license and have telemetry and reporting software bundled in. If you don’t like that, you can download pre-built binaries of vscode without the telemetry from the vscodium project. VSCodium is the same thing just without the telemetry. Everything in this guide is the same for both vscode and vscodium.

For writing Lisp in vscode, there’s 3 primary extensions that I would recommend installing.

1. Syntax highlighting Gotta have syntax highlighting, right?
2. Rainbow Brackets This will help make your code much more legible by highlighting each level of parentheses a different colour, which helps you see matching parentheses more easily.

3. parinfer This plugin helps make writing Lisp code feel more like Python. It automatically managers your parentheses for you based on the indentation of your code. Which a) means you don’t have to manage them yourself and b) forces your code to be formatted properly.

   With these installed, there’s two ways that you can execute your code from inside vscode - either using the terminal, or telling vscode how to execute it with a run button.

Atom is another popular editor that people use for this class and it has pretty decent support for Common Lisp.

For writing Lisp in Atom, there’s 4 primary extensions that I would recommend installing.

1. Syntax highlighting Gotta have syntax highlighting, right?
2. Rainbow Brackets This will help make your code much more legible by highlighting each level of parentheses a different colour, which helps you see matching parentheses more easily.
3. parinfer This plugin helps make writing Lisp code feel more like Python. It automatically managers your parentheses for you based on the indentation of your code. Which a) means you don’t have to manage them yourself and b) forces your code to be formatted properly.
4. SLIMA The Superior Lisp Interaction Mode for Atom. Heavily inspired from a similar plugin for Emacs, it’s probably the best way to run Lisp code inside Atom.

With these installed, there’s two ways that you can execute your code from inside vscode - either using the terminal, or through SLIMA.

I’ve never used SLIMA before however, so I would recommend that you read through the page for it linked about that guides you through setting it up and using it.

Vim isn’t a super popular editor for students in this class, but if you use Vim then you use Vim.

For writing Lisp in Vim, there’s 3 primary extensions that I would recommend installing.

1. Rainbow Brackets This will help make your code much more legible by highlighting each level of parentheses a different colour, which helps you see matching parentheses more easily.
2. parinfer This plugin helps make writing Lisp code feel more like Python. It automatically managers your parentheses for you based on the indentation of your code. Which a) means you don’t have to manage them yourself and b) forces your code to be formatted properly.

3. SLIMV The Superior Lisp Interaction Mode for Vim. Very heavily inspired from a similar plugin for Emacs, it’s probably the best way to run Lisp code inside Vim.

   Note that I am not a vim user myself and have no idea how well these plugins work.

Surprise! Portacle is actually just Emacs! Scroll back up to my recommendations for using Emacs instead of using Portacle right out of the box.

Ultimately, any text editor will work for writing your Lisp code. Notepad++, Sublime, etc. If you use any of these other editors though, I’d highly recommend taking some time to figure out what the best plugins for working with Lisp are because it will really be helpful.

Unless you find a plugin that supports executing code from the editor, you’ll also probably need to learn to compile your lisp code in the terminal/command line. I’d recommend reading about running from the terminal to familiarize yourself with the commands.