1Armed Bear Common Lisp (ABCL) README
2====================================
3
4Armed Bear Common Lisp is a conforming implementation of ANSI X3J13
5Common Lisp that runs in a Java virtual machine. It compiles Lisp
6code directly to Java byte code for execution.
7
8
9LICENSE
10-------
11
12Armed Bear Common Lisp is distributed under the GNU General Public
13License with a classpath exception (see "Classpath Exception" below).
14
15A copy of GNU General Public License (GPLv2) is included in this
16distribution, in <file:COPYING>.
17
18We have modified our GPLv2 license section 13 to read:
19
20 13. Linking this library statically or dynamically with other
21 modules is making a combined work based on this library. Thus, the
22 terms and conditions of the GNU General Public License cover the
23 whole combination.
24
25 The following paragraph details the "classpath exception" which ABCL
26 allows as an exception to the statement about linking libraries.
27
28 As a special exception, the copyright holders of this software give
29 you permission to link this software with independent modules to
30 produce an executable, regardless of the license terms of these
31 independent modules, and to copy and distribute the resulting
32 executable under terms of your choice, provided that you also meet,
33 for each linked independent module, the terms and conditions of the
34 license of that module. An independent module is a module which is
35 not derived from or based on this software. If you modify this
36 software, you may extend this exception to your version of the
37 software, but you are not obligated to do so. If you do not wish to
38 do so, delete this exception statement from your version.
39
40
41RUNNING FROM DOCKER
42-------------------
43
44With [Docker Engine][] installed one may execute:
45
46 docker build -t YOURID/abcl .
47 docker run -it YOURID/abcl
48
49to get something like
50
51 illin:~/work/abcl$ docker run -it YOURID/abcl
52 Armed Bear Common Lisp 1.8.0
53 Java 11.0.8 AdoptOpenJDK
54 OpenJDK 64-Bit Server VM
55 Low-level initialization completed in 0.295 seconds.
56 Startup completed in 1.425 seconds.
57 Type ":help" for a list of available commands.
58 CL-USER(1): (lisp-implementation-version)
59 "1.8.0"
60 "OpenJDK_64-Bit_Server_VM-AdoptOpenJDK-11.0.8+10"
61 "x86_64-Mac_OS_X-10.15.7"
62
63To install Quicklisp for ABCL in the Docker container run:
64
65 docker run -t YOURID/abcl abcl \
66 --batch --load /home/abcl/work/abcl/ci/install-quicklisp.lisp
67
68See <file:Dockerfile> for the build instructions.
69
70[Docker Engine]: https://www.docker.com/products/docker-engine
71
72
73
74RUNNING FROM BINARY RELEASE
75---------------------------
76
77After you have downloaded a binary release from either [the
78distributed Maven POM graph][maven-abcl] or from
79[abcl.org][abcl.org-release] archive unpack it into its own
80directory. To run ABCL directly from this directory, make sure the
81Java executable (`java`) (Java 6, 7, 8, 11, 13, 14, and 15 are
82supported by ABCL 1.7.0) is in your shell's path.
83
84[maven-abcl]: <https://mvnrepository.com/artifact/org.abcl/abcl/1.8.0>
85[maven-abcl-contrib]: <https://mvnrepository.com/artifact/org.abcl/abcl-contrib/1.8.0>
86[abcl.org-release]: <http://abcl.org/releases/1.8.0/>
87
88To start ABCL, simply issue the following command:
89
90 cmd$ java -jar abcl.jar
91
92which should result in output like the following
93
94 Armed Bear Common Lisp 1.8.0
95 Java 11.0.8 AdoptOpenJDK
96 OpenJDK 64-Bit Server VM
97 Low-level initialization completed in 0.222 seconds.
98 Startup completed in 1.09 seconds.
99 Type ":help" for a list of available commands.
100 CL-USER(1):
101
102Yer now at the interactive ABCL "Read Eval Print Loop" (REPL): hacks
103'n glory await.
104
105
106SLIME
107-----
108
109For usage of ABCL with the [Superior Lisp Interaction Mode for
110Emacs][slime], one may easily start a Swank listener via:
111
112 (require :asdf)
113 (require :abcl-contrib)
114 (asdf:load-system :quicklisp-abcl)
115 (ql:quickload :swank)
116 (swank:create-server :dont-close t)
117
118[slime]: https://common-lisp.net/project/slime/
119
120
121Building From Source Release
122----------------------------
123
124ABCL may be built from its source code by executing the build
125instructions <file:build.xml> expressed by the venerable Apache Ant
126tool.
127
128To build, one must have a Java 6, 7, 8, 11, 13, 14 or 15 Java
129Development Kit (openjdk) installed locally. Just the Java Runtime
130Environment (JRE) isn't enough, as you need the Java compiler
131('javac') to compile the Java source of the ABCL implementation.
132
133Download a binary distribution [Ant version 1.7.1 or greater][ant].
134Unpack the files somewhere convenient, ensuring that the 'ant' (or
135'ant.bat' under Windows) executable is in your path and executable.
136
137[ant]: http://ant.apache.org/bindownload.cgi
138
139Then simply executing
140
141 cmd$ ant
142
143from the directory containing the <file:build.xml> instructions will
144create an executable wrapper ('abcl' under UNIX, 'abcl.bat' under
145Windows). Use this wrapper to start ABCL.
146
147The build may be customized by copying <file:abcl.properties.in> to
148<file:abcl.properties>, which will cause Ant to attempt to build
149incrementally as well as optimizing the runtime for a contemporary
15064bit desktop/server machine running Java 8 or 11. The file contains
151incomplete documentation on how it may be edited for subsequent
152customization. As an alternative to copying the prototype, if one has
153a version of bash locally, one may issue via Ant
154
155 ant abcl.properties.autoconfigure.openjdk.11
156
157or from the shell as
158
159 bash ci/create-abcl-properties.bash openjdk11
160
161Currently supported platforms are 'openjdk6', 'openjdk7', 'openjdk8',
162'openjdk11', 'openjdk13', 'openjdk14', and 'openjdk15'.
163
164
165Using NetBeans
166--------------
167
168Alternatively, one may install the [Netbeans visual integrated
169development environment][netbeans], which contains both the Java
170Development Kit as well as the Ant build tool. The source
171distribution contains Netbeans-specific project artifacts under
172<file:nbproject> for loading ABCL as a Netbeans project.
173
174With Netbeans, one should be able to open the ABCL directory as a
175project whereupon the usual build, run, and debug targets as invoked
176in the GUI are available. Use the 'slime' config with a suitably
177linked SLIME `swank.asd` ASDF configuration
178<file:~/.config/common-lisp/source-registry.conf.d/> to connect a REPL
179to the NetBeans debug process.
180
181[netbeans]: http://netbeans.org/downloads/
182
183
184Bugs
185----
186
187Armed Bear Common Lisp strives to be a conforming ANSI X3J13 Common
188Lisp implementation. Any other behavior should be reported as a bug.
189
190ABCL has a [User Manual][manual] stating its conformance to the ANSI
191standard, providing a compliant and practical Common Lisp
192implementation.
193
194[manual]: https://abcl.org/releases/1.8.0/abcl-1.8.0.pdf
195
196
197Tests
198-----
199
200ABCL 1.8.0 currently fails ~49 out of 21848 total tests, whereas ABCL
2011.5.0 failed 48 out of 21708 total tests in the [revised and expanded
202ANSI CL test suite][ansi-test] (derived from the tests originally
203written for GCL).
204
205[ansi-test]: git+https://gitlab.common-lisp.net/ansi-test/ansi-test.git
206
207Maxima's test suite runs without failures.
208
209ABCL comes with a test suite. Consult the output of `ant help.test`
210for more information.
211
212
213Support
214-------
215
216ABCL has many deficiencies, both known and unknown. Descriptions,
217tests, and even patches to address them will be gladly accepted.
218
219Please report problems to the [development mailing list][mailing-list]
220or via opening an issue on either the [ABCL trac instance][trac] or
221[github][].
222
223[mailing-list]: https://mailman.common-lisp.net/pipermail/armedbear-devel/
224[github]: https://github.com/armedbear/abcl/issues
225[trac]: https://abcl.org/trac/
226
227
228Authors
229-------
230
231On behalf of all ABCL development team and contributors,
232
233 Mark Evenson
234 Erik Hülsmann
235 Rudolf Schlatte
236 Alessio Stalla
237 Ville Voutilainen
238
239 alan
240 dmiles
241 Dmitry Nadezhin
242 olof ferada
243 pipping
244 slyrus
245 vibhu
246
247 András Simon
248 Peter Graves
249
250Have fun!
251
252October 2020
253