0.8.10.61:
[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" and "Slime" modes provide many
62 convenient features, like command line editing, tab completion, and
63 various kinds of coupling between Common Lisp source files and the
64 interactive SBCL subprocess.
65
66 .SH OVERVIEW
67
68 SBCL compiles Common Lisp to native code. (Even today, some 30 years
69 after the MacLisp compiler, people will tell you that Lisp is an
70 interpreted language. Ignore them.)
71
72 SBCL aims for but has not completely achieved compliance with the ANSI
73 standard for Common Lisp. More information about this is available in
74 the BUGS section below.
75
76 SBCL also includes various non-ANSI extensions, described more fully
77 in the User Manual.  Some of these are in the base system and others
78 are "contrib" modules loaded on request using REQUIRE.  For example,
79 to load the SB-BSD-SOCKETS module that providces TCP/IP connectivity,
80
81    * (require 'asdf)
82    * (require 'sb-bsd-sockets)
83
84 Many Lispy extensions have been retained from CMU CL:
85 .TP 3
86 \--
87 CMU-CL-style safe implementation of type declarations:
88 "Declarations are assertions."
89 .TP 3
90 \--
91 the source level debugger (very similar to CMU CL's)
92 .TP 3
93 \--
94 the profiler (now somewhat different from CMU CL's)
95 .TP 3
96 \--
97 saving the state of the running SBCL process, producing a
98 "core" file which can be restarted later
99 .TP 3
100 \--
101 Gray streams (a de-facto standard system of overloadable CLOS classes
102 whose instances can be used wherever ordinary ANSI streams can be used)
103 .TP 3
104 \--
105 weak pointers and finalization (which have unfortunately
106 suffered from at least some code rot, so that e.g. weak hash
107 tables don't work)
108 .PP
109
110 Fundamental system interface extensions are also provided:
111 .TP 3
112 \--
113 calling out to C code (a.k.a. FFI, foreign function interface,
114 with very nearly the same interface as CMU CL)
115 .TP 3
116 \--
117 some simple support for operations with a "scripting language" 
118 flavor, e.g. reading POSIX argc and argv, or executing a 
119 subprogram
120 .PP
121
122 .SH DIFFERENCES FROM CMU CL
123
124 SBCL can be built from scratch using a plain vanilla ANSI Common Lisp
125 system and a C compiler, and all of its properties are specified by
126 the version of the source code that it was created from. This clean
127 bootstrappability was the immediate motivation for forking off of the
128 CMU CL development tree. A variety of implementation differences are
129 motivated by this design goal.
130
131 Maintenance work in SBCL since the fork has diverged somewhat from the
132 maintenance work in CMU CL. Many but not all bug fixes and
133 improvements have been shared between the two projects, and sometimes
134 the two projects disagree about what would be an improvement.
135
136 Most extensions supported by CMU CL have been unbundled from SBCL,
137 including Motif support, the Hemlock editor, search paths, the
138 low-level Unix interface, the WIRE protocol, various user-level macros
139 and functions (e.g. LETF, ITERATE, MEMQ, REQUIRED-ARGUMENT), and many
140 others.
141
142 SBCL inplements multithreading, but in a completely different fashion
143 from CMU CL: see the User Manual for details.  As of 0.8.5 this is
144 considered beta-quality and must be explicitly enabled at build time.
145
146 SBCL has retained some extensions from its parent CMU CL. Many of the
147 retained extensions are in these categories:
148 .TP 3
149 \--
150 things which might be in the new ANSI spec, e.g. safe type
151 declarations, weak pointers, finalization, foreign function
152 interface to C, and Gray streams
153 .TP 3
154 \--
155 things which are universally available in Unix scripting languages,
156 e.g. RUN-PROGRAM and POSIX argv and getenv
157 .TP 3
158 \--
159 hooks into the low level workings of the system which can be useful
160 for debugging, e.g. requesting that a particular function be executed
161 whenever GC occurs, or tuning compiler diagnostic output
162 .TP 3
163 \--
164 unportable performance hacks, e.g. FREEZE-TYPE and PURIFY. For more
165 information about these, look at the online documentation for symbols
166 in the SB-EXT package, and look at the user manual.
167 .PP
168
169 There are also a few retained extensions which don't fall into any
170 particular category, e.g. the ability to save running Lisp images as
171 executable files.
172
173 Some of the retained extensions have new names and/or different
174 options than their CMU CL counterparts. For example, the SBCL function
175 which saves a Lisp image to disk and kills the running process is
176 called SAVE-LISP-AND-DIE instead of SAVE-LISP, and SBCL's
177 SAVE-LISP-AND-DIE supports fewer keyword options than CMU CL's
178 SAVE-LISP does.
179
180 (Why doesn't SBCL support more extensions natively?  Why drop all
181 those nice extensions from CMU CL when the code already exists? This
182 is a frequently asked question on the mailing list.  There are two
183 principal reasons.  First, it's a design philosophy issue: arguably
184 SBCL has done its job by supplying a stable FFI, and the right design
185 decision is to move functionality derived from that, like socket
186 support, into separate libraries.  Some of these are distributed with
187 SBCL as "contrib" modules, others are distributed as separate software
188 packages by separate maintainers. Second, it's a practical decision -
189 focusing on a smaller number of things will, we hope, let us do a
190 better job on them.)
191
192 .SH THE COMPILER
193
194 SBCL inherits from CMU CL the "Python" native code compiler. (Though
195 we often avoid that name in order to avoid confusion with the
196 scripting language also called Python.) This compiler is very clever
197 about understanding the type system of Common Lisp and using it to
198 optimize code, and about producing notes to let the user know when the
199 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 compiler reportedly produces pretty good code for modern CPU
206 architectures which have lots of registers, but its code for the X86
207 is marred by many extra loads and stores to stack-based temporary
208 variables. Because of this, and because of the extra levels of
209 indirection in Common Lisp relative to C, the performance of SBCL
210 isn't going to impress people who are impressed by small constant
211 factors. However, even on the X86 it tends to be faster than byte
212 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 COMMAND LINE SYNTAX
224
225 Command line syntax can be considered an advanced topic; for ordinary
226 interactive use, no command line arguments should be necessary.
227
228 In order to understand the command line argument syntax for SBCL, it
229 is helpful to understand that the SBCL system is implemented as two
230 components, a low-level runtime environment written in C and a
231 higher-level system written in Common Lisp itself. Some command line
232 arguments are processed during the initialization of the low-level
233 runtime environment, some command line arguments are processed during
234 the initialization of the Common Lisp system, and any remaining
235 command line arguments are passed on to user code.
236
237 The full, unambiguous syntax for invoking SBCL at the command line is
238 .TP 3
239 .B sbcl [runtime options] --end-runtime-options [toplevel options] --end-toplevel-options [user options]
240 .PP
241
242 For convenience, the --end-runtime-options and --end-toplevel-options
243 elements can be omitted. Omitting these elements can be convenient
244 when you are running the program interactively, and you can see that
245 no ambiguities are possible with the option values you are using.
246 Omitting these elements is probably a bad idea for any batch file
247 where any of the options are under user control, since it makes it
248 impossible for SBCL to detect erroneous command line input, so that
249 erroneous command line arguments will be passed on to the user program
250 even if they was intended for the runtime system or the Lisp system.
251
252 Supported runtime options are
253 .TP 3
254 .B --core <corefilename>
255 Run the specified Lisp core file instead of the default. (See the FILES
256 section for the standard core, or the system documentation for
257 SB-INT:SAVE-LISP-AND-DIE for information about how to create a 
258 custom core.) Note that if the Lisp core file is a user-created core
259 file, it may run a nonstandard toplevel which does not recognize the
260 standard toplevel options.
261 .TP 3
262 .B --noinform
263 Suppress the printing of any banner or other informational message at
264 startup. (This makes it easier to write Lisp programs which work
265 cleanly in Unix pipelines. See also the "--noprint" and
266 "--disable-debugger" options.)
267 .TP 3
268 .B --help
269 Print some basic information about SBCL, then exit.
270 .TP 3
271 .B --version
272 Print SBCL's version information, then exit.
273 .PP
274
275 In the future, runtime options may be added to control behavior such
276 as lazy allocation of memory.
277
278 Runtime options, including any --end-runtime-options option,
279 are stripped out of the command line before the
280 Lisp toplevel logic gets a chance to see it.
281
282 The toplevel options supported by the standard SBCL core are
283 .TP 3
284 .B --sysinit <filename>
285 Load filename instead of the default system-wide initialization file.
286 (See the FILES section.) There is no special option to cause no
287 system-wide initialization file to be read, but on a Unix system
288 "--sysinit /dev/null" can be used to achieve the same effect.
289 .TP 3
290 .B --userinit <filename>
291 Load filename instead of the default user initialization file. (See
292 the FILES section.) There is no special option to cause no user
293 initialization file to be read, but on a Unix system "--userinit
294 /dev/null" can be used to achieve the same effect.
295 .TP 3
296 .B --eval <command>
297 After executing any initialization file, but before starting the
298 read-eval-print loop on standard input, read and evaluate the command
299 given. More than one --eval option can be used, and all will be read
300 and executed, in the order they appear on the command line.
301 .TP 3
302 .B --load <filename>
303 This is equivalent to --eval '(load "<filename>")'. The special
304 syntax is intended to reduce quoting headaches when invoking SBCL
305 from shell scripts.
306 .TP 3
307 .B --noprint
308 When ordinarily the toplevel "read-eval-print loop" would be executed,
309 execute a "read-eval loop" instead, i.e. don't print a prompt and
310 don't echo results. Combined with the --noinform runtime option, this
311 makes it easier to write Lisp "scripts" which work cleanly in Unix
312 pipelines.
313 .TP 3
314 .B --disable-debugger
315 This is equivalent to --eval '(sb-ext:disable-debugger)'. By default,
316 a Common Lisp system tries to ask the programmer for help when it gets
317 in trouble (by printing a debug prompt, then listening, on
318 *DEBUG-IO*). However, this is not useful behavior for a system running
319 with no programmer available, and this option tries to set up more
320 appropriate behavior for that situation. This is implemented by
321 redefining INVOKE-DEBUGGER so that any call exits the process with a
322 failure code after printing a backtrace, and by redefining *DEBUG-IO*
323 to send its output to *ERROR-OUTPUT* and to raise an error if any
324 input is requested from it. (Note that because it is implemented by
325 modifying special variables and FDEFINITIONs, its effects persist in
326 .core files created by SB-EXT:SAVE-LISP-AND-DIE. If you want to undo
327 its effects, e.g. if you build a system unattended and then want to
328 operate a derived system interactively, see the SB-EXT:ENABLE-DEBUGGER
329 command.)
330 .PP
331
332 Regardless of the order in which --sysinit, --userinit, and --eval
333 options appear on the command line, the sysinit file, if it exists, is
334 loaded first; then the userinit file, if it exists, is loaded; then
335 any --eval commands are read and executed in sequence; then the
336 read-eval-print loop is started on standard input. At any step, error
337 conditions or commands such as SB-EXT:QUIT can cause execution to be
338 terminated before proceeding to subsequent steps.
339
340 Note that when running SBCL with the --core option, using a core file
341 created by a user call to the SB-EXT:SAVE-LISP-AND-DIE, the toplevel
342 options may be under the control of user code passed as arguments to
343 SB-EXT:SAVE-LISP-AND-DIE. For this purpose, the --end-toplevel-options
344 option itself can be considered a toplevel option, i.e. the user core,
345 at its option, may not support it.
346
347 In the standard SBCL startup sequence (i.e. with no user core
348 involved) toplevel options and any --end-toplevel-options option are
349 stripped out of the command line argument list before user code gets a
350 chance to see it.
351
352 .SH SYSTEM REQUIREMENTS
353
354 SBCL currently runs on X86 (Linux, FreeBSD, OpenBSD, and NetBSD), Alpha
355 (Linux, Tru64), PPC (Linux, Darwin/MacOS X), SPARC (Linux and Solaris
356 2.x), and MIPS (Linux).  For information on other ongoing and possible
357 ports, see the sbcl-devel mailing list, and/or the web site.
358
359 SBCL requires on the order of 16Mb RAM to run on X86 systems, though
360 all but the smallest programs would be happier with 32Mb or more.
361
362 .SH KNOWN BUGS
363
364 This section attempts to list the most serious and long-standing bugs.
365 For more detailed and current information on bugs, see the BUGS file
366 in the distribution.
367
368 It is possible to get in deep trouble by exhausting heap memory.  The
369 SBCL system overcommits memory at startup, so, on typical Unix-alikes
370 like Linux and FreeBSD, this means that if the SBCL system turns out
371 to use more virtual memory than the system has available for it, other
372 processes tend to be killed randomly (!).
373
374 The compiler's handling of function return values unnecessarily
375 violates the "declarations are assertions" principle that it otherwise
376 adheres to. Using PROCLAIM or DECLAIM to specify the return type of a
377 function causes the compiler to believe you without checking. Thus
378 compiling a file containing
379 (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
380 (DEFUN SOMETIMES (X) (ODDP X))
381 (DEFUN FOO (X) (IF (SOMETIMES X) 'THIS-TIME 'NOT-THIS-TIME))
382 then running (FOO 1) gives NOT-THIS-TIME, because the compiler
383 relied on the truth of the DECLAIM without checking it.
384
385 Some things are implemented very inefficiently.
386 .TP 3
387 \--
388 Multidimensional arrays are inefficient, especially
389 multidimensional arrays of floating point numbers.
390 .TP 3
391 \--
392 The DYNAMIC-EXTENT declaration isn't implemented at all, not even
393 for &REST lists or upward closures, so such constructs always allocate
394 their temporary storage from the heap, causing GC overhead.
395 .TP 3
396 \--
397 CLOS isn't particularly efficient. (In part, CLOS is so dynamic
398 that it's slow for fundamental reasons, but beyond that, the
399 SBCL implementation of CLOS doesn't do some important known
400 optimizations.)
401 .TP 3
402 \--
403 SBCL, like most (maybe all?) implementations of Common Lisp on 
404 stock hardware, has trouble
405 passing floating point numbers around efficiently, because a floating
406 point number, plus a few extra bits to identify its type,
407 is larger than a machine word. (Thus, they get "boxed" in
408 heap-allocated storage, causing GC overhead.) Within
409 a single compilation unit,
410 or when doing built-in operations like SQRT and AREF,
411 or some special operations like structure slot accesses,
412 this is avoidable: see the user manual for some
413 efficiency hints. But for general function calls across
414 the boundaries of compilation units, passing the result of 
415 a floating point calculation
416 as a function argument (or returning a floating point
417 result as a function value) is a fundamentally slow operation.
418 .PP
419
420 There are still some nagging pre-ANSIisms, notably
421 .TP 3
422 --
423 The ANSI-recommended idiom for creating a function which is only
424 sometimes expanded inline,
425 (DECLAIM (INLINE F))
426 (DEFUN F ...)
427 (DECLAIM (NOTINLINE F)),
428 doesn't do what you'd expect. (Instead, you have to declare the
429 function as SB-EXT:MAYBE-INLINE to get the desired effect.)
430 .TP 3
431 \--
432 There are several nonconforming bits of type syntax. E.g. (1) The type
433 FOO is strictly equivalent to (FOO), so e.g. the type OR is treated as
434 the type (OR), i.e. the empty type. This is the way that the ancestral
435 code worked, and even though ANSI specifically forbids it, it hasn't
436 been fixed yet. (2) The symbol * is the name of a type similar to T.
437 (It's used as part of the implementation of compound types like (ARRAY
438 * 1) and (CONS * *). In a strict ANSI implementation, * would not be
439 the name of a type, but instead just a symbol which is recognized and
440 handled specially by certain type expanders.)
441 .PP
442
443 .SH REPORTING BUGS
444
445 To report a bug, please send mail to the mailing lists sbcl-help or
446 sbcl-devel. You can find the complete mailing list addresses on the
447 web pages at <http://sbcl.sourceforge.net/>. (You may also find fancy
448 SourceForge bug-tracking machinery there, but don't be fooled. As of
449 2002-07-25 anyway, we don't actively monitor that machinery, and it
450 exists only because we haven't been able to figure out how to turn
451 it off.)
452
453 As with any software bug report, it's most helpful if you can provide
454 enough information to reproduce the symptoms reliably, and if you say
455 clearly what the symptoms are. E.g. "There seems to be something wrong
456 with TAN of very small negative arguments. When I execute
457 (TAN LEAST-NEGATIVE-SINGLE-FLOAT) interactively on sbcl-1.2.3 on my
458 Linux 4.5 X86 box, I get an UNBOUND-VARIABLE error."
459
460 .SH SUPPORT
461
462 Various information about SBCL is available at
463 <http://ww.sbcl.org/>. The mailing lists there are the recommended
464 place to look for support.
465
466 .SH ENVIRONMENT
467
468 .TP 10n
469 .BR SBCL_HOME
470 This variable controls where files like "sbclrc", "sbcl.core", and the
471 add-on "contrib" systems are searched for.  If it is not set, then
472 sbcl sets it from a compile-time default location which is usually
473 /usr/local/lib/sbcl/ but may have been changed e.g. by a third-party
474 packager.
475
476 .SH FILES
477
478 .TP
479 .I sbcl
480 executable program containing some low-level runtime support and
481 a loader, used to read sbcl.core
482 .TP
483 .I sbcl.core
484 dumped memory image containing most of SBCL, to be loaded by
485 the 'sbcl' executable.  Looked for in $SBCL_HOME, 
486 unless overridden by the --core option.
487 .TP
488 .I sbclrc
489 optional system-wide startup script, looked for in $SBCL_HOME/sbclrc
490 then /etc/sbclrc, unless overridden by the --sysinit command line
491 option.
492 .TP
493 .I .sbclrc
494 optional per-user customizable startup script (in user's home
495 directory, or as specified by  --userinit)
496
497 .SH AUTHORS
498
499 Dozens of people have made substantial contributions to SBCL and its
500 subsystems, and to the CMU CL system on which it was based, over the
501 years. See the CREDITS file in the distribution for more information.
502
503 .SH SEE ALSO
504
505 Full SBCL documentation is maintained as a Texinfo manual. If is has
506 been installed, the command
507 .IP
508 .B info sbcl
509 .PP
510 should give you access to the complete manual. Depending on your
511 installation it may also be available in HTML and PDF formats in eg.
512 .IP
513 .B /usr/local/share/doc/sbcl/
514 .PP
515 See the SBCL homepage 
516 .IP
517 .B http://www.sbcl.org/
518 .PP
519 for more information, including directions on how to subscribe to the
520 sbcl-devel and sbcl-help mailing-lists.