Home

Awesome

Emacs For Common Lisp (Emacs4CL)

This repository provides a tiny .emacs file to set up Emacs quickly for Common Lisp programming. This document provides a detailed description of how to set it up and get started with Common Lisp programming.

View Source MIT License Mastodon

This repository provides a good middle ground between configuring Emacs manually by installing SLIME, Paredit, etc. yourself with M-x package-install commands and installing Portacle. It promotes a do-it-yourself approach to automate customizing Emacs for Common Lisp programming. Here is how the development environment is going to look like:

Screenshot of Emacs

If you are already comfortable with Emacs and only want to understand the content of the .emacs file, you can skip ahead directly to the Line-by-Line Explanation section that describes every line of this Emacs initialization file in detail.

Contents

Who Is This For?

Are you an absolute beginner to Emacs? Are you so new to Emacs that you do not even have ~/.emacs or ~/.emacs.d on your file system? Have you considered learning Common Lisp but when you picked up a book like Practical Common Lisp, you learnt that it recommends Emacs and SLIME for development environment and it seemed like a significant additional learning curve for you? If you answered "yes" to most of these questions, then this project is for you.

The .emacs file in this project provides you a quick way to get started with setting up your development environment. This document explains how to do so in a step-by-step manner. This document also explains the content of .emacs file in a line-by-line manner.

Get Started

This section helps you to set up Emacs for Common Lisp development quickly and see what the end result looks like. Perform the following steps to get started:

  1. Install SBCL and Emacs.

    On macOS, enter the following command if you have Homebrew:

    brew install sbcl
    brew install --cask emacs
    

    On Debian, Ubuntu, or another Debian-based Linux system, enter the following command:

    sudo apt-get install sbcl emacs
    

    For other environments, download SBCL and Emacs from http://www.sbcl.org/platform-table.html and https://www.gnu.org/software/emacs/ respectively.

  2. Copy the Emacs initialization file .emacs provided here to your home directory. Here is an example curl command that copies the initialization file to its traditional location:

    curl -L https://github.com/susam/emacs4cl/raw/main/.emacs >> ~/.emacs
    

    Here is another alternative that copies the initialization file to a more convenient location:

    mkdir ~/.emacs.d
    curl -L https://github.com/susam/emacs4cl/raw/main/.emacs >> ~/.emacs.d/init.el
    

    Yet another popular alternative is to copy the initialization file to an XDG-compatible location as follows:

    mkdir -p ~/.config/emacs
    curl -L https://github.com/susam/emacs4cl/raw/main/.emacs >> ~/.config/emacs/init.el
    

    Emacs can automatically load the Emacs initialization file from any of the paths used above. See section The Emacs Initialization File of the Emacs manual for more details about this. Most users these days prefer one of the last two locations because it allows all Emacs configuration to conveniently remain in one directory.

  3. Start Emacs:

    emacs
    

    On macOS, you may receive the following error message in a dialog box: '“Emacs.app” can’t be opened because Apple cannot check it for malicious software.' To resolve this issue, go to Apple menu > System Preferences > Security & Privacy > General and click 'Open Anyway'.

    It may take a minute or so for Emacs to start the very first time. When it starts the first time with the new Emacs initialization file obtained in the previous step, it installs the packages specified in it. This is only a one-time activity. The next time you start Emacs, it will start instantly. We will see how .emacs takes care of it in the line-by-line guide later.

  4. Within Emacs, start SLIME by typing the following key sequence:

    M-x slime RET
    

    In the Emacs world (and elsewhere too), the prefix M- denotes the meta modifier key. It does not exist on most modern keyboards. Use the <kbd>alt</kbd> key or the <kbd>option</kbd> key as a modifier key or <kbd>esc</kbd> as a prefix key to enter M-.

    For example, M-x is going to be <kbd>alt</kbd> + <kbd>x</kbd> or <kbd>option</kbd> + <kbd>x</kbd> or <kbd>esc</kbd> <kbd>x</kbd> on a modern keyboard.

    Similarly, RET denotes the <kbd>enter</kbd> key or the <kbd>return</kbd> key.

  5. After SLIME REPL starts, enter the following expression at the CL-USER> prompt and type <kbd>enter</kbd>.

    (format t "hello, world~%")
    

    If the output "hello, world" appears in SLIME REPL, the development environment setup is complete.

  6. Optionally, install Quicklisp with the following commands:

    curl -O https://beta.quicklisp.org/quicklisp.lisp
    sbcl --load quicklisp.lisp --eval "(quicklisp-quickstart:install)" --quit
    sbcl --load ~/quicklisp/setup.lisp --eval "(ql:add-to-init-file)" --quit
    

    Quicklisp helps in installing Common Lisp libraries from its repository. You do not need it when you have just begun learning Common Lisp. But as you grow more experienced with Common Lisp and begin developing real world applications, sooner or later, you will need Quicklisp to install libraries that help you solve your problems.

    The first command in the code block fetches quicklisp.lisp. The second command installs Quicklisp to ~/quicklisp. The third command adds some code to SBCL's initialization file at ~/.sbclrc, so that Quicklisp is automatically loaded when SBCL starts.

Now that your environment is setup, read the next section to learn how to use this environment in more detail.

Step-by-Step Usage

Use SBCL

Steel Bank Common Lisp (SBCL) is a high performance Common Lisp compiler. It runs on several Unix and Unix-like systems such as Linux, FreeBSD, macOS, etc. It also runs experimentally on Windows. It is the most popular free and open source implementation of Common Lisp as of December 2020. See the Opinion References section for survey results related to this.

The steps provided below show how to run SBCL independently. This is not a typical way to run SBCL because most of the time we interact with SBCL via SLIME right from within Emacs. However running it independently once helps one appreciate that it is an independent program that compiles and executes Common Lisp code. Here are the steps:

  1. Open your favourite editor, type this code, and save it as hello.lisp:

    (format t "hello, world~%")
    
  2. Then enter this command in the shell to run the program:

    sbcl --script hello.lisp
    
  3. Now start the SBCL Read-Eval-Print Loop (REPL) with the following command in the shell:

    sbcl
    
  4. An asterisk prompt appears. Enter a Common Lisp expression at the asterisk prompt like this and type <kbd>enter</kbd>:

    (+ 1 2)
    

    The result should appear as the output.

  5. Similarly, enter the following expression at the SBCL prompt and type <kbd>enter</kbd>:

    (format t "hello, world~%")
    
  6. Finally, enter the following expression and type <kbd>enter</kbd> to exit the SBCL REPL:

    (exit)
    

Use Emacs

Emacs is a very powerful and extensible editor. It comes with over 10,000 built-in commands. A small section like this can barely scratch the surface of Emacs. Yet, this section makes a modest attempt at getting you started with Emacs and then provides more resources to learn further. Perform the following steps to get started:

  1. Start Emacs:

    emacs
    
  2. Within Emacs, enter the following command to open a file, say, hello.txt:

    C-x C-f hello.txt RET
    

    A new buffer to edit hello.txt is created. If a file with that name already exists on your file system, then it loads the content of the file into the buffer.

    Note that in the Emacs world (and elsewhere too), the notation C- denotes the <kbd>ctrl</kbd> modifier key. Thus C-x denotes <kbd>ctrl</kbd> + <kbd>x</kbd>.

    The notation RET denotes the <kbd>enter</kbd> or <kbd>return</kbd> key.

    Typing consecutive C- key sequences can be optimized by pressing and holding down the <kbd>ctrl</kbd> key, then typing the other keys, and then releasing the <kbd>ctrl</kbd> key. For example, to type C-x C-f, first press and hold down <kbd>ctrl</kbd>, then type <kbd>x</kbd>, then type <kbd>f</kbd>, and then release <kbd>ctrl</kbd>. In other words, think of C-x C-f as C-(x f). This shortcut works for other modifier keys too.

  3. Now type some text into the buffer. Type out at least 3-4 words. We will need it for the next two steps.

  4. Move backward by one word with the following key sequence:

    M-b
    

    Remember from the previous section that M- denotes the meta modifier key. The above command can be typed with <kbd>alt</kbd> + <kbd>b</kbd> or <kbd>option</kbd> + <kbd>b</kbd> or <kbd>esc</kbd> <kbd>b</kbd>.

    If you face any issue with the <kbd>alt</kbd> key or the <kbd>option</kbd> key, read Emacs Wiki: Meta Key Problems.

  5. Now move forward by one word with the following key sequence:

    M-f
    
  6. The C-g key sequence cancels the current command. This can be used when you mistype a command and want to start over or if you type a command partially, then change your mind and then you want to cancel the partially typed command. Try out these examples:

    C-x C-f C-g
    
    C-x C-g
    
  7. Save the buffer to a file on the file system with this command:

    C-x C-s
    
  8. Quit Emacs:

    C-x C-c
    

Now you know how to start Emacs, open a file, save it, and quit. Improve your Emacs knowledge further by taking the Emacs tutorial that comes along with Emacs. In Emacs, type C-h t to start the tutorial.

The key bindings to perform various operations like creating file, saving file, quitting the editor, etc. may look arcane at first, but repeated usage of the key bindings develops muscle memory soon and after having used them for a few days, one does not even have to think about them. The fingers do what the mind wants effortlessly due to muscle memory.

While you are getting used to the Emacs key bindings, keep this GNU Emacs Reference Card handy.

Use SLIME

Superior Lisp Interaction Mode for Emacs (SLIME) is a very popular Emacs mode that adds support for interacting with a running Common Lisp process for compilation, debugging, document lookup, etc. while developing Common Lisp applications. Perform the following steps to get started with it:

  1. Start Emacs:

    emacs
    
  2. Within Emacs, start SLIME by typing the following key sequence:

    M-x slime RET
    

    Remember that M-x translates to <kbd>alt</kbd> + <kbd>x</kbd> or <kbd>esc</kbd> <kbd>x</kbd> on a modern keyboard.

  3. A new buffer named *slime-repl sbcl* should have now appeared with the following prompt:

    CL-USER>
    

    This is a Read-Eval-Print-Loop (REPL) where you can evaluate Common Lisp expressions.

  4. Enter the following expression in the REPL:

    (+ 1 2)
    

    The following result should appear when you type <kbd>enter</kbd>:

    3
    
  5. We will now see how to work on a Lisp source file and send expressions to the REPL for evaluation using SLIME commands without having to leave Emacs. First, create a buffer for a new file, for example:

    C-x C-f foo.lisp
    
  6. Now enter this Lisp code into the buffer for foo.lisp:

    (+ 1 2)
    
  7. While the cursor is placed after the closing parenthesis (not on it, but after it), type the following command:

    C-x C-e
    

    The result 3 should appear in a minibuffer at the bottom.

There is a lot more to SLIME than what is described above. To learn more about SLIME, see Slime User Manual. Also, keep this Slime Quick Reference Card handy.

Use Paredit

Paredit helps in keeping parentheses balanced and also in performing structured editing of S-expressions in Lisp code. It provides a powerful set of commands to manipulate S-expressions in various ways. Perform the following steps to get started with Paredit:

  1. Run Emacs:

    emacs
    
  2. Open a Common Lisp source file:

    C-x C-f foo.lisp
    
  3. Type the following code only:

    (defun square (x
    

    At this point, Paredit should have inserted the two closing parentheses automatically. The code should look like this:

    (defun square (x))
                    -
    

    The cursor should be situated just after the parameter x. The underbar shows where the cursor should be.

  4. Type the closing parentheses now. Yes, type it even if the closing parenthesis is already present. The cursor should now skip over the first closing parenthesis like this:

    (defun square (x))
                     -
    

    Of course, there was no need to type the closing parenthesis because it was already present but typing it out to skip over it is more efficient than moving over it with movement commands. This is, in fact, a very nifty feature of Paredit. We can enter code with the same keystrokes as we would without Paredit.

  5. Now type <code>enter</code> to create a new line just before the last parenthesis. A newline is inserted like this:

    (defun square (x)
      )
      -
    
  6. Now type only this:

    (* x x
    

    Again, Paredit would have inserted the closing parenthesis automatically. The code should look like this now:

    (defun square (x)
      (* x x))
            -
    

There is a lot more to Paredit than this. To learn more, see The Animated Guide to Paredit.

Note: While many Lisp programmers find Paredit very convenient and powerful while manipulating S-expressions in Lisp code, there are a few people who do not like Paredit because they find the Paredit behaviour intrusive. See the Opinion References section for more discussion on this topic.

Use Rainbow Delimiters

There is not much to learn about using Rainbow Delimiters. In the previous sections, you must have seen that as you type nested parentheses, each parenthesis is highlighted with a different color. That is done by Rainbow Delimiters. It colors each parenthesis according to its nesting depth level.

Note: Not everyone likes Rainbow Delimiters. Some people find parentheses in multiple colors distracting. See the Opinion References section for more discussion on this topic.

Use Quicklisp

This is an optional section for beginners to Common Lisp. Quicklisp helps in installing Common Lisp libraries from its repository. You would not need it when you are just learning Common Lisp as a beginner. But as you grow more experienced with Common Lisp and begin developing real world applications, sooner or later, you will need Quicklisp to install libraries that help you solve your problems.

Ensure that you have installed Quicklisp as specified in the Get Started section. Then follow these steps to become familiar with Quicklisp:

  1. Start Emacs:

    emacs
    
  2. Within Emacs, start SLIME by typing the following key sequence:

    M-x slime RET
    
  3. Open a new file, say server.lisp with the following key sequence:

    C-x C-f server.lisp
    
  4. Enter the following code into the buffer for the new file:

    (ql:quickload "hunchentoot")
    (hunchentoot:start (make-instance 'hunchentoot:easy-acceptor :port 4242))
    

    The first line fetches and loads Hunchentoot from Quicklisp. Hunchentoot is a popular Common Lisp web server toolkit for building dynamic websites. The second line uses Hunchentoot to start a web server listening on TCP port 4242.

  5. Evaluate the whole buffer with the following key sequence:

    M-x slime-eval-buffer RET
    
  6. Visit http://127.0.0.1:4242/ with your web browser. A web page with a welcome message from Hunchentoot should appear.

Line-by-Line Explanation

This section explains the .emacs file provided here line-by-line.

Tweak UI

The first few lines in our .emacs merely tweak the Emacs user interface. These are of course not essential for Common Lisp programming. However, many new Emacs users often ask how to customize the user interface to add a good color scheme and make it look minimal, so this section indulges a little in customizing the user interface. The actual Common Lisp related customization begins in the next section: Highlight Parentheses.

Here is a line-by-line explanation of the UI tweaks in .emacs:

Use Spaces for Indentation

The following point shows how to configure Emacs to insert spaces, not tabs, for indenting code.

Highlight Parentheses

The following points describe how we enable highlighting of parentheses:

Install Packages

The following points describe how we automate the installation of Emacs packages we need. These points are essential to Common Lisp programming with Emacs:

Inferior Lisp Program

The following steps describe setting up the inferior-lisp-program variable so that Emacs can use SBCL to load and execute SLIME:

Add Hooks

This section describes how to enable Paredit and Rainbow Delimiters. These are not absolutely essential for having an interactive programming environment for Common Lisp. However many programmers find them useful while some do not.

In case you decide not to use either Paredit or Rainbow Delimiters, then you may skip this section. In that case, you might also want to remove these packages from the dolist expression of .emacs.

You may have noticed that we did not enable Rainbow Delimiters for eval-expression. That is because it does not work as expected as of Dec 2020. See https://github.com/Fanael/rainbow-delimiters/issues/57 for more details.

Colorful Parentheses

The default colors that the Rainbow Delimiters package chooses for the nested parentheses are too subtle to easily recognize the matching pair of parentheses. Some Lisp programmers like to customize the colors to make the parentheses look more colorful. This section shows one way to do this.

More Emacs Customization

This project focusses primarily on setting up a Common Lisp development environment. If you want to enhance your Emacs setup from being a Common Lisp development environment to being a more general purpose editing and programming environment, please see my new project Emfy. Emfy is similar to this project, however, Emfy offers more customization to make Emacs easier to use for general purpose editing and programming.

Alternatives

There are two popular alternatives to Emacs4CL:

Both are good alternatives to Emacs4CL. Since Lem is a completely different editor, there is not much to compare between Lem and Emacs4CL. Lem offers an appealing option for those who prefer to engage in Common Lisp development activities using an editor that is written in Common Lisp itself.

Portacle, however, is Emacs packaged with custom packages, configuration, and Common Lisp tools. Portacle tucks away the underlying details of what goes into making Emacs ready for Common Lisp development in its rather large configuration directory. Since Portacle is still Emacs, to use Portacle effectively, you have to learn Emacs and SLIME anyway. If you are going to learn Emacs and SLIME anyway, you might as well set it up yourself. Then you can add only those customizations to Emacs that you need instead of Portacle deciding what your Emacs experience should be like.

Emacs4CL provides a good middle ground between setting up Emacs from scratch manually and installing Portacle. It promotes a do-it-yourself approach to setting up Emacs for Common Lisp programming. More importantly, it helps you understand each step of the work that goes into customizing Emacs as an environment for Common Lisp programming.

Opinion References

Channels

The following channels are available for asking questions, seeking help and receiving updates regarding this project:

You are welcome to follow or subscribe to one or more of these channels to receive updates and ask questions about this project.

License

This is free and open source software. You can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of it, under the terms of the MIT License. See LICENSE.md for details.

This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND, express or implied. See LICENSE.md for details.