Common Lisp bindings for SDL2 using C2FFI.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Michael Fiano 80410b5145
Update author email contact in README.
5 months ago
examples Check the program variable. 4 years ago
src Add render-fill-rect-f and render-fill-rects-f 5 months ago
.gitattributes Add .gitattributes to tell github .spec files are lisp 4 years ago
.gitignore Add basic render drawing functions 8 years ago
LICENSE Include license text 7 years ago Update author email contact in README. 5 months ago
sdl2.asd Add nicer wrapper around the Hints API 6 months ago


cl-sdl2 is a Common Lisp wrapper for the SDL 2.0 C Library, with many contributors, currently maintained by Michael Fiano

It is licensed under the MIT license.


sdl2 is in Quicklisp, see below for instructions.

SDL 2.0 C Library Install


On Linux, you can probably find SDL2 in your distribution's package set. For other platforms, or for building manually, download the source.


  • Debian based: Ubuntu, Mint etc
sudo apt-get install libsdl2-2.0
  • Arch
sudo pacman -S sdl2


If you need to compile from source for your Linux platform:

  1. Download source code
  2. Compile
  3. Install

For example:

cd /tmp
tar -xzvf SDL2-2.?.?.tar.gz
cd SDL2-2.?.?
sudo make install

This will install the SDL-2.0.x C Library into your /usr/local location.

It's generally a good idea to install at a minimum the version of SDL2 that was wrapped; however, sub revisions should not introduce binary incompatibility and should be fine. If you install a different version, certain features may not be available or may not work correctly.

Quicklisp Install

sdl2 is best installed via QuickLisp, though for cutting-edge changes, you may want to install from github as below.

If you don't have Quicklisp, then follow the directions to install it. We assume you placed the Quicklisp repository in the default place as indicated by the directions and have added it to your lisp init file.

github install

cd $HOME/quicklisp/local-projects
git clone
git clone

Then, use quicklisp to install the libraries required by cl-sdl2:

Start your lisp. Then, just:

(ql:quickload "sdl2")

Swank/Slynk features

sdl2 enables certain restarts for friendly interaction with SLIME or Sly if you have either properly installed. "Proper installation" in this case means swank.asd or slynk.asd is linked such that ASDF can find and load it.

Note this is easily achieved even if you have installed them from github or some other non-Quicklisp repository:

  • Symlink the directory to $HOME/quicklisp/local-projects/
  • Symlink the .asd to $HOME/.local/common-lisp/sources/

Similarly you could just clone into ~/quicklisp/local-projects as well; this should work on Windows as well. There are numerous other options for configuring and managing ASDs, as well.

Running the sdl2 examples

Start your lisp:

(ql:quickload :sdl2/examples)

This example will open a window with an opengl primitive in it. Any mouse movements or keystrokes are recorded in the terminal (or emacs SLIME output buffer *inferior-lisp*). Hitting the ESCAPE key will terminate the example.


Newer versions of OSX have had some difficulties as calls which require nextEventMatchingMask must be called from the main thread of your program.

This is especially relevant to SBCL, although issues have also been noticed in CCL.

Currently, initialisation must take place on your main thread:

(ql:quickload :sdl2/examples)

;; We should be able to run examples as normal on CCL
#-sbcl (sdl2-examples:basic-test)

;; SBCL requires that we initialise in the main thread
#+sbcl (sdl2:make-this-thread-main #'sdl2-examples:basic-test)

Thank you for using sdl2!