source: trunk/abcl/README

Last change on this file was 15522, checked in by Mark Evenson, 9 months ago

Update build artifacts for openjdk17

  • Property svn:eol-style set to native
File size: 7.8 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
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, 15, 16 or 17 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', 'openjdk15', 'openjd16', and
163'openjdk17'.
164
165
166Using NetBeans
167--------------
168
169Alternatively, one may install the [Netbeans visual integrated
170development environment][netbeans], which contains both the Java
171Development Kit as well as the Ant build tool.  The source
172distribution contains Netbeans-specific project artifacts under
173<file:nbproject> for loading ABCL as a Netbeans project.
174
175With Netbeans, one should be able to open the ABCL directory as a
176project whereupon the usual build, run, and debug targets as invoked
177in the GUI are available.  Use the 'slime' config with a suitably
178linked SLIME `swank.asd` ASDF configuration
179<file:~/.config/common-lisp/source-registry.conf.d/> to connect a REPL
180to the NetBeans debug process.
181
182[netbeans]: http://netbeans.org/downloads/
183
184
185Bugs
186----
187
188Armed Bear Common Lisp strives to be a conforming ANSI X3J13 Common
189Lisp implementation.  Any other behavior should be reported as a bug.
190
191ABCL has a [User Manual][manual] stating its conformance to the ANSI
192standard, providing a compliant and practical Common Lisp
193implementation.
194
195[manual]: https://abcl.org/releases/1.8.0/abcl-1.8.0.pdf
196
197
198Tests
199-----
200
201ABCL 1.8.0 currently fails ~49 out of 21848 total tests, whereas ABCL
2021.5.0 failed 48 out of 21708 total tests in the [revised and expanded
203ANSI CL test suite][ansi-test] (derived from the tests originally
204written for GCL).
205
206[ansi-test]: git+https://gitlab.common-lisp.net/ansi-test/ansi-test.git
207
208Maxima's test suite runs without failures.
209
210ABCL comes with a test suite.  Consult the output of `ant help.test`
211for more information.
212
213
214Support
215-------
216
217ABCL has many deficiencies, both known and unknown.  Descriptions,
218tests, and even patches to address them will be gladly accepted.
219
220Please report problems to the [development mailing list][mailing-list]
221or via opening an issue on either the [ABCL trac instance][trac] or
222[github][].
223
224[mailing-list]: https://mailman.common-lisp.net/pipermail/armedbear-devel/
225[github]: https://github.com/armedbear/abcl/issues
226[trac]: https://abcl.org/trac/
227
228
229Authors
230-------
231
232On behalf of all ABCL development team and contributors,
233
234    Mark Evenson
235    Erik HÃŒlsmann
236    Rudolf Schlatte
237    Alessio Stalla
238    Ville Voutilainen
239
240    alan
241    dmiles
242    Dmitry Nadezhin
243    olof ferada
244    pipping
245    slyrus
246    vibhu
247
248    András Simon
249    Peter Graves
250
251Have fun!
252
253October 2020
Note: See TracBrowser for help on using the repository browser.