# Day 3: Roswell: Common Lisp scripting

Hi, all Common Lispers.  
🎊 And, happy new year in 2022! 🎍

I'm happy that you came to this blog again this year 😆

I explained how to install Lisp implementations, libraries, and applications with Roswell until the previous article.

* [Day 2: Roswell: Install libraries/applications](https://fukamachi.hashnode.dev/day-2-roswell-install-libraries-and-applications)

Today, I can finally introduce a different aspect of [Roswell](https://github.com/roswell/roswell) -- as a scripting supporter.

## Scripting in Common Lisp world

Let's think about writing a script in Common Lisp.

It has to accept input as a shell command, execute some code, and quit.

How to achieve it in the REPL first language? In SBCL, the `--script` option is just for it.

```shell
$ sbcl --script hello.lisp
```

Using this in shebang, it works as a shell command.

```shell
#!/usr/local/bin/sbcl --script

(write-line "Hello, World!")
```

Save this code as a "hello.lisp" file and give it execute permission.

```
$ ./hello.lisp
Hello, World!
```

Good work. But, this requires SBCL to be installed at "/usr/local/bin/sbcl". If it's installed at the other location, the shell raises an error:

```
$ ./hello.lisp
-bash: ./hello.lisp: /usr/local/bin/sbcl: bad interpreter: No such file or directory
```

This problem is not limited to Common Lisp but also in Python, Ruby, and other languages. A standard solution is to rewrite shebang using `/usr/bin/env`.

```shell
#!/usr/bin/env -S sbcl --script

(write-line "Hello, World!")
```

The `-S` option is specified to make `/usr/bin/env` accept options. If you don't specify it, an error will occur trying to find the program named "sbcl --script".

Command-line arguments can be accessed via `sb-ext:*posix-argv*`. Looks good, huh?

## Is it portable enough?

Of course, this only works with SBCL, but it's not so bad for UNIX-like OSes where SBCL is installed. Not often, but I use this method in Docker containers.

However, what if you want to write a Common Lisp application with a command-line interface that is supposed to run in various environments. Is the SBCL script portable enough?

First of all, it's not easy to load libraries via Quicklisp. Because `sbcl --script` doesn't read `.sbclrc`, and don't load Quicklisp even if it's installed.

Besides, it also becomes more difficult if you are aiming for a general-purpose script, such as if you want to run it on other implementations or if you want to support Windows.

## Roswell Script

"Roswell script" is a good option in that case.

Start writing a Roswell script that outputs "Hello, World!". `ros init` is a command to create a template for a Roswell script.

```
$ ros init hello-world
Successfully generated: hello-world.ros
```

The output file ending with `.ros` will look like the following:

```lisp
#!/bin/sh
#|-*- mode:lisp -*-|#
#|
exec ros -Q -- $0 "$@"
|#
(progn ;;init forms
  (ros:ensure-asdf)
  #+quicklisp(ql:quickload '() :silent t)
  )

(defpackage :ros.script.hello-world.3848003839
  (:use :cl))
(in-package :ros.script.hello-world.3848003839)

(defun main (&rest argv)
  (declare (ignorable argv)))
;;; vim: set ft=lisp lisp:
```

It will be bewildering at first, so let's take a look at what it does, part by part.

### Line 1-5: Hack to make the startup portable

The first 5 lines are for hacking to make the startup process portable. You don't need to know how these lines work, but I'm writing this just for curious people.

```shell
#!/bin/sh
#|-*- mode:lisp -*-|#
#|
exec ros -Q -- $0 "$@"
|#
```

The terminal reads the first line as its shebang and launches the program with `/bin/sh`. `#` is a comment in the shell, so the 2-3 lines are skipped. Next, the shell comes to the `exec ros` line and finally invokes `ros`.

The second launch is with `ros`. `ros` will skip the first shebang. Also, inside of `#|` to`|#` will be ignored since it's a multi-line comment in Common Lisp. Then, execute the code below as Common Lisp.

### Line 6-9: Initial forms

Lines 6 to 9 are the place to write the code for initialization.

```lisp
(progn ;;init forms
  (ros:ensure-asdf)
  #+quicklisp(ql:quickload '() :silent t)
  )
```

Mainly, this is for loading external libraries.

I asked the Roswell author, [@snmsts](https://github.com/snmsts), something like, "Is there any significance to write external dependencies here?" He said, "I think it would be treated special when it's built to the binary, but I don't remember much. That is for fast startup, maybe?"

After some investigation, he found it didn't work as intended. Nowadays, it seems to remain merely a good manner to list all dependencies in one place.

### After Line 10: Main part

The rest of the file is a normal Common Lisp program.

```lisp
(defpackage :ros.script.hello-world.3848003839
  (:use :cl))
(in-package :ros.script.hello-world.3848003839)

(defun main (&rest argv)
  (declare (ignorable argv)))
```

The `main` function is always required. It will be the entry function when the Roswell script is executed. It takes command-line arguments as a list of strings.

There are no restrictions on defining other functions and so on. This part can be written like a regular program.

## Benefits of Roswell script

Why should you write a script in a Roswell manner? There are 3 benefits to writing Roswell scripts.

First of all, the Roswell script is independent of Lisp implementations. `sbcl --script` obviously doesn't work other than SBCL; however, the Roswell script works every Lisp supported by Roswell.

The second benefit is automatic script installation with `ros install`.

I introduced `ros install` in "Day 2", which is for installing Common Lisp applications/libraries. Not only placing files, but also it treats Roswell scripts special. When the application has a directory named `roswell`, copy all scripts under it into `~/.roswell/bin`. This is the reason why you can use the `qlot` command right after running `ros install fukamachi/qlot`.

The last one is binary-build.

Roswell scripts can be built as a binary by running `ros build`. It can be a boon as it skips reading a file, compilations, and loading external libraries.

To summarize,

* Lisp implementation portable
* Automatic installation with `ros install`
* Allow building a binary with `ros build`

These benefits make it the perfect way to distribute a general-purpose application and provide its command-line interface.

## Examples

At last, I introduce the real examples of Roswell scripts. See inside `~/.roswell` directory of those projects.

* [Qlot](https://github.com/fukamachi/qlot)
  * A project-local library installer
  * Provides `qlot` command to install/update project dependencies and utilize them.
* [Clack](https://github.com/fukamachi/clack)
  * Web server abstraction layer
  * Provides `clackup` command to start a web application.
* [lem](https://github.com/lem-project/lem)
  * Common Lisp editor/IDE with high expansibility
  * Provides `lem` command to start an editor.
