8.8 KiB
Install
CIEL can be used in two different roles:
- As a library that you can load into any Common Lisp implementation.
- As a binary based on
sbcl, which is a command-line tool for use in the terminal or in shell scripts. It provides a more feature-rich REPL than standardsbcl, and a much faster startup time than startingsbcland then loading the CIEL library.
If you use a Lisp development environment, such as Emacs with Slime, you should opt for the library rather than the binary. To get the same fast startup time, you can use a prebuilt core image, as we will explain below.
In the following, we will explain how to install the library, the binary, and the prebuilt core image, for various common SBCL setups.
Download a prebuilt binary.
To download a CIEL binary:
- check our releases on https://github.com/ciel-lang/CIEL/releases/
- we provide a binary from a CI for some systems: go to
https://gitlab.com/vindarel/ciel/-/pipelines, download the latest
artifacts, unzip the
ciel-v0-{platform}.ziparchive and runciel-v0-{platform}/ciel. - if you use the Guix package manager, install package
sbcl-ciel-repl.
CIEL is currently built for the following platforms:
| Platform | System Version (release date) |
|---|---|
| debian | Debian Buster (2019) |
| void | Void Linux glibc (2023-05), using cinerion's Docker image |
Start it with ./ciel (adapt the path if you put the binary somewhere else).
With no arguments, you enter CIEL's terminal REPL.
You can give a CIEL script as first argument, or call a built-in one. See the scripting section.
Run the binary in a Docker container
We have a Dockerfile.
Build your CIEL image:
docker build -t ciel .
The executable is built in /usr/local/bin/ciel of the Docker image.
Get a CIEL REPL:
docker run --rm -it ciel /usr/local/bin/ciel
Run a script on your filesystem:
docker run --rm -it ciel /usr/local/bin/ciel path/to/your/lisp/script.lisp
Run a built-in script:
docker run --rm -it ciel /usr/local/bin/ciel -s simpleHTTPserver
So, save you some typing with a shell alias:
alias ciel="sudo docker run --rm -it ciel /usr/local/bin/ciel"
Install CIEL as a library
You can install and CIEL like any other Common Lisp library, but you must make sure to also get all of its dependencies, a task that is best left to a package manager.
Quicklisp
CIEL is not on Quicklisp yet, but it is on Ultralisp.
So, either clone this repository:
git clone https://github.com/ciel-lang/CIEL ~/quicklisp/local-projects/CIEL
or install the Ultralisp distribution and pull the library from there:
(ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)
Install our Lisp dependencies [MANDATORY]
Even if you have a Lisp setup with Quicklisp installed, the current distribution of Quicklisp is quite old (as of August, 2024) and you need to pull recent dependencies.
We'll clone the required ones into your ~/quicklisp/local-projects/.
make ql-deps
Other tools exist for this (Qlot, ocicl…), we are just not using them yet.
Loading CIEL with Quicklisp
Now, in both cases, you can load the ciel.asd file (with asdf:load-asd
or C-c C-k in Slime) or quickload "ciel":
(ql:quickload "ciel")
be sure to enter the ciel-user package:
(in-package :ciel-user)
you now have access to all CIEL's packages and functions.
Guix
CIEL is available via the Guix package manager, as a source code package (cl-ciel) or precompiled for SBCL (sbcl-ciel) and ECL (ecl-ciel). You have to add Lisp itself (package sbcl or ecl), and any other Lisp library you may want to use.
In Lisp, do
(require "asdf")
(asdf:load-system :ciel)
(in-package :ciel-user)
Alternatively, or in addition, you can install sbcl-ciel:image, which contains a prebuilt core image under bin/ciel.image. It is executable, so you can run it in place of sbcl, or you can load it from the sbcl command line:
sbcl --core $(GUIX_PROFILE)/bin/ciel.image
In either case, you get a Lisp environment with CIEL preloaded, so all you have to do is
(in-package :ciel-user)
Using CIEL as a library in your Lisp code
To use it in your project, create a package and "use" ciel in addition
to cl:
(defpackage yourpackage
(:use :cl :ciel))
Alternatively, you can use generic-ciel, based on
generic-cl (warn:
generic-ciel is less tested at the moment).
(defpackage yourpackage
(:use :cl :generic-ciel))
generic-cl allows you to define + or equalp methods for your own
objects (and more).
Building CIEL binaries and core images
To build CIEL, both the binary and the core image, you need a couple system dependencies and you have to check a couple things on the side of Lisp before proceeding.
Dependencies
System dependencies
You will probably need the following system dependencies (names for a Debian Bullseye system):
zlib1g-dev # from deploy for SBCL < 2.2.6
If your SBCL version is >= 2.2.6 you might want to use the more
performant libzstd-dev library instead of zlib1g-dev.
libzstd-dev # from deploy for SBCL >= 2.2.6
On Linux:
inotify-tools
On MacOS:
fsevent
You can run: make debian-deps or make macos-deps.
ASDF >= 3.3.4 (local-nicknames)
ASDF is the de-facto system definition facility of Common Lisp, that lets you define your system's metadata (author, dependencies, sources, modules…).
Please ensure that you have ASDF >= 3.3.4.
It is for instance not the case with SBCL 2.2.9.
Ask the version with (asdf:asdf-version) on a Lisp REPL, or with
this one-liner from a terminal:
$ sbcl --eval '(and (print (asdf:asdf-version)) (quit))'
Here's a one-liner to update ASDF:
$ mkdir ~/common-lisp/
$ ( cd ~/common-lisp/ && wget https://asdf.common-lisp.dev/archives/asdf-3.3.5.tar.gz && tar -xvf asdf-3.3.5.tar.gz && mv asdf-3.3.5 asdf )
Install Quicklisp
To build CIEL on your machine, you need the Quicklisp library manager. Quicklisp downloads and installs a library and its dependencies on your machine. It's very slick, we can install everything from the REPL without restarting our Lisp process. It follows a "distrubution" approach, think Debian releases, where libraries are tested to load.
It isn't the only library manager nowadays. See https://github.com/CodyReichert/awesome-cl#library-manager.
Install it:
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
It creates a ~/quicklisp/ directory. Read its installation instructions to know more.
See the section above for loading CIEL via Quicklisp for how to make sure you have all the required dependencies.
Run the build procedure
You need the dependencies above: Quicklisp, a good ASDF version, our up-to-date Lisp dependencies.
To build CIEL's binary, use:
$ make build
This creates a ciel binary in the current directory.
To create a Lisp image:
$ make image
# or
$ sbcl --load build-image.lisp
This creates the ciel-core Lisp image.
Unlike binaries, we cannot distribute core images. They depend on the machine they was were built on.
Using the core image
The way we use a core image is to load it at startup like this:
sbcl --core ciel-core --eval '(in-package :ciel-user)'
It loads fast and you have all CIEL libraries and goodies at your disposal.
Then you have to configure your editor, like Slime, to have the choice of the Lisp image to start. See below.
Core image: configure your editor
The advantage of a core image is that it loads instantly, faster than
a (ql:quickload "ciel"). We'll ask our editor to start SBCL with our
CIEL core image.
We'll configure SLIME for multiple Lisps.
You need to add this to your Emacs init file:
(setq slime-lisp-implementations
`((sbcl ("sbcl" "--dynamic-space-size" "2000")) ;; default. Adapt if needed.
(ciel-sbcl ("sbcl" "--core" "/path/to/ciel/ciel-core" "--eval" "(in-package :ciel-user)"))))
(setq slime-default-lisp 'ciel-sbcl)
and start a Lisp process with M-x slime.
If you didn't set ciel-sbcl as the default, then start the Lisp
process with M-- M-x slime (alt-minus prefix), and choose
ciel-sbcl. You can start more than one Lisp process from SLIME.
The Lisp process should start instantly, as fast as the default SBCL, you won't wait for the quicklisp libraries to load.