source: public_html/faq.shtml @ 13543

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

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