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