source: trunk/abcl/README @ 15334

Last change on this file since 15334 was 15334, checked in by Mark Evenson, 15 months ago

doc: correct ANSI specification identifier

  • Property svn:eol-style set to native
File size: 7.3 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.7.0
53    Java 11.0.7 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.7.0"
60    "OpenJDK_64-Bit_Server_VM-AdoptOpenJDK-11.0.7+10"
61    "x86_64-Mac_OS_X-10.15.5"
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, and 14 are supported
82by ABCL 1.7.0) is in your shell's path.
83
84[maven-abcl]:          <https://mvnrepository.com/artifact/org.abcl/abcl/1.7.0>
85[maven-abcl-contrib]:  <https://mvnrepository.com/artifact/org.abcl/abcl-contrib/1.7.0>
86[abcl.org-release]:    <http://abcl.org/releases/1.7.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.7.0
95    Java 1.8.0_252 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
105SWANK
106-----
107
108One may easily start a swank listener via:
109
110    (require :asdf)
111    (require :abcl-contrib)
112    (asdf:load-system :quicklisp-abcl)
113    (ql:quickload :swank)
114    (swank:create-server :dont-close t)
115
116
117Building From Source Release
118----------------------------
119
120ABCL may be built from its source code by executing the build
121instructions <file:build.xml> expressed by the venerable Apache Ant
122tool.
123
124To build, one must have a Java 6, 7, 8, 11, 13 or 14 Java Development
125Kit (openjdk) installed locally. Just the Java Runtime Environment
126(JRE) isn't enough, as you need the Java compiler ('javac') to compile
127the Java source of the ABCL implementation.
128
129Download a binary distribution [Ant version 1.7.1 or greater][ant].
130Unpack the files somewhere convenient, ensuring that the 'ant' (or
131'ant.bat' under Windows) executable is in your path and executable.
132
133[ant]: http://ant.apache.org/bindownload.cgi
134
135Then simply executing
136
137    cmd$ ant
138
139from the directory containing the <file:build.xml> instructions will
140create an executable wrapper ('abcl' under UNIX, 'abcl.bat' under
141Windows).  Use this wrapper to start ABCL.
142
143The build may be customized by copying <file:abcl.properties.in> to
144<file:abcl.properties>, which will cause Ant to attempt to build
145incrementally as well as optimizing the runtime for a contemporary
14664bit desktop/server machine running Java 8 or 11.  The file contains
147incomplete documentation on how it may be edited for subsequent
148customization.  As an alternative to copying the prototype, if one has
149a version of bash locally, one may issue via Ant
150
151    ant abcl.properties.autoconfigure.openjdk.11
152
153or from the shell as
154
155    bash ci/create-abcl-properties.bash openjdk11
156
157Currently supported platforms are 'openjdk6', 'openjdk7', 'openjdk8',
158'openjdk11', 'openjdk13', and 'openjdk14'.
159
160
161Using NetBeans
162--------------
163
164Alternatively, one may install the [Netbeans visual integrated
165development environment][netbeans], which contains both the Java
166Development Kit as well as the Ant build tool.  The source
167distribution contains Netbeans-specific project artifacts under
168<file:nbproject> for loading ABCL as a Netbeans project.
169
170With Netbeans, one should be able to open the ABCL directory as a
171project whereupon the usual build, run, and debug targets as invoked
172in the GUI are available.  Use the 'slime' config with a suitably
173linked 'swank.asd' in '~/.asdf-install-dir/systems/' to connect a REPL
174to the NetBeans debug process.
175
176[netbeans]: http://netbeans.org/downloads/
177
178
179Bugs
180----
181
182Armed Bear Common Lisp is a conforming ANSI X3J13 Common Lisp
183implementation.  Any other behavior should be reported as a bug.
184
185ABCL has a user manual stating its conformance to the ANSI standard,
186providing a compliant and practical Common Lisp implementation.
187
188
189Tests
190-----
191
192ABCL 1.7.0 currently fails ~45-46 out of 21848 total tests, whereas ABCL
1931.5.0 failed 48 out of 21708 total tests in the [revised and expanded
194ANSI CL test suite][ansi-test] (derived from the tests originally
195written for GCL).
196
197[ansi-test]: git+https://gitlab.common-lisp.net/ansi-test/ansi-test.git
198
199Maxima's test suite runs without failures.
200
201ABCL comes with a test suite, see the output of `ant help.test` for
202more information.
203
204
205Support
206-------
207
208ABCL has many deficiencies, both known and unknown.  Descriptions,
209tests, and even patches to address will be gladly accepted.
210
211
212Please report problems to the development mailing list:
213
214    <armedbear-devel@common-lisp.net>
215
216Authors
217=======
218
219On behalf of all ABCL development team and contributors,
220
221    Mark Evenson
222    Erik HÃŒlsmann
223    Rudolf Schlatte
224    Alessio Stalla
225    Ville Voutilainen
226
227    alan
228    olof ferada
229    pipping
230    slyrus
231    vibhu
232    dmiles
233
234    András Simon
235    Peter Graves
236
237Have fun!
238
239June 2020
Note: See TracBrowser for help on using the repository browser.