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}; note that as a spam-reduction measure you
34 must subscribe before you can post.
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. @inforef{Top,the asdf manual,asdf}, for
56 @item Third-party Extension Installation Tool
57 @code{asdf-install} is a tool that can be used to download and install
58 third-party libraries and applications, automatically handling
61 @item Foreign Function Interface
62 @code{sb-alien} package allows interfacing with C-code, loading shared
63 object files, etc. @xref{Foreign Function Interface}.
65 @code{sb-grovel} can be used to partially automate generation of
66 foreign function interface definitions. @xref{sb-grovel}.
68 @item Recursive Event Loop
69 SBCL provides a recursive event loop (@code{serve-event}) for doing
70 non-blocking IO on multiple streams without using threads.
72 @item Metaobject Protocol
73 @code{sb-mop} package provides a metaobject protocol for the Common
74 Lisp Object System as described in @cite{Art of Metaobject Protocol}.
77 SBCL has native threads on x86/Linux, capable of taking advantage
78 of SMP on multiprocessor machines. @xref{Threading}.
80 @item Network Interface
81 @code{sb-bsd-sockets} is a low-level networking interface, providing
82 both TCP and UDP sockets. @xref{Networking}.
84 @item Introspective Facilities
85 @code{sb-introspect} module offers numerous introspective extensions,
86 including access to function lambda-lists and a cross referencing
89 @item Operating System Interface
90 @code{sb-ext} contains a number of functions for running external
91 processes, accessing environment variables, etc.
93 @code{sb-posix} module provides a lispy interface to standard POSIX
96 @item Extensible Streams
97 @code{sb-gray} is an implementation of @emph{Gray Streams}. @xref{Gray
100 @code{sb-simple-streams} is an implementation of the @emph{simple
101 streams} API proposed by Franz Inc. @xref{Simple Streams}.
104 @code{sb-profile} is a exact per-function profiler. @xref{Deterministic
107 @code{sb-sprof} is a statistical profiler, capable of call-graph
108 generation and instruction level profiling, which also supports
109 allocation profiling. @xref{Statistical Profiler}.
111 @item Customization Hooks
112 SBCL contains a number of extra-standard customization hooks that
113 can be used to tweak the behaviour of the system. @xref{Customization
116 @code{sb-aclrepl} provides an Allegro CL -style toplevel for SBCL,
117 as an alternative to the classic CMUCL-style one. @xref{sb-aclrepl}.
119 @item CLTL2 Compatility Layer
120 @code{sb-cltl2} module provides @code{compiler-let} and environment
121 access functionality described in @cite{Common Lisp The Language, 2nd
122 Edition} which were removed from the language during the ANSI
123 standardization process.
125 @item Executable Delivery
126 The @code{:executable} argument to @ref{Function
127 sb-ext:save-lisp-and-die} can produce a `standalone' executable
128 containing both an image of the current Lisp session and an SBCL
131 @item Bitwise Rotation
132 @code{sb-rotate-byte} provides an efficient primitive for bitwise
133 rotation of integers, an operation required by eg. numerous
134 cryptographic algorithms, but not available as a primitive in ANSI
135 Common Lisp. @xref{sb-rotate-byte}.
138 @code{sb-rt} module is a simple yet attractive regression and
142 @code{sb-md5} is an implementation of the MD5 message digest algorithm
143 for Common Lisp, using the modular arithmetic optimizations provided
144 by SBCL. @xref{sb-md5}.
152 @comment node-name, next, previous, up
153 @section Idiosyncrasies
155 The information in this section describes some of the ways that SBCL
156 deals with choices that the ANSI standard leaves to the
162 * Compiler-only Implementation::
163 * Defining Constants::
168 @comment node-name, next, previous, up
169 @subsection Declarations
171 Declarations are generally treated as assertions. This general
172 principle, and its implications, and the bugs which still keep the
173 compiler from quite satisfying this principle, are discussed in
174 @ref{Declarations as Assertions}.
178 @comment node-name, next, previous, up
179 @subsection FASL Format
181 SBCL fasl-format is binary compatible only with the exact SBCL version
182 it was generated with. While this is obviously suboptimal, it has
183 proven more robust than trying to maintain fasl compatibility across
184 versions: accidentally breaking things is far too easy, and can lead
185 to hard to diagnose bugs.
187 The following snippet handles fasl recompilation automatically for
188 ASDF-based systems, and makes a good candidate for inclusion in
189 the user or system initialization file (@pxref{Initialization Files}.)
194 ;;; If a fasl was stale, try to recompile and load (once).
195 (defmethod asdf:perform :around ((o asdf:load-op)
196 (c asdf:cl-source-file))
197 (handler-case (call-next-method o c)
198 ;; If a fasl was stale, try to recompile and load (once).
199 (sb-ext:invalid-fasl ()
200 (asdf:perform (make-instance 'asdf:compile-op) c)
201 (call-next-method))))
205 @node Compiler-only Implementation
206 @comment node-name, next, previous, up
207 @subsection Compiler-only Implementation
209 SBCL is essentially a compiler-only implementation of Common Lisp.
210 That is, for all but a few special cases, @code{eval} creates a lambda
211 expression, calls @code{compile} on the lambda expression to create a
212 compiled function, and then calls @code{funcall} on the resulting
213 function object. This is explicitly allowed by the ANSI standard, but
214 leads to some oddities, e.g. collapsing @code{functionp} and
215 @code{compiled-function-p} into the same predicate.
217 @node Defining Constants
218 @comment node-name, next, previous, up
219 @subsection Defining Constants
222 SBCL is quite strict about ANSI's definition of @code{defconstant}.
223 ANSI says that doing @code{defconstant} of the same symbol more than
224 once is undefined unless the new value is @code{eql} to the old value.
225 Conforming to this specification is a nuisance when the ``constant''
226 value is only constant under some weaker test like @code{string=} or
229 It's especially annoying because, in SBCL, @code{defconstant} takes
230 effect not only at load time but also at compile time, so that just
231 compiling and loading reasonable code like
233 (defconstant +foobyte+ '(1 4))
235 runs into this undefined behavior. Many implementations of Common Lisp
236 try to help the programmer around this annoyance by silently accepting
237 the undefined code and trying to do what the programmer probably
240 SBCL instead treats the undefined behavior as an error. Often such
241 code can be rewritten in portable ANSI Common Lisp which has the
242 desired behavior. E.g., the code above can be given an exactly defined
243 meaning by replacing @code{defconstant} either with
244 @code{defparameter} or with a customized macro which does the right
247 (defmacro define-constant (name value &optional doc)
248 `(defconstant ,name (if (boundp ',name) (symbol-value ',name) ,value)
249 ,@@(when doc (list doc))))
251 or possibly along the lines of the @code{defconstant-eqx} macro used
252 internally in the implementation of SBCL itself. In circumstances
253 where this is not appropriate, the programmer can handle the condition
254 type @code{sb-ext:defconstant-uneql}, and choose either the
255 @command{continue} or @command{abort} restart as appropriate.
258 @comment node-name, next, previous, up
259 @subsection Style Warnings
261 SBCL gives style warnings about various kinds of perfectly legal code,
267 @code{defmethod} without a preceding @code{defgeneric};
270 multiple @code{defun}s of the same symbol in different units;
273 special variables not named in the conventional @code{*foo*} style,
274 and lexical variables unconventionally named in the @code{*foo*} style
278 This causes friction with people who point out that other ways of
279 organizing code (especially avoiding the use of @code{defgeneric}) are
280 just as aesthetically stylish. However, these warnings should be read
281 not as ``warning, bad aesthetics detected, you have no style'' but
282 ``warning, this style keeps the compiler from understanding the code
283 as well as you might like.'' That is, unless the compiler warns about
284 such conditions, there's no way for the compiler to warn about some
285 programming errors which would otherwise be easy to overlook. (Related
286 bug: The warning about multiple @code{defun}s is pointlessly annoying
287 when you compile and then load a function containing @code{defun}
288 wrapped in @code{eval-when}, and ideally should be suppressed in that
289 case, but still isn't as of SBCL 0.7.6.)
294 @node Development Tools
295 @comment node-name, next, previous, up
296 @section Development Tools
299 * Editor Integration::
300 * Language Reference::
301 * Generating Executables::
304 @node Editor Integration
305 @comment node-name, next, previous, up
306 @subsection Editor Integration
308 Though SBCL can be used running ``bare'', the recommended mode of
309 development is with an editor connected to SBCL, supporting not
310 only basic lisp editing (paren-matching, etc), but providing among
311 other features an integrated debugger, interactive compilation, and
312 automated documentation lookup.
314 Currently @dfn{SLIME}@footnote{Historically, the ILISP package at
315 @uref{http://ilisp.cons.org/} provided similar functionality, but it
316 does not support modern SBCL versions.} (Superior Lisp Interaction
317 Mode for Emacs) together with Emacs is recommended for use with
318 SBCL, though other options exist as well.
320 SLIME can be downloaded from
321 @uref{http://www.common-lisp.net/project/slime/}.
323 @node Language Reference
324 @comment node-name, next, previous, up
325 @subsection Language Reference
327 @dfn{CLHS} (Common Lisp Hyperspec) is a hypertext version of the ANSI
328 standard, made freely available by @emph{LispWorks} -- an invaluable
331 See: @uref{http://www.lispworks.com/reference/HyperSpec/index.html}
333 @node Generating Executables
334 @comment node-name, next, previous, up
335 @subsection Generating Executables
337 SBCL can generate stand-alone executables. The generated executables
338 include the SBCL runtime itself, so no restrictions are placed on
339 program functionality. For example, a deployed program can call
340 @code{compile} and @code{load}, which requires the compiler to be present
341 in the executable. For further information, @xref{Function
342 sb-ext:save-lisp-and-die}.
345 @node More SBCL Information
346 @comment node-name, next, previous, up
347 @section More SBCL Information
351 * Additional Distributed Documentation::
352 * Online Documentation::
353 * Internals Documentation::
357 @comment node-name, next, previous, up
358 @subsection SBCL Homepage
360 The SBCL website at @uref{http://www.sbcl.org/} has some general
361 information, plus links to mailing lists devoted to SBCL, and to
362 archives of these mailing lists. Subscribing to the mailing lists
363 @cite{sbcl-help} and @cite{sbcl-announce} is recommended: both are
364 fairly low-volume, and help you keep abrest with SBCL development.
366 @node Additional Distributed Documentation
367 @comment node-name, next, previous, up
368 @subsection Additional Distributed Documentation
370 Besides this user manual both SBCL source and binary distributions
371 include some other SBCL-specific documentation files, which should be
372 installed along with this manual in on your system, eg. in
373 @file{/usr/local/share/doc/sbcl/}.
378 Lists known bugs in the distribution.
381 Licence and copyright summary.
384 Authorship information on various parts of SBCL.
387 Covers installing SBCL from both source and binary distributions on
388 your system, and also has some installation related troubleshooting
392 Summarizes changes between various SBCL versions.
395 Lists SBCL developers available for-pay development of SBCL.
399 @node Online Documentation
400 @comment node-name, next, previous, up
401 @subsection Online Documentation
403 Documentation for non-ANSI extensions for various commands is
404 available online from the SBCL executable itself. The extensions
405 for functions which have their own command prompts (e.g. the debugger,
406 and @code{inspect}) are documented in text available by typing
407 @command{help} at their command prompts. The extensions for functions
408 which don't have their own command prompt (such as @code{trace}) are
409 described in their documentation strings, unless your SBCL was
410 compiled with an option not to include documentation strings, in which
411 case the documentation strings are only readable in the source code.
413 @node Internals Documentation
414 @comment node-name, next, previous, up
415 @subsection Internals Documentation
417 If you're interested in the development of the SBCL system itself,
418 then subscribing to @cite{sbcl-devel} is a good idea.
420 SBCL internals documentation -- besides comments in the source -- is
421 currently maintained as a @emph{wiki-like} website:
422 @uref{http://sbcl-internals.cliki.net/}.
424 Some low-level information describing the programming details of the
425 conversion from CMUCL to SBCL is available in the
426 @file{doc/FOR-CMUCL-DEVELOPERS} file in the SBCL distribution, though
427 it is not installed by default.
429 @node More Common Lisp Information
430 @comment node-name, next, previous, up
431 @section More Common Lisp Information
434 * Internet Community::
435 * Third-party Libraries::
436 * Common Lisp Books::
439 @node Internet Community
440 @comment node-name, next, previous, up
441 @subsection Internet Community
443 @c FIXME: Say something smart here
445 The Common Lisp internet community is fairly diverse:
446 @uref{news://comp.lang.lisp} is fairly high volume newsgroup, but has
447 a rather poor signal/noise ratio. Various special interest mailing
448 lists and IRC tend to provide more content and less flames.
449 @uref{http://www.lisp.org} and @uref{http://www.cliki.net} contain
450 numerous pointers places in the net where lispers talks shop.
452 @node Third-party Libraries
453 @comment node-name, next, previous, up
454 @subsection Third-party Libraries
456 For a wealth of information about free Common Lisp libraries and tools
457 we recommend checking out @emph{CLiki}: @uref{http://www.cliki.net/}.
459 @node Common Lisp Books
460 @comment node-name, next, previous, up
461 @subsection Common Lisp Books
463 If you're not a programmer and you're trying to learn, many
464 introductory Lisp books are available. However, we don't have any
465 standout favorites. If you can't decide, try checking the Usenet
466 @uref{news://comp.lang.lisp} FAQ for recent recommendations.
468 @c FIXME: This non-stance is silly. Maybe we could recommend SICP,
469 @c Touretzky, or something at least.
471 If you are an experienced programmer in other languages but need to
472 learn about Common Lisp, some books stand out:
476 @item Practical Common Lisp, by Peter Seibel
477 An excellent introduction to the language, covering both the basics
478 and ``advanced topics'' like macros, CLOS, and packages. Available
479 both in print format and on the web: @uref{http://www.gigamonkeys.com/book/}.
481 @item Paradigms Of Artificial Intelligence Programming, by Peter Norvig
482 Good information on general Common Lisp programming, and many
483 nontrivial examples. Whether or not your work is AI, it's a very good
486 @item On Lisp, by Paul Graham
487 An in-depth treatment of macros, but not recommended as a first Common
488 Lisp book, since it is slightly pre-ANSI so you need to be on your
489 guard against non-standard usages, and since it doesn't really even
490 try to cover the language as a whole, focusing solely on macros.
491 Downloadable from @uref{http://www.paulgraham.com/onlisp.html}.
493 @item Object-Oriented Programming In Common Lisp, by Sonya Keene
494 With the exception of @cite{Practical Common Lisp} most introductory
495 books don't emphasize CLOS. This one does. Even if you're very
496 knowledgeable about object oriented programming in the abstract, it's
497 worth looking at this book if you want to do any OO in Common Lisp.
498 Some abstractions in CLOS (especially multiple dispatch) go beyond
499 anything you'll see in most OO systems, and there are a number of
500 lesser differences as well. This book tends to help with the culture
503 @item Art Of Metaobject Programming, by Gregor Kiczales et al.
504 Currently to prime source of information on the Common Lisp Metaobject
505 Protocol, which is supported by SBCL. Section 2 (Chapers 5 and 6) are
506 freely available at @uref{http://www.lisp.org/mop/}.
513 @node History and Implementation of SBCL
514 @comment node-name, next, previous, up
515 @section History and Implementation of SBCL
517 You can work productively with SBCL without knowing or
518 understanding anything about where it came from, how it is
519 implemented, or how it extends the ANSI Common Lisp standard. However,
520 a little knowledge can be helpful in order to understand error
521 messages, to troubleshoot problems, to understand why some parts of
522 the system are better debugged than others, and to anticipate which
523 known bugs, known performance problems, and missing extensions are
524 likely to be fixed, tuned, or added.
526 SBCL is descended from CMUCL, which is itself descended from Spice
527 Lisp, including early implementations for the Mach operating system on
528 the IBM RT, back in the 1980s. Some design decisions from that time are
529 still reflected in the current implementation:
534 The system expects to be loaded into a fixed-at-compile-time location
535 in virtual memory, and also expects the location of all of its heap
536 storage to be specified at compile time.
539 The system overcommits memory, allocating large amounts of address
540 space from the system (often more than the amount of virtual memory
541 available) and then failing if ends up using too much of the allocated
545 The system is implemented as a C program which is responsible for
546 supplying low-level services and loading a Lisp @file{.core}
551 @cindex Garbage Collection, generational
552 SBCL also inherited some newer architectural features from CMUCL. The
553 most important is that on some architectures it has a generational
554 garbage collector (``GC''), which has various implications (mostly
555 good) for performance. These are discussed in another chapter,
558 SBCL has diverged from CMUCL in that SBCL is now essentially a
559 ``compiler-only implementation'' of Common Lisp. This is a change in
560 implementation strategy, taking advantage of the freedom ``any of these
561 facilities might share the same execution strategy'' guaranteed in the
562 ANSI specification section 3.1 (``Evaluation''). It does not mean SBCL
563 can't be used interactively, and in fact the change is largely invisible
564 to the casual user, since SBCL still can and does execute code
565 interactively by compiling it on the fly. (It is visible if you know how
566 to look, like using @code{compiled-function-p}; and it is visible in the
567 way that SBCL doesn't have many bugs which behave differently in
568 interpreted code than in compiled code.) What it means is that in SBCL,
569 the @code{eval} function only truly ``interprets'' a few easy kinds of
570 forms, such as symbols which are @code{boundp}. More complicated forms
571 are evaluated by calling @code{compile} and then calling @code{funcall}
572 on the returned result.
574 The direct ancestor of SBCL is the x86 port of CMUCL. This port was in
575 some ways the most cobbled-together of all the CMUCL ports, since a
576 number of strange changes had to be made to support the register-poor
577 x86 architecture. Some things (like tracing and debugging) do not work
578 particularly well there. SBCL should be able to improve in these areas
579 (and has already improved in some other areas), but it takes a while.
581 @cindex Garbage Collection, conservative
582 On the x86 SBCL -- like the x86 port of CMUCL -- uses a
583 @emph{conservative} GC. This means that it doesn't maintain a strict
584 separation between tagged and untagged data, instead treating some
585 untagged data (e.g. raw floating point numbers) as possibly-tagged
586 data and so not collecting any Lisp objects that they point to. This
587 has some negative consequences for average time efficiency (though
588 possibly no worse than the negative consequences of trying to
589 implement an exact GC on a processor architecture as register-poor as
590 the X86) and also has potentially unlimited consequences for
591 worst-case memory efficiency. In practice, conservative garbage
592 collectors work reasonably well, not getting anywhere near the worst
593 case. But they can occasionally cause odd patterns of memory usage.
595 The fork from CMUCL was based on a major rewrite of the system
596 bootstrap process. CMUCL has for many years tolerated a very unusual
597 ``build'' procedure which doesn't actually build the complete system
598 from scratch, but instead progressively overwrites parts of a running
599 system with new versions. This quasi-build procedure can cause various
600 bizarre bootstrapping hangups, especially when a major change is made
601 to the system. It also makes the connection between the current source
602 code and the current executable more tenuous than in other software
603 systems -- it's easy to accidentally ``build'' a CMUCL system
604 containing characteristics not reflected in the current version of the
607 Other major changes since the fork from CMUCL include
612 SBCL has removed many CMUCL extensions, (e.g. IP networking,
613 remote procedure call, Unix system interface, and X11 interface) from
614 the core system. Most of these are available as contributed modules
615 (distributed with sbcl) or third-party modules instead.
618 SBCL has deleted or deprecated some nonstandard features and code
619 complexity which helped efficiency at the price of
620 maintainability. For example, the SBCL compiler no longer implements
621 memory pooling internally (and so is simpler and more maintainable,
622 but generates more garbage and runs more slowly), and various
623 block-compilation efficiency-increasing extensions to the language
624 have been deleted or are no longer used in the implementation of SBCL