Introduction
************

SBCL is a mostly-conforming implementation of the ANSI Common Lisp standard. This manual focuses on behavior which is specific to SBCL, not on behavior which is common to all implementations of ANSI Common Lisp.

Sources of information about Common Lisp
========================================

Regardless of your ability level, two very useful resources for working with any implementation of Common Lisp are the SLIME package (Historically, the ILISP package at http://ilisp.cons.org/ provided similar functionality, but it does not support modern SBCL versions.)  for Emacs at http://www.common-lisp.net/project/slime and the Common Lisp HyperSpec at http://www.lispworks.com/reference/HyperSpec/index.html.

If you're not a programmer and you're trying to learn, many introductory Lisp books are available. However, we don't have any standout favorites. If you can't decide, try checking the Usenet news://comp.lang.lisp FAQ for recent recommendations.

If you are an experienced programmer in other languages but need to learn about Lisp, three books stand out.

  * ANSI Common Lisp, by Paul Graham, will teach you about most of the language. (And later it might also be worth checking out On Lisp, by the same author.)

  * Paradigms Of Artificial Intelligence Programming, by Peter Norvig, also has some good information on general Common Lisp programming, and many nontrivial examples. Whether or not your work is AI, it's a very good book to look at.

  * Neither of the books above emphasizes CLOS, but Object-Oriented Programming In Common Lisp by Sonya Keene does. Even if you're very knowledgeable about object oriented programming in the abstract, it's worth looking at this book if you want to do any OO in Common Lisp. Some abstractions in CLOS (especially multiple dispatch) go beyond anything you'll see in most OO systems, and there are a number of lesser differences as well. This book tends to help with the culture shock.

Sources of more information about SBCL
======================================

Before you read this user manual, you should probably read two other things.

  * You should know how to program in Common Lisp.  If you don't already know how, you should probably read a book on it.  See More Common Lisp Information.

  * The Unix ``man page'' for SBCL will tell you how to start the SBCL environment, so you can get to the classic ``hello, world'' level of knowledge. It's the file called sbcl.1 in the SBCL distribution. If SBCL is installed on your system, you can read a formatted copy by executing the command man sbcl.

Besides this user manual and the Unix man page, some other SBCL-specific information is available:

  * The SBCL home page at http://www.sbcl.org/ has some general information, plus links to mailing lists devoted to SBCL, and to archives of these mailing lists.

  * Documentation for non-ANSI extensions for various commands is available online from the SBCL executable itself. The extensions for functions which have their own command prompts (e.g. the debugger, and inspect) are documented in text available by typing help at their command prompts. The extensions for functions which don't have their own command prompt (such as trace) are described in their documentation strings, unless your SBCL was compiled with an option not to include documentation strings, in which case the doc strings are only readable in the source code.

  * Some low-level information describing the programming details of the conversion from CMUCL to SBCL is available in the doc/FOR-CMUCL-DEVELOPERS file in the SBCL distribution.

History and Implementation
==========================

You can work productively with SBCL without knowing anything understanding anything about where it came from, how it is implemented, or how it extends the ANSI Common Lisp standard. However, a little knowledge can be helpful in order to understand error messages, to troubleshoot problems, to understand why some parts of the system are better debugged than others, and to anticipate which known bugs, known performance problems, and missing extensions are likely to be fixed, tuned, or added.

SBCL is descended from CMUCL, which is itself descended from Spice Lisp, including early implementations for the Mach operating system on the IBM RT, back in the 1980s. Some design decisions from that time are still reflected in the current implementation:

  * The system expects to be loaded into a fixed-at-compile-time location in virtual memory, and also expects the location of all of its heap storage to be specified at compile time.

  * The system overcommits memory, allocating large amounts of address space from the system (often more than the amount of virtual memory available) and then failing if ends up using too much of the allocated storage.

  * The system is implemented as a C program which is responsible for supplying low-level services and loading a Lisp .core file.

SBCL also inherited some newer architectural features from CMUCL. The most important is that on some architectures it has a generational garbage collector (``GC''), which has various implications (mostly good) for performance. These are discussed in another chapter, Efficiency.

SBCL has diverged from CMUCL in that SBCL is now essentially a ``compiler-only implementation'' of Common Lisp. This is a change in implementation strategy, taking advantage of the freedom ``any of these facilities might share the same execution strategy'' guaranteed in the ANSI specification section 3.1 (``Evaluation''). It does not mean SBCL can't be used interactively, and in fact the change is largely invisible to the casual user, since SBCL still can and does execute code interactively by compiling it on the fly. (It is visible if you know how to look, like using compiled-function-p; and it is visible in the way that that SBCL doesn't have many bugs which behave differently in interpreted code than in compiled code.) What it means is that in SBCL, the eval function only truly ``interprets'' a few easy kinds of forms, such as symbols which are boundp. More complicated forms are evaluated by calling compile and then calling funcall on the returned result.

The direct ancestor of SBCL is the x86 port of CMUCL. This port was in some ways the most cobbled-together of all the CMUCL ports, since a number of strange changes had to be made to support the register-poor x86 architecture. Some things (like tracing and debugging) do not work particularly well there. SBCL should be able to improve in these areas (and has already improved in some other areas), but it takes a while.

On the x86 SBCL -- like the x86 port of CMUCL -- uses a conservative GC. This means that it doesn't maintain a strict separation between tagged and untagged data, instead treating some untagged data (e.g. raw floating point numbers) as possibly-tagged data and so not collecting any Lisp objects that they point to. This has some negative consequences for average time efficiency (though possibly no worse than the negative consequences of trying to implement an exact GC on a processor architecture as register-poor as the X86) and also has potentially unlimited consequences for worst-case memory efficiency. In practice, conservative garbage collectors work reasonably well, not getting anywhere near the worst case. But they can occasionally cause odd patterns of memory usage.

The fork from CMUCL was based on a major rewrite of the system bootstrap process. CMUCL has for many years tolerated a very unusual ``build'' procedure which doesn't actually build the complete system from scratch, but instead progressively overwrites parts of a running system with new versions. This quasi-build procedure can cause various bizarre bootstrapping hangups, especially when a major change is made to the system. It also makes the connection between the current source code and the current executable more tenuous than in other software systems -- it's easy to accidentally ``build'' a CMUCL system containing characteristics not reflected in the current version of the source code.

Other major changes since the fork from CMUCL include

  * SBCL has removed many CMUCL extensions, (e.g. IP networking, remote procedure call, Unix system interface, and X11 interface) from the core system.  Most of these are available as contributed modules (distributed with sbcl) or third-party modules instead.

  * SBCL has deleted or deprecated some nonstandard features and code complexity which helped efficiency at the price of maintainability. For example, the SBCL compiler no longer implements memory pooling internally (and so is simpler and more maintainable, but generates more garbage and runs more slowly), and various block-compilation efficiency-increasing extensions to the language have been deleted or are no longer used in the implementation of SBCL itself.