Skip to content

Commit 427dd0b

Browse files
khinsenvindarel
khinsen
authored and
vindarel
committed
Restructured installation instructions
1 parent 1a50e54 commit 427dd0b

File tree

1 file changed

+137
-113
lines changed

1 file changed

+137
-113
lines changed

‎docs/install.md

+137-113
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,24 @@
11

22
# Install
33

4-
## Download a binary. For scripting and the custom REPL.
4+
CIEL can be used in two different roles:
55

6-
Getting a binary allows you to run scripts, to play around in its
7-
terminal readline REPL. A binary doesn't allow you to use CIEL in your
8-
existing Common Lisp editor (which still offers the most interactive
9-
and fast development experience).
6+
- As a library that you can load into any Common Lisp implementation.
7+
- 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 standard `sbcl`, and a much faster startup time than starting `sbcl` and then loading the CIEL library.
8+
9+
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.
10+
11+
In the following, we will explain how to install the library, the binary, and the prebuilt core image, for various common SBCL setups.
12+
13+
## Download a prebuilt binary.
1014

1115
To download a CIEL binary:
1216

1317
- check our releases on https://github.com/ciel-lang/CIEL/releases/
1418
- we provide a binary from a CI for some systems: go to
1519
<https://gitlab.com/vindarel/ciel/-/pipelines>, download the latest
1620
artifacts, unzip the `ciel-v0-{platform}.zip` archive and run `ciel-v0-{platform}/ciel`.
17-
- using the [Guix](https://guix.gnu.org/) package manager, install package `sbcl-ciel-repl`.
21+
- if you use the [Guix](https://guix.gnu.org/) package manager, install package `sbcl-ciel-repl`.
1822

1923
CIEL is currently built for the following platforms:
2024

@@ -23,18 +27,135 @@ CIEL is currently built for the following platforms:
2327
| debian | Debian Buster (2019) |
2428
| void | Void Linux glibc (2023-05), using [cinerion's Docker image](https://github.com/cinerion/sbcl-voidlinux-docker) |
2529

26-
27-
Start it with `./ciel`.
30+
Start it with `./ciel` (adapt the path if you put the binary somewhere else).
2831

2932
With no arguments, you enter CIEL's terminal REPL.
3033

3134
You can give a CIEL script as first argument, or call a built-in one. See the scripting section.
3235

33-
# Build
36+
## Run the binary in a Docker container
37+
38+
We have a Dockerfile.
39+
40+
Build your CIEL image:
41+
42+
docker build -t ciel .
43+
44+
The executable is built in `/usr/local/bin/ciel` of the Docker image.
45+
46+
Get a CIEL REPL:
47+
48+
docker run --rm -it ciel /usr/local/bin/ciel
49+
50+
Run a script on your filesystem:
51+
52+
docker run --rm -it ciel /usr/local/bin/ciel path/to/your/lisp/script.lisp
53+
54+
Run a built-in script:
55+
56+
docker run --rm -it ciel /usr/local/bin/ciel -s simpleHTTPserver
57+
58+
So, save you some typing with a shell alias:
59+
60+
alias ciel="sudo docker run --rm -it ciel /usr/local/bin/ciel"
61+
62+
## Install CIEL as a library
63+
64+
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.
65+
66+
### Quicklisp
67+
68+
CIEL is not on Quicklisp yet, but it is on [Ultralisp](https://ultralisp.org).
69+
70+
So, either clone this repository:
71+
72+
git clone https://github.com/ciel-lang/CIEL ~/quicklisp/local-projects/CIEL
73+
74+
or install the Ultralisp distribution and pull the library from there:
75+
76+
```lisp
77+
(ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)
78+
```
79+
80+
#### Install our Lisp dependencies [MANDATORY]
81+
82+
Even if you have a Lisp setup with Quicklisp installed, the current
83+
distribution of Quicklisp is quite old (as of August, 2024) and you
84+
need to pull recent dependencies.
85+
86+
We'll clone the required ones into your `~/quicklisp/local-projects/`.
87+
88+
make ql-deps
89+
90+
Other tools exist for this (Qlot, ocicl…), we are just not using them yet.
91+
92+
#### Loading CIEL with Quicklisp
93+
94+
Now, in both cases, you can load the `ciel.asd` file (with `asdf:load-asd`
95+
or `C-c C-k` in Slime) or quickload "ciel":
96+
97+
```lisp
98+
(ql:quickload "ciel")
99+
```
100+
101+
be sure to enter the `ciel-user` package:
102+
103+
```lisp
104+
(in-package :ciel-user)
105+
```
106+
you now have access to all CIEL's packages and functions.
107+
108+
### Guix
109+
110+
CIEL is available via the [Guix](https://guix.gnu.org/) 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.
111+
112+
In Lisp, do
113+
```lisp
114+
(require "asdf")
115+
(asdf:load-system :ciel)
116+
(in-package :ciel-user)
117+
```
118+
119+
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:
120+
121+
```
122+
sbcl --core $(GUIX_PROFILE)/bin/ciel.image
123+
```
124+
125+
In either case, you get a Lisp environment with CIEL preloaded, so all you have to do is
126+
127+
```lisp
128+
(in-package :ciel-user)
129+
```
130+
131+
132+
## Using CIEL as a library in your Lisp code
133+
134+
To use it in your project, create a package and "use" `ciel` in addition
135+
to `cl`:
136+
137+
```lisp
138+
(defpackage yourpackage
139+
(:use :cl :ciel))
140+
```
141+
142+
Alternatively, you can use `generic-ciel`, based on
143+
[generic-cl](https://github.com/alex-gutev/generic-cl/) (warn:
144+
generic-ciel is less tested at the moment).
145+
146+
```lisp
147+
(defpackage yourpackage
148+
(:use :cl :generic-ciel))
149+
```
150+
151+
`generic-cl` allows you to define `+` or `equalp` methods for your own
152+
objects (and more).
153+
154+
# Building CIEL binaries and core images
34155

35156
To build CIEL, both the binary and the core image, you need a couple
36157
system dependencies and you have to check a couple things on the side
37-
of lisp before proceeding.
158+
of Lisp before proceeding.
38159

39160
## Dependencies
40161

@@ -103,58 +224,12 @@ sbcl --load ~/quicklisp/setup.lisp --eval "(ql:add-to-init-file)" --quit
103224

104225
It creates a `~/quicklisp/` directory. Read its installation instructions to know more.
105226

106-
### Install our Lisp dependencies [MANDATORY]
107-
108-
Even if you have a Lisp setup with Quicklisp installed, the current
109-
distribution of Quicklisp is quite old (as of August, 2024) and you
110-
need to pull recent dependencies.
111-
112-
We'll clone the required ones into your `~/quicklisp/local-projects/`.
113-
114-
make ql-deps
115-
116-
Other tools exist for this (Qlot, ocicl…), we are just not using them yet.
117-
227+
See the section above for loading CIEL via Quicklisp for how to make sure you have all the required dependencies.
118228

119-
## How to load CIEL with Quicklisp
229+
### Run the build procedure
120230

121231
You need the dependencies above: Quicklisp, a good ASDF version, our up-to-date Lisp dependencies.
122232

123-
This shows you how to load CIEL and all its goodies, in order to use it in your current editor.
124-
125-
CIEL is not on Quicklisp yet, but it is on [Ultralisp](https://ultralisp.org).
126-
127-
So, either clone this repository:
128-
129-
git clone https://github.com/ciel-lang/CIEL ~/quicklisp/local-projects/CIEL
130-
131-
or install the Ultralisp distribution and pull the library from there:
132-
133-
```lisp
134-
(ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)
135-
```
136-
137-
Now, in both cases, you can load the `ciel.asd` file (with `asdf:load-asd`
138-
or `C-c C-k` in Slime) and quickload "ciel":
139-
140-
```lisp
141-
(ql:quickload "ciel")
142-
```
143-
144-
be sure to enter the `ciel-user` package:
145-
146-
```lisp
147-
(in-package :ciel-user)
148-
```
149-
you now have access to all CIEL's packages and functions.
150-
151-
152-
## How to build a CIEL binary and a core image
153-
154-
If you use the [Guix](https://guix.gnu.org/) package manager, install package output `sbcl-ciel:image`. It contains a prebuilt image under `bin/ciel.image`.
155-
156-
For all other setups, you have to build a core image yourself. You need the dependencies above: Quicklisp, a good ASDF version, our up-to-date Lisp dependencies.
157-
158233
To build CIEL's binary, use:
159234

160235
$ make build
@@ -169,7 +244,9 @@ To create a Lisp image:
169244

170245
This creates the `ciel-core` Lisp image.
171246

172-
Unlike a binary, we can not distribute core images. It is dependent on the machine it was built on.
247+
Unlike binaries, we cannot distribute core images. They depend on the machine they was were built on.
248+
249+
### Using the core image
173250

174251
The way we use a core image is to load it at startup like this:
175252

@@ -180,60 +257,7 @@ It loads fast and you have all CIEL libraries and goodies at your disposal.
180257
Then you have to configure your editor, like Slime, to have the choice of the Lisp image to
181258
start. See below.
182259

183-
184-
## Docker
185-
186-
We have a Dockerfile.
187-
188-
Build your CIEL image:
189-
190-
docker build -t ciel .
191-
192-
The executable is built in `/usr/local/bin/ciel` of the Docker image.
193-
194-
Get a CIEL REPL:
195-
196-
docker run --rm -it ciel /usr/local/bin/ciel
197-
198-
Run a script on your filesystem:
199-
200-
docker run --rm -it ciel /usr/local/bin/ciel path/to/your/lisp/script.lisp
201-
202-
Run a built-in script:
203-
204-
docker run --rm -it ciel /usr/local/bin/ciel -s simpleHTTPserver
205-
206-
So, save you some typing with a shell alias:
207-
208-
alias ciel="sudo docker run --rm -it ciel /usr/local/bin/ciel"
209-
210-
# Usage as a library
211-
212-
## "use" ciel in your Lisp systems
213-
214-
You can install and `quickload` CIEL like any other Common Lisp library. It is also available via the [Guix](https://guix.gnu.org/) package manager, as a source code package (`cl-ciel`) or precompiled for SBCL (`sbcl-ciel`) and ECL (`ecl-ciel`).
215-
216-
To use it in your project, create a package and "use" `ciel` in addition
217-
of `cl`:
218-
219-
```lisp
220-
(defpackage yourpackage
221-
(:use :cl :ciel))
222-
```
223-
224-
You can also use `generic-ciel`, based on
225-
[generic-cl](https://github.com/alex-gutev/generic-cl/) (warn:
226-
generic-ciel is less tested at the moment).
227-
228-
~~~lisp
229-
(defpackage yourpackage
230-
(:use :cl :generic-ciel))
231-
~~~
232-
233-
generic-cl allows us to define our `+` or `equalp` methods for our own
234-
objects (and more).
235-
236-
## Core image: configure your editor
260+
### Core image: configure your editor
237261

238262
The advantage of a core image is that it loads instantly, faster than
239263
a `(ql:quickload "ciel")`. We'll ask our editor to start SBCL with our

0 commit comments

Comments
 (0)