source: public_html/faq.shtml @ 13544

Last change on this file since 13544 was 13544, checked in by Mark Evenson, 14 years ago

Spellchecking and proofreading.
  • Property svn:eol-style set to LF
  • Property svn:keywords set to Id
File size: 10.4 KB
Line 
1<?xml version="1.0"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
3    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5<head>
6  <title>FAQ: ABCL - Common Lisp on the JVM</title>
7  <link rel="stylesheet" type="text/css" href="style.css" />
8  <link rel="stylesheet" type="text/css" href="faq-style.css" />
9  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
10</head>
11
12<body>
13 <div class="header">
14   <h1>FAQ: ABCL - Common Lisp on the JVM</h1>
15 </div>
16
17<!--#include virtual="left-menu" -->
18
19<div style="margin-left:auto;margin-right:auto;width:20cm">
20<h1>Index</h1>
21<ol id="toc">
22  <li><a href="#general">General</a>
23  <ol>
24    <li><a href="#what">What is ABCL?</a></li>
25    <li><a href="#license">What license is used for ABCL?</a></li>
26    <li><a href="#bug-reporting">How/Where should I report bugs?</a></li>
27    <li><a href="#speed">Is ABCL faster or slower than implementation XYZ?</a></li>
28    <li><a href="#qa">What is the quality of the implementation? How can you tell?</a></li>
29    <li><a href="#repository">Where is ABCL's source code repository?</a></li>
30    <li><a href="#documentation">Where is ABCL's documentation?</a></li>
31  </ol>
32  </li> <!-- general -->
33
34  <li><a href="#building">Building</a>
35  <ol>
36    <li><a href="#avoiding-recompilation">The Ant build process seems to recompile from scratch each time.  How do I avoid this?</a></li>
37  </ol>
38  </li> 
39
40  <li><a href="#running">Running</a>
41  <ol>
42    <li><a href="#maxpermgen-errors">Java is running out of memory
43    with an error reporting something about
44    "java.lang.OutOfMemoryError: PermGen space".  What can I
45    do?</a></li>
46  </ol>
47  </li> 
48</ol>
49
50
51<div class="h2" title="general" id="general">
52<h2>General</h2>
53
54<div class="h3" title="what" id="what">
55<h3>What is ABCL?</h3>
56<p>ABCL is an implementation of the full Common Lisp specification, with
57the exception of the implementation of the long form of
58DEFINE-METHOD-COMBINATION.</p>
59
60<p>
61Unfortunately, the CLOS implementation is not fully completely through
62a MOP (MetaObject Protocol). Perhaps roughly a third of the
63functionality defined by <a
64href="http://www.lisp.org/mop/index.html">AMOP</a> is present.  Any
65contributions in this area would be greatly appreciated, of course.
66</p>
67</div>
68
69
70<div class="h3" title="license" id="license">
71<h3>What license is used for ABCL?</h3>
72
73<p>ABCL is distributed under the <a href="http://www.gnu.org/copyleft/gpl.html"
74>GNU General Public License</a> with <a
75href="http://www.gnu.org/software/classpath/license.html">Classpath
76exception</a>. This is the same license as used for JAVA SE and GNU Classpath.</p>
77
78<p>Basically this means you can use ABCL from your application without the
79need to make your own application open source.</p>
80
81<p>
82In general, such usage means that whenever you keep ABCL as a separate
83jar file, you won't have licensing problems. The combining in the
84Classpath exception means that you can
85</p>
86<ol>
87<li>Extend ABCL java classes in your program</li>
88<li>Use ABCL java classes in your program</li>
89<li>Invoke ABCL lisp functions in your program</li>
90</ol>
91<p>
92without having to worry about the licensing. You do have to
93distribute the source code of ABCL (including modifications)
94if you distribute ABCL, but otherwise the license of ABCL is not viral.
95</p>
96</div>
97
98<div class="h3" title="bug-reporting" id="bug-reporting">
99<h3>How/Where should I report bugs?</h3>
100
101<p>
102The current state of issues can be found in the <a
103href="http://trac.common-lisp.net/armedbear/report/1">ABCL issue
104tracker</a>.  Individuals with an <a
105href="http://en.wikipedia.org/wiki/Openid">OpenID</a> such as a Google
106ID may enter information directly in the bug tracker after
107authenticating by your provider. </p>
108
109<p>
110
111Alternatively, to report a bug, please mail a description of the
112problem, the version of ABCL you are using, and if possible a set of
113steps to reproduce the problem to the <a
114href="http://common-lisp.net/cgi-bin/mailman/listinfo/armedbear-devel">armedbear-devel
115mailing list</a>.  We try to respond within a day at most to messages.
116A convenient way to browse the mailing list archives can be found by
117<a href="http://news.gmane.org/gmane.lisp.armedbear.devel">the gmane
118loom interface to the NNTP group gmane.lisp.armedbear.devel</a>.
119</p>
120
121<p>
122Developers can also usually be found on the <a
123href="http://webchat.freenode.net/?randomnick=1&channels=abcl&prompt=1&uio=d4">#abcl
124irc channel</a>.
125</p>
126
127<div class="h3" title="speed" id="speed">
128<h3>Is ABCL faster or slower than implementation XYZ?</h3>
129
130<p>General comparisons are hard to make, the relative speeds depend
131on a lot of factors. For example timing outcomes of specific bits
132of Java may have different timings depending on the settings of
133the HotSpot JIT compiler (if the tests are run on Sun).</p>
134
135<p>Some statements can be made in general though. Due to the fact that
136ABCL has been implemented in Java, it inherits some of the aspects of
137Java itself as well as the fact that it can't directly manipulate
138CPU content. Implementations such as SBCL and Closure CL can do that and
139take that to their advantage: for example in SBCL a boxed fixnum is a
140direct register value, while in ABCL it's encapsulated in an object.</p>
141
142<p>On the other hand, ABCL - like SBCL - supports unboxed fixnums. ABCL's
143fixnums support the full 32 bit range of integer values, while SBCL due
144to its boxing strategy can only use 29 bit integers (on 32bit platforms).</p>
145
146<p>Given ABCL's age - a young project by Lisp standards - there is also
147plenty of room for improvement in the area of execution speed and optimization.
148The project welcomes initiatives to improve performance.</p>
149</div>
150
151
152<div class="h3" title="qa" id="qa">
153<h3>What is the quality of the implementation? How can you tell?</h3>
154
155<p>The project recognizes there are several dimensions to quality:</p>
156<ol>
157<li> The level of compliance to the standard </li>
158<li> The level of 'usability': whether (or not) the application is able
159  to run existing Lisp code</li>
160</ol>
161
162<p>
163The plan is to ensure that ABCL runs with the software provided by
164<a href="http://www.quicklisp.org/">Quicklisp</a>.  For many packages available from Quicklisp,
165this is already the case.
166</p>
167
168<p>The first item is being measured by running the ANSI test suite compliance
169  tests. The second item is measured by compiling and running the test suite
170  in the <a href="http://maxima.sourceforge.net/">Maxima application</a>.
171  Additionally, compilation of <a href="http://ap5.com/">AP5</a> is used to
172  improve this measure too.</p>
173
174<p>ABCL 0.26.2 fails roughly 20 out of 21702 tests in the ANSI test
175suite in interpreted and compiled modes, a constant number over the
176past releases.</p>
177
178<p>As a measure of 'improvement achieved', the development team refers
179  to the number of failing tests in the Maxima test suite too.
180  ABCL 0.23.0 is able to run the test suite without failures, coming from
181  'only' ca 75 failing tests at the time of 0.15.0, and even 1400 failures
182  around October 2008.</p>
183</div>
184
185<div class="h3" title="repository" id="repository">
186<h3>Where is ABCL's source code repository?</h3>
187
188<p>If you want to build the latest (unstable) ABCL code,
189you can check out through
190svn://common-lisp.net/project/armedbear/svn/trunk/abcl.</p>
191
192<p>
193This repository is also exported read-only via HTTP at
194<a href="http://svn.common-lisp.net/armedbear/trunk/abcl">http://svn.common-lisp.net/armedbear/trunk/abcl</a>
195</p>
196</div>
197
198<div class="h3" title="documentation" id="documentation">
199<h3>Where is ABCL's documentation?</h3>
200
201<p>Documentation on ABCL can be found in several places, depending on the
202  kind of documentation you're looking for.</p>
203
204<ol>
205  <li>Our <a href="http://trac.common-lisp.net/armedbear/wiki">wiki</a></li>
206  <li>The <a href="http://trac.common-lisp.net/armedbear/browser">source
207    code (JavaDoc and general comments)</a></li>
208  <li>Specific <a
209href="http://trac.common-lisp.net/armedbear/browser/trunk/abcl/examples">examples</a></li>
210</ol>
211</div>
212
213</div>
214
215<div class="h2" title="Building" id="building">
216<h2>Building</h2>
217
218<div class="h3" title="Avoiding recompilation" id="avoiding-recompilation">
219<h3>The Ant build process seems to recompile from scratch each time.  How do I avoid this?</h3>
220
221<p>
222If the JVM system property <code>abcl.build.incremental</code> is set,
223the Ant build process will attempt to build ABCL incrementally
224by not removing any intermediate results.  The easiest way to enable
225this property is to copy the 'abcl.properties.in' file to
226'abcl.properties', then uncomment the line referencing the setting of
227the <code>abcl.build.incremental</code> property.
228</p>
229</div>
230
231</div>
232
233<div class="h2" title="Running" id="running">
234<h2>Running</h2>
235
236<div class="h3" title="Out of Memory errors" id="maxpermgen-errors">
237<h3>Java is running out of memory with an error reporting something
238about "java.lang.OutOfMemoryError: PermGen space".  What can I
239do?</h3>
240
241<p>
242  You need to increase the memory which the Java allocates for
243  permanent generation ("PermGen)" objects by using the appropriate
244  switch on command line which invokes the JVM hosting ABCL.  When the
245  implementation compiles or loads Lisp code, it creates a separate
246  JVM class for each top-level form.  With large workloads, this can
247  overrun the part of memory which Java reserves for storing the class
248  definition which results in the error you are seeing.
249</p>
250
251<p>
252  The exact manner of configuring this option unfortunately varies by
253  Java implementation.  For the Oracle HotSpot 64bit JVM, something
254  like <code>"-d64 -Xmx4g -XX:MaxPermSize=1g
255  -XX:+CMSClassUnloadingEnabled"</code> will not only increase the
256  PermGen space, but will ensure you always invoke the 64bit JVM,
257  increase the maximum memory space available to the Java to 4GiB, and
258  allow the garbage collection of class definitions which are deemed
259  to be unused.
260</p>
261
262<p>
263  If you are compiling ABCL from source, a handy way to have the build
264  process incorporate such runtime flags in the JVM invocation would
265  be to copy the <code>'abcl.properties.in'</code> file to
266  <code>'abcl.properties'</code>, and then ensure that the
267  <code>'java.options'</code> variable is set to the desired options.
268</p>
269</div>
270
271</div>
272
273</div>
274
275<div style="float:left;width:100%">
276 <hr />
277 <p>Back to <a href="http://common-lisp.net/">Common-lisp.net</a>.</p>
278
279 <div class="check">
280   <a href="http://validator.w3.org/check/referer">Valid XHTML 1.0 Strict</a>
281 </div>
282<div style="float:right;font-size:10px;font-family:monospace">$Id: faq.shtml 13544 2011-08-28 08:39:42Z mevenson $</div>
283</div>
284</div>
285</body>
286</html>
Note: See TracBrowser for help on using the repository browser.