hub-description-template.org 5.94 KB
Newer Older
Eric Timmons's avatar
Eric Timmons committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#+TITLE: CCL Docker Images
#+AUTHOR: Eric Timmons

* Supported Tags

** Simple Tags

   INSERT-SIMPLE-TAGS

** Shared Tags

   INSERT-SHARED-TAGS

* Quick Reference

  + CCL Home Page :: [[https://ccl.clozure.com/][https://ccl.clozure.com/]]
  + Where to file Docker image related issues :: [[https://gitlab.common-lisp.net/cl-docker-images/ccl]]
  + Where to file issues for CCL itself :: [[https://github.com/Clozure/ccl/issues][https://github.com/Clozure/ccl/issues]]
19
  + Maintained by :: [[https://common-lisp.net/project/cl-docker-images][CL Docker Images Project]]
Eric Timmons's avatar
Eric Timmons committed
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
  + Supported architectures :: =linux/amd64=, =linux/arm/v7=, =windows/amd64=

* What is CCL?

  From [[https://ccl.clozure.com][CCL's Home Page]]:

  #+begin_quote
  Clozure CL (often called CCL for short) is a free Common Lisp implementation
  with a long history. Some distinguishing features of the implementation
  include fast compilation speed, native threads, a precise, generational,
  compacting garbage collector, and a convenient foreign-function interface.
  #+end_quote

* How to use this image

** Create a =Dockerfile= in your CCL project

   #+begin_src dockerfile
     FROM %%IMAGE%%:latest
     COPY . /usr/src/app
     WORKDIR /usr/src/app
     CMD [ "ccl", "--load", "./your-daemon-or-script.lisp" ]
   #+end_src

   You can then build and run the Docker image:

   #+begin_src console
     $ docker build -t my-ccl-app
     $ docker run -it --rm --name my-running-app my-ccl-app
   #+end_src

** Run a single Common Lisp script

   For many simple, single file projects, you may find it inconvenient to write
   a complete `Dockerfile`. In such cases, you can run a Lisp script by using
   the CCL Docker image directly:

   #+begin_src console
     $ docker run -it --rm --name my-running-script -v "$PWD":/usr/src/app -w /usr/src/app %%IMAGE%%:latest ccl --load ./your-daemon-or-script.lisp
   #+end_src

** Developing using SLIME

   [[https://common-lisp.net/project/slime/][SLIME]] provides a convenient and fun environment for hacking on Common
   Lisp. To develop using SLIME, first start the Swank server in a container:

   #+begin_src console
     $ docker run -it --rm --name ccl-slime -p 127.0.0.1:4005:4005 -v /path/to/slime:/usr/src/slime -v "$PWD":/usr/src/app -w /usr/src/app %%IMAGE%%:latest ccl --load /usr/src/slime/swank-loader.lisp --eval '(swank-loader:init)' --eval '(swank:create-server :dont-close t :interface "0.0.0.0")'
   #+end_src

   Then, in an Emacs instance with slime loaded, type:

   #+begin_src emacs
     M-x slime-connect RET RET RET
   #+end_src


* Image variants

  This image comes in several variants, each designed for a specific use case.

** =%%IMAGE%%:<version>=

   This is the defacto image. If you are unsure about what your needs are, you
   probably want to use this one. It is designed to be used both as a throw
   away container (mount your source code and start the container to start your
   app), as well as the base to build other images off of.

   Some of these tags may have names like buster or stretch in them. These are
   the suite code names for releases of Debian and indicate which release the
   image is based on. If your image needs to install any additional packages
   beyond what comes with the image, you'll likely want to specify one of these
   explicitly to minimize breakage when there are new releases of Debian.

   These images are built off the buildpack-deps image. It, by design, has a
   large number of extremely common Debian packages.

97
   These images contain the Quicklisp installer, located at
98
99
100
101
102
103
104
105
106
107
108
109
   =/usr/local/share/common-lisp/source/quicklisp/quicklisp.lisp=. Additionally,
   there is a script at =/usr/local/bin/install-quicklisp= that will use the
   bundled installer to install Quicklisp. You can configure the Quicklisp
   install with the following environment variables:

   + =QUICKLISP_DIST_VERSION= :: The dist version to use. Of the form
     yyyy-mm-dd. =latest= means to install the latest version (the default).
   + =QUICKLISP_CLIENT_VERSION= :: The client version to use. Of the form
     yyyy-mm-dd. =latest= means to install the latest version (the default).
   + =QUICKLISP_ADD_TO_INIT_FILE= :: If set to =true=, =(ql:add-to-init-file)=
     is used to add code to the implementation's user init file to load
     Quicklisp on startup. Not set by default.
110

Eric Timmons's avatar
Eric Timmons committed
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
** =%%IMAGE%%:<version>-slim=

   This image does not contain the common packages contained in the default tag
   and only contains the minimal packages needed to run CCL. Unless you are
   working in an environment where only this image will be deployed and you
   have space constraints, we highly recommend using the default image of this
   repository.

** =%%IMAGE%%:<version>-windowsservercore=

   This image is based on [[https://hub.docker.com/_/microsoft-windows-servercore][Windows Server Core
   (=microsoft/windowsservercore=)]]. As such, it only works in places which that
   image does, such as Windows 10 Professional/Enterprise (Anniversary Edition)
   or Windows Server 2016.

   For information about how to get Docker running on Windows, please see the
   relevant "Quick Start" guide provided by Microsoft:

   + [[https://msdn.microsoft.com/en-us/virtualization/windowscontainers/quick_start/quick_start_windows_server][Windows Server Quick Start]]
   + [[https://msdn.microsoft.com/en-us/virtualization/windowscontainers/quick_start/quick_start_windows_10][Windows 10 Quick Start]]

* License

  CCL is licensed under the [[https://www.apache.org/licenses/LICENSE-2.0][Apache v2.0]].

  The Dockerfiles used to build the images are licensed under BSD-2-Clause.

  As with all Docker images, these likely also contain other software which may
  be under other licenses (such as Bash, etc from the base distribution, along
  with any direct or indirect dependencies of the primary software being
  contained).

  As for any pre-built image usage, it is the image user's responsibility to
  ensure that any use of this image complies with any relevant licenses for all
  software contained within.