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