[3d19a6]: doc / sbcl.1 Maximize Restore History

Download this file

sbcl.1    524 lines (455 with data), 21.4 kB

  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
.\" -*- Mode: Text -*-
.\"
.\" man page introduction to SBCL
.\"
.\" SBCL, including this man page, is derived from CMU Common Lisp, of
.\" which it was said (ca. 1991)
.\" **********************************************************************
.\" This code was written as part of the CMU Common Lisp project at
.\" Carnegie Mellon University, and has been placed in the public domain.
.\" If you want to use this code or any part of CMU Common Lisp, please
.\" contact Scott Fahlman or slisp-group@cs.cmu.edu.
.\" **********************************************************************
.\" Most of SBCL, including this man page, is in the public domain. See
.\" COPYING in the distribution for more information.
.\"
.TH SBCL 1 "$Date$"
.AT 3
.SH NAME
SBCL -- Steel Bank Common Lisp
.SH DESCRIPTION
SBCL is a free Common Lisp programming environment. It is derived from
the free CMU CL programming environment. (The name is intended to
acknowledge the connection: steel and banking are the industries where
Carnegie and Mellon made the big bucks.)
.SH LICENSING
It is free software, mostly in the public domain, but with some
subsystems under BSD-style licenses which allow modification and
reuse as long as credit is given. It is provided "as is", with no
warranty of any kind.
For more information about license issues, see the COPYING file in
the distribution. For more information about history, see the
CREDITS file in the distribution.
.SH RUNNING SBCL
To run SBCL, type "sbcl" at the command line with no arguments. (SBCL
understands command line arguments, but you probably won't need to use
them unless you're a fairly advanced user. If you are, you should
read the COMMAND LINE SYNTAX section, below.) You should see some
startup messages, then a prompt ("*"). Type a Lisp expression at the
prompt, and SBCL will read it, execute it, print any values returned,
give you another prompt, and wait for your next input. E.g.
* (+ 1 2 3)
6
* (funcall (lambda (x y) (list x y y)) :toy :choo)
(:TOY :CHOO :CHOO)
* "Hello World"
"Hello World"
*
Many people like to run SBCL, like other Lisp systems, as a subprocess
under Emacs. The Emacs "ilisp" mode provides many convenient features,
like command line editing, tab completion, and various kinds of
coupling between Common Lisp source files and the interactive SBCL
subprocess, but can be somewhat fragile because it tries to be so
clever and intimate in its interactions with the Lisp subprocess. In
case of ilisp problems, running SBCL in the Emacs "shell" mode can a
useful substitute.
.SH OVERVIEW
SBCL compiles Common Lisp to native code. (Even today, some 30 years
after the MacLisp compiler, people will tell you that Lisp is an
interpreted language. Ignore them.)
SBCL aims for but has not completely achieved compliance with the ANSI
standard for Common Lisp. More information about this is available in
the BUGS section below.
SBCL also includes various non-ANSI extensions, described more fully
in the User Manual. Some of these are in the base system and others
are "contrib" modules loaded on request using REQUIRE. For example,
to load the SB-BSD-SOCKETS module that providces TCP/IP connectivity,
* (require 'asdf)
* (require 'sb-bsd-sockets)
Many Lispy extensions have been retained from CMU CL:
.TP 3
\--
CMU-CL-style safe implementation of type declarations:
"Declarations are assertions."
.TP 3
\--
the source level debugger (very similar to CMU CL's)
.TP 3
\--
the profiler (now somewhat different from CMU CL's)
.TP 3
\--
saving the state of the running SBCL process, producing a
"core" file which can be restarted later
.TP 3
\--
Gray streams (a de-facto standard system of overloadable CLOS classes
whose instances can be used wherever ordinary ANSI streams can be used)
.TP 3
\--
weak pointers and finalization (which have unfortunately
suffered from at least some code rot, so that e.g. weak hash
tables don't work)
.PP
Fundamental system interface extensions are also provided:
.TP 3
\--
calling out to C code (a.k.a. FFI, foreign function interface,
with very nearly the same interface as CMU CL)
.TP 3
\--
some simple support for operations with a "scripting language"
flavor, e.g. reading POSIX argc and argv, or executing a
subprogram
.PP
.SH DIFFERENCES FROM CMU CL
SBCL can be built from scratch using a plain vanilla ANSI Common Lisp
system and a C compiler, and all of its properties are specified by
the version of the source code that it was created from. This clean
bootstrappability was the immediate motivation for forking off of the
CMU CL development tree. A variety of implementation differences are
motivated by this design goal.
Maintenance work in SBCL since the fork has diverged somewhat from the
maintenance work in CMU CL. Many but not all bug fixes and
improvements have been shared between the two projects, and sometimes
the two projects disagree about what would be an improvement.
Most extensions supported by CMU CL have been unbundled from SBCL,
including Motif support, the Hemlock editor, search paths, the
low-level Unix interface, the WIRE protocol, various user-level macros
and functions (e.g. LETF, ITERATE, MEMQ, REQUIRED-ARGUMENT), and many
others.
SBCL inplements multithreading, but in a completely different fashion
from CMU CL: see the User Manual for details. As of 0.8.5 this is
considered beta-quality and must be explicitly enabled at build time.
SBCL has retained some extensions from its parent CMU CL. Many of the
retained extensions are in these categories:
.TP 3
\--
things which might be in the new ANSI spec, e.g. safe type
declarations, weak pointers, finalization, foreign function
interface to C, and Gray streams
.TP 3
\--
things which are universally available in Unix scripting languages,
e.g. RUN-PROGRAM and POSIX argv and getenv
.TP 3
\--
hooks into the low level workings of the system which can be useful
for debugging, e.g. requesting that a particular function be executed
whenever GC occurs, or tuning compiler diagnostic output
.TP 3
\--
unportable performance hacks, e.g. FREEZE-TYPE and PURIFY. For more
information about these, look at the online documentation for symbols
in the SB-EXT package, and look at the user manual.
.PP
There are also a few retained extensions which don't fall into any
particular category, e.g. the ability to save running Lisp images as
executable files.
Some of the retained extensions have new names and/or different
options than their CMU CL counterparts. For example, the SBCL function
which saves a Lisp image to disk and kills the running process is
called SAVE-LISP-AND-DIE instead of SAVE-LISP, and SBCL's
SAVE-LISP-AND-DIE supports fewer keyword options than CMU CL's
SAVE-LISP does.
(Why doesn't SBCL support more extensions natively? Why drop all
those nice extensions from CMU CL when the code already exists? This
is a frequently asked question on the mailing list. There are two
principal reasons. First, it's a design philosophy issue: arguably
SBCL has done its job by supplying a stable FFI, and the right design
decision is to move functionality derived from that, like socket
support, into separate libraries. Some of these are distributed with
SBCL as "contrib" modules, others are distributed as separate software
packages by separate maintainers. Second, it's a practical decision -
focusing on a smaller number of things will, we hope, let us do a
better job on them.)
.SH THE COMPILER
SBCL is essentially a compiler-only implementation of Common Lisp. All
nontrivial Lisp code is compiled to native machine code before being
executed, even when the Lisp code is typed interactively at the
"interpreter" prompt.
SBCL inherits from CMU CL the "Python" native code compiler. (Though
we often avoid that name in order to avoid confusion with the
scripting language also called Python.) This compiler is very clever
about understanding the type system of Common Lisp and using it to
optimize code, and about producing notes to let the user know when the
compiler doesn't have enough type information to produce efficient
code. It also tries (almost always successfully) to follow the unusual
but very useful principle that "declarations are assertions", i.e.
type declarations should be checked at runtime unless the user
explicitly tells the system that speed is more important than safety.
The compiler reportedly produces pretty good code for modern CPU
architectures which have lots of registers, but its code for the X86
is marred by many extra loads and stores to stack-based temporary
variables. Because of this, and because of the extra levels of
indirection in Common Lisp relative to C, the performance of SBCL
isn't going to impress people who are impressed by small constant
factors. However, even on the X86 it tends to be faster than byte
interpreted languages (and can be a lot faster).
The compiled code uses garbage collection to automatically
manage memory. The garbage collector implementation varies considerably
from CPU to CPU. In particular, on some CPUs the GC is nearly exact,
while on others it's more conservative, and on some CPUs the GC
is generational, while on others simpler stop and copy strategies
are used.
For more information about the compiler, see the user manual.
.SH DOCUMENTATION
Currently, the documentation for the system is
.TP 3
\--
this man page
.TP 3
\--
the user manual
.TP 3
\--
doc strings and online help built into the SBCL executable
.PP
.SH COMMAND LINE SYNTAX
Command line syntax can be considered an advanced topic; for ordinary
interactive use, no command line arguments should be necessary.
In order to understand the command line argument syntax for SBCL, it
is helpful to understand that the SBCL system is implemented as two
components, a low-level runtime environment written in C and a
higher-level system written in Common Lisp itself. Some command line
arguments are processed during the initialization of the low-level
runtime environment, some command line arguments are processed during
the initialization of the Common Lisp system, and any remaining
command line arguments are passed on to user code.
The full, unambiguous syntax for invoking SBCL at the command line is
.TP 3
.B sbcl [runtime options] --end-runtime-options [toplevel options] --end-toplevel-options [user options]
.PP
For convenience, the --end-runtime-options and --end-toplevel-options
elements can be omitted. Omitting these elements can be convenient
when you are running the program interactively, and you can see that
no ambiguities are possible with the option values you are using.
Omitting these elements is probably a bad idea for any batch file
where any of the options are under user control, since it makes it
impossible for SBCL to detect erroneous command line input, so that
erroneous command line arguments will be passed on to the user program
even if they was intended for the runtime system or the Lisp system.
Supported runtime options are
.TP 3
.B --core <corefilename>
Run the specified Lisp core file instead of the default. (See the FILES
section for the standard core, or the system documentation for
SB-INT:SAVE-LISP-AND-DIE for information about how to create a
custom core.) Note that if the Lisp core file is a user-created core
file, it may run a nonstandard toplevel which does not recognize the
standard toplevel options.
.TP 3
.B --noinform
Suppress the printing of any banner or other informational message at
startup. (This makes it easier to write Lisp programs which work
cleanly in Unix pipelines. See also the "--noprint" and
"--disable-debugger" options.)
.TP 3
.B --help
Print some basic information about SBCL, then exit.
.TP 3
.B --version
Print SBCL's version information, then exit.
.PP
In the future, runtime options may be added to control behavior such
as lazy allocation of memory.
Runtime options, including any --end-runtime-options option,
are stripped out of the command line before the
Lisp toplevel logic gets a chance to see it.
The toplevel options supported by the standard SBCL core are
.TP 3
.B --sysinit <filename>
Load filename instead of the default system-wide initialization file.
(See the FILES section.) There is no special option to cause no
system-wide initialization file to be read, but on a Unix system
"--sysinit /dev/null" can be used to achieve the same effect.
.TP 3
.B --userinit <filename>
Load filename instead of the default user initialization file. (See
the FILES section.) There is no special option to cause no user
initialization file to be read, but on a Unix system "--userinit
/dev/null" can be used to achieve the same effect.
.TP 3
.B --eval <command>
After executing any initialization file, but before starting the
read-eval-print loop on standard input, read and evaluate the command
given. More than one --eval option can be used, and all will be read
and executed, in the order they appear on the command line.
.TP 3
.B --load <filename>
This is equivalent to --eval '(load "<filename>")'. The special
syntax is intended to reduce quoting headaches when invoking SBCL
from shell scripts.
.TP 3
.B --noprint
When ordinarily the toplevel "read-eval-print loop" would be executed,
execute a "read-eval loop" instead, i.e. don't print a prompt and
don't echo results. Combined with the --noinform runtime option, this
makes it easier to write Lisp "scripts" which work cleanly in Unix
pipelines.
.TP 3
.B --disable-debugger
This is equivalent to --eval '(sb-ext:disable-debugger)'. By default,
a Common Lisp system tries to ask the programmer for help when it gets
in trouble (by printing a debug prompt, then listening, on
*DEBUG-IO*). However, this is not useful behavior for a system running
with no programmer available, and this option tries to set up more
appropriate behavior for that situation. This is implemented by
redefining INVOKE-DEBUGGER so that any call exits the process with a
failure code after printing a backtrace, and by redefining *DEBUG-IO*
to send its output to *ERROR-OUTPUT* and to raise an error if any
input is requested from it. (Note that because it is implemented by
modifying special variables and FDEFINITIONs, its effects persist in
.core files created by SB-EXT:SAVE-LISP-AND-DIE. If you want to undo
its effects, e.g. if you build a system unattended and then want to
operate a derived system interactively, see the SB-EXT:ENABLE-DEBUGGER
command.)
.PP
Regardless of the order in which --sysinit, --userinit, and --eval
options appear on the command line, the sysinit file, if it exists, is
loaded first; then the userinit file, if it exists, is loaded; then
any --eval commands are read and executed in sequence; then the
read-eval-print loop is started on standard input. At any step, error
conditions or commands such as SB-EXT:QUIT can cause execution to be
terminated before proceeding to subsequent steps.
Note that when running SBCL with the --core option, using a core file
created by a user call to the SB-EXT:SAVE-LISP-AND-DIE, the toplevel
options may be under the control of user code passed as arguments to
SB-EXT:SAVE-LISP-AND-DIE. For this purpose, the --end-toplevel-options
option itself can be considered a toplevel option, i.e. the user core,
at its option, may not support it.
In the standard SBCL startup sequence (i.e. with no user core
involved) toplevel options and any --end-toplevel-options option are
stripped out of the command line argument list before user code gets a
chance to see it.
.SH SYSTEM REQUIREMENTS
SBCL currently runs on X86 (Linux, FreeBSD, OpenBSD, and NetBSD), Alpha
(Linux, Tru64), PPC (Linux, Darwin/MacOS X), SPARC (Linux and Solaris
2.x), and MIPS (Linux). For information on other ongoing and possible
ports, see the sbcl-devel mailing list, and/or the web site.
SBCL requires on the order of 16Mb RAM to run on X86 systems, though
all but the smallest programs would be happier with 32Mb or more.
.SH KNOWN BUGS
This section attempts to list the most serious and long-standing bugs.
For more detailed and current information on bugs, see the BUGS file
in the distribution.
It is possible to get in deep trouble by exhausting heap memory. The
SBCL system overcommits memory at startup, so, on typical Unix-alikes
like Linux and FreeBSD, this means that if the SBCL system turns out
to use more virtual memory than the system has available for it, other
processes tend to be killed randomly (!).
The compiler's handling of function return values unnecessarily
violates the "declarations are assertions" principle that it otherwise
adheres to. Using PROCLAIM or DECLAIM to specify the return type of a
function causes the compiler to believe you without checking. Thus
compiling a file containing
(DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
(DEFUN SOMETIMES (X) (ODDP X))
(DEFUN FOO (X) (IF (SOMETIMES X) 'THIS-TIME 'NOT-THIS-TIME))
then running (FOO 1) gives NOT-THIS-TIME, because the compiler
relied on the truth of the DECLAIM without checking it.
Some things are implemented very inefficiently.
.TP 3
\--
Multidimensional arrays are inefficient, especially
multidimensional arrays of floating point numbers.
.TP 3
\--
The DYNAMIC-EXTENT declaration isn't implemented at all, not even
for &REST lists or upward closures, so such constructs always allocate
their temporary storage from the heap, causing GC overhead.
.TP 3
\--
CLOS isn't particularly efficient. (In part, CLOS is so dynamic
that it's slow for fundamental reasons, but beyond that, the
SBCL implementation of CLOS doesn't do some important known
optimizations.)
.TP 3
\--
SBCL, like most (maybe all?) implementations of Common Lisp on
stock hardware, has trouble
passing floating point numbers around efficiently, because a floating
point number, plus a few extra bits to identify its type,
is larger than a machine word. (Thus, they get "boxed" in
heap-allocated storage, causing GC overhead.) Within
a single compilation unit,
or when doing built-in operations like SQRT and AREF,
or some special operations like structure slot accesses,
this is avoidable: see the user manual for some
efficiency hints. But for general function calls across
the boundaries of compilation units, passing the result of
a floating point calculation
as a function argument (or returning a floating point
result as a function value) is a fundamentally slow operation.
.PP
There are still some nagging pre-ANSIisms, notably
.TP 3
--
The ANSI-recommended idiom for creating a function which is only
sometimes expanded inline,
(DECLAIM (INLINE F))
(DEFUN F ...)
(DECLAIM (NOTINLINE F)),
doesn't do what you'd expect. (Instead, you have to declare the
function as SB-EXT:MAYBE-INLINE to get the desired effect.)
.TP 3
\--
There are several nonconforming bits of type syntax. E.g. (1) The type
FOO is strictly equivalent to (FOO), so e.g. the type OR is treated as
the type (OR), i.e. the empty type. This is the way that the ancestral
code worked, and even though ANSI specifically forbids it, it hasn't
been fixed yet. (2) The symbol * is the name of a type similar to T.
(It's used as part of the implementation of compound types like (ARRAY
* 1) and (CONS * *). In a strict ANSI implementation, * would not be
the name of a type, but instead just a symbol which is recognized and
handled specially by certain type expanders.)
.PP
.SH REPORTING BUGS
To report a bug, please send mail to the mailing lists sbcl-help or
sbcl-devel. You can find the complete mailing list addresses on the
web pages at <http://sbcl.sourceforge.net/>. (You may also find fancy
SourceForge bug-tracking machinery there, but don't be fooled. As of
2002-07-25 anyway, we don't actively monitor that machinery, and it
exists only because we haven't been able to figure out how to turn
it off.)
As with any software bug report, it's most helpful if you can provide
enough information to reproduce the symptoms reliably, and if you say
clearly what the symptoms are. E.g. "There seems to be something wrong
with TAN of very small negative arguments. When I execute
(TAN LEAST-NEGATIVE-SINGLE-FLOAT) interactively on sbcl-1.2.3 on my
Linux 4.5 X86 box, I get an UNBOUND-VARIABLE error."
.SH SUPPORT
Various information about SBCL is available at
<http://sbcl.sourceforge.net/>. The mailing lists there are the
recommended place to look for support.
.SH ENVIRONMENT
.TP 10n
.BR SBCL_HOME
This variable controls where files like "sbclrc", "sbcl.core", and the
add-on "contrib" systems are searched for. If it is not set, then
sbcl sets it from a compile-time default location which is usually
/usr/local/lib/sbcl/ but may have been changed e.g. by a third-party
packager.
.SH FILES
.TP
.I sbcl
executable program containing some low-level runtime support and
a loader, used to read sbcl.core
.TP
.I sbcl.core
dumped memory image containing most of SBCL, to be loaded by
the 'sbcl' executable. Looked for in $SBCL_HOME,
unless overridden by the --core option.
.TP
.I sbclrc
optional system-wide startup script, looked for in $SBCL_HOME/sbclrc
then /etc/sbclrc, unless overridden by the --sysinit command line
option.
.TP
.I .sbclrc
optional per-user customizable startup script (in user's home
directory, or as specified by --userinit)
.SH AUTHORS
Dozens of people have made substantial contributions to SBCL and its
subsystems, and to the CMU CL system on which it was based, over the
years. See the CREDITS file in the distribution for more information.