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