1.0.4.9: writing bignum characters onto a single line
[sbcl.git] / doc / manual / intro.texinfo
1 @node Introduction
2 @comment  node-name,  next,  previous,  up
3 @chapter Introduction
4
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
8 Lisp.
9
10 @menu
11 * ANSI Conformance::            
12 * Extensions::                  
13 * Idiosyncrasies::              
14 * Development Tools::           
15 * More SBCL Information::       
16 * More Common Lisp Information::  
17 * History and Implementation of SBCL::  
18 @end menu
19
20
21
22 @node ANSI Conformance
23 @comment  node-name,  next,  previous,  up
24 @section ANSI Conformance
25
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
29 distribution.
30
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}.
34
35
36
37
38 @node Extensions
39 @comment  node-name,  next,  previous,  up
40 @section Extensions
41
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.
45
46 @c FIXME: Once bits and pieces referred to here get real documentation
47 @c add xrefs there.
48
49 @table @strong
50
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
54 more information.
55
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
59 dependencies, etc.
60
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}.
64
65 @code{sb-grovel} can be used to partially automate generation of
66 foreign function interface definitions. @xref{sb-grovel}.
67
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.
71
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}.
75
76 @item Native Threads
77 SBCL has native threads on x86/Linux, capable of taking advantage
78 of SMP on multiprocessor machines. @xref{Threading}.
79
80 @item Network Interface
81 @code{sb-bsd-sockets} is a low-level networking interface, providing
82 both TCP and UDP sockets. x@ref{Networking}.
83
84 @item Introspective Facilities
85 @code{sb-introspect} module offers numerous introspective extensions,
86 including access to function lambda-lists.
87
88 @item Operating System Interface
89 @code{sb-ext} contains a number of functions for running external
90 processes, accessing environment variables, etc.
91
92 @code{sb-posix} module provides a lispy interface to standard POSIX
93 facilities.
94
95 @item Extensible Streams
96 @code{sb-gray} is an implentation of @emph{Gray Streams}. @xref{Gray
97 Streams}.
98
99 @code{sb-simple-streams} is an implementation of the @emph{simple
100 streams} API proposed by Franz Inc. @xref{Simple Streams}.
101
102 @item Profiling
103 @code{sb-profile} is a exact per-function profiler. @xref{Deterministic
104 Profiler}.
105
106 @code{sb-sprof} is a statistical profiler, capable of call-graph
107 generation and instruction level profiling. @xref{Statistical
108 Profiler}.
109
110 @item Customization Hooks
111 SBCL contains a number of extra-standard customization hooks that
112 can be used to tweak the behaviour of the system. @xref{Customization
113 Hooks for Users}.
114
115 @code{sb-aclrepl} provides an Allegro CL -style toplevel for SBCL,
116 as an alternative to the classic CMUCL-style one. @xref{sb-aclrepl}.
117
118 @item CLTL2 Compatility Layer
119 @code{sb-cltl2} module provides @code{compiler-let} and environment
120 access functionality described in @cite{Common Lisp The Language, 2nd
121 Edition} which were removed from the language during the ANSI
122 standardization process.
123
124 @item Executable Fasl Packaging
125 @code{sb-executable} can be used to concatenate multiple fasls into a
126 single executable (though the presense of an SBCL runtime and core image
127 is still required to run it).
128
129 The @code{:executable} argument to @ref{Function
130 sb-ext:save-lisp-and-die} can produce a `standalone' executable
131 containing both an image of the current Lisp session and an SBCL
132 runtime.
133
134 @item Bitwise Rotation
135 @code{sb-rotate-byte} provides an efficient primitive for bitwise
136 rotation of integers, an operation required by eg. numerous
137 cryptographic algorightms, but not available as a primitive in ANSI
138 Common Lisp. @xref{sb-rotate-byte}.
139
140 @item Test Harness
141 @code{sb-rt} module is a simple yet attractive regression and
142 unit-test framework.
143
144 @item MD5 Sums
145 @code{sb-md5} is an implementation of the MD5 message digest algorithm
146 for Common Lisp, using the modular arithmetic optimizations provided
147 by SBCL. @xref{sb-md5}.
148
149 @end table
150
151
152
153
154 @node Idiosyncrasies
155 @comment  node-name,  next,  previous,  up
156 @section Idiosyncrasies
157
158 The information in this section describes some of the ways that SBCL
159 deals with choices that the ANSI standard leaves to the
160 implementation.
161
162 @menu
163 * Declarations::                
164 * Compiler-only Implementation::  
165 * Defining Constants::          
166 * Style Warnings::              
167 @end menu
168
169 @node Declarations
170 @comment  node-name,  next,  previous,  up
171 @subsection Declarations
172
173 Declarations are generally treated as assertions. This general
174 principle, and its implications, and the bugs which still keep the
175 compiler from quite satisfying this principle, are discussed in
176 @ref{Declarations as Assertions}.
177
178 @node Compiler-only Implementation
179 @comment  node-name,  next,  previous,  up
180 @subsection Compiler-only Implementation
181
182 SBCL is essentially a compiler-only implementation of Common Lisp.
183 That is, for all but a few special cases, @code{eval} creates a lambda
184 expression, calls @code{compile} on the lambda expression to create a
185 compiled function, and then calls @code{funcall} on the resulting
186 function object. This is explicitly allowed by the ANSI standard, but
187 leads to some oddities, e.g. collapsing @code{functionp} and
188 @code{compiled-function-p} into the same predicate.
189
190 @node Defining Constants
191 @comment  node-name,  next,  previous,  up
192 @subsection Defining Constants
193 @findex defconstant
194
195 SBCL is quite strict about ANSI's definition of @code{defconstant}.
196 ANSI says that doing @code{defconstant} of the same symbol more than
197 once is undefined unless the new value is @code{eql} to the old value.
198 Conforming to this specification is a nuisance when the ``constant''
199 value is only constant under some weaker test like @code{string=} or
200 @code{equal}.
201
202 It's especially annoying because, in SBCL, @code{defconstant} takes
203 effect not only at load time but also at compile time, so that just
204 compiling and loading reasonable code like
205 @lisp
206 (defconstant +foobyte+ '(1 4))
207 @end lisp
208 runs into this undefined behavior. Many implementations of Common Lisp
209 try to help the programmer around this annoyance by silently accepting
210 the undefined code and trying to do what the programmer probably
211 meant. 
212
213 SBCL instead treats the undefined behavior as an error. Often such
214 code can be rewritten in portable ANSI Common Lisp which has the
215 desired behavior. E.g., the code above can be given an exactly defined
216 meaning by replacing @code{defconstant} either with
217 @code{defparameter} or with a customized macro which does the right
218 thing, eg.
219 @lisp
220 (defmacro define-constant (name value &optional doc)
221   `(defconstant ,name (if (boundp ',name) (symbol-value ',name) ,value)
222                       ,@@(when doc (list doc))))
223 @end lisp
224 or possibly along the lines of the @code{defconstant-eqx} macro used
225 internally in the implementation of SBCL itself. In circumstances
226 where this is not appropriate, the programmer can handle the condition
227 type @code{sb-ext:defconstant-uneql}, and choose either the
228 @command{continue} or @command{abort} restart as appropriate.
229
230 @node Style Warnings
231 @comment  node-name,  next,  previous,  up
232 @subsection Style Warnings
233
234 SBCL gives style warnings about various kinds of perfectly legal code,
235 e.g.
236
237 @itemize
238   
239 @item
240 @code{defmethod} without a preceding @code{defgeneric};
241   
242 @item
243 multiple @code{defun}s of the same symbol in different units;
244   
245 @item
246 special variables not named in the conventional @code{*foo*} style,
247 and lexical variables unconventionally named in the @code{*foo*} style
248
249 @end itemize
250
251 This causes friction with people who point out that other ways of
252 organizing code (especially avoiding the use of @code{defgeneric}) are
253 just as aesthetically stylish.  However, these warnings should be read
254 not as ``warning, bad aesthetics detected, you have no style'' but
255 ``warning, this style keeps the compiler from understanding the code
256 as well as you might like.'' That is, unless the compiler warns about
257 such conditions, there's no way for the compiler to warn about some
258 programming errors which would otherwise be easy to overlook. (Related
259 bug: The warning about multiple @code{defun}s is pointlessly annoying
260 when you compile and then load a function containing @code{defun}
261 wrapped in @code{eval-when}, and ideally should be suppressed in that
262 case, but still isn't as of SBCL 0.7.6.)
263
264
265
266
267 @node Development Tools
268 @comment  node-name,  next,  previous,  up
269 @section Development Tools
270
271 @menu
272 * Editor Integration::          
273 * Language Reference::          
274 @end menu
275
276 @node Editor Integration
277 @comment  node-name,  next,  previous,  up
278 @subsection Editor Integration
279
280 Though SBCL can be used running ``bare'', the recommended mode of
281 development is with an editor connected to SBCL, supporting not
282 only basic lisp editing (paren-matching, etc), but providing among
283 other features an integrated debugger, interactive compilation, and
284 automated documentation lookup.
285
286 Currently @dfn{SLIME}@footnote{Historically, the ILISP package at
287 @uref{http://ilisp.cons.org/} provided similar functionality, but it
288 does not support modern SBCL versions.} (Superior Lisp Interaction
289 Mode for Emacs) together with Emacs is recommended for use with
290 SBCL, though other options exist as well. 
291
292 SLIME can be downloaded from
293 @uref{http://www.common-lisp.net/project/slime/}.
294
295 @node Language Reference
296 @comment  node-name,  next,  previous,  up
297 @subsection Language Reference
298
299 @dfn{CLHS} (Common Lisp Hyperspec) is a hypertext version of the ANSI
300 standard, made freely available by @emph{Xanalyst} -- an invaluable
301 reference.
302
303 See: @uref{http://www.lispworks.com/reference/HyperSpec/index.html}
304
305
306
307
308 @node More SBCL Information
309 @comment  node-name,  next,  previous,  up
310 @section More SBCL Information
311
312 @menu
313 * SBCL Homepage::               
314 * Additional Distributed Documentation::  
315 * Online Documentation::        
316 * Internals Documentation::     
317 @end menu
318
319 @node SBCL Homepage
320 @comment  node-name,  next,  previous,  up
321 @subsection SBCL Homepage
322
323 The SBCL website at @uref{http://www.sbcl.org/} has some general
324 information, plus links to mailing lists devoted to SBCL, and to
325 archives of these mailing lists. Subscribing to the mailing lists
326 @cite{sbcl-help} and @cite{sbcl-announce} is recommended: both are
327 fairly low-volume, and help you keep abrest with SBCL development.
328
329 @node Additional Distributed Documentation
330 @comment  node-name,  next,  previous,  up
331 @subsection Additional Distributed Documentation
332
333 Besides this user manual both SBCL source and binary distributions
334 include some other SBCL-specific documentation files, which should be
335 installed along with this manual in on your system, eg. in
336 @file{/usr/local/share/doc/sbcl/}.
337
338 @table @file
339
340 @item BUGS
341 Lists known bugs in the distribution.
342
343 @item COPYING
344 Licence and copyright summary.
345
346 @item CREDITS
347 Authorship information on various parts of SBCL.
348
349 @item INSTALL
350 Covers installing SBCL from both source and binary distributions on
351 your system, and also has some installation related troubleshooting
352 information.
353
354 @item NEWS
355 Summarizes changes between various SBCL versions.
356
357 @item SUPPORT
358 Lists SBCL developers available for-pay development of SBCL.
359
360 @end table
361
362 @node Online Documentation
363 @comment  node-name,  next,  previous,  up
364 @subsection Online Documentation
365
366 Documentation for non-ANSI extensions for various commands is
367 available online from the SBCL executable itself. The extensions
368 for functions which have their own command prompts (e.g. the debugger,
369 and @code{inspect}) are documented in text available by typing
370 @command{help} at their command prompts. The extensions for functions
371 which don't have their own command prompt (such as @code{trace}) are
372 described in their documentation strings, unless your SBCL was
373 compiled with an option not to include documentation strings, in which
374 case the documentation strings are only readable in the source code.
375
376 @node Internals Documentation
377 @comment  node-name,  next,  previous,  up
378 @subsection Internals Documentation
379
380 If you're interested in the development of the SBCL system itself,
381 then subcribing to @cite{sbcl-devel} is a good idea.
382
383 SBCL internals documentation -- besides comments in the source -- is
384 currenly maitained as a @emph{wiki-like} website:
385 @uref{http://sbcl-internals.cliki.net/}.
386
387 Some low-level information describing the programming details of the
388 conversion from CMUCL to SBCL is available in the
389 @file{doc/FOR-CMUCL-DEVELOPERS} file in the SBCL distribution, though
390 it is not installed by default.
391
392 @node More Common Lisp Information
393 @comment  node-name,  next,  previous,  up
394 @section More Common Lisp Information
395
396 @menu
397 * Internet Community::          
398 * Third-party Libraries::       
399 * Common Lisp Books::           
400 @end menu
401
402 @node Internet Community
403 @comment  node-name,  next,  previous,  up
404 @subsection Internet Community
405
406 @c FIXME: Say something smart here
407
408 The Common Lisp internet community is fairly diverse:
409 @uref{news://comp.lang.lisp} is fairly high volume newsgroup, but has
410 a rather poor signal/noise ratio. Various special interest mailing
411 lists and IRC tend to provide more content and less flames.
412 @uref{http://www.lisp.org} and @uref{http://www.cliki.net} contain
413 numerous pointers places in the net where lispers talks shop.
414
415 @node Third-party Libraries
416 @comment  node-name,  next,  previous,  up
417 @subsection Third-party Libraries
418
419 For a wealth of information about free Common Lisp libraries and tools
420 we recommend checking out @emph{CLiki}: @uref{http://www.cliki.net/}.
421
422 @node Common Lisp Books
423 @comment  node-name,  next,  previous,  up
424 @subsection Common Lisp Books
425
426 If you're not a programmer and you're trying to learn, many
427 introductory Lisp books are available. However, we don't have any
428 standout favorites. If you can't decide, try checking the Usenet
429 @uref{news://comp.lang.lisp} FAQ for recent recommendations.
430
431 @c FIXME: This non-stance is silly. Maybe we could recommend SICP,
432 @c Touretzky, or something at least.
433
434 If you are an experienced programmer in other languages but need to
435 learn about Common Lisp, some books stand out:
436
437 @table @cite
438
439 @c FIXME: Ask Seibel if he minds us referring to the preview
440 @c 
441 @c @item Practical Common Lisp, by Peter Seibel
442 @c A forthcoming book from APress with a web free preview at
443 @c @uref{http://www.gigamonkeys.com/book/}. An excellent introduction to
444 @c the language, covering both the basics and ``advanced topics'' like
445 @c macros, CLOS, and packages.
446
447 @item ANSI Common Lisp, by Paul Graham
448 Introduces most of the language, though some parts (eg. CLOS) are
449 covered only lightly.
450
451 @item On Lisp, by Paul Graham
452 An in-depth treatment of macros, but not recommended as a first Common
453 Lisp book, since it is slightly pre-ANSI so you need to be on your
454 guard against non-standard usages, and since it doesn't really even
455 try to cover the language as a whole, focusing solely on macros.
456 Downloadable from @uref{http://www.paulgraham.com/onlisp.html}.
457
458 @item Paradigms Of Artificial Intelligence Programming, by Peter Norvig
459 Good information on general Common Lisp programming, and many
460 nontrivial examples. Whether or not your work is AI, it's a very good
461 book to look at.
462
463 @item Object-Oriented Programming In Common Lisp, by Sonya Keene
464 @c With the exception of @cite{Practical Common Lisp} 
465 None the books above emphasize CLOS, but this one does. Even if you're
466 very knowledgeable about object oriented programming in the abstract,
467 it's worth looking at this book if you want to do any OO in Common
468 Lisp. Some abstractions in CLOS (especially multiple dispatch) go
469 beyond anything you'll see in most OO systems, and there are a number
470 of lesser differences as well. This book tends to help with the
471 culture shock.
472
473 @item Art Of Metaobject Programming, by Gregor Kiczales et al.
474 Currently to prime source of information on the Common Lisp Metaobject
475 Protocol, which is supported by SBCL. Section 2 (Chapers 5 and 6) are
476 freely available at @uref{http://www.lisp.org/mop/}.
477
478 @end table
479
480
481
482
483 @node History and Implementation of SBCL
484 @comment  node-name,  next,  previous,  up
485 @section History and Implementation of SBCL
486
487 You can work productively with SBCL without knowing anything
488 understanding anything about where it came from, how it is
489 implemented, or how it extends the ANSI Common Lisp standard. However,
490 a little knowledge can be helpful in order to understand error
491 messages, to troubleshoot problems, to understand why some parts of
492 the system are better debugged than others, and to anticipate which
493 known bugs, known performance problems, and missing extensions are
494 likely to be fixed, tuned, or added.
495
496 SBCL is descended from CMUCL, which is itself descended from Spice
497 Lisp, including early implementations for the Mach operating system on
498 the IBM RT, back in the 1980s. Some design decisions from that time are
499 still reflected in the current implementation:
500
501 @itemize
502
503 @item
504 The system expects to be loaded into a fixed-at-compile-time location
505 in virtual memory, and also expects the location of all of its heap
506 storage to be specified at compile time.
507
508 @item
509 The system overcommits memory, allocating large amounts of address
510 space from the system (often more than the amount of virtual memory
511 available) and then failing if ends up using too much of the allocated
512 storage.
513
514 @item
515 The system is implemented as a C program which is responsible for
516 supplying low-level services and loading a Lisp @file{.core}
517 file.
518
519 @end itemize
520
521 @cindex Garbage Collection, generational
522 SBCL also inherited some newer architectural features from CMUCL. The
523 most important is that on some architectures it has a generational
524 garbage collector (``GC''), which has various implications (mostly
525 good) for performance. These are discussed in another chapter,
526 @ref{Efficiency}.
527
528 SBCL has diverged from CMUCL in that SBCL is now essentially a
529 ``compiler-only implementation'' of Common Lisp. This is a change in
530 implementation strategy, taking advantage of the freedom ``any of these
531 facilities might share the same execution strategy'' guaranteed in the
532 ANSI specification section 3.1 (``Evaluation''). It does not mean SBCL
533 can't be used interactively, and in fact the change is largely invisible
534 to the casual user, since SBCL still can and does execute code
535 interactively by compiling it on the fly. (It is visible if you know how
536 to look, like using @code{compiled-function-p}; and it is visible in the
537 way that that SBCL doesn't have many bugs which behave differently in
538 interpreted code than in compiled code.) What it means is that in SBCL,
539 the @code{eval} function only truly ``interprets'' a few easy kinds of
540 forms, such as symbols which are @code{boundp}. More complicated forms
541 are evaluated by calling @code{compile} and then calling @code{funcall}
542 on the returned result.
543   
544 The direct ancestor of SBCL is the x86 port of CMUCL. This port was in
545 some ways the most cobbled-together of all the CMUCL ports, since a
546 number of strange changes had to be made to support the register-poor
547 x86 architecture. Some things (like tracing and debugging) do not work
548 particularly well there. SBCL should be able to improve in these areas
549 (and has already improved in some other areas), but it takes a while.
550
551 @cindex Garbage Collection, conservative
552 On the x86 SBCL -- like the x86 port of CMUCL -- uses a
553 @emph{conservative} GC. This means that it doesn't maintain a strict
554 separation between tagged and untagged data, instead treating some
555 untagged data (e.g. raw floating point numbers) as possibly-tagged
556 data and so not collecting any Lisp objects that they point to. This
557 has some negative consequences for average time efficiency (though
558 possibly no worse than the negative consequences of trying to
559 implement an exact GC on a processor architecture as register-poor as
560 the X86) and also has potentially unlimited consequences for
561 worst-case memory efficiency. In practice, conservative garbage
562 collectors work reasonably well, not getting anywhere near the worst
563 case. But they can occasionally cause odd patterns of memory usage.
564
565 The fork from CMUCL was based on a major rewrite of the system
566 bootstrap process. CMUCL has for many years tolerated a very unusual
567 ``build'' procedure which doesn't actually build the complete system
568 from scratch, but instead progressively overwrites parts of a running
569 system with new versions. This quasi-build procedure can cause various
570 bizarre bootstrapping hangups, especially when a major change is made
571 to the system. It also makes the connection between the current source
572 code and the current executable more tenuous than in other software
573 systems -- it's easy to accidentally ``build'' a CMUCL system
574 containing characteristics not reflected in the current version of the
575 source code.
576
577 Other major changes since the fork from CMUCL include
578
579 @itemize
580
581 @item
582 SBCL has removed many CMUCL extensions, (e.g. IP networking,
583 remote procedure call, Unix system interface, and X11 interface) from
584 the core system. Most of these are available as contributed modules
585 (distributed with sbcl) or third-party modules instead.
586
587 @item
588 SBCL has deleted or deprecated some nonstandard features and code
589 complexity which helped efficiency at the price of
590 maintainability. For example, the SBCL compiler no longer implements
591 memory pooling internally (and so is simpler and more maintainable,
592 but generates more garbage and runs more slowly), and various
593 block-compilation efficiency-increasing extensions to the language
594 have been deleted or are no longer used in the implementation of SBCL
595 itself.
596
597 @end itemize