source: public_html/faq.shtml @ 14220

Last change on this file since 14220 was 14220, checked in by Mark Evenson, 8 years ago

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