source: trunk/abcl/README

Last change on this file was 15079, checked in by mevenson, 6 months ago

Mark source as building 1.6.0-dev

  • Property svn:eol-style set to native
File size: 6.3 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 modfied 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 run -it easye/abcl
50
51to get
52
53    illin:~/work/abcl$ docker run -it easye/abcl
54    Armed Bear Common Lisp 1.6.0-dev
55    Java 1.8.0_111 Oracle Corporation
56    OpenJDK 64-Bit Server VM
57    Low-level initialization completed in 0.295 seconds.
58    Startup completed in 1.425 seconds.
59    Type ":help" for a list of available commands.
60    CL-USER(1): 23
61    23
62
63
64[Docker Engine]: https://www.docker.com/products/docker-engine
65
66
67Building a Docker Image With Modifications
68------------------------------------------
69
70Get the source (see below); make yer mods; use the Dockerfile to build.
71
72        docker build -t YOURID/abcl .
73        docker run -it YOURID/abcl
74
75See <file:Dockerfile> for the build instructions.
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 Java
85(version 1.6 or up) is in your shell's path.
86
87[maven-abcl]:          <https://mvnrepository.com/artifact/org.abcl/abcl/1.5.0>
88[maven-abcl-contrib]:  <https://mvnrepository.com/artifact/org.abcl/abcl-contrib/1.5.0>
89[abcl.org-release]:    <http://abcl.org/releases/1.5.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.6.0-dev
98    Java 1.8.0_131 Oracle Corporation
99    Java HotSpot(TM) 64-Bit Server VM
100    Low-level initialization completed in 0.324 seconds.
101    Startup completed in 1.892 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
108
109BUILDING FROM SOURCE RELEASE
110============================
111
112ABCL may be built from its source code by executing the build
113instructions <file:build.xml> expressed by the venerable Apache Ant
114tool.
115
116To build, one must have a Java 6, 7 or 8 Java Development Kit (JDK)
117installed locally. Just the Java Runtime Environment (JRE) isn't
118enough, as you need the Java compiler ('javac') to compile the Java
119source of the ABCL implementation.
120
121Download a binary distribution [Ant version 1.7.1 or greater][ant].
122Unpack the files somewhere convenient, ensuring that the 'ant' (or
123'ant.bat' under Windows) executable is in your path and executable.
124
125[ant]: http://ant.apache.org/bindownload.cgi
126
127Then simply executing
128
129    cmd$ ant
130
131from the directory containing the <file:build.xml> instructions will
132create an executable wrapper ('abcl' under UNIX, 'abcl.bat' under
133Windows).  Use this wrapper to start ABCL.
134
135The build may be customized by copying <file:abcl.properties.in> to
136<file:abcl.properties>, which will cause Ant to attempt to build
137incrementally as well as optimizing the runtime for a contemporary
13864bit desktop/server machine running Java 8.  The file may be edited
139for further customization.
140
141
142Using NetBeans
143--------------
144
145Alternatively, one may install the [Netbeans visual integrated
146development environment][netbeans], which contains both the Java
147Development Kit as well as the Ant build tool.
148
149With Netbeans, one should be able to open the ABCL directory as a
150project whereupon the usual build, run, and debug targets as invoked
151in the GUI are available.  Use the 'slime' config with a suitably
152linked 'swank.asd' in '~/.asdf-install-dir/systems/' to connect a REPL
153to the NetBeans debug process.
154
155[netbeans]: http://netbeans.org/downloads/
156
157
158BUGS
159====
160
161ABCL is a conforming ANSI Common Lisp implementation.  Any other
162behavior should be reported as a bug.
163
164ABCL now has a manual stating its conformance to the ANSI standard,
165providing a compliant and practical Common Lisp implementation.
166
167
168Tests
169-----
170
171ABCL 1.5.0 now fails 48 out of 21708 total tests in the [revised and
172expanded ANSI CL test suite][ansi-test] (derived from the tests
173originally written for GCL).
174
175[ansi-test]: git+https://gitlab.common-lisp.net/ansi-test/ansi-test.git
176
177Maxima's test suite runs without failures.
178
179ABCL comes with a test suite, see the output of `ant help.test` for
180more information.
181
182### Deficiencies
183
184Many.  But patches to address issues mentioned above will be gladly
185accepted.
186
187CONTACT
188=======
189
190Please report problems to the development mailing list:
191
192    <armedbear-devel@common-lisp.net>
193
194Have fun!
195
196AUTHORS
197=======
198
199On behalf of all ABCL development team and contributors,
200
201    Mark Evenson
202    Erik Huelsmann
203    Rudolf Schlatte
204    Alessio Stalla
205    Ville Voutilainen
206
207    alan
208    olof ferada
209    pipping
210    slyrus
211    vibhu
212    dmiles
213
214June 2017
215
216
Note: See TracBrowser for help on using the repository browser.