0.7.7.6:
[sbcl.git] / doc / sbcl.1
1 .\" -*- Mode: Text -*-
2 .\"
3 .\" man page introduction to SBCL
4 .\"
5 .\" SBCL, including this man page, is derived from CMU Common Lisp, of
6 .\" which it was said (ca. 1991)
7 .\"   **********************************************************************
8 .\"   This code was written as part of the CMU Common Lisp project at
9 .\"   Carnegie Mellon University, and has been placed in the public domain.
10 .\"   If you want to use this code or any part of CMU Common Lisp, please
11 .\"   contact Scott Fahlman or slisp-group@cs.cmu.edu.
12 .\"   **********************************************************************
13 .\" Most of SBCL, including this man page, is in the public domain. See
14 .\" COPYING in the distribution for more information.
15 .\"
16 .TH SBCL 1 "$Date$"
17 .AT 3
18 .SH NAME
19 SBCL -- "Steel Bank Common Lisp"
20
21 .SH DESCRIPTION
22
23 SBCL is a free Common Lisp programming environment. It is derived from
24 the free CMU CL programming environment. (The name is intended to
25 acknowledge the connection: steel and banking are the industries where
26 Carnegie and Mellon made the big bucks.)
27
28 .SH LICENSING
29
30 It is free software, mostly in the public domain, but with some
31 subsystems under BSD-style licenses which allow modification and
32 reuse as long as credit is given. It is provided "as is", with no
33 warranty of any kind.
34
35 For more information about license issues, see the COPYING file in
36 the distribution. For more information about history, see the 
37 CREDITS file in the distribution.
38
39 .SH RUNNING SBCL
40
41 To run SBCL, type "sbcl" at the command line with no arguments. (SBCL
42 understands command line arguments, but you probably won't need to use
43 them unless you're a fairly advanced user. If you are, you should
44 read the COMMAND LINE SYNTAX section, below.) You should see some
45 startup messages, then a prompt ("*"). Type a Lisp expression at the
46 prompt, and SBCL will read it, execute it, print any values returned, 
47 give you another prompt, and wait for your next input. E.g.
48
49   * (+ 1 2 3)
50
51   6
52   * (funcall (lambda (x y) (list x y y)) :toy :choo)
53
54   (:TOY :CHOO :CHOO)
55   * "Hello World"
56
57   "Hello World"
58   *
59
60 Many people like to run SBCL, like other Lisp systems, as a subprocess
61 under Emacs. The Emacs "ilisp" mode provides many convenient features,
62 like command line editing, tab completion, and various kinds of
63 coupling between Common Lisp source files and the interactive SBCL
64 subprocess, but can be somewhat fragile because it tries to be so
65 clever and intimate in its interactions with the Lisp subprocess. In
66 case of ilisp problems, running SBCL in the Emacs "shell" mode can a
67 useful substitute.
68
69 .SH OVERVIEW
70
71 SBCL compiles Common Lisp to native code. (Even today, some 30 years
72 after the MacLisp compiler, people will tell you that Lisp is an
73 interpreted language. Ignore them.)
74
75 SBCL aims for but has not yet reached compliance with the ANSI
76 standard for Common Lisp. More information about this is available in
77 the BUGS section below.
78
79 SBCL also includes various non-ANSI extensions.
80
81 Many Lispy extensions have been retained from CMU CL:
82 .TP 3
83 \--
84 CMU-CL-style safe implementation of type declarations:
85 "Declarations are assertions."
86 .TP 3
87 \--
88 the source level debugger (very similar to CMU CL's)
89 .TP 3
90 \--
91 the profiler (now somewhat different from CMU CL's)
92 .TP 3
93 \--
94 saving the state of the running SBCL process, producing a
95 "core" file which can be restarted later
96 .TP 3
97 \--
98 Gray streams (a de-facto standard system of overloadable CLOS classes
99 whose instances can be used wherever ordinary ANSI streams can be used)
100 .TP 3
101 \--
102 weak pointers and finalization (which have unfortunately
103 suffered from at least some code rot, so that e.g. weak hash
104 tables don't work)
105 .PP
106
107 Fundamental system interface extensions are also provided:
108 .TP 3
109 \--
110 calling out to C code (a.k.a. FFI, foreign function interface,
111 with very nearly the same interface as CMU CL)
112 .TP 3
113 \--
114 some simple support for operations with a "scripting language" 
115 flavor, e.g. reading POSIX argc and argv, or executing a 
116 subprogram
117 .PP
118
119 .SH DIFFERENCES FROM CMU CL
120
121 SBCL can be built from scratch using a plain vanilla ANSI Common Lisp
122 system and a C compiler, and all of its properties are specified by
123 the version of the source code that it was created from. This clean
124 bootstrappability was the immediate motivation for forking off of the
125 CMU CL development tree. A variety of implementation differences are
126 motivated by this design goal.
127
128 Maintenance work in SBCL since the fork has diverged somewhat from the
129 maintenance work in CMU CL. Many but not all bug fixes and
130 improvements have been shared between the two projects, and sometimes
131 the two projects disagree about what would be an improvement.
132
133 Most extensions supported by CMU CL are not supported in SBCL,
134 including Motif support, the Hemlock editor, search paths, the
135 low-level Unix interface, the WIRE protocol, multithreading, various
136 user-level macros and functions (e.g. LETF, ITERATE, MEMQ,
137 REQUIRED-ARGUMENT), and many others.
138
139 SBCL has retained some extensions from parent CMU CL. Many of the
140 retained extensions are in these categories:
141 .TP 3
142 \--
143 things which might be in the new ANSI spec, e.g. safe type
144 declarations, weak pointers, finalization, foreign function
145 interface to C, and Gray streams
146 .TP 3
147 \--
148 things which are universally available in Unix scripting languages,
149 e.g. RUN-PROGRAM and POSIX argv and getenv
150 .TP 3
151 \--
152 hooks into the low level workings of the system which can be useful
153 for debugging, e.g. requesting that a particular function be executed
154 whenever GC occurs, or tuning compiler diagnostic output
155 .TP 3
156 \--
157 unportable performance hacks, e.g. FREEZE-TYPE and PURIFY. For more
158 information about these, look at the online documentation for symbols
159 in the SB-EXT package, and look at the user manual.
160 .PP
161
162 There are also a few retained extensions which don't fall into any
163 particular category, e.g. the ability to save running Lisp images as
164 executable files.
165
166 Some of the retained extensions have new names and/or different
167 options than their CMU CL counterparts. For example, the SBCL function
168 which saves a Lisp image to disk and kills the running process is
169 called SAVE-LISP-AND-DIE instead of SAVE-LISP, and SBCL's
170 SAVE-LISP-AND-DIE supports fewer keyword options than CMU CL's
171 SAVE-LISP does.
172
173 (Why doesn't SBCL support more extensions? Why drop all those nice
174 extensions from CMU CL when the code already exists? This is a
175 frequently asked question on the mailing list. In some cases, it's a
176 design philosophy issue: arguably SBCL has done its job by supplying a
177 stable FFI, and the right design decision is to move functionality
178 derived from that, like socket support, into separate libraries,
179 distributed as separate software packages by separate maintainers. In
180 other cases it's a practical decision, hoping that focusing on a
181 smaller number of things will let us do a better job on them. This is
182 very much the case for multithreading: it's an important, valuable
183 extension, but it's not easy to get right, and especially while SBCL
184 is still working on basic ANSI compliance, difficult extensions aren't
185 likely to be a priority.)
186
187 .SH THE COMPILER
188
189 SBCL is essentially a compiler-only implementation of Lisp. All
190 nontrivial Lisp code is compiled to native machine code before being
191 executed, even when the Lisp code is typed interactively at the
192 "interpreter" prompt.
193
194 SBCL inherits from CMU CL the "Python" native code compiler. (Though
195 we've essentially dropped that name in order to avoid confusion with
196 the scripting language also called Python.) This compiler is very
197 clever about understanding the type system of Common Lisp and using it
198 to optimize code, and about producing notes to let the user know when
199 the compiler doesn't have enough type information to produce efficient
200 code. It also tries (almost always successfully) to follow the unusual
201 but very useful principle that "declarations are assertions", i.e.
202 type declarations should be checked at runtime unless the user
203 explicitly tells the system that speed is more important than safety.
204
205 The CMU CL version of this compiler reportedly produces pretty good
206 code for modern CPU architectures which have lots of registers, but
207 its code for the X86 is marred by a lot of extra loads and stores to
208 stack-based temporary variables. Because of this, and because of the
209 extra levels of indirection in Common Lisp relative to C, the
210 performance of SBCL isn't going to impress people who are impressed by
211 small constant factors. However, even on the X86 it tends to be faster
212 than byte interpreted languages (and can be a lot faster).
213
214 The compiled code uses garbage collection to automatically
215 manage memory. The garbage collector implementation varies considerably
216 from CPU to CPU. In particular, on some CPUs the GC is nearly exact,
217 while on others it's more conservative, and on some CPUs the GC
218 is generational, while on others simpler stop and copy strategies
219 are used.
220
221 For more information about the compiler, see the user manual.
222
223 .SH DOCUMENTATION
224
225 Currently, the documentation for the system is
226 .TP 3
227 \--
228 this man page
229 .TP 3
230 \--
231 the user manual
232 .TP 3
233 \--
234 doc strings and online help built into the SBCL executable
235 .PP
236
237 .SH COMMAND LINE SYNTAX
238
239 Command line syntax can be considered an advanced topic; for ordinary
240 interactive use, no command line arguments should be necessary.
241
242 In order to understand the command line argument syntax for SBCL, it
243 is helpful to understand that the SBCL system is implemented as two
244 components, a low-level runtime environment written in C and a
245 higher-level system written in Common Lisp itself. Some command line
246 arguments are processed during the initialization of the low-level
247 runtime environment, some command line arguments are processed during
248 the initialization of the Common Lisp system, and any remaining
249 command line arguments are passed on to user code.
250
251 The full, unambiguous syntax for invoking SBCL at the command line is
252 .TP 3
253 .B sbcl [runtime options] --end-runtime-options [toplevel options] --end-toplevel-options [user options]
254 .PP
255
256 For convenience, the --end-runtime-options and --end-toplevel-options
257 elements can be omitted. Omitting these elements can be convenient
258 when you are running the program interactively, and you can see that
259 no ambiguities are possible with the option values you are using.
260 Omitting these elements is probably a bad idea for any batch file
261 where any of the options are under user control, since it makes it
262 impossible for SBCL to detect erroneous command line input, so that
263 erroneous command line arguments will be passed on to the user program
264 even if they was intended for the runtime system or the Lisp system.
265
266 Supported runtime options are
267 .TP 3
268 .B --core <corefilename>
269 Run the specified Lisp core file instead of the default. (See the FILES
270 section.) Note that if the Lisp core file is a user-created core file, it may
271 run a nonstandard toplevel which does not recognize the standard toplevel
272 options.
273 .TP 3
274 .B --noinform
275 Suppress the printing of any banner or other informational message at
276 startup. (This makes it easier to write Lisp programs which work
277 cleanly in Unix pipelines. See also the "--noprint" and
278 "--disable-debugger" options.)
279 .PP
280
281 In the future, runtime options may be added to control behavior such
282 as lazy allocation of memory.
283
284 Runtime options, including any --end-runtime-options option,
285 are stripped out of the command line before the
286 Lisp toplevel logic gets a chance to see it.
287
288 Supported toplevel options for the standard SBCL core are
289 .TP 3
290 .B --sysinit <filename>
291 Load filename instead of the default system-wide initialization file.
292 (See the FILES section.) There is no special option to cause no
293 system-wide initialization file to be read, but on a Unix system
294 "--sysinit /dev/null" can be used to achieve the same effect.
295 .TP 3
296 .B --userinit <filename>
297 Load filename instead of the default user initialization file. (See
298 the FILES section.) There is no special option to cause no user
299 initialization file to be read, but on a Unix system "--userinit
300 /dev/null" can be used to achieve the same effect.
301 .TP 3
302 .B --eval <command>
303 After executing any initialization file, but before starting the
304 read-eval-print loop on standard input, evaluate the command given.
305 More than one --eval option can be used, and all will be executed, in
306 the order they appear on the command line.
307 .TP 3
308 .B --load <filename>
309 This is equivalent to --eval '(load "<filename>")'. The special
310 syntax is intended to reduce quoting headaches when invoking SBCL
311 from shell scripts.
312 .TP 3
313 .B --noprint
314 When ordinarily the toplevel "read-eval-print loop" would be executed,
315 execute a "read-eval loop" instead, i.e. don't print a prompt and
316 don't echo results. Combined with the --noinform runtime option, this
317 makes it easier to write Lisp "scripts" which work cleanly in Unix
318 pipelines.
319 .TP 3
320 .B --disable-debugger
321 This is equivalent to --eval '(sb-ext:disable-debugger)'.
322 By default, a Common Lisp system tries to ask the programmer for help
323 when it gets in trouble (by printing a debug prompt on *DEBUG-IO*).
324 However, this is not useful behavior for a system running with no
325 programmer available, and this option tries to set up more appropriate
326 behavior for that situation. This is implemented by modifying special
327 variables: we set *DEBUG-IO* to send its output to *ERROR-OUTPUT*, and
328 to raise an error if any input is requested from it, and we set
329 *DEBUGGER-HOOK* to output a backtrace, then exit the process with a
330 failure code. Because it is implemented by modifying special variables,
331 its effects persist in .core files created by SB-EXT:SAVE-LISP-AND-DIE.
332 (If you want to undo its effects, see the SB-EXT:ENABLE-DEBUGGER
333 command.)
334 .PP
335
336 Regardless of the order in which --sysinit, --userinit, and --eval
337 options appear on the command line, the sysinit file, if it exists, is
338 loaded first; then the userinit file, if it exists, is loaded; then
339 any --eval commands are executed in sequence; then the read-eval-print
340 loop is started on standard input. At any step, error conditions or
341 commands such as SB-EXT:QUIT can cause execution to be terminated
342 before proceeding to subsequent steps.
343
344 Note that when running SBCL with the --core option, using a core file
345 created by a user call to the SB-EXT:SAVE-LISP-AND-DIE, the toplevel
346 options may be under the control of user code passed as arguments to
347 SB-EXT:SAVE-LISP-AND-DIE. For this purpose, the --end-toplevel-options
348 option itself can be considered a toplevel option, i.e. the user core,
349 at its option, may not support it.
350
351 In the standard SBCL startup sequence (i.e. with no user core
352 involved) toplevel options and any --end-toplevel-options option are
353 stripped out of the command line argument list before user code gets a
354 chance to see it.
355
356 .SH SYSTEM REQUIREMENTS
357
358 SBCL currently runs on
359 X86 (Linux, FreeBSD, and OpenBSD), Alpha (Linux, Tru64), PPC
360 (Linux) and SPARC (Linux and Solaris 2.x).
361 For information on other ongoing and possible ports, see the
362 sbcl-devel mailing list, and/or the web site.
363
364 SBCL requires on the order of 16Mb RAM to run on X86 systems, 
365 though for all but the smallest programs would be happier with 32Mb
366 or more.
367
368 .SH ENVIRONMENT
369
370 .TP 10n
371 .BR SBCL_HOME
372 If this variable is set, it overrides the default directories for
373 files like "sbclrc" and "sbcl.core", so that instead of being searched
374 for in e.g. /etc/, /usr/local/etc/, /usr/lib/, and /usr/local/lib/, they
375 are searched for only in the directory named by SBCL_HOME. This is
376 intended to support users who wish to use their own version of SBCL
377 instead of the version which is currently installed as the system
378 default.
379 .PP
380
381 .SH FILES
382
383 /usr/lib/sbcl.core and /usr/local/lib/sbcl.core are the standard
384 locations for the standard SBCL core, unless overridden by the SBCL_HOME
385 variable.
386
387 /etc/sbclrc and /usr/local/etc/sbclrc are the standard locations for
388 system-wide SBCL initialization files, unless overridden by the
389 SBCL_HOME variable or the --sysinit command line option.
390
391 $HOME/.sbclrc is the standard location for a user's SBCL
392 initialization file, unless overridden by the --userinit
393 command line option.
394
395 .SH KNOWN BUGS
396
397 This section attempts to list the most serious and long-standing bugs.
398 For more detailed and current information on bugs, see the BUGS file
399 in the distribution.
400
401 It is possible to get in deep trouble by exhausting 
402 memory. To plagiarize a sadly apt description of a language not
403 renowned for the production of bulletproof software, "[The current
404 SBCL implementation of] Common Lisp makes it harder for you to shoot
405 yourself in the foot, but when you do, the entire universe explodes."
406 .TP 3
407 \--
408 Like CMU CL, the SBCL system overcommits memory at startup. On typical
409 Unix-alikes like Linux and FreeBSD, this means that if the SBCL system
410 turns out to use more virtual memory than the system has available for
411 it, other processes tend to be killed randomly (!).
412 .PP
413
414 The compiler's handling of function return values unnecessarily
415 violates the "declarations are assertions" principle that it otherwise
416 adheres to. Using PROCLAIM or DECLAIM to specify the return type of a
417 function causes the compiler to believe you without checking. Thus
418 compiling a file containing
419 (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
420 (DEFUN SOMETIMES (X) (ODDP X))
421 (DEFUN FOO (X) (IF (SOMETIMES X) 'THIS-TIME 'NOT-THIS-TIME))
422 then running (FOO 1) gives NOT-THIS-TIME, because the
423 never compiled code to check the declaration.
424
425 Some things are implemented very inefficiently.
426 .TP 3
427 \--
428 Multidimensional arrays are inefficient, especially
429 multidimensional arrays of floating point numbers.
430 .TP 3
431 \--
432 The DYNAMIC-EXTENT declaration isn't implemented at all, not even
433 for &REST lists or upward closures, so such constructs always allocate
434 their temporary storage from the heap, causing GC overhead.
435 .TP 3
436 \--
437 CLOS isn't particularly efficient. (In part, CLOS is so dynamic
438 that it's slow for fundamental reasons, but beyond that, the
439 SBCL implementation of CLOS doesn't do some important known
440 optimizations.)
441 .TP 3
442 \--
443 SBCL, like most (maybe all?) implementations of Common Lisp on 
444 stock hardware, has trouble
445 passing floating point numbers around efficiently, because a floating
446 point number, plus a few extra bits to identify its type,
447 is larger than a machine word. (Thus, they get "boxed" in
448 heap-allocated storage, causing GC overhead.) Within
449 a single compilation unit,
450 or when doing built-in operations like SQRT and AREF,
451 or some special operations like structure slot accesses,
452 this is avoidable: see the user manual for some
453 efficiency hints. But for general function calls across
454 the boundaries of compilation units, passing the result of 
455 a floating point calculation
456 as a function argument (or returning a floating point
457 result as a function value) is a fundamentally slow operation.
458 .PP
459
460 There are still some nagging pre-ANSIisms, notably
461 .TP 3
462 \--
463 CLOS (based on the PCL reference implementation) is incompletely
464 integrated into the system, so that e.g. SB-PCL::FIND-CLASS is a
465 different function than CL::FIND-CLASS. (In practice, you need to
466 be a pretty advanced user before this is a serious problem, and
467 by then you can usually work around it, but it's still distasteful.
468 It's arguably the outstanding "This should be fixed by version 1.0"
469 issue.)
470 .TP 3
471 --
472 The ANSI-recommended idiom for creating a function which is only
473 sometimes expanded inline,
474 (DECLAIM (INLINE F))
475 (DEFUN F ...)
476 (DECLAIM (NOTINLINE F)),
477 doesn't do what you'd expect. (Instead, you have to declare the
478 function as SB-EXT:MAYBE-INLINE to get the desired effect.)
479 .TP 3
480 \--
481 There are several nonconforming bits of type syntax. E.g. (1) The type
482 FOO is strictly equivalent to (FOO), so e.g. the type OR is treated as
483 the type (OR), i.e. the empty type. This is the way that the ancestral
484 code worked, and even though ANSI specifically forbids it, it hasn't
485 been fixed yet. (2) The symbol * is the name of a type similar to T.
486 (It's used as part of the implementation of compound types like (ARRAY
487 * 1) and (CONS * *). In a strict ANSI implementation, * would not be
488 the name of a type, but instead just a symbol which is recognized and
489 handled specially by certain type expanders.)
490 .PP
491
492 .SH REPORTING BUGS
493
494 To report a bug, please send mail to the mailing lists sbcl-help or
495 sbcl-devel. You can find the complete mailing list addresses on the
496 web pages, <http://sbcl.sourceforge.net/>. (You may also find fancy
497 SourceForge bug-tracking machinery there, but don't be fooled. As of
498 2002-07-25 anyway, we don't actively monitor that machinery, and it
499 exists only because we haven't been able to figure out how to turn
500 it off.)
501
502 As with any software bug report, it's most helpful if you can provide
503 enough information to reproduce the symptoms reliably, and if you say
504 clearly what the symptoms are. E.g. "There seems to be something wrong
505 with TAN of very small negative arguments. When I execute
506 (TAN LEAST-NEGATIVE-SINGLE-FLOAT) interactively on sbcl-1.2.3 on my
507 Linux 4.5 X86 box, I get an UNBOUND-VARIABLE error."
508
509 .SH SUPPORT
510
511 Various information about SBCL is available at
512 <http://sbcl.sourceforge.net/>. The mailing lists there are the
513 recommended place to look for support.
514
515 .SH FILES
516
517 .TP
518 .I sbcl
519 executable program containing some low-level runtime support and
520 a loader, used to read sbcl.core
521 .TP
522 .I sbcl.core
523 dumped memory image containing most of SBCL, to be loaded by the
524 'sbcl' executable
525 .TP
526 .I sbclrc
527 optional system-wide startup script (in an etc-ish system
528 configuration file directory)
529 .TP
530 .I .sbclrc
531 optional per-user customizable startup script (in user's home directory)
532
533 .SH AUTHORS
534
535 Dozens of people have made substantial contributions to SBCL and its
536 subsystems, and to the CMU CL system on which it was based, over the
537 years. See the CREDITS file in the distribution.