Lisp for the web -5

These are the most popular posts which dealt with the topic before my post. Please feel free to check them out if you want to have more perspective on web development with Lisp.

• List for the Web

• Lisp for The Modern Web

• Lisp & the Web

To get started with Lisp for Web development, you basically need two things. A Lisp implementation installed on your machine and an editor with IDE like capabilities to develop web applications with lisp. I am using SBCL as my Lisp implementation and Emacs as my editor. You are free to choose any editor for the task but nothing comes close to Emacs for editing Lisp code. It is the perfect tool for the job at hand.

Steel Bank Common Lisp (SBCL) is a high performance Common Lisp compiler. It is open source / free software, with a permissive license. In addition to the compiler and runtime system for ANSI Common Lisp, it provides an interactive environment including a debugger, a statistical profiler, a code coverage tool, and many other extensions.

SBCL runs on a number of POSIX platforms, and experimentally on Windows. See the download page for supported platforms, and getting started guide for additional help.

Installing SBCL on Ubuntu

sudo apt-get install sbcl

Installing SBCL on Mac using Homebrew

brew install sbcl

Once you have installed SBCL in your machine, you can start playing around in the REPL by invoking it from the command line.

sbcl

You can type in any Lisp expression in the REPL and get the result immediately.

CL-USER> (+ 1 2)
3

Once you installed SBCL , the next step is to setup Quicklisp. Quicklisp is a library manager for Common Lisp. It works with your existing Common Lisp implementation to download, install, and load any of over 1,500 libraries with a few simple commands. It's like npm for Node.js, cargo for Rust and similar to other package managers for other language implementations. Go to their home page and refer to the installation instructions for how to install and setup quicklisp for your Lisp implementation.

Next comes our editor which is Emacs. Emacs is an extensible, customizable and free text editor, which is, at its core, an interpreter for Emacs Lisp. So what this basically means is that, it has got built in support for editing Lisp code. You can go to their website and follow the instructions for installing on various operating systems and platforms. Emacs has also got a ton of awesome stuff like org-mode, a built-in file explorer called dired and so on. It is an operating system within itself.

SLIME is a Emacs mode for Common Lisp development. It is an environment for hacking Common Lisp. It has got a Common Lisp debugger, REPL (Read-Eval-Print-Loop) which is written in Emacs Lisp for tighter integration with Emacs and an interactive object-inspector. So this is a must have addon for Emacs if you are interested in doing serious Lisp. Once you installed Emacs, you can install slime with `M-x package-install` and then type `slime` and press Enter. You can also refer to the Quick setup instructions on their github README to quickly configure SLIME.

You can start SLIME with `M-x slime` which is `Alt` or `Meta` key + x and then type `slime` and enter. It will start the default Lisp program you configured (SBCL in our case) before, within Emacs itself. You can play around in the interpreter just like you did with SBCL earlier.

Once you are ready with your IDE setup and the required tools installed in your machine, it's time to do the real job. Creating a web application project with Lisp. In the older posts I mentioned above, there were really no frameworks used for setting up and developing web applications for Lisp. They were just hand-made, plain and simple. But if you want to have scalable and maintainable code base for your web applications you need to have some sort of conventions on how you organize your Lisp code for building websites and applications. Having used frameworks like Ruby on Rails and Express.js, I am naturally inclined to bootstrap our project with a framework. Because conventions make you productive in the long run, it save you from making arbitrary decisions about how you organize your code and make your codebase maintainable in the future.

Hence I chose Caveman for this project. After having been played around with and without Caveman for building web applications in Common Lisp, I found that it is the best framework out there for developing web apps in Lisp. Caveman is a lightweight web application framework created by Eitaro Fukamachi for Common lisp. Fukamachi has got some serious tools for doing web development in Lisp. Please feel free to check out his Github profile for more useful tools.

Caveman is available on Quicklisp, so you can install it with:

(ql:quickload :caveman2)

And this is how you can generate a project skeletion with Caveman:

(caveman2:make-project #P"~/quicklisp/local-projects/hello-caveman" :author "Rajasegar")

This will generate a project folder in "~/quicklisp/local-projects", which is the default location from where you can load your projects into Quicklisp. So which means you can load our newly created app in quicklisp like below:

(ql:quickload :hello-caveman)

Your application has functions named start and stop to start/stop your web application. So you can start the development web server like this:

(hello-caveman:start :port 3000)

Open your browser and visit the url `http://localhost:3000`. You will get a blank web page saying `Welcome to Caveman2`.

(defroute "/about" ()
  (render #P"about.html"))

(in-package :cl-user)
(defpackage super-rentals.web
  (:use :cl
        :caveman2
        :super-rentals.config
        :super-rentals.view
        :super-rentals.db
        :datafly
        :sxql)
  (:export :*web*))
(in-package :super-rentals.web)

;; for @route annotation
(syntax:use-syntax :annot)

;;
;; Application

(defclass <web> (<app>) ())
(defvar *web* (make-instance '<web>))
(clear-routing-rules *web*)

;;
;; Routing rules

(defroute "/" ()
  (render #P"index.html"))

(defroute "/about" ()
  (render #P"about.html"))

;;
;; Error pages

(defmethod on-exception ((app <web>) (code (eql 404)))
  (declare (ignore app))
  (merge-pathnames #P"_errors/404.html"
                   *template-directory*))

<h1>About page</h1>
<p>This is the about page</p>

/* static/css/main.css */
h1 {
color: red;
}

{% extends "layouts/default.html" %}
{% block title %}Lisp for the web{% endblock %}
{% block content %}
<div id="main">
  <h1>Lisp for the Web</h1>
  <nav>
    <ul>
      <li><a href="/">Home</a></li>
      <li><a href="/about">About</a></li>
    </ul>
  </nav>
  <p>Source Code: <a href="https://github.com/rajasegar/lisp-for-the-web">Github</a></p>
</div>
{% endblock %}

Now we will see how to deploy our Common Lisp web app to the cloud. I am using Heroku for it. Heroku is a powerful PaaS (Platform as a Service) provider which has got a ton of features for building and deploying web applications. It has got a cool CLI tool with which you can deploy your apps in just minutes, you can view the logs from your command line , use custom buildpacks and so much more. I have been using Heroku for a decade now, and I have a lot of demos created in it. So for our app, we are going to use the same.

First we need to heroku CLI tool to be installed in our machine. You can visit the heroku-cli official page for instructions on how to install in various platforms. Once you installed the heroku CLI, for creating a new app all you need to do is just fire this command from the project folder.

heroku apps:create my-awesome-app

But for our Lisp application, this is not enough, becuase we don't have inbuilt support for Lisp language within Heroku platform, so we are going to use something called buildpacks.

Buildpacks are the scripts that power app builds on Heroku. They are composed of a set of scripts, and depending on the programming language, the scripts will retrieve dependencies, output generated assets or compiled code, and more. This output is assembled into a slug by the slug compiler. Heroku’s support for Ruby, Python, Java, Clojure, Node.js, Scala, Go and PHP is implemented via a set of open source buildpacks. Heroku maintains a collection of officially supported buildpacks that are available by default to all Heroku apps.

So for our Common Lisp web application to be properly deployed into Heroku, we need a custom buildpack. Fortunately there are so many Common Lisp buildpacks created by some awesome people for deploying Lisp web apps into the Heroku platform. We are going to use one of them, called `heroku-buildpack-roswell` created by gos-k. So how we are going to use this buildpack. We need to pass a flag `–buildpack` with the url of the buildpack to our heroku command like this.

heroku apps:create my-awesome-app --buildpack https://github.com/gos-k/heroku-buildpack-roswell

This tells Heroku to use the custom buildpack for building our Common Lisp web apps and deploy them. But before creating the app we need to do some setup in our project for the buildpack to work. The buildpack is based on roswell.

clack

sbcl-bin

clack

web: clackup --port $PORT --address 0.0.0.0 app.lisp

;; app.lisp
(push #p"/app/" asdf:*central-registry*)

git push heroku master