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