source: public_html/faq.shtml

Last change on this file was 15540, checked in by Mark Evenson, 4 years ago

html: really fix the link to the User Manual
  • Property svn:eol-style set to LF
  • Property svn:keywords set to Id
File size: 11.7 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: 9em;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> with
90the <a href="http://www.gnu.org/software/classpath/license.html">Classpath
91exception</a>. 
92</p>
93
94<p>
95  This allows the distribution of programs running on ABCL to specify
96their own licensing terms as long as ABCL itself is unmodified.  This
97means you can use ABCL from your application without the need to make
98your own application open source.
99</p>
100
101<p>
102  In general, such usage means that whenever you keep ABCL as a
103separate jar file, you won't have licensing problems. The combining in
104the Classpath exception means that you can
105</p>
106
107<ol>
108  <li>Extend ABCL java classes in your program</li>
109  <li>Use ABCL java classes in your program</li>
110  <li>Invoke ABCL lisp functions in your program</li>
111</ol>
112<p>
113  without having to worry about the licensing. You do have to
114distribute the source code of ABCL (including modifications) if you
115distribute ABCL, but otherwise the license of ABCL is not viral.
116</p>
117</div>
118
119<div class="h3" title="bug-reporting" id="bug-reporting">
120<h3 class="question">How/Where should I report bugs?</h3>
121
122<p>
123The current state of issues can be found in the <a
124href="http://abcl.org/trac/report/1">ABCL issue
125tracker</a>.  Individuals with an <a
126href="http://en.wikipedia.org/wiki/Openid">OpenID</a> such as a Google
127ID may enter information directly in the bug tracker after
128authenticating by your provider. </p>
129
130<p>
131
132Alternatively, to report a bug, please mail a description of the
133problem, the version of ABCL you are using, and if possible a set of
134steps to reproduce the problem to
135the <a href="https://mailman.common-lisp.net/pipermail/armedbear-devel/">armedbear-devel
136mailing list</a>.  We endeavor to respond within a day to messages.
137</p>
138
139<p>
140Developers can also usually be found on the
141<a href="https://web.libera.chat/gamja#abcl">#abcl Libera IRC channel</a>.
142</p>
143
144<div class="h3" title="speed" id="speed">
145<h3 class="question">Is ABCL faster or slower than implementation XYZ?</h3>
146
147<p>General comparisons are hard to make, the relative speeds depend
148on a lot of factors. For example timing outcomes of specific bits
149of Java may have different timings depending on the settings of
150the HotSpot JIT compiler (if the tests are run on Sun).</p>
151
152<p>Some statements can be made in general though. Due to the fact that
153ABCL has been implemented in Java, it inherits some of the aspects of
154Java itself as well as the fact that it can't directly manipulate
155CPU content. Implementations such as SBCL and Closure CL can do that and
156take that to their advantage: for example in SBCL a boxed fixnum is a
157direct register value, while in ABCL it's encapsulated in an object.</p>
158
159<p>On the other hand, ABCL - like SBCL - supports unboxed fixnums. ABCL's
160fixnums support the full 32 bit range of integer values, while SBCL due
161to its boxing strategy can only use 29 bit integers (on 32bit platforms).</p>
162
163<p>Given ABCL's age - a young project by Lisp standards - there is also
164plenty of room for improvement in the area of execution speed and optimization.
165The project welcomes initiatives to improve performance.</p>
166</div>
167
168
169<div class="h3" title="qa" id="qa">
170<h3 class="question">What is the quality of the implementation? How can you tell?</h3>
171
172<p>The project recognizes there are several dimensions to quality:</p>
173<ol>
174<li> The level of compliance to the standard </li>
175<li> The level of 'usability': whether (or not) the application is able
176  to run existing Lisp code</li>
177</ol>
178
179<p>
180The plan is to ensure that ABCL runs with the software provided by
181<a href="http://www.quicklisp.org/">Quicklisp</a>.  For many packages available from Quicklisp,
182this is already the case.
183</p>
184
185<p>The first item is being measured by running the ANSI test suite compliance
186  tests. The second item is measured by compiling and running the test suite
187  in the <a href="http://maxima.sourceforge.net/">Maxima application</a>.
188  Additionally, compilation of <a href="http://ap5.com/">AP5</a> is used to
189  improve this measure too.</p>
190
191<p>ABCL 1.7.0 fails 46 out of 21848 tests in the
192<a href="https://gitlab.common-lisp.net/ansi-test/ansi-test">ANSI-TEST
193suite</a>.
194
195<p>As a measure of 'improvement achieved', the development team refers
196  to the number of failing tests in the Maxima test suite too.
197  ABCL 0.23.0 is able to run the test suite without failures, coming from
198  'only' ca 75 failing tests at the time of 0.15.0, and even 1400 failures
199  around October 2008.</p>
200</div>
201
202<div class="h3" title="repository" id="repository">
203<h3 class="question">Where is ABCL's source code repository?</h3>
204
205<p>
206  We synchronize our source code across three repositories, two using
207  git and one using subversion.  These days, most people seem to
208  colloborate on our Github instance.
209</p>
210
211<dl>
212  <dt>
213    <a href="https://github.com/armedbear/abcl">Github</a>
214  </dt>
215  <dd>
216    &lt;git+https://github.com/armedbear/abcl&gt;
217  </dd>
218  <dt>
219    Git on <a href="https://gitlab.common-lisp.net/abcl/abcl/">gitlab.common-lisp.net</a>
220  </dt>
221  <dd>
222    &lt;git+https://gitlab.common-lisp.net/abcl/abcl&gt;
223  </dd>
224  <dt>
225    SVN on <a href="https://abcl.org/svn/">abcl.org</a>
226  </dt>
227  <dd>
228    &lt;svn+https://abcl.org/svn/trunk/abcl&gt;
229  </dd>
230</dl>
231
232</div>
233
234<div class="h3" title="documentation" id="documentation">
235<h3 class="question">Where is ABCL's documentation?</h3>
236
237<p>Documentation on ABCL can be found in several places, depending on the
238  kind of documentation you're looking for.</p>
239
240<ol>
241  <li id="user-manual">Users of the system are invited to start with the fine <a href="https://abcl.org/releases/1.8.0/abcl-1.8.0.pdf">User Manual</a></li>
242  <li>Our <a href="http://abcl.org/trac/wiki">wiki</a></li>
243  <li>The <a href="http://abcl.org/trac/browser">source
244    code (JavaDoc and general comments)</a></li>
245  <li>Specific <a href="http://abcl.org/trac/browser/trunk/abcl/examples">examples</a></li>
246  <li>Issues filed against the the GitHub <a href="https://github.com/armedbear/abcl/issues">clone</a>.
247</ol>
248</div>
249
250</div>
251
252<div class="h2" title="Building" id="building">
253<h2 class="topic">Building</h2>
254
255<div class="h3" title="Avoiding recompilation" id="avoiding-recompilation">
256<h3 class="question">The Ant build process seems to recompile from scratch each time.  How do I avoid this?</h3>
257
258<p>
259If the JVM system property <code>abcl.build.incremental</code> is set,
260the Ant build process will attempt to build ABCL incrementally
261by not removing any intermediate results.  The easiest way to enable
262this property is to copy the 'abcl.properties.in' file to
263'abcl.properties', then uncomment the line referencing the setting of
264the <code>abcl.build.incremental</code> property.
265</p>
266
267</div>
268
269</div>
270
271<div class="h2" title="Running" id="running">
272<h2 class="topic">Running</h2>
273
274<div class="h3" title="Out of Memory errors" id="maxpermgen-errors">
275<h3 class="question">Java is running out of memory with an error reporting something
276about "java.lang.OutOfMemoryError: PermGen space".  What can I
277do?</h3>
278
279<p>
280  One needs to increase the memory which the Java allocates for
281  permanent generation ("PermGen)" objects by using the appropriate
282  switch on command line which invokes the JVM hosting ABCL.  When the
283  implementation compiles or loads Lisp code, it creates a separate
284  JVM class for each top-level form.  With large workloads, this can
285  overrun the part of memory which Java reserves for storing the class
286  definition which results in the error you are seeing.
287</p>
288
289<p>
290  The exact manner of configuring this option unfortunately varies by
291  Java implementation.  For the Oracle HotSpot 64bit JVM, something
292  like <code>"-d64 -Xmx4g -XX:MaxPermSize=1g
293  -XX:+CMSClassUnloadingEnabled"</code> will not only increase the
294  PermGen space, but will ensure you always invoke the 64bit JVM,
295  increase the maximum memory space available to the Java to 4GiB, and
296  allow the garbage collection of class definitions which are deemed
297  to be unused.
298</p>
299
300<p>
301  If you are compiling ABCL from source, a handy way to have the build
302  process incorporate such runtime flags in the JVM invocation would
303  be to copy the <code>'abcl.properties.in'</code> file to
304  <code>'abcl.properties'</code>, and then ensure that the
305  <code>'java.options'</code> variable is set to the desired options.
306</p>
307
308<div class="h3" title="What is the name of the startup run control script?" id="dotabclrc">
309<h3 class="question">Is there a file that customizes the startup of the ABCL process?</h3>
310
311<p>
312  The file <code>~/.abclrc</code> is loaded by the implementation if the <code>--noinit</code> flag is not specified.
313</p>
314</div>
315</div>
316
317</div>
318
319</div>
320
321</div>
322
323<div class="footer">
324  <hr />
325  <p>Hosted as part of <a href="https://common-lisp.net/">common-lisp.net</a></p>
326</div>
327
328</body>
329</html>
Note: See TracBrowser for help on using the repository browser.