made debugger handle errors in printing *DEBUG-CONDITION*
[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 .\"
14 .TH SBCL 1 "$Date$"
15 .AT 3
16 .SH NAME
17 SBCL -- "Steel Bank Common Lisp"
18
19 .SH DESCRIPTION
20
21 SBCL is a free Common Lisp programming environment. It is derived from
22 the free CMU CL programming environment. (The name is intended to
23 acknowledge the connection: steel and banking are the industries where
24 Carnegie and Mellon made the big bucks.)
25
26 .SH COMMAND LINE SYNTAX
27
28 Command line syntax can be considered an advanced topic; for ordinary
29 interactive use, no command line arguments should be necessary.
30
31 In order to understand the command line argument syntax for SBCL, it
32 is helpful to understand that the SBCL system is implemented as two
33 components, a low-level runtime environment written in C and a
34 higher-level system written in Common Lisp itself. Some command line
35 arguments are processed during the initialization of the low-level
36 runtime environment, some command line arguments are processed during
37 the initialization of the Common Lisp system, and any remaining
38 command line arguments are passed on to user code.
39
40 The full, unambiguous syntax for SBCL is
41 .TP 3
42 .B sbcl [runtime options] --end-runtime-options [toplevel options] --end-toplevel-options [user options]
43 .PP
44
45 For convenience, the --end-runtime-options and --end-toplevel-options
46 elements can be omitted. Omitting these elements can be convenient
47 when you are running the program interactively, and you can see that
48 no ambiguities are possible with the option values you are using.
49 Omitting these elements is probably a bad idea for any batch file
50 where any of the options are under user control, since it makes it
51 impossible for SBCL to detect erroneous command line input, so that
52 erroneous command line arguments will be passed on to the user program
53 even if they was intended for the runtime system or the Lisp system.
54
55 Supported runtime options are
56 .TP 3
57 .B --core <corefilename>
58 Run the specified Lisp core file instead of the default. (See the FILES
59 section.) Note that if the Lisp core file is a user-created core file, it may
60 run a nonstandard toplevel which does not accept the standard toplevel options.
61 .TP 3
62 .B --noinform
63 Suppress the printing of any banner or other informational message at
64 startup. (This makes it easier to write Lisp programs which work in
65 Unix pipelines. See also the "--noinform" option.)
66 .PP
67
68 In the future, runtime options may be added to control behavior such
69 as lazy allocation of memory.
70
71 Runtime options, including any --end-runtime-options option,
72 are stripped out of the command line before the
73 Lisp toplevel logic gets a chance to see it.
74
75 Supported toplevel options for the standard SBCL core are
76 .TP 3
77 .B --sysinit <filename>
78 Load filename instead of the default system-wide
79 initialization file. (See the FILES section.)
80 There is no special option to cause
81 no system-wide initialization file to be read, but on a Unix
82 system "--sysinit /dev/null" can be used to achieve the same effect.
83 .TP 3
84 .B --userinit <filename>
85 Load filename instead of the default user
86 initialization file. (See the FILES section.)
87 There is no special option to cause
88 no user initialization file to be read, but on a Unix
89 system "--userinit /dev/null" can be used to achieve the same effect.
90 .TP 3
91 .B --eval <command>
92 After executing any initialization file, but before starting the
93 read-eval-print loop on standard input,
94 evaluate the command given. More than
95 one --eval option can be used, and all will be executed,
96 in the order they appear on the command line.
97 .TP 3
98 .B --noprint
99 When ordinarily the toplevel "read-eval-print loop" would be
100 executed, execute a "read-eval loop" instead, i.e. don't print
101 a prompt and don't echo results. (Combined with the --noinform
102 runtime option, this makes it easier to write Lisp
103 "scripts" which work in Unix pipelines.)
104 .TP 3
105 .B --noprogrammer
106 Ordinarily the system initializes *DEBUG-IO* to *TERMINAL-IO*.
107 When the --notty option is set, however, *DEBUG-IO* is instead
108 set to a stream which sends its output to *ERROR-OUTPUT* and
109 which raises an error on input. As a result, any attempt by the
110 program to get programmer feedback through the debugger
111 causes an error which abnormally terminates the entire
112 Lisp environment. (This can be useful behavior for programs
113 which are to run without programmer supervision.)
114 .PP
115
116 Regardless of the order in which --sysinit, --userinit, and --eval
117 options appear on the command line, the sysinit file, if it exists, is
118 loaded first; then the userinit file, if it exists, is loaded; then
119 any --eval commands are executed in sequence; then the read-eval-print
120 loop is started on standard input. At any step, error conditions or
121 commands such as SB-EXT:QUIT can cause execution to be terminated
122 before proceeding to subsequent steps.
123
124 Note that when running SBCL from a core file created by a user call to
125 the SB-EXT:SAVE-LISP-AND-DIE, the toplevel options may be under the
126 control of user code passed as arguments to SB-EXT:SAVE-LISP-AND-DIE.
127 For this purpose, the --end-toplevel-options option itself can be
128 considered a toplevel option, i.e. the user core, at its option, may
129 not support it.
130
131 In the standard SBCL startup sequence (i.e. with no user core
132 involved) toplevel options and any --end-toplevel-options option are
133 stripped out of the command line argument list before user code gets a
134 chance to see it.
135
136 .SH OVERVIEW
137
138 SBCL aims for but has not reached ANSI compliance.
139
140 SBCL compiles Lisp to native code, or optionally to more-compact but
141 much slower byte code.
142
143 SBCL's garbage collector is generational and conservative.
144
145 SBCL includes a source level debugger, as well as the ANSI TRACE
146 facility and a rudimentary profiler.
147
148 .SH DIFFERENCES FROM CMU CL
149
150 SBCL can be built from scratch using a plain vanilla ANSI Common Lisp
151 system and a C compiler, and all of its properties are specified by
152 the version of the source code that it was created from. (This clean
153 bootstrappability was the immediate motivation for forking off of the
154 CMU CL development tree.)
155
156 Many extensions supported by CMU CL, like Motif support,
157 the Hemlock editor, search paths, the WIRE protocol, various
158 user-level macros and functions (e.g. LETF, ITERATE, MEMQ,
159 REQUIRED-ARGUMENT), and many others.
160
161 SBCL has retained some extensions of its parent CMU CL. Many
162 of them are in three categories:
163 .TP 3
164 \--
165 hooks into the low level workings of the system which can be useful
166 for debugging (e.g. a list of functions to be run whenever GC occurs,
167 or an operator to cause a particular string to be compiled into a fasl
168 file)
169 .TP 3
170 \--
171 non-portable performance hacks (e.g. PURIFY, which causes
172 everything currently in existence to become immune to GC)
173 .TP 3
174 \--
175 things which might be in the new ANSI spec (e.g. weak pointers,
176 finalization, foreign function interface to C, and Gray streams)
177 .PP
178
179 There are also various retained extensions which don't fall into
180 any particular category, e.g.
181 .TP 3
182 \--
183 the ability to save running Lisp images as executable files
184 .PP
185
186 Some of the retained extensions have new names and/or different
187 options than their CMU CL counterparts. For example, the SBCL function
188 which saves a Lisp image to disk and kills it is called
189 SAVE-LISP-AND-DIE instead of SAVE-LISP, and it supports fewer keyword
190 options than CMU CL's SAVE-LISP.
191
192 .SH THE COMPILER
193
194 SBCL inherits from CMU CL the "Python" native code compiler. This
195 compiler is very clever about understanding the type system of Common
196 Lisp and using it to produce efficient code, and about producing notes
197 to let the user know when the compiler doesn't have enough type
198 information to produce efficient code. It also tries (almost always
199 successfully) to follow the unusual but very useful principle that
200 type declarations should be checked at runtime unless the user
201 explicitly tells the system that speed is more important than safety.
202
203 The CMU CL version of this compiler reportedly produces pretty good
204 code for modern machines which have lots of registers, but its code
205 for the X86 is marred by a lot of extra loads and stores to
206 stack-based temporary variables. Because of this, and because of the
207 extra levels of indirection in Common Lisp relative to C, we find a
208 typical performance decrease by a factor of perhaps 2 to 5 for small
209 programs coded in SBCL instead of GCC.
210
211 For more information about the compiler, see the user manual.
212
213 .SH DOCUMENTATION
214
215 Currently, the documentation for the system is
216 .TP 3
217 \--
218 the user manual
219 .TP 3
220 \--
221 this man page
222 .TP 3
223 \--
224 doc strings and online help built into the SBCL executable
225 .PP
226
227 .SH SYSTEM REQUIREMENTS
228
229 Unlike its distinguished ancestor CMU CL, SBCL is currently only
230 supported on X86. Linux, FreeBSD, and OpenBSD ports are currently
231 available. It would probably be straightforward to port the CMU CL
232 support for SPARC or Alpha, or to port to NetBSD. Some work on a
233 port to the Alpha has been reported on the mailing lists; check
234 the archives (available from the home page at
235 <http://sbcl.sourceforge.net/>) for information.
236
237 As of version 0.6.8, SBCL requires on the order of 16Mb to run. In
238 some future version, this number could shrink significantly, since
239 large parts of the system are far from execution bottlenecks and could
240 reasonably be stored in compact byte compiled form. (CMU CL does this
241 routinely; the only reason SBCL doesn't currently do this is a
242 combination of bootstrapping technicalities and inertia.)
243
244 .SH ENVIRONMENT
245
246 .TP 10n
247 .BR SBCL_HOME
248 If this variable is set, it overrides the default directories for
249 files like "sbclrc" and "sbcl.core", so that instead of being searched
250 for in e.g. /etc/, /usr/local/etc/, /usr/lib/, and /usr/local/lib/, they
251 are searched for only in the directory named by SBCL_HOME. This is
252 intended to support users who wish to use their own version of SBCL
253 instead of the version which is currently installed as the system
254 default.
255 .PP
256
257 .SH FILES
258
259 /usr/lib/sbcl.core and /usr/local/lib/sbcl.core are the standard
260 locations for the standard SBCL core, unless overridden by the SBCL_HOME
261 variable.
262
263 /etc/sbclrc and /usr/local/etc/sbclrc are the standard locations for
264 system-wide SBCL initialization files, unless overridden by the
265 SBCL_HOME variable.
266
267 $HOME/.sbclrc is the standard location for a user's SBCL
268 initialization file.
269
270 .SH BUGS
271
272 Too numerous to list, alas. This section attempts to list the most
273 serious known bugs, and a reasonably representative sampling of
274 others. For more information on bugs, see the BUGS file in the
275 distribution.
276
277 It is possible to get in deep trouble by exhausting
278 memory. To plagiarize a sadly apt description of a language not
279 renowned for the production of bulletproof software, "[The current
280 SBCL implementation of] Common Lisp makes it harder for you to shoot
281 yourself in the foot, but when you do, the entire universe explodes."
282 .TP 3
283 \--
284 The system doesn't deal well with stack overflow.
285 .TP 3
286 \--
287 The SBCL system overcommits memory at startup. On typical Unix-alikes
288 like Linux and *BSD, this means that if the SBCL system turns out to
289 use more virtual memory than the system has available for it, other
290 processes to be killed randomly (!)
291 .PP
292
293 The facility for dumping a running Lisp image to disk gets confused
294 when run without the PURIFY option, and creates an unnecessarily large
295 core file (apparently representing memory usage up to the previous
296 high-water mark). Moreover, when the file is loaded, it confuses the
297 GC, so that thereafter memory usage can never be reduced below that
298 level.
299
300 The compiler is overaggressive about static typing, assuming that a
301 function's return type never changes. Thus compiling and loading a
302 file containing
303 (DEFUN FOO (X) NIL)
304 (DEFUN BAR (X) (IF (FOO X) 1 2))
305 (DEFUN FOO (X) (PLUSP X))
306 then running (FOO 1) gives 2 (because the compiler "knew"
307 that FOO's return type is NULL).
308
309 The compiler's handling of function return values unnecessarily
310 violates the "declarations are assertions" principle that it otherwise
311 adheres to. Using PROCLAIM or DECLAIM to specify the return type of a
312 function causes the compiler to believe you without checking. Thus
313 compiling a file containing
314 (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
315 (DEFUN SOMETIMES (X) (ODDP X))
316 (DEFUN FOO (X) (IF (SOMETIMES X) 'THIS-TIME 'NOT-THIS-TIME))
317 then running (FOO 1) gives NOT-THIS-TIME, because the
318 never compiled code to check the declaration.
319
320 The TRACE facility can't be used on some kinds of functions.
321
322 SYMBOL-FUNCTION is much slower than you'd expect, being implemented
323 not as a slot access but as a search through the compiler/kernel
324 "globaldb" database.
325
326 CLOS (based on the PCL reference implementation) is quite slow.
327
328 There are many nagging pre-ANSIisms, e.g.
329 .TP 3
330 \--
331 CLOS (based on the PCL reference implementation) is incompletely
332 integrated into the system, so that e.g. SB-PCL::FIND-CLASS is a
333 different function than CL::FIND-CLASS. (This is less of a problem in
334 practice than the speed, but it's still distasteful.)
335 .TP 3
336 --
337 The ANSI-recommended idiom for creating a function which is only
338 sometimes expanded inline,
339 (DECLAIM (INLINE F))
340 (DEFUN F ...)
341 (DECLAIM (NOTINLINE F)),
342 doesn't do what you'd expect. (Instead, you have to declare the
343 function as SB-EXT:MAYBE-INLINE to get the desired effect.)
344 .TP 3
345 \--
346 The DYNAMIC-EXTENT declaration is not implemented, and is simply
347 ignored. (This is allowed by the ANSI spec, but can have a large
348 efficiency cost in some kinds of code.)
349 .TP 3
350 --
351 Compiling DEFSTRUCT in strange places (e.g. inside a DEFUN) doesn't
352 do anything like what it should.
353 .TP 3
354 \--
355 The symbol * is the name of a type similar to T. (It's used as part
356 of the implementation of compound types like (ARRAY * 1).)
357 .PP
358
359 .SH SUPPORT
360
361 Various information about SBCL is available at
362 <http://sbcl.sourceforge.net/>. The mailing lists there are the
363 recommended place to look for support.
364
365 .SH DISTRIBUTION
366
367 SBCL is a free implementation of Common Lisp derived from CMU CL. Both
368 sources and executables are freely available; this software is "as
369 is", and has no warranty of any kind. CMU and the authors assume no
370 responsibility for the consequences of any use of this software. See
371 the CREDITS file in the distribution for more information about
372 history, contributors and permissions.
373