Getting Started

Requirements

Linux or Windows.
git 2.29 or later; on Windows, Git for Windows.
For the executable of a release: Linux on x86-64, with glibc 2.38 or later, as Debian 13, Ubuntu 24.04 and Fedora 39 have.
Elsewhere, as on Windows: SBCL, to build the stift executable from a clone.

The Lisps stift runs may be SBCL or CCL; on Windows, CCL's program is wx86cl64. stift loads no other Lisp library.

Installing a release

Each release on stift's releases page carries the executable for Linux on x86-64, built with the SBCL release that stift's suite passed on just before:

stift-VERSION-linux-x86_64.tar.gz holds stift, LICENSE and README.org in a directory of the same name;
stift-VERSION-linux-x86_64.tar.gz.sha256 holds its SHA-256 checksum.

Download both, check the archive, unpack it and copy stift into a directory on your PATH. With version set to the release's version, without its v:

base=https://fakehacker.cc/dxtr/stift/releases/download/v$version
curl -fLO "$base/stift-$version-linux-x86_64.tar.gz"
curl -fLO "$base/stift-$version-linux-x86_64.tar.gz.sha256"
sha256sum -c "stift-$version-linux-x86_64.tar.gz.sha256"
tar xzf "stift-$version-linux-x86_64.tar.gz"
install -D "stift-$version-linux-x86_64/stift" ~/.local/bin/stift

The executable holds SBCL itself, so it needs no Lisp to run; the Lisps it starts are yours. The checksum beside the archive catches a damaged download, not a release changed on the server.

Building from a clone

git clone https://fakehacker.cc/dxtr/stift.git
cd stift
sbcl --script install.lisp

install.lisp builds bin/stift, or bin\stift.exe on Windows, an executable of about 40 MB that holds SBCL itself, and copies it into the directory XDG_BIN_HOME names, or else .local/bin in your home directory: ~/.local/bin on Linux, %USERPROFILE%\.local\bin on Windows. A directory named after it goes first:

sbcl --script install.lisp /usr/local/bin

It tells you when the directory is not on your PATH. The command reads the same in sh, cmd.exe and PowerShell, and needs nothing but SBCL: no Quicklisp and no make. The copy is written beside its place and renamed into it, so a link there to the clone's own bin/stift is replaced rather than written through.

Once stift is installed, stift build in the clone rebuilds bin/stift (see Building Programs).

stift is built with SBCL even for running CCL, because CCL's run-program starts every program in a process group of its own, which would leave an interactive Lisp in the background of the terminal.

A first project

A project is a directory, usually a git repository, with its .asd files:

;;; hello.asd
(defsystem "hello"
  :depends-on ("alexandria")
  :components ((:file "hello"))
  :perform (test-op (op c)
             (unless (equal '(1 2 3) (uiop:symbol-call :hello :numbers))
               (error "hello's tests failed."))))

;;; hello.lisp
(defpackage #:hello (:use #:cl) (:export #:numbers))
(in-package #:hello)
(defun numbers () (alexandria:flatten '(1 (2 (3)))))

stift init writes its stiftfile, naming the project by its repository's host and path, given as a name or a URL, by default that of the git remote origin. stift get requires a project, fetches it into the cache and records its commit, with an indirect entry for each project it requires in turn:

stift init example.org/me/hello
stift get https://gitlab.common-lisp.net/alexandria/alexandria.git
stift list

example.org/me/hello                          main project
gitlab.common-lisp.net/alexandria/alexandria  f283e25efbe9  branch master

stift exec starts a Lisp with the build list, and stift test runs the project's test suites, each in a new Lisp:

stift exec sbcl --non-interactive --eval '(asdf:load-system "hello")' \
                --eval '(print (hello:numbers))'
stift test --lisp sbcl --lisp ccl

ok    hello  sbcl  0.2s
ok    hello  ccl   1.0s

Commit the stiftfile: it is what another machine needs to build the project the same way.

stift's own tests

stift's suite needs git, and sbcl and ccl on the PATH, but no network: every repository it uses, it makes. It runs on Linux and on Windows, where CCL's wx86cl64.exe answers to ccl when copied to ccl.exe beside it, with its image as ccl.image. stift runs it, with Parachute from its own stiftfile:

bin/stift test --lisp sbcl --lisp ccl

stift

Reference

API Reference