source: trunk/abcl/README

Last change on this file was 15464, checked in by Mark Evenson, 4 months ago

abcl 1.8.0 metadata

rc14

TODO manual needs much description about pathnames

  • 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 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
Note: See TracBrowser for help on using the repository browser.