source: public_html/releases/1.7.0/README @ 15301

Last change on this file since 15301 was 15301, checked in by Mark Evenson, 8 months ago

1.7.0 release README and known N3 metadata about build

File size: 7.1 KB
Line 
1Armed Bear Common Lisp README
2=============================
3
4GENERAL INFORMATION
5-------------------
6
7Armed Bear Common Lisp is a conforming implementation of ANSI Common
8Lisp that runs in a Java virtual machine.  It compiles Lisp code
9directly to Java byte code.
10
11
12LICENSE
13=======
14
15Armed Bear Common Lisp is distributed under the GNU General Public
16License with a classpath exception (see "Classpath Exception" below).
17
18A copy of GNU General Public License (GPLv2) is included in this
19distribution, in <file:COPYING>.
20
21We have modified our GPLv2 license section 13 to read:
22
23     13. Linking this library statically or dynamically with other
24     modules is making a combined work based on this library. Thus, the
25     terms and conditions of the GNU General Public License cover the
26     whole combination.
27
28     The following paragraph details the "classpath exception" which ABCL
29     allows as an exception to the statement about linking libraries.
30
31     As a special exception, the copyright holders of this software give
32     you permission to link this software with independent modules to
33     produce an executable, regardless of the license terms of these
34     independent modules, and to copy and distribute the resulting
35     executable under terms of your choice, provided that you also meet,
36     for each linked independent module, the terms and conditions of the
37     license of that module. An independent module is a module which is
38     not derived from or based on this software. If you modify this
39     software, you may extend this exception to your version of the
40     software, but you are not obligated to do so. If you do not wish to
41     do so, delete this exception statement from your version.
42
43
44RUNNING FROM DOCKER
45===================
46
47With [Docker Engine][] installed one may execute:
48
49    docker build -t YOURID/abcl .
50    docker run -it YOURID/abcl
51
52to get something like
53
54    illin:~/work/abcl$ docker run -it YOURID/abcl
55    Armed Bear Common Lisp 1.7.0
56    Java 1.7.0_252 Oracle Corporation
57    OpenJDK 64-Bit Server VM
58    Low-level initialization completed in 0.295 seconds.
59    Startup completed in 1.425 seconds.
60    Type ":help" for a list of available commands.
61    CL-USER(1): (lisp-implementation-version)
62    "1.7.0"
63    "OpenJDK_64-Bit_Server_VM-AdoptOpenJDK-11.0.7+10"
64    "x86_64-Mac_OS_X-10.15.5"
65
66To install Quicklisp for ABCL in the Docker container run:
67
68    docker run -t YOURID/abcl abcl \
69      --batch --load /home/abcl/work/abcl/ci/install-quicklisp.lisp
70
71See <file:Dockerfile> for the build instructions.
72
73[Docker Engine]: https://www.docker.com/products/docker-engine
74
75
76
77RUNNING FROM BINARY RELEASE
78===========================
79
80After you have downloaded a binary release from either [the
81distributed Maven POM graph][maven-abcl] or from
82[abcl.org][abcl.org-release] archive unpack it into its own
83directory. To run ABCL directly from this directory, make sure Java
84(Java 6, 7, 8, 11, 13, and 14 are supported by ABCL 1.7.0) is in your
85shell's path.
86
87[maven-abcl]:          <https://mvnrepository.com/artifact/org.abcl/abcl/1.7.0>
88[maven-abcl-contrib]:  <https://mvnrepository.com/artifact/org.abcl/abcl-contrib/1.7.0>
89[abcl.org-release]:    <http://abcl.org/releases/1.7.0/>
90
91To start ABCL, simply issue the following command:
92
93    cmd$ java -jar abcl.jar
94
95which should result in output like the following
96
97    Armed Bear Common Lisp 1.7.0
98    Java 1.8.0_252 AdoptOpenJDK
99    OpenJDK 64-Bit Server VM
100    Low-level initialization completed in 0.222 seconds.
101    Startup completed in 1.09 seconds.
102    Type ":help" for a list of available commands.
103    CL-USER(1):
104
105Yer now at the interactive ABCL "Read Eval Print Loop" (REPL): hacks
106'n glory await.
107
108SWANK
109-----
110
111One may easily start a swank listener via
112
113    (require :asdf)
114    (require :abcl-contrib)
115    (asdf:load-system :quicklisp-abcl :force t)
116    (ql:quickload :swank)                     
117
118
119BUILDING FROM SOURCE RELEASE
120============================
121
122ABCL may be built from its source code by executing the build
123instructions <file:build.xml> expressed by the venerable Apache Ant
124tool.
125
126To build, one must have a Java 6, 7, 8, 11, 13 or 14 Java Development
127Kit (JDK) installed locally. Just the Java Runtime Environment (JRE)
128isn't enough, as you need the Java compiler ('javac') to compile the
129Java source of the ABCL implementation.
130
131Download a binary distribution [Ant version 1.7.1 or greater][ant].
132Unpack the files somewhere convenient, ensuring that the 'ant' (or
133'ant.bat' under Windows) executable is in your path and executable.
134
135[ant]: http://ant.apache.org/bindownload.cgi
136
137Then simply executing
138
139    cmd$ ant
140
141from the directory containing the <file:build.xml> instructions will
142create an executable wrapper ('abcl' under UNIX, 'abcl.bat' under
143Windows).  Use this wrapper to start ABCL.
144
145The build may be customized by copying <file:abcl.properties.in> to
146<file:abcl.properties>, which will cause Ant to attempt to build
147incrementally as well as optimizing the runtime for a contemporary
14864bit desktop/server machine running Java 8 or 11.  The file contains
149incomplete documentation on how it may be edited for subsequent
150customization.  As an alternative to copying the prototype, if one has
151a version of bash locally, one may issue via Ant
152
153    ant abcl.properties.autoconfigure.openjdk.11
154
155or from the shell as
156
157    bash ci/create-abcl-properties.bash openjdk11
158
159Currently upported platforms are 'openjdk6', 'openjdk7', 'openjdk8',
160'openjdk11', 'openjdk13', and 'openjdk14'.
161
162
163Using NetBeans
164--------------
165
166Alternatively, one may install the [Netbeans visual integrated
167development environment][netbeans], which contains both the Java
168Development Kit as well as the Ant build tool.
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
182ABCL is a conforming ANSI Common Lisp implementation.  Any other
183behavior should be reported as a bug.
184
185ABCL now has a 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### Deficiencies
205
206Many.  But patches to address issues mentioned above will be gladly
207accepted.
208
209CONTACT
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 Huelsmann
223    Rudolf Schlatte
224    Alessio Stalla
225    Ville Voutilainen
226
227    alan
228    olof ferada
229    pipping
230    slyrus
231    vibhu
232    dmiles
233
234Have fun!
235
236June 2020
Note: See TracBrowser for help on using the repository browser.