source: public_html/faq.shtml @ 15316

Last change on this file since 15316 was 15316, checked in by Mark Evenson, 3 years ago

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