source: public_html/faq.shtml @ 13759

Last change on this file since 13759 was 13759, checked in by Mark Evenson, 11 years ago

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