1SBCL(1) General Commands Manual SBCL(1)
2
6 SBCL -- Steel Bank Common Lisp
7
10 SBCL is an implementation of ANSI Common Lisp, featuring a high-perfor‐
11 mance native compiler, native threads on several platforms, a socket
12 interface, a source-level debugger, a statistical profiler, and much
13 more.
14 It is free software, mostly in the public domain, but with some subsys‐
16 tems under BSD-style licenses which allow modification and reuse as
17 long as credit is given. It is provided "as is", with no warranty of
18 any kind.
19 For more information about license issues, see the COPYING file in the
21 distribution. For more information about history, see the CREDITS file
22 in the distribution.
23
26 To run SBCL, type "sbcl". After startup messages a prompt ("*") ap‐
27 pears. Enter a Lisp expression, and SBCL will read and execute it,
28 print any values returned, give you another prompt, and wait for your
29 next input.
30 $ sbcl
33 ...[startup messages elided]...
34 * (+ 1 2 3)
35 6
37 * (exit)
38 Most people like to run SBCL as a subprocess under Emacs. The Emacs
40 "Slime" mode provides many convenient features, like command line edit‐
41 ing, tab completion, and various kinds of coupling between Common Lisp
42 source files and the interactive SBCL subprocess.
43 For information on creating "standalone executables" using SBCL, see
45 SB-EXT:SAVE-LISP-AND-DIE in the User Manual.
46
49 For ordinary interactive use, no command line arguments should be nec‐
50 essary.
51 In order to understand the SBCL command line syntax, it is helpful to
53 understand that the system is composed of two parts: a runtime environ‐
54 ment, and the Common Lisp system it supports. Some command line argu‐
55 ments are processed during the initialization of the runtime, and some
56 during the initialization of the Lisp system -- any remaining command
57 line arguments are passed on to user code.
58 The overall command line syntax is:
60 sbcl [runtime options] --end-runtime-options [toplevel options]
62 --end-toplevel-options [user options]
63 Both --end-runtime-options and --end-toplevel-options are optional, and
65 may be omitted. They are intended for use in situations where any com‐
66 mand line options are under user control (e.g. in batch files): by us‐
67 ing them you can prevent options intended for your program being acci‐
68 dentally processed by SBCL.
69 Supported runtime options are
71 --core <corefilename>
73 Use the specified Lisp core file instead of the default. (See the
74 FILES section for the standard core, or the system documentation for
75 SB-EXT:SAVE-LISP-AND-DIE for information about how to create a cus‐
76 tom core.) Note that if the Lisp core file is a user-created core
77 file, it may run a nonstandard toplevel which does not recognize the
78 standard toplevel options.
79 --dynamic-space-size <megabytes>
81 Size of the dynamic space reserved on startup in megabytes. Default
82 value is platform dependent.
83 --control-stack-size <megabytes>
85 Size of control stack reserved for each thread in megabytes. Default
86 value is 2.
87 --noinform
89 Suppress the printing of any banner or other informational message
90 at startup. (This makes it easier to write Lisp programs which work
91 cleanly in Unix pipelines. See also the "--noprint" and "--dis‐
92 able-debugger" options.)
93 --disable-ldb
95 Disable the low-level debugger. Only effective if SBCL is compiled
96 with LDB.
97 --lose-on-corruption
99 There are some dangerous low level errors (for instance, control
100 stack exhausted, memory fault) that (or whose handlers) can corrupt
101 the image. By default SBCL prints a warning, then tries to continue
102 and handle the error in Lisp, but this will not always work and SBCL
103 may malfunction or even hang. With this option, upon encountering
104 such an error SBCL will invoke ldb (if present and enabled) or else
105 exit.
106 --script <filename>
108 As a runtime option equivalent to --noinform --disable-ldb
109 --lose-on-corruption --end-runtime-options --script <filename>. See
110 the description of --script as a toplevel option below.
111 --merge-core-pages
113 When platform support is present, provide hints to the operating
114 system that identical pages may be shared between processes until
115 they are written to. This can be useful to reduce the memory usage
116 on systems with multiple SBCL processes started from similar but
117 differently-named core files, or from compressed cores. Without
118 platform support, do nothing. By default only compressed cores trig‐
119 ger hinting.
120 --no-merge-core-pages
122 Ensures that no sharing hint is provided to the operating system.
123 --help
125 Print some basic information about SBCL, then exit.
126 --version
128 Print SBCL's version information, then exit.
129 In the future, runtime options may be added to control behavior such as
131 lazy allocation of memory.
132 Runtime options, including any --end-runtime-options option, are
134 stripped out of the command line before the Lisp toplevel logic gets a
135 chance to see it.
136 The toplevel options supported by the standard SBCL core are
138 --sysinit <filename>
140 Load filename instead of the default system-wide initialization
141 file. (See the FILES section.)
142 --no-sysinit
144 Do not load a system-wide initialization file. If this option is
145 given, the --sysinit option is ignored.
146 --userinit <filename>
148 Load filename instead of the default user initialization file. (See
149 the FILES section.)
150 --no-userinit
152 Do not load a user initialization file. If this option is given, the
153 --userinit option is ignored.
154 --eval <command>
156 After executing any initialization file, but before starting the
157 read-eval-print loop on standard input, read and evaluate the com‐
158 mand given. More than one --eval option can be used, and all will be
159 read and executed, in the order they appear on the command line.
160 --load <filename>
162 This is equivalent to --eval '(load "<filename>")'. The special syn‐
163 tax is intended to reduce quoting headaches when invoking SBCL from
164 shell scripts.
165 --noprint
167 When ordinarily the toplevel "read-eval-print loop" would be exe‐
168 cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
169 and don't echo results. Combined with the --noinform runtime option,
170 this makes it easier to write Lisp "scripts" which work cleanly in
171 Unix pipelines.
172 --disable-debugger
174 By default when SBCL encounters an error, it enters the builtin de‐
175 bugger, allowing interactive diagnosis and possible intercession.
176 This option disables the debugger, causing errors to print a back‐
177 trace and exit with status 1 instead -- which is a mode of operation
178 better suited for batch processing. See the User Manual on
179 SB-EXT:DISABLE-DEBUGGER for details.
180 --quit
182 At the end of toplevel option processing, exit SBCL with a success‐
183 ful code of zero. Note that the effect of this option is delayed
184 until after toplevel options following this one.
185 --non-interactive
187 This option disables the read-eval-print loop for both exceptional
188 and non-exceptional reasons. It is short for --disable-debugger and
189 --quit in combination and is useful for batch uses where the special
190 option processing implied by --script is not desired.
191 --script <filename>
193 Implies --no-sysinit --no-userinit --disable-debugger
194 --end-toplevel-options.
195 Causes the system to load the specified file and exit immediately
197 afterwards, instead of entering the read-eval-print loop. If the
198 file begins with a shebang line, it is ignored.
199 Regardless of the order in which toplevel options appear on the command
201 line, the order of actions is:
202 1. Debugger is disabled, if requested.
205 2. Any system initialization file is loaded, unless prohibited.
207 3. Any user initialization file is loaded, unless prohibited.
209 4. --eval and --load options are processed in the order given.
211 Finally, either the read-eval-print loop is entered or the file speci‐
213 fied with --script option is loaded.
214 When running in the read-eval-print loop the system exits on end of
216 file. Similarly, the system exits immediately after processing the file
217 specified with --script.
218 Note that when running SBCL with the --core option, using a core file
220 created by a user call to the SB-EXT:SAVE-LISP-AND-DIE, the toplevel
221 options may be under the control of user code passed as arguments to
222 SB-EXT:SAVE-LISP-AND-DIE. For this purpose, the --end-toplevel-options
223 option itself can be considered a toplevel option, i.e. the user core,
224 at its option, may not support it.
225 In the standard SBCL startup sequence (i.e. with no user core involved)
227 toplevel options and any --end-toplevel-options option are stripped out
228 of the command line argument list before user code gets a chance to see
229 it.
230
233 SBCL is derived from the CMU CL. (The name is intended to acknowledge
234 the connection: steel and banking are the industries where Carnegie and
235 Mellon made the big bucks.)
236 SBCL compiles by default: even functions entered in the read-eval-print
238 loop are compiled to native code, unless the evaluator has been explic‐
239 itly turned on. (Even today, some 40 years after the MacLisp compiler,
240 people will tell you that Lisp is an interpreted language. Ignore
241 them.)
242 SBCL aims for but has not completely achieved compliance with the ANSI
244 standard for Common Lisp. More information about this is available in
245 the BUGS section below.
246 SBCL also includes various non-ANSI extensions, described more fully in
248 the User Manual. Some of these are in the base system and others are
249 "contrib" modules loaded on request using REQUIRE. For example, to
250 load the SB-BSD-SOCKETS module that provides TCP/IP connectivity,
251 * (require 'asdf)
252 * (require 'sb-bsd-sockets)
253 For more information, see the User Manual.
255
257 SBCL inherits from CMU CL the "Python" native code compiler. (Though we
258 often avoid that name in order to avoid confusion with the scripting
259 language also called Python.) This compiler is very clever about under‐
260 standing the type system of Common Lisp and using it to optimize code,
261 and about producing notes to let the user know when the compiler
262 doesn't have enough type information to produce efficient code. It also
263 tries (almost always successfully) to follow the unusual but very use‐
264 ful principle that "declarations are assertions", i.e. type declara‐
265 tions should be checked at runtime unless the user explicitly tells the
266 system that speed is more important than safety.
267 The compiled code uses garbage collection to automatically manage mem‐
269 ory. The garbage collector implementation varies considerably from CPU
270 to CPU. In particular, on some CPUs the GC is nearly exact, while on
271 others it's more conservative, and on some CPUs the GC is generational,
272 while on others simpler stop and copy strategies are used.
273 For more information about the compiler, see the user manual.
275
278 SBCL currently runs on X86 (Linux, FreeBSD, OpenBSD, and NetBSD),
279 X86-64 (Linux), PPC (Linux), SPARC (Linux and Solaris 2.x), and MIPS
280 (Linux). For information on other ongoing and possible ports, see the
281 sbcl-devel mailing list, and/or the web site.
282 SBCL requires on the order of 16Mb RAM to run on X86 systems, though
284 all but the smallest programs would be happier with 32Mb or more.
285
288 This section attempts to list the most serious and long-standing bugs.
289 For more detailed and current information on bugs, see the BUGS file in
290 the distribution.
291 It is possible to get in deep trouble by exhausting heap memory. The
293 SBCL system overcommits memory at startup, so, on typical Unix-alikes
294 like Linux and FreeBSD, this means that if the SBCL system turns out to
295 use more virtual memory than the system has available for it, other
296 processes tend to be killed randomly (!).
297 The compiler's handling of function return values unnecessarily vio‐
299 lates the "declarations are assertions" principle that it otherwise ad‐
300 heres to. Using PROCLAIM or DECLAIM to specify the return type of a
301 function causes the compiler to believe you without checking. Thus com‐
302 piling a file containing
303 (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
304 (DEFUN SOMETIMES (X) (ODDP X))
305 (DEFUN FOO (X) (IF (SOMETIMES X) 'THIS-TIME 'NOT-THIS-TIME))
306 then running (FOO 1) gives NOT-THIS-TIME, because the compiler relied
307 on the truth of the DECLAIM without checking it.
308 Some things are implemented very inefficiently.
310 -- Multidimensional arrays are inefficient, especially multidimensional
312 arrays of floating point numbers.
313 -- SBCL, like most (maybe all?) implementations of Common Lisp on stock
315 hardware, has trouble passing floating point numbers around effi‐
316 ciently, because a floating point number, plus a few extra bits to
317 identify its type, is larger than a machine word. (Thus, they get
318 "boxed" in heap-allocated storage, causing GC overhead.) Within a
319 single compilation unit, or when doing built-in operations like SQRT
320 and AREF, or some special operations like structure slot accesses,
321 this is avoidable: see the user manual for some efficiency hints.
322 But for general function calls across the boundaries of compilation
323 units, passing the result of a floating point calculation as a func‐
324 tion argument (or returning a floating point result as a function
325 value) is a fundamentally slow operation.
326
328 To report a bug, please send mail to the mailing lists sbcl-help or
329 sbcl-devel. You can find the complete mailing list addresses on the web
330 pages at <http://sbcl.sourceforge.net/>; note that as a spam reduction
331 measure you must subscribe to the lists before you can post. (You may
332 also find fancy SourceForge bug-tracking machinery there, but don't be
333 fooled. As of 2002-07-25 anyway, we don't actively monitor that machin‐
334 ery, and it exists only because we haven't been able to figure out how
335 to turn it off.)
336 As with any software bug report, it's most helpful if you can provide
338 enough information to reproduce the symptoms reliably, and if you say
339 clearly what the symptoms are. For example, "There seems to be some‐
340 thing wrong with TAN of very small negative arguments. When I execute
341 (TAN LEAST-NEGATIVE-SINGLE-FLOAT) interactively on sbcl-1.2.3 on my
342 Linux 4.5 X86 box, I get an UNBOUND-VARIABLE error."
343
346 SBCL can be built from scratch using a plain vanilla ANSI Common Lisp
347 system and a C compiler, and all of its properties are specified by the
348 version of the source code that it was created from. This clean boot‐
349 strappability was the immediate motivation for forking off of the CMU
350 CL development tree. A variety of implementation differences are moti‐
351 vated by this design goal.
352 Maintenance work in SBCL since the fork has diverged somewhat from the
354 maintenance work in CMU CL. Many but not all bug fixes and improvements
355 have been shared between the two projects, and sometimes the two
356 projects disagree about what would be an improvement.
357 Most extensions supported by CMU CL have been unbundled from SBCL, in‐
359 cluding Motif support, the Hemlock editor, search paths, the WIRE pro‐
360 tocol, various user-level macros and functions (e.g. LETF, ITERATE,
361 MEMQ, REQUIRED-ARGUMENT), and many others.
362 (Why doesn't SBCL support more extensions natively? Why drop all those
364 nice extensions from CMU CL when the code already exists? This is a
365 frequently asked question on the mailing list. There are two principal
366 reasons. First, it's a design philosophy issue: arguably SBCL has done
367 its job by supplying a stable FFI, and the right design decision is to
368 move functionality derived from that, like socket support, into sepa‐
369 rate libraries. Some of these are distributed with SBCL as "contrib"
370 modules, others are distributed as separate software packages by sepa‐
371 rate maintainers. Second, it's a practical decision - focusing on a
372 smaller number of things will, we hope, let us do a better job on
373 them.)
374
377 Various information about SBCL is available at <http://www.sbcl.org/>.
378 The mailing lists there are the recommended place to look for support.
379
382 Dozens of people have made substantial contributions to SBCL and its
383 subsystems, and to the CMU CL system on which it was based, over the
384 years. See the CREDITS file in the distribution for more information.
385
388 SBCL_HOME This variable controls where files like "sbclrc",
389 "sbcl.core", and the add-on "contrib" systems are searched
390 for. If it is not set, then sbcl looks in ../lib/sbcl/ rela‐
391 tive to the location of the executable, or in the current di‐
392 rectory. If your executable is in the default location
393 /usr/local/bin/ then it will look in /usr/local/lib/sbcl/.
394
397 sbcl executable program containing some low-level runtime support and
398 a loader, used to read sbcl.core
399 sbcl.core
401 dumped memory image containing most of SBCL, to be loaded by the
402 `sbcl' executable. Looked for in $SBCL_HOME, unless overridden
403 by the --core option.
404 sbclrc optional system-wide startup script, looked for in $SBCL_HOME
406 then /etc, unless overridden by the --sysinit command line op‐
407 tion.
408 .sbclrc
410 optional per-user customizable startup script (in user's home
411 directory, or as specified by --userinit)
412
415 Full SBCL documentation is maintained as a Texinfo manual. If it has
416 been installed, the command
417 info sbcl
419 should give you access to the complete manual. Depending on your in‐
421 stallation it may also be available in HTML and PDF formats in e.g.
422 /usr/local/share/doc/sbcl/
424 See the SBCL homepage
426 <http://www.sbcl.org/>
428 for more information, including directions on how to subscribe to the
430 sbcl-devel and sbcl-help mailing-lists.
4317th Edition $Date$ SBCL(1)