1SBCL(1) General Commands Manual SBCL(1)
2
6 SBCL -- Steel Bank Common Lisp
7
10 SBCL is a free Common Lisp programming environment. It is derived from
11 the free CMU CL programming environment. (The name is intended to
12 acknowledge the connection: steel and banking are the industries where
13 Carnegie and Mellon made the big bucks.)
14
17 It is free software, mostly in the public domain, but with some subsys‐
18 tems under BSD-style licenses which allow modification and reuse as
19 long as credit is given. It is provided "as is", with no warranty of
20 any kind.
21 For more information about license issues, see the COPYING file in the
23 distribution. For more information about history, see the CREDITS file
24 in the distribution.
25
28 To run SBCL, type "sbcl" at the command line with no arguments. (SBCL
29 understands command line arguments, but you probably won't need to use
30 them unless you're a fairly advanced user. If you are, you should read
31 the COMMAND LINE SYNTAX section, below.) You should see some startup
32 messages, then a prompt ("*"). Type a Lisp expression at the prompt,
33 and SBCL will read it, execute it, print any values returned, give you
34 another prompt, and wait for your next input. For example,
35 * (+ 1 2 3)
36 6
38 * (funcall (lambda (x y) (list x y y)) :toy :choo)
39 (:TOY :CHOO :CHOO)
41 * "Hello World"
42 "Hello World"
44 *
45 Many people like to run SBCL, like other Lisp systems, as a subprocess
47 under Emacs. The Emacs "Slime" and "ilisp" modes provide many conve‐
48 nient features, like command line editing, tab completion, and various
49 kinds of coupling between Common Lisp source files and the interactive
50 SBCL subprocess, but they can be somewhat fragile wrt. packages and
51 readtables, in which case SBCL in the Emacs "shell" mode can a useful
52 substitute.
53
56 SBCL compiles Common Lisp to native code. (Even today, some 30 years
57 after the MacLisp compiler, people will tell you that Lisp is an inter‐
58 preted language. Ignore them.)
59 SBCL aims for but has not completely achieved compliance with the ANSI
61 standard for Common Lisp. More information about this is available in
62 the BUGS section below.
63 SBCL also includes various non-ANSI extensions, described more fully in
65 the User Manual. Some of these are in the base system and others are
66 "contrib" modules loaded on request using REQUIRE. For example, to
67 load the SB-BSD-SOCKETS module that providces TCP/IP connectivity,
68 * (require 'asdf)
69 * (require 'sb-bsd-sockets)
70 Many Lispy extensions have been retained from CMU CL:
72 -- CMU-CL-style safe implementation of type declarations: "Declarations
74 are assertions."
75 -- the source level debugger (very similar to CMU CL's)
77 -- the profiler (now somewhat different from CMU CL's)
79 -- saving the state of the running SBCL process, producing a "core"
81 file which can be restarted later
82 -- Gray streams (a de-facto standard system of overloadable CLOS
84 classes whose instances can be used wherever ordinary ANSI streams
85 can be used)
86 -- weak pointers and finalization (which have unfortunately suffered
88 from at least some code rot, so that e.g. weak hash tables don't
89 work)
90 Fundamental system interface extensions are also provided:
92 -- calling out to C code (a.k.a. FFI, foreign function interface, with
94 very nearly the same interface as CMU CL)
95 -- some simple support for operations with a "scripting language" fla‐
97 vor, e.g. reading POSIX argc and argv, or executing a subprogram
98
100 SBCL can be built from scratch using a plain vanilla ANSI Common Lisp
101 system and a C compiler, and all of its properties are specified by the
102 version of the source code that it was created from. This clean boot‐
103 strappability was the immediate motivation for forking off of the CMU
104 CL development tree. A variety of implementation differences are moti‐
105 vated by this design goal.
106 Maintenance work in SBCL since the fork has diverged somewhat from the
108 maintenance work in CMU CL. Many but not all bug fixes and improvements
109 have been shared between the two projects, and sometimes the two
110 projects disagree about what would be an improvement.
111 Most extensions supported by CMU CL have been unbundled from SBCL,
113 including Motif support, the Hemlock editor, search paths, the low-
114 level Unix interface, the WIRE protocol, various user-level macros and
115 functions (e.g. LETF, ITERATE, MEMQ, REQUIRED-ARGUMENT), and many oth‐
116 ers.
117 SBCL inplements multithreading, but in a completely different fashion
119 from CMU CL: see the User Manual for details. As of 0.8.5 this is con‐
120 sidered beta-quality and must be explicitly enabled at build time.
121 SBCL has retained some extensions from its parent CMU CL. Many of the
123 retained extensions are in these categories:
124 -- things which might be in the new ANSI spec, e.g. safe type declara‐
126 tions, weak pointers, finalization, foreign function interface to C,
127 and Gray streams;
128 -- things which are universally available in Unix scripting languages,
130 e.g. RUN-PROGRAM and POSIX argv and getenv;
131 -- hooks into the low level workings of the system which can be useful
133 for debugging, e.g. requesting that a particular function be exe‐
134 cuted whenever GC occurs, or tuning compiler diagnostic output;
135 -- unportable performance hacks, e.g. FREEZE-TYPE and PURIFY. For more
137 information about these, look at the online documentation for sym‐
138 bols in the SB-EXT package, and look at the user manual.
139 There are also a few retained extensions which don't fall into any par‐
141 ticular category, e.g. the ability to save running Lisp images as exe‐
142 cutable files.
143 Some of the retained extensions have new names and/or different options
145 than their CMU CL counterparts. For example, the SBCL function which
146 saves a Lisp image to disk and kills the running process is called
147 SAVE-LISP-AND-DIE instead of SAVE-LISP, and SBCL's SAVE-LISP-AND-DIE
148 supports fewer keyword options than CMU CL's SAVE-LISP does.
149 (Why doesn't SBCL support more extensions natively? Why drop all those
151 nice extensions from CMU CL when the code already exists? This is a
152 frequently asked question on the mailing list. There are two principal
153 reasons. First, it's a design philosophy issue: arguably SBCL has done
154 its job by supplying a stable FFI, and the right design decision is to
155 move functionality derived from that, like socket support, into sepa‐
156 rate libraries. Some of these are distributed with SBCL as "contrib"
157 modules, others are distributed as separate software packages by sepa‐
158 rate maintainers. Second, it's a practical decision - focusing on a
159 smaller number of things will, we hope, let us do a better job on
160 them.)
161
164 SBCL inherits from CMU CL the "Python" native code compiler. (Though we
165 often avoid that name in order to avoid confusion with the scripting
166 language also called Python.) This compiler is very clever about under‐
167 standing the type system of Common Lisp and using it to optimize code,
168 and about producing notes to let the user know when the compiler
169 doesn't have enough type information to produce efficient code. It also
170 tries (almost always successfully) to follow the unusual but very use‐
171 ful principle that "declarations are assertions", i.e. type declara‐
172 tions should be checked at runtime unless the user explicitly tells the
173 system that speed is more important than safety.
174 The compiler reportedly produces pretty good code for modern CPU archi‐
176 tectures which have lots of registers, but its code for the X86 is
177 marred by many extra loads and stores to stack-based temporary vari‐
178 ables. Because of this, and because of the extra levels of indirection
179 in Common Lisp relative to C, the performance of SBCL isn't going to
180 impress people who are impressed by small constant factors. However,
181 even on the X86 it tends to be faster than byte interpreted languages
182 (and can be a lot faster).
183 The compiled code uses garbage collection to automatically manage mem‐
185 ory. The garbage collector implementation varies considerably from CPU
186 to CPU. In particular, on some CPUs the GC is nearly exact, while on
187 others it's more conservative, and on some CPUs the GC is generational,
188 while on others simpler stop and copy strategies are used.
189 For more information about the compiler, see the user manual.
191
194 Command line syntax can be considered an advanced topic; for ordinary
195 interactive use, no command line arguments should be necessary.
196 In order to understand the command line argument syntax for SBCL, it is
198 helpful to understand that the SBCL system is implemented as two compo‐
199 nents, a low-level runtime environment written in C and a higher-level
200 system written in Common Lisp itself. Some command line arguments are
201 processed during the initialization of the low-level runtime environ‐
202 ment, some command line arguments are processed during the initializa‐
203 tion of the Common Lisp system, and any remaining command line argu‐
204 ments are passed on to user code.
205 The full, unambiguous syntax for invoking SBCL at the command line is
207 sbcl [runtime options] --end-runtime-options [toplevel options]
209 --end-toplevel-options [user options]
210 For convenience, the --end-runtime-options and --end-toplevel-options
212 elements can be omitted. Omitting these elements can be convenient when
213 you are running the program interactively, and you can see that no
214 ambiguities are possible with the option values you are using. Omit‐
215 ting these elements is probably a bad idea for any batch file where any
216 of the options are under user control, since it makes it impossible for
217 SBCL to detect erroneous command line input, so that erroneous command
218 line arguments will be passed on to the user program even if they was
219 intended for the runtime system or the Lisp system.
220 Supported runtime options are
222 --core <corefilename>
224 Run the specified Lisp core file instead of the default. (See the
225 FILES section for the standard core, or the system documentation for
226 SB-EXT:SAVE-LISP-AND-DIE for information about how to create a cus‐
227 tom core.) Note that if the Lisp core file is a user-created core
228 file, it may run a nonstandard toplevel which does not recognize the
229 standard toplevel options.
230 --dynamic-space-size <megabytes>
232 Size of the dynamic space reserved on startup in megabytes. Default
233 value is platform dependent.
234 --noinform
236 Suppress the printing of any banner or other informational message
237 at startup. (This makes it easier to write Lisp programs which work
238 cleanly in Unix pipelines. See also the "--noprint" and "--dis‐
239 able-debugger" options.)
240 --help
242 Print some basic information about SBCL, then exit.
243 --version
245 Print SBCL's version information, then exit.
246 In the future, runtime options may be added to control behavior such as
248 lazy allocation of memory.
249 Runtime options, including any --end-runtime-options option, are
251 stripped out of the command line before the Lisp toplevel logic gets a
252 chance to see it.
253 The toplevel options supported by the standard SBCL core are
255 --sysinit <filename>
257 Load filename instead of the default system-wide initialization
258 file. (See the FILES section.)
259 --no-sysinit
261 Do not load a system-wide initialization file. If this option is
262 given, the --sysinit option is ignored.
263 --userinit <filename>
265 Load filename instead of the default user initialization file. (See
266 the FILES section.)
267 --no-userinit
269 Do not load a user initialization file. If this option is given, the
270 --userinit option is ignored.
271 --eval <command>
273 After executing any initialization file, but before starting the
274 read-eval-print loop on standard input, read and evaluate the com‐
275 mand given. More than one --eval option can be used, and all will be
276 read and executed, in the order they appear on the command line.
277 --load <filename>
279 This is equivalent to --eval '(load "<filename>")'. The special syn‐
280 tax is intended to reduce quoting headaches when invoking SBCL from
281 shell scripts.
282 --noprint
284 When ordinarily the toplevel "read-eval-print loop" would be exe‐
285 cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
286 and don't echo results. Combined with the --noinform runtime option,
287 this makes it easier to write Lisp "scripts" which work cleanly in
288 Unix pipelines.
289 --disable-debugger
291 This is equivalent to --eval '(sb-ext:disable-debugger)'. By
292 default, a Common Lisp system tries to ask the programmer for help
293 when it gets in trouble (by printing a debug prompt, then listening,
294 on *DEBUG-IO*). However, this is not useful behavior for a system
295 running with no programmer available, and this option tries to set
296 up more appropriate behavior for that situation. This is implemented
297 by redefining INVOKE-DEBUGGER so that any call exits the process
298 with a failure code after printing a backtrace. (Note that because
299 it is implemented by modifying special variables and FDEFINITIONs,
300 its effects persist in .core files created by
301 SB-EXT:SAVE-LISP-AND-DIE. If you want to undo its effects, e.g. if
302 you build a system unattended and then want to operate a derived
303 system interactively, see the SB-EXT:ENABLE-DEBUGGER command.)
304 Regardless of the order in which --sysinit, --userinit, and --eval
306 options appear on the command line, the sysinit file, if it exists, is
307 loaded first; then the userinit file, if it exists, is loaded; then any
308 --eval commands are read and executed in sequence; then the read-eval-
309 print loop is started on standard input. At any step, error conditions
310 or commands such as SB-EXT:QUIT can cause execution to be terminated
311 before proceeding to subsequent steps.
312 Note that when running SBCL with the --core option, using a core file
314 created by a user call to the SB-EXT:SAVE-LISP-AND-DIE, the toplevel
315 options may be under the control of user code passed as arguments to
316 SB-EXT:SAVE-LISP-AND-DIE. For this purpose, the --end-toplevel-options
317 option itself can be considered a toplevel option, i.e. the user core,
318 at its option, may not support it.
319 In the standard SBCL startup sequence (i.e. with no user core involved)
321 toplevel options and any --end-toplevel-options option are stripped out
322 of the command line argument list before user code gets a chance to see
323 it.
324
327 SBCL currently runs on X86 (Linux, FreeBSD, OpenBSD, and NetBSD),
328 X86-64 (Linux), Alpha (Linux, Tru64), PPC (Linux, Darwin/MacOS X),
329 SPARC (Linux and Solaris 2.x), and MIPS (Linux). For information on
330 other ongoing and possible ports, see the sbcl-devel mailing list,
331 and/or the web site.
332 SBCL requires on the order of 16Mb RAM to run on X86 systems, though
334 all but the smallest programs would be happier with 32Mb or more.
335
338 This section attempts to list the most serious and long-standing bugs.
339 For more detailed and current information on bugs, see the BUGS file in
340 the distribution.
341 It is possible to get in deep trouble by exhausting heap memory. The
343 SBCL system overcommits memory at startup, so, on typical Unix-alikes
344 like Linux and FreeBSD, this means that if the SBCL system turns out to
345 use more virtual memory than the system has available for it, other
346 processes tend to be killed randomly (!).
347 The compiler's handling of function return values unnecessarily vio‐
349 lates the "declarations are assertions" principle that it otherwise
350 adheres to. Using PROCLAIM or DECLAIM to specify the return type of a
351 function causes the compiler to believe you without checking. Thus com‐
352 piling a file containing
353 (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
354 (DEFUN SOMETIMES (X) (ODDP X))
355 (DEFUN FOO (X) (IF (SOMETIMES X) 'THIS-TIME 'NOT-THIS-TIME))
356 then running (FOO 1) gives NOT-THIS-TIME, because the compiler relied
357 on the truth of the DECLAIM without checking it.
358 Some things are implemented very inefficiently.
360 -- Multidimensional arrays are inefficient, especially multidimensional
362 arrays of floating point numbers.
363 -- CLOS isn't particularly efficient. (In part, CLOS is so dynamic that
365 it's slow for fundamental reasons, but beyond that, the SBCL imple‐
366 mentation of CLOS doesn't do some important known optimizations.)
367 -- SBCL, like most (maybe all?) implementations of Common Lisp on stock
369 hardware, has trouble passing floating point numbers around effi‐
370 ciently, because a floating point number, plus a few extra bits to
371 identify its type, is larger than a machine word. (Thus, they get
372 "boxed" in heap-allocated storage, causing GC overhead.) Within a
373 single compilation unit, or when doing built-in operations like SQRT
374 and AREF, or some special operations like structure slot accesses,
375 this is avoidable: see the user manual for some efficiency hints.
376 But for general function calls across the boundaries of compilation
377 units, passing the result of a floating point calculation as a func‐
378 tion argument (or returning a floating point result as a function
379 value) is a fundamentally slow operation.
380
382 To report a bug, please send mail to the mailing lists sbcl-help or
383 sbcl-devel. You can find the complete mailing list addresses on the web
384 pages at <http://sbcl.sourceforge.net/>. (You may also find fancy
385 SourceForge bug-tracking machinery there, but don't be fooled. As of
386 2002-07-25 anyway, we don't actively monitor that machinery, and it
387 exists only because we haven't been able to figure out how to turn it
388 off.)
389 As with any software bug report, it's most helpful if you can provide
391 enough information to reproduce the symptoms reliably, and if you say
392 clearly what the symptoms are. For example, "There seems to be some‐
393 thing wrong with TAN of very small negative arguments. When I execute
394 (TAN LEAST-NEGATIVE-SINGLE-FLOAT) interactively on sbcl-1.2.3 on my
395 Linux 4.5 X86 box, I get an UNBOUND-VARIABLE error."
396
399 Various information about SBCL is available at <http://www.sbcl.org/>.
400 The mailing lists there are the recommended place to look for support.
401
404 SBCL_HOME This variable controls where files like "sbclrc",
405 "sbcl.core", and the add-on "contrib" systems are searched
406 for. If it is not set, then sbcl sets it from a compile-time
407 default location which is usually /usr/local/lib/sbcl/ but
408 may have been changed e.g. by a third-party packager.
409
412 sbcl executable program containing some low-level runtime support and
413 a loader, used to read sbcl.core
414 sbcl.core
416 dumped memory image containing most of SBCL, to be loaded by the
417 `sbcl' executable. Looked for in $SBCL_HOME, unless overridden
418 by the --core option.
419 sbclrc optional system-wide startup script, looked for in
421 $SBCL_HOME/sbclrc then /etc/sbclrc, unless overridden by the
422 --sysinit command line option.
423 .sbclrc
425 optional per-user customizable startup script (in user's home
426 directory, or as specified by --userinit)
427
430 Dozens of people have made substantial contributions to SBCL and its
431 subsystems, and to the CMU CL system on which it was based, over the
432 years. See the CREDITS file in the distribution for more information.
433
436 Full SBCL documentation is maintained as a Texinfo manual. If is has
437 been installed, the command
438 info sbcl
440 should give you access to the complete manual. Depending on your
442 installation it may also be available in HTML and PDF formats in eg.
443 /usr/local/share/doc/sbcl/
445 See the SBCL homepage
447 <http://www.sbcl.org/>
449 for more information, including directions on how to subscribe to the
451 sbcl-devel and sbcl-help mailing-lists.
4527th Edition $Date: 2007/02/22 20:14:14 $ SBCL(1)