source: trunk/abcl/README

Last change on this file was 15613, checked in by Mark Evenson, 2 months ago

metadata: annotate ability to run on openjdk19

  • Property svn:eol-style set to native
File size: 8.5 KB
Line 
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
40CONTAINERIZATION
41----------------
42
43We recommend using podman over docker for political reasons, but the
44surface syntax is identical so if you must, just subsitute `docker`
45for `podman` in the following examples.
46
47With [podman][] installed, one may execute:
48
49    podman build -t YOURID/abcl .
50    podman run -it YOURID/abcl
51
52to get something like
53
54    illin:~/work/abcl$ podman run -it YOURID/abcl
55    VM settings:
56    Max. Heap Size (Estimated): 498.00M
57    Using VM: OpenJDK 64-Bit Server VM
58
59    Armed Bear Common Lisp 1.9.0
60    Java 17.0.2 Oracle Corporation
61    OpenJDK 64-Bit Server VM
62    Low-level initialization completed in 0.952 seconds.
63    Startup completed in 4.248 seconds.
64    Type ":help" for a list of available commands.
65    CL-USER(1):
66
67To install Quicklisp for ABCL in the Docker container run:
68
69    podman run -t YOURID/abcl abcl \
70      --batch --load /home/abcl/work/abcl/ci/install-quicklisp.lisp
71
72See <file:Dockerfile> for the build instructions.
73
74[podman]: https://podman.io/releases/2022/02/22/podman-release-v4.0.0.html
75[Docker Engine]: https://www.docker.com/products/docker-engine
76
77
78RUNNING FROM BINARY RELEASE
79---------------------------
80
81After you have downloaded a binary release from either [the
82distributed Maven POM graph][maven-abcl] or from
83[abcl.org][abcl.org-release] archive unpack it into its own
84directory. To run ABCL directly from this directory, make sure the
85Java executable (`java`) (Java 6, 7, 8, 11, 13, 14, 15, 16, 17, 18,
86and 19 are supported by ABCL 1.9.1) is in your shell's path.
87
88[maven-abcl]:          <https://mvnrepository.com/artifact/org.abcl/abcl/1.9.0>
89[maven-abcl-contrib]:  <https://mvnrepository.com/artifact/org.abcl/abcl-contrib/1.9.0>
90[abcl.org-release]:    <http://abcl.org/releases/1.9.0/>
91
92To start ABCL, simply issue the following command:
93
94    cmd$ java -jar abcl.jar
95
96which should result in output like the following
97
98    Armed Bear Common Lisp 1.9.0
99    Java 17.0.2 OpenJDK Porters Group
100    OpenJDK 64-Bit Server VM
101    Low-level initialization completed in 0.107 seconds.
102    Startup completed in 0.493 seconds.
103    CL-USER(1):
104
105Yer now at the interactive ABCL "Read Eval Print Loop" (REPL): hacks
106'n glory await.
107
108See the section headed "SLIME" for instructions to connect to this
109repl from Emacs.
110
111
112BUILDING FROM SOURCE RELEASE
113----------------------------
114
115ABCL may be built from its source code by executing the build
116instructions <file:build.xml> expressed by the venerable Apache Ant
117tool.
118
119To build, one must have a Java 6, 7, 8, 11, 13, 14, 15, 16 or 17 Java
120Development Kit (openjdk) installed locally. Just the Java Runtime
121Environment (JRE) isn't enough, as you need the Java compiler
122('javac') to compile the Java source of the ABCL implementation.
123
124Download a binary distribution [Ant version 1.7.1 or greater][ant].
125Unpack the files somewhere convenient, ensuring that the 'ant' (or
126'ant.bat' under Windows) executable is in your path and executable.
127
128[ant]: http://ant.apache.org/bindownload.cgi
129
130Then simply executing
131
132    cmd$ ant
133
134from the directory containing the <file:build.xml> instructions will
135create an executable wrapper ('abcl' under UNIX, 'abcl.bat' under
136Windows).  Use this wrapper to start ABCL.
137
138The build may be customized by copying <file:abcl.properties.in> to
139<file:abcl.properties>, which will cause Ant to attempt to build
140incrementally as well as optimizing the runtime for a contemporary
14164bit desktop/server machine running Java 8, 11, and/or 17.  The file
142contains incomplete documentation on how it may be edited for
143subsequent customization.  As an alternative to copying the prototype,
144if one has a version of bash locally, one may issue via Ant
145
146    ant abcl.properties.autoconfigure.openjdk.17
147
148or from the shell as
149
150    bash ci/create-abcl-properties.bash openjdk17
151
152Currently supported platforms are 'openjdk6', 'openjdk7', 'openjdk8',
153'openjdk11', 'openjdk13', 'openjdk14', 'openjdk15', 'openjd16',
154'openjdk17', 'openjdk18', and 'openjdk19'.
155
156
157USING APACHE NETBEANS
158---------------------
159
160Alternatively, one may install the [Netbeans visual integrated
161development environment][netbeans], which contains both the Java
162Development Kit as well as the Ant build tool.  The source
163distribution contains Netbeans-specific project artifacts under
164<file:nbproject> for loading ABCL as a Netbeans project.
165
166With Netbeans, one should be able to open the ABCL directory as a
167project whereupon the usual build, run, and debug targets as invoked
168in the GUI are available.  Use the 'slime' config with a suitably
169linked SLIME `swank.asd` ASDF configuration
170<file:~/.config/common-lisp/source-registry.conf.d/> to connect a REPL
171to the NetBeans debug process.
172
173[netbeans]: http://netbeans.org/downloads/
174
175
176SLIME
177-----
178
179For usage of ABCL with the [Superior Lisp Interaction Mode for
180Emacs][slime], one may easily start a Swank listener via:
181
182    (require :asdf)
183    (require :abcl-contrib)
184    (asdf:load-system :quicklisp-abcl)
185    (or
186       (asdf:make :swank)
187       (ql:quickload :swank))
188    (swank:create-server :dont-close t)
189
190[slime]: https://common-lisp.net/project/slime/
191
192
193
194BUGS
195----
196
197Armed Bear Common Lisp strives to be a conforming ANSI X3J13 Common
198Lisp implementation.  Any other behavior should be reported as a bug.
199
200ABCL has a [User Manual][manual] stating its conformance to the ANSI
201standard, providing a compliant and practical Common Lisp
202implementation.
203
204[manual]: https://abcl.org/releases/1.9.0/abcl-1.9.0.pdf
205
206
207TESTS
208-----
209
210    | Version | Failures | Total |
211    |---------+----------+-------|
212    |   1.9.0 |       61 | 21870 |
213    |   1.8.0 |       49 | 21848 |
214    |   1.5.0 |       48 | 21708 |
215
216ABCL 1.9.0 currently fails ~49(!!) out of 21848(!!) the current ANSI
217test suite derived from the tests originally written for GCL.
218
219[ansi-test]: git+https://gitlab.common-lisp.net/ansi-test/ansi-test.git
220
221Maxima's test suite runs without failures.
222
223ABCL comes with a test suite.  Consult the output of `ant help.test`
224for more information.
225
226
227SUPPORT
228-------
229
230ABCL has many deficiencies, both known and unknown.  Descriptions,
231tests, and even patches to address them will be gladly accepted.
232
233Please report problems to the [development mailing list][mailing-list]
234or via opening an issue on either the [ABCL trac instance][trac] or
235[github][].
236
237[mailing-list]: https://mailman.common-lisp.net/pipermail/armedbear-devel/
238[github]: https://github.com/armedbear/abcl/issues
239[trac]: https://abcl.org/trac/
240
241
242AUTHORS
243-------
244
245On behalf of all ABCL development team and contributors,
246
247    Mark Evenson
248    Erik HÃŒlsmann
249    Rudolf Schlatte
250    Alessio Stalla
251    Ville Voutilainen
252
253    alan
254    dmiles
255    Dmitry Nadezhin
256    olof ferada
257    pipping
258    slyrus
259    vibhu
260
261    Jonathan Cunningham
262    Uthar
263    alejandrozf
264    phoe
265    jackdaniel
266    Robert Munyer
267    Eric Timmons (daewok)
268    contrapunctus
269    Scott Burson
270    Samuel Hunter
271    Phil Eaton
272
273    András Simon
274    Peter Graves
275
276Have fun!
277
278May 2022
Note: See TracBrowser for help on using the repository browser.