source: public_html/faq.shtml @ 15271

Last change on this file since 15271 was 15271, checked in by Mark Evenson, 2 years ago

site: publish abcl-1.6.1 URIs

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