FAQ: ABCL - Common Lisp on the JVM

Frequently Asked Questions about Armed Bear Common Lisp

  1. General Questions about ABCL
    1. What is ABCL?
    2. What license is used for ABCL?
    3. How/Where should I report bugs?
    4. Is ABCL faster or slower than implementation XYZ?
    5. What is the quality of the implementation? How can you tell?
    6. Where is ABCL's source code repository?
    7. Where is ABCL's documentation?
  2. Questions about Building ABCL
    1. The Ant build process seems to recompile from scratch each time. How do I avoid this?
  3. Questions about Running ABCL
    1. Java is running out of memory with an error reporting something about "java.lang.OutOfMemoryError: PermGen space". What can I do?
    2. What's the name of the startup configuration file?

General

What is ABCL?

ABCL stands for Armed Bear Common Lisp. ABCL is an implementation of Common Lisp hosted on the Java Virtual Machine. With the release of abcl-1.0, Armed Bear Common Lisp is a conforming implementation of the ANSI Common Lisp specification. The required statement of conformance is included in the User Manual.

With the release of version 1.1.0, ABCL contains a complete implementation of The Common Lisp Object System MetaObject Protocol, and is now supported by CLOSER-MOP.

What license is used for ABCL?

ABCL is distributed under the GNU General Public License with the Classpath exception.

This allows the distribution of programs running on ABCL to specify their own licensing terms as long as ABCL itself is unmodified. This means you can use ABCL from your application without the need to make your own application open source.

In general, such usage means that whenever you keep ABCL as a separate jar file, you won't have licensing problems. The combining in the Classpath exception means that you can

  1. Extend ABCL java classes in your program
  2. Use ABCL java classes in your program
  3. Invoke ABCL lisp functions in your program

without having to worry about the licensing. You do have to distribute the source code of ABCL (including modifications) if you distribute ABCL, but otherwise the license of ABCL is not viral.

How/Where should I report bugs?

The current state of issues can be found in the ABCL issue tracker. Individuals with an OpenID such as a Google ID may enter information directly in the bug tracker after authenticating by your provider.

Alternatively, to report a bug, please mail a description of the problem, the version of ABCL you are using, and if possible a set of steps to reproduce the problem to the armedbear-devel mailing list. We endeavor to respond within a day to messages.

Developers can also usually be found on the #abcl Libera IRC channel.

Is ABCL faster or slower than implementation XYZ?

General comparisons are hard to make, the relative speeds depend on a lot of factors. For example timing outcomes of specific bits of Java may have different timings depending on the settings of the HotSpot JIT compiler (if the tests are run on Sun).

Some statements can be made in general though. Due to the fact that ABCL has been implemented in Java, it inherits some of the aspects of Java itself as well as the fact that it can't directly manipulate CPU content. Implementations such as SBCL and Closure CL can do that and take that to their advantage: for example in SBCL a boxed fixnum is a direct register value, while in ABCL it's encapsulated in an object.

On the other hand, ABCL - like SBCL - supports unboxed fixnums. ABCL's fixnums support the full 32 bit range of integer values, while SBCL due to its boxing strategy can only use 29 bit integers (on 32bit platforms).

Given ABCL's age - a young project by Lisp standards - there is also plenty of room for improvement in the area of execution speed and optimization. The project welcomes initiatives to improve performance.

What is the quality of the implementation? How can you tell?

The project recognizes there are several dimensions to quality:

  1. The level of compliance to the standard
  2. The level of 'usability': whether (or not) the application is able to run existing Lisp code

The plan is to ensure that ABCL runs with the software provided by Quicklisp. For many packages available from Quicklisp, this is already the case.

The first item is being measured by running the ANSI test suite compliance tests. The second item is measured by compiling and running the test suite in the Maxima application. Additionally, compilation of AP5 is used to improve this measure too.

ABCL 1.7.0 fails 46 out of 21848 tests in the ANSI-TEST suite.

As a measure of 'improvement achieved', the development team refers to the number of failing tests in the Maxima test suite too. ABCL 0.23.0 is able to run the test suite without failures, coming from 'only' ca 75 failing tests at the time of 0.15.0, and even 1400 failures around October 2008.

Where is ABCL's source code repository?

We synchronize our source code across three repositories, two using git and one using subversion. These days, most people seem to colloborate on our Github instance.

Github
<git+https://github.com/armedbear/abcl>
Git on gitlab.common-lisp.net
<git+https://gitlab.common-lisp.net/abcl/abcl>
SVN on abcl.org
<svn+https://abcl.org/svn/trunk/abcl>

Where is ABCL's documentation?

Documentation on ABCL can be found in several places, depending on the kind of documentation you're looking for.

  1. Users of the system are invited to start with the fine User Manual
  2. Our wiki
  3. The source code (JavaDoc and general comments)
  4. Specific examples
  5. Issues filed against the the GitHub clone.

Building

The Ant build process seems to recompile from scratch each time. How do I avoid this?

If the JVM system property abcl.build.incremental is set, the Ant build process will attempt to build ABCL incrementally by not removing any intermediate results. The easiest way to enable this property is to copy the 'abcl.properties.in' file to 'abcl.properties', then uncomment the line referencing the setting of the abcl.build.incremental property.

Running

Java is running out of memory with an error reporting something about "java.lang.OutOfMemoryError: PermGen space". What can I do?

One needs to increase the memory which the Java allocates for permanent generation ("PermGen)" objects by using the appropriate switch on command line which invokes the JVM hosting ABCL. When the implementation compiles or loads Lisp code, it creates a separate JVM class for each top-level form. With large workloads, this can overrun the part of memory which Java reserves for storing the class definition which results in the error you are seeing.

The exact manner of configuring this option unfortunately varies by Java implementation. For the Oracle HotSpot 64bit JVM, something like "-d64 -Xmx4g -XX:MaxPermSize=1g -XX:+CMSClassUnloadingEnabled" will not only increase the PermGen space, but will ensure you always invoke the 64bit JVM, increase the maximum memory space available to the Java to 4GiB, and allow the garbage collection of class definitions which are deemed to be unused.

If you are compiling ABCL from source, a handy way to have the build process incorporate such runtime flags in the JVM invocation would be to copy the 'abcl.properties.in' file to 'abcl.properties', and then ensure that the 'java.options' variable is set to the desired options.

Is there a file that customizes the startup of the ABCL process?

The file ~/.abclrc is loaded by the implementation if the --noinit flag is not specified.