2 @comment node-name, next, previous, up
5 SBCL is a mostly-conforming implementation of the ANSI Common Lisp
6 standard. This manual focuses on behavior which is specific to SBCL,
7 not on behavior which is common to all implementations of ANSI Common
15 * More SBCL Information::
16 * More Common Lisp Information::
17 * History and Implementation of SBCL::
22 @node ANSI Conformance
23 @comment node-name, next, previous, up
24 @section ANSI Conformance
26 Essentially every type of non-conformance is considered a bug. (The
27 exceptions involve internal inconsistencies in the standard.) In SBCL
28 the master record of known bugs is in the @file{BUGS} file in the
31 The recommended way to report bugs is through the @cite{sbcl-help} or
32 @cite{sbcl-devel} mailing lists. For mailing list addresses,
33 see @ref{SBCL Homepage}.
39 @comment node-name, next, previous, up
42 SBCL comes with numerous extensions, some in core and some in modules
43 loadable with @code{require}. Unfortunately, not all of these
44 extensions have proper documentation yet.
46 @c FIXME: Once bits and pieces referred to here get real documentation
51 @item System Definition Tool
52 @code{asdf} is a flexible and popular protocol-oriented system
53 definition tool by Daniel Barlow.
55 @item Third-party Extension Installation Tool
56 @code{asdf-install} is a tool that can be used to download and install
57 third-party libraries and applications, automatically handling
60 @item Foreign Function Interface
61 @code{sb-alien} package allows interfacing with C-code, loading shared
62 object files, etc. @xref{Foreign Function Interface}.
64 @code{sb-grovel} can be used to partially automate generation of
65 foreign function interface definitions. @xref{sb-grovel}.
67 @item Recursive Event Loop
68 SBCL provides a recursive event loop (@code{serve-event}) for doing
69 non-blocking IO on multiple streams without using threads.
71 @item Metaobject Protocol
72 @code{sb-mop} package provides a metaobject protocol for the Common
73 Lisp Object System as described in @cite{Art of Metaobject Protocol}.
76 SBCL has native threads on x86/Linux, capable of taking advantage
77 of SMP on multiprocessor machines. @xref{Threading}.
79 @item Network Interface
80 @code{sb-bsd-sockets} is a low-level networking interface, providing
81 both TCP and UDP sockets. x@ref{Networking}.
83 @item Introspective Facilities
84 @code{sb-introspect} module offers numerous introspective extensions,
85 including access to function lambda-lists.
87 @item Operating System Interface
88 @code{sb-ext} contains a number of functions for running external
89 processes, accessing environment variables, etc.
91 @code{sb-posix} module provides a lispy interface to standard POSIX
94 @item Extensible Streams
95 @code{sb-gray} is an implentation of @emph{Gray Streams}. @xref{Gray
98 @code{sb-simple-streams} is an implementation of the @emph{simple
99 streams} API proposed by Franz Inc. @xref{Simple Streams}.
102 @code{sb-profile} is a exact per-function profiler. @xref{Accurate
105 @code{sb-sprof} is a statistical profiler, capable of call-graph
106 generation and instruction level profiling. @xref{Statistical
109 @item Customization Hooks
110 SBCL contains a number of extra-standard customization hooks that
111 can be used to tweak the behaviour of the system. @xref{Customization
114 @code{sb-aclrepl} provides an Allegro CL -style toplevel for SBCL,
115 as an alternative to the classic CMUCL-style one. @xref{sb-aclrepl}.
117 @item CLTL2 Compatility Layer
118 @code{sb-cltl2} module provides @code{compiler-let} and environment
119 access functionality described in @cite{Common Lisp The Language, 2nd
120 Edition} which were removed from the language during the ANSI
121 standardization process.
123 @item Executable Fasl Packaging
124 @code{sb-executable} can be used to concatenate multiple fasls into a
125 single executable (though the presense of an SBCL runtime and core
126 image is still required to run it).
128 @item Bitwise Rotation
129 @code{sb-rotate-byte} provides an efficient primitive for bitwise
130 rotation of integers, an operation required by eg. numerous
131 cryptographic algorightms, but not available as a primitive in ANSI
132 Common Lisp. @xref{sb-rotate-byte}.
135 @code{sb-rt} module is a simple yet attractive regression and
139 @code{sb-md5} is an implementation of the MD5 message digest algorithm
140 for Common Lisp, using the modular arithmetic optimizations provided
141 by SBCL. @xref{sb-md5}.
149 @comment node-name, next, previous, up
150 @section Idiosyncrasies
152 The information in this section describes some of the ways that SBCL
153 deals with choices that the ANSI standard leaves to the
158 * Compiler-only Implementation::
159 * Defining Constants::
164 @comment node-name, next, previous, up
165 @subsection Declarations
167 Declarations are generally treated as assertions. This general
168 principle, and its implications, and the bugs which still keep the
169 compiler from quite satisfying this principle, are discussed in
170 @ref{Declarations as Assertions}.
172 @node Compiler-only Implementation
173 @comment node-name, next, previous, up
174 @subsection Compiler-only Implementation
176 SBCL is essentially a compiler-only implementation of Common Lisp.
177 That is, for all but a few special cases, @code{eval} creates a lambda
178 expression, calls @code{compile} on the lambda expression to create a
179 compiled function, and then calls @code{funcall} on the resulting
180 function object. This is explicitly allowed by the ANSI standard, but
181 leads to some oddities, e.g. collapsing @code{functionp} and
182 @code{compiled-function-p} into the same predicate.
184 @node Defining Constants
185 @comment node-name, next, previous, up
186 @subsection Defining Constants
189 SBCL is quite strict about ANSI's definition of @code{defconstant}.
190 ANSI says that doing @code{defconstant} of the same symbol more than
191 once is undefined unless the new value is @code{eql} to the old value.
192 Conforming to this specification is a nuisance when the ``constant''
193 value is only constant under some weaker test like @code{string=} or
196 It's especially annoying because, in SBCL, @code{defconstant} takes
197 effect not only at load time but also at compile time, so that just
198 compiling and loading reasonable code like
200 (defconstant +foobyte+ '(1 4))
202 runs into this undefined behavior. Many implementations of Common Lisp
203 try to help the programmer around this annoyance by silently accepting
204 the undefined code and trying to do what the programmer probably
207 SBCL instead treats the undefined behavior as an error. Often such
208 code can be rewritten in portable ANSI Common Lisp which has the
209 desired behavior. E.g., the code above can be given an exactly defined
210 meaning by replacing @code{defconstant} either with
211 @code{defparameter} or with a customized macro which does the right
214 (defmacro define-constant (name value &optional doc)
215 `(defconstant ,name (if (boundp ',name) (symbol-value ',name) ,value)
216 ,@@(when doc (list doc))))
218 or possibly along the lines of the @code{defconstant-eqx} macro used
219 internally in the implementation of SBCL itself. In circumstances
220 where this is not appropriate, the programmer can handle the condition
221 type @code{sb-ext:defconstant-uneql}, and choose either the
222 @command{continue} or @command{abort} restart as appropriate.
225 @comment node-name, next, previous, up
226 @subsection Style Warnings
228 SBCL gives style warnings about various kinds of perfectly legal code,
234 @code{defmethod} without a preceding @code{defgeneric};
237 multiple @code{defun}s of the same symbol in different units;
240 special variables not named in the conventional @code{*foo*} style,
241 and lexical variables unconventionally named in the @code{*foo*} style
245 This causes friction with people who point out that other ways of
246 organizing code (especially avoiding the use of @code{defgeneric}) are
247 just as aesthetically stylish. However, these warnings should be read
248 not as ``warning, bad aesthetics detected, you have no style'' but
249 ``warning, this style keeps the compiler from understanding the code
250 as well as you might like.'' That is, unless the compiler warns about
251 such conditions, there's no way for the compiler to warn about some
252 programming errors which would otherwise be easy to overlook. (Related
253 bug: The warning about multiple @code{defun}s is pointlessly annoying
254 when you compile and then load a function containing @code{defun}
255 wrapped in @code{eval-when}, and ideally should be suppressed in that
256 case, but still isn't as of SBCL 0.7.6.)
261 @node Development Tools
262 @comment node-name, next, previous, up
263 @section Development Tools
266 * Editor Integration::
267 * Language Reference::
270 @node Editor Integration
271 @comment node-name, next, previous, up
272 @subsection Editor Integration
274 Though SBCL can be used running ``bare'', the recommended mode of
275 development is with an editor connected to SBCL, supporting not
276 only basic lisp editing (paren-matching, etc), but providing among
277 other features an integrated debugger, interactive compilation, and
278 automated documentation lookup.
280 Currently @dfn{SLIME}@footnote{Historically, the ILISP package at
281 @uref{http://ilisp.cons.org/} provided similar functionality, but it
282 does not support modern SBCL versions.} (Superior Lisp Interaction
283 Mode for Emacs) togather with Emacs is recommended for use with
284 SBCL, though other options exist as well.
286 SLIME can be downloaded from
287 @uref{http://www.common-lisp.net/project/slime/}.
289 @node Language Reference
290 @comment node-name, next, previous, up
291 @subsection Language Reference
293 @dfn{CLHS} (Common Lisp Hyperspec) is a hypertext version of the ANSI
294 standard, made freely available by @emph{Xanalyst} -- an invaluable
297 See: @uref{http://www.lispworks.com/reference/HyperSpec/index.html}
302 @node More SBCL Information
303 @comment node-name, next, previous, up
304 @section More SBCL Information
308 * Additional Distributed Documentation::
309 * Online Documentation::
310 * Internals Documentation::
314 @comment node-name, next, previous, up
315 @subsection SBCL Homepage
317 The SBCL website at @uref{http://www.sbcl.org/} has some general
318 information, plus links to mailing lists devoted to SBCL, and to
319 archives of these mailing lists. Subscribing to the mailing lists
320 @cite{sbcl-help} and @cite{sbcl-announce} is recommended: both are
321 fairly low-volume, and help you keep abrest with SBCL development.
323 @node Additional Distributed Documentation
324 @comment node-name, next, previous, up
325 @subsection Additional Distributed Documentation
327 Besides this user manual both SBCL source and binary distributions
328 include some other SBCL-specific documentation files, which should be
329 installed along with this manual in on your system, eg. in
330 @file{/usr/local/share/doc/sbcl/}.
335 Lists known bugs in the distribution.
338 Licence and copyright summary.
341 Authorship information on various parts of SBCL.
344 Covers installing SBCL from both source and binary distributions on
345 your system, and also has some installation related troubleshooting
349 Summarizes changes between various SBCL versions.
352 Lists SBCL developers available for-pay development of SBCL.
356 @node Online Documentation
357 @comment node-name, next, previous, up
358 @subsection Online Documentation
360 Documentation for non-ANSI extensions for various commands is
361 available online from the SBCL executable itself. The extensions
362 for functions which have their own command prompts (e.g. the debugger,
363 and @code{inspect}) are documented in text available by typing
364 @command{help} at their command prompts. The extensions for functions
365 which don't have their own command prompt (such as @code{trace}) are
366 described in their documentation strings, unless your SBCL was
367 compiled with an option not to include documentation strings, in which
368 case the documentation strings are only readable in the source code.
370 @node Internals Documentation
371 @comment node-name, next, previous, up
372 @subsection Internals Documentation
374 If you're interested in the development of the SBCL system itself,
375 then subcribing to @cite{sbcl-devel} is a good idea.
377 SBCL internals documentation -- besides comments in the source -- is
378 currenly maitained as a @emph{wiki-like} website:
379 @uref{http://sbcl-internals.cliki.net/}.
381 Some low-level information describing the programming details of the
382 conversion from CMUCL to SBCL is available in the
383 @file{doc/FOR-CMUCL-DEVELOPERS} file in the SBCL distribution, though
384 it is not installed by default.
386 @node More Common Lisp Information
387 @comment node-name, next, previous, up
388 @section More Common Lisp Information
391 * Internet Community::
392 * Third-party Libraries::
393 * Common Lisp Books::
396 @node Internet Community
397 @comment node-name, next, previous, up
398 @subsection Internet Community
400 @c FIXME: Say something smart here
402 The Common Lisp internet community is fairly diverse:
403 @uref{news://comp.lang.lisp} is fairly high volume newsgroup, but has
404 a rather poor signal/noise ratio. Various special interest mailing
405 lists and IRC tend to provide more content and less flames.
406 @uref{http://www.lisp.org} and @uref{http://www.cliki.net} contain
407 numerous pointers places in the net where lispers talks shop.
409 @node Third-party Libraries
410 @comment node-name, next, previous, up
411 @subsection Third-party Libraries
413 For a wealth of information about free Common Lisp libraries and tools
414 we recommend checking out @emph{CLiki}: @uref{http://www.cliki.net/}.
416 @node Common Lisp Books
417 @comment node-name, next, previous, up
418 @subsection Common Lisp Books
420 If you're not a programmer and you're trying to learn, many
421 introductory Lisp books are available. However, we don't have any
422 standout favorites. If you can't decide, try checking the Usenet
423 @uref{news://comp.lang.lisp} FAQ for recent recommendations.
425 @c FIXME: This non-stance is silly. Maybe we could recommend SICP,
426 @c Touretzky, or something at least.
428 If you are an experienced programmer in other languages but need to
429 learn about Common Lisp, some books stand out:
433 @c FIXME: Ask Seibel if he minds us referring to the preview
435 @c @item Practical Common Lisp, by Peter Seibel
436 @c A forthcoming book from APress with a web free preview at
437 @c @uref{http://www.gigamonkeys.com/book/}. An excellent introduction to
438 @c the language, covering both the basics and ``advanced topics'' like
439 @c macros, CLOS, and packages.
441 @item ANSI Common Lisp, by Paul Graham
442 Introduces most of the language, though some parts (eg. CLOS) are
443 covered only lightly.
445 @item On Lisp, by Paul Graham
446 An in-depth treatment of macros, but not recommended as a first Common
447 Lisp book, since it is slightly pre-ANSI so you need to be on your
448 guard against non-standard usages, and since it doesn't really even
449 try to cover the language as a whole, focusing solely on macros.
450 Downloadable from @uref{http://www.paulgraham.com/onlisp.html}.
452 @item Paradigms Of Artificial Intelligence Programming, by Peter Norvig
453 Good information on general Common Lisp programming, and many
454 nontrivial examples. Whether or not your work is AI, it's a very good
457 @item Object-Oriented Programming In Common Lisp, by Sonya Keene
458 @c With the exception of @cite{Practical Common Lisp}
459 None the books above emphasize CLOS, but this one does. Even if you're
460 very knowledgeable about object oriented programming in the abstract,
461 it's worth looking at this book if you want to do any OO in Common
462 Lisp. Some abstractions in CLOS (especially multiple dispatch) go
463 beyond anything you'll see in most OO systems, and there are a number
464 of lesser differences as well. This book tends to help with the
467 @item Art Of Metaobject Programming, by Gregor Kiczales et al.
468 Currently to prime source of information on the Common Lisp Metaobject
469 Protocol, which is supported by SBCL. Section 2 (Chapers 5 and 6) are
470 freely available at @uref{http://www.lisp.org/mop/}.
477 @node History and Implementation of SBCL
478 @comment node-name, next, previous, up
479 @section History and Implementation of SBCL
481 You can work productively with SBCL without knowing anything
482 understanding anything about where it came from, how it is
483 implemented, or how it extends the ANSI Common Lisp standard. However,
484 a little knowledge can be helpful in order to understand error
485 messages, to troubleshoot problems, to understand why some parts of
486 the system are better debugged than others, and to anticipate which
487 known bugs, known performance problems, and missing extensions are
488 likely to be fixed, tuned, or added.
490 SBCL is descended from CMUCL, which is itself descended from Spice
491 Lisp, including early implementations for the Mach operating system on
492 the IBM RT, back in the 1980s. Some design decisions from that time are
493 still reflected in the current implementation:
498 The system expects to be loaded into a fixed-at-compile-time location
499 in virtual memory, and also expects the location of all of its heap
500 storage to be specified at compile time.
503 The system overcommits memory, allocating large amounts of address
504 space from the system (often more than the amount of virtual memory
505 available) and then failing if ends up using too much of the allocated
509 The system is implemented as a C program which is responsible for
510 supplying low-level services and loading a Lisp @file{.core}
515 @cindex Garbage Collection, generational
516 SBCL also inherited some newer architectural features from CMUCL. The
517 most important is that on some architectures it has a generational
518 garbage collector (``GC''), which has various implications (mostly
519 good) for performance. These are discussed in another chapter,
522 SBCL has diverged from CMUCL in that SBCL is now essentially a
523 ``compiler-only implementation'' of Common Lisp. This is a change in
524 implementation strategy, taking advantage of the freedom ``any of these
525 facilities might share the same execution strategy'' guaranteed in the
526 ANSI specification section 3.1 (``Evaluation''). It does not mean SBCL
527 can't be used interactively, and in fact the change is largely invisible
528 to the casual user, since SBCL still can and does execute code
529 interactively by compiling it on the fly. (It is visible if you know how
530 to look, like using @code{compiled-function-p}; and it is visible in the
531 way that that SBCL doesn't have many bugs which behave differently in
532 interpreted code than in compiled code.) What it means is that in SBCL,
533 the @code{eval} function only truly ``interprets'' a few easy kinds of
534 forms, such as symbols which are @code{boundp}. More complicated forms
535 are evaluated by calling @code{compile} and then calling @code{funcall}
536 on the returned result.
538 The direct ancestor of SBCL is the x86 port of CMUCL. This port was in
539 some ways the most cobbled-together of all the CMUCL ports, since a
540 number of strange changes had to be made to support the register-poor
541 x86 architecture. Some things (like tracing and debugging) do not work
542 particularly well there. SBCL should be able to improve in these areas
543 (and has already improved in some other areas), but it takes a while.
545 @cindex Garbage Collection, conservative
546 On the x86 SBCL -- like the x86 port of CMUCL -- uses a
547 @emph{conservative} GC. This means that it doesn't maintain a strict
548 separation between tagged and untagged data, instead treating some
549 untagged data (e.g. raw floating point numbers) as possibly-tagged
550 data and so not collecting any Lisp objects that they point to. This
551 has some negative consequences for average time efficiency (though
552 possibly no worse than the negative consequences of trying to
553 implement an exact GC on a processor architecture as register-poor as
554 the X86) and also has potentially unlimited consequences for
555 worst-case memory efficiency. In practice, conservative garbage
556 collectors work reasonably well, not getting anywhere near the worst
557 case. But they can occasionally cause odd patterns of memory usage.
559 The fork from CMUCL was based on a major rewrite of the system
560 bootstrap process. CMUCL has for many years tolerated a very unusual
561 ``build'' procedure which doesn't actually build the complete system
562 from scratch, but instead progressively overwrites parts of a running
563 system with new versions. This quasi-build procedure can cause various
564 bizarre bootstrapping hangups, especially when a major change is made
565 to the system. It also makes the connection between the current source
566 code and the current executable more tenuous than in other software
567 systems -- it's easy to accidentally ``build'' a CMUCL system
568 containing characteristics not reflected in the current version of the
571 Other major changes since the fork from CMUCL include
576 SBCL has removed many CMUCL extensions, (e.g. IP networking,
577 remote procedure call, Unix system interface, and X11 interface) from
578 the core system. Most of these are available as contributed modules
579 (distributed with sbcl) or third-party modules instead.
582 SBCL has deleted or deprecated some nonstandard features and code
583 complexity which helped efficiency at the price of
584 maintainability. For example, the SBCL compiler no longer implements
585 memory pooling internally (and so is simpler and more maintainable,
586 but generates more garbage and runs more slowly), and various
587 block-compilation efficiency-increasing extensions to the language
588 have been deleted or are no longer used in the implementation of SBCL