source: branches/1.2.x/README @ 14509

Last change on this file since 14509 was 14509, checked in by Mark Evenson, 9 years ago

abcl-1.2.0-rc-0-1: additional non-functional changes in project metadata.

There should be no direct mention of previous hosting URIs in the
current sources and binaries.

Hopefully clarified licensing for those distributors who choose to
emit the classpath exception to the overarching GPL.

Update README.

  • Property svn:eol-style set to native
File size: 7.5 KB
Line 
1README for Armed Bear Common Lisp
2=================================
3
4### Colophon
5
6<> dc:created "2005" ;
7   a dc:readme ;
8   dc:author "Mark <evenson.not.org@gmail.com>";
9   dc:revised "03-JUN-2012" ;
10   rdfs:seeAlso <http://abcl.org/releases/1.2.0> .
11
12GENERAL INFORMATION
13-------------------
14
15Armed Bear Common Lisp (ABCL) is a conforming implementation of ANSI
16Common Lisp (CL) running in a Java virtual machine (JVM).  ABCL
17features an implementation of CL:COMPILE-FILE that emits operating
18system neutral byte archives packaged by the zip compression format
19which contains artifacts whose loading the implementation of CL:LOAD
20understands.
21
22LICENSE
23=======
24
25Armed Bear Common Lisp is distributed under the GNU General Public
26License with a classpath exception (see "Classpath Exception" below).
27
28A copy of GNU General Public License (GPL) is included in this
29distribution, in the file COPYING.
30
31Linking this software statically or dynamically with other modules is
32making a combined work based on this software. Thus, the terms and
33conditions of the GNU General Public License cover the whole
34combination.
35
36** Classpath Exception
37
38As a special exception, the copyright holders of this software give
39you permission to link this software with independent modules to
40produce an executable, regardless of the license terms of these
41independent modules, and to copy and distribute the resulting
42executable under terms of your choice, provided that you also meet,
43for each linked independent module, the terms and conditions of the
44license of that module. An independent module is a module which is not
45derived from or based on this software. If you modify this software,
46you may extend this exception to your version of the software, but you
47are not obligated to do so. Otherwise, your modified implementation
48now falls under the terms of the original license minus this
49exception.  If you do not wish to do so, delete this exception
50statement from your version.
51
52BUGS
53====
54
55ABCL is a conforming ANSI Common Lisp implementation.  Any other
56behavior should be reported as a bug.
57
58ABCL now has a manual stating its conformance to the ANSI standard,
59providing a compliant and practical Common Lisp implementation.
60
61RUNNING FROM BINARY RELEASE
62===========================
63
64After you have downloaded a binary release archive unpack it into its
65own directory. To run ABCL directly from this directory, make sure
66Java (version 1.5 or up) is in your shell's path. Then issue the
67following command:
68
69    cmd$ java -jar abcl.jar
70
71which should result in output like the following
72
73    Armed Bear Common Lisp 1.2.0
74    Java 1.6.0_21 Sun Microsystems Inc.
75    Java HotSpot(TM) Client VM
76    Low-level initialization completed in 0.3 seconds.
77    Startup completed in 2.294 seconds.
78    Type ":help" for a list of available commands.
79    CL-USER(1):
80
81
82BUILDING FROM SOURCE RELEASE
83============================
84
85There are three ways to build ABCL from the source release with the
86preferred (and most tested way) is to being to use the Ant build tool:
87
88* Use the Ant build tool for Java environments.
89
90* Use the NetBeans [67].x IDE to open ABCL as a project.
91
92* Bootstrap ABCL using a Common Lisp implementation. Supported
93  implementations for this process: SBCL, CMUCL, OpenMCL, Allegro
94  CL, LispWorks or CLISP.
95
96In all cases you need a Java 5 or later JDK (JDK 1.[567] have been
97tested).  Just the JRE isn't enough, as you need the Java compiler
98('javac') to compile the Java source of the ABCL implementation.
99
100Note that when deploying ABCL having JDK isn't a requirement for the
101installation site, just the equivalent JRE, as ABCL compiles directly
102to byte code, avoiding the need for the 'javac' compiler in deployment
103environments.
104
105
106Using Ant
107---------
108
109Download a binary distribution [Ant version 1.7.1 or greater][1].
110Unpack the files somewhere convenient, ensuring that the 'ant' (or
111'ant.bat' under Windows) executable is in your path and executable.
112
113[1]: http://ant.apache.org/bindownload.cgi
114
115Then simply executing
116
117    unix$ ant
118
119or
120
121    dos> ant.bat
122
123from the directory containing this README file will create an
124executable wrapper ('abcl' under UNIX, 'abcl.bat' under Windows).  Use
125this wrapper to start ABCL.
126
127
128Using NetBeans
129--------------
130
131Obtain and install the [NetBeans IDE][2]. One should be able to open
132the ABCL directory as a project in the Netbeans 6.x application,
133whereupon the usual build, run, and debug targets as invoked in the
134GUI are available.
135
136[2]: http://netbeans.org/downloads/
137
138
139Building from Lisp
140------------------
141
142Building from a Lisp is the most venerable and untested way of
143building ABCL.  It produces a "non-standard" version of the
144distribution that doesn't share build instructions with the previous
145two methods, but it still may be of interest to those who absolutely
146don't want to know anything about Java.
147
148First, copy the file 'customizations.lisp.in' to 'customization.lisp',
149in the directory containing this README file, editing to suit your
150situation, paying attention to the comments in the file.  The critical
151step is to have Lisp special variable '*JDK*' point to the root of the
152Java Development Kit.  Underneath the directory referenced by the
153value of '*JDK*' there should be an executable Java compiler in
154'bin/javac' ('bin/java.exe' under Windows).
155
156Then, one may either use the 'build-from-lisp.sh' shell script or load
157the necessary files into your Lisp image by hand.
158
159** Using the 'build-from-lisp.sh' script
160
161Under UNIX-like systems, you may simply invoke the
162'build-from-lisp.sh' script as './build-from-lisp.sh
163<lisp-of-choice>', e.g.
164
165    unix$ ./build-from-lisp.sh sbcl
166
167After a successful build, you may use 'abcl' ('abcl.bat' on Windows)
168to start ABCL.  Note that this wrappers contain absolute paths, so
169you'll need to edit them if you move things around after the build.
170
171If you're developing on ABCL, you may want to use
172
173    unix$ ./build-from-lisp.sh <implementation> --clean=nil
174
175to not do a full rebuild.
176
177In case of failure in the javac stage, you might try this:
178
179    unix$ ./build-from-lisp.sh <implementation> --full=t --clean=t --batch=nil
180
181This invokes javac separately for each .java file, which avoids running
182into limitations on command line length (but is a lot slower).
183
184** Building from another Lisp by hand
185
186There is also an ASDF definition in 'abcl.asd' for the BUILD-ABCL
187which can be used to load the necessary Lisp definitions, after which
188
189    CL-USER> (build-abcl:build-abcl :clean t :full t)
190
191will build ABCL.  If ASDF isn't present, simply LOAD the
192'customizations.lisp' and 'build-abcl.lisp' files to achieve the same
193effect as loading the ASDF definition.
194
195
196
197## Contact
198
199Please report problems to either the [development mailing list][abcl-smtp]:
200
201[abcl-smtp]: http://news.gmane.org/gmane.lisp.armedbear.devel
202
203or the [Trac interface with a suitable OpenID][abcl-trac].
204
205[abcl-trac]   http://lisp.not.org/trac/armedbear
206
207
208
209### Tests
210
211ABCL 1.2.0 now fails only 1[1-3] out of 21708 total tests in the ANSI CL
212test suite (derived from the tests originally written for GCL).
213
214Maxima's test suite runs without failures.
215
216ABCL comes with a test suite.  Please see the output of `ant
217help.test` for more information.
218
219### Deficiencies
220
221As of abcl-1.2.0, there are no known deficiencies with the
222implementation of (A)MOP.
223
224[Please consult the state of issues][abcl-issues] for detailed
225information on the state of the implementation with respect to
226conformance to the ANSI standard.
227
228[abcl-issues]: http://lisp.not.org/trac/armedbear/report/1
229
230Have fun!
231
232# Authors
233
234On behalf of all ABCL development team and contributors,
235
236    Mark Evenson
237    Erik Huelsmann
238    Rudolf Schlatte
239    Alessio Stalla
240    Ville Voutilainen
241
242June 2013
243
Note: See TracBrowser for help on using the repository browser.