1SBCL(1)                     General Commands Manual                    SBCL(1)
2
3
4

NAME

6       SBCL -- Steel Bank Common Lisp
7
8

DESCRIPTION

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
15       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
20       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
24

RUNNING SBCL

26       To  run  SBCL,  type  "sbcl".  After  startup  messages  a prompt ("*")
27       appears. 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
31
32         $ sbcl
33         ...[startup messages elided]...
34         * (+ 1 2 3)
35
36         6
37         * (exit)
38
39       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
44       For  information  on  creating "standalone executables" using SBCL, see
45       SB-EXT:SAVE-LISP-AND-DIE in the User Manual.
46
47

COMMAND LINE SYNTAX

49       For ordinary interactive use, no command line arguments should be  nec‐
50       essary.
51
52       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
59       The overall command line syntax is:
60
61              sbcl [runtime options] --end-runtime-options [toplevel  options]
62              --end-toplevel-options [user options]
63
64       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
67       using them you can prevent options  intended  for  your  program  being
68       accidentally processed by SBCL.
69
70       Supported runtime options are
71
72       --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
80       --dynamic-space-size <megabytes>
81          Size of the dynamic space reserved on startup in megabytes.  Default
82          value is platform dependent.
83
84       --control-stack-size <megabytes>
85          Size of control stack reserved for each thread in megabytes. Default
86          value is 2.
87
88       --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
94       --disable-ldb
95          Disable  the  low-level debugger. Only effective if SBCL is compiled
96          with LDB.
97
98       --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
107       --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
112       --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
121       --no-merge-core-pages
122          Ensures that no sharing hint is provided to the operating system.
123
124       --help
125          Print some basic information about SBCL, then exit.
126
127       --version
128          Print SBCL's version information, then exit.
129
130       In the future, runtime options may be added to control behavior such as
131       lazy allocation of memory.
132
133       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
137       The toplevel options supported by the standard SBCL core are
138
139       --sysinit <filename>
140          Load  filename  instead  of  the  default system-wide initialization
141          file.  (See the FILES section.)
142
143       --no-sysinit
144          Do not load a system-wide initialization file.  If  this  option  is
145          given, the --sysinit option is ignored.
146
147       --userinit <filename>
148          Load  filename instead of the default user initialization file. (See
149          the FILES section.)
150
151       --no-userinit
152          Do not load a user initialization file. If this option is given, the
153          --userinit option is ignored.
154
155       --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
161       --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
166       --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
173       --disable-debugger
174          By default when SBCL encounters an  error,  it  enters  the  builtin
175          debugger,  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
181       --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
186       --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
192       --script <filename>
193          Implies      --no-sysinit      --no-userinit      --disable-debugger
194          --end-toplevel-options.
195
196          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
200       Regardless of the order in which toplevel options appear on the command
201       line, the order of actions is:
202
203
204       1. Debugger is disabled, if requested.
205
206       2. Any system initialization file is loaded, unless prohibited.
207
208       3. Any user initialization file is loaded, unless prohibited.
209
210       4. --eval and --load options are processed in the order given.
211
212       Finally, either the read-eval-print loop is entered or the file  speci‐
213       fied with --script option is loaded.
214
215       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
219       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
226       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
231

OVERVIEW

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
237       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
243       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
247       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
254       For more information, see the User Manual.
255

THE COMPILER

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
268       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
274       For more information about the compiler, see the user manual.
275
276

SYSTEM REQUIREMENTS

278       SBCL  currently  runs  on  X86  (Linux,  FreeBSD, OpenBSD, and NetBSD),
279       X86-64 (Linux), Alpha (Linux,  Tru64),  PPC  (Linux,  Darwin/MacOS  X),
280       SPARC  (Linux  and  Solaris  2.x), and MIPS (Linux). For information on
281       other ongoing and possible ports,  see  the  sbcl-devel  mailing  list,
282       and/or the web site.
283
284       SBCL  requires  on  the order of 16Mb RAM to run on X86 systems, though
285       all but the smallest programs would be happier with 32Mb or more.
286
287

KNOWN BUGS

289       This section attempts to list the most serious and long-standing  bugs.
290       For more detailed and current information on bugs, see the BUGS file in
291       the distribution.
292
293       It is possible to get in deep trouble by exhausting heap  memory.   The
294       SBCL  system  overcommits memory at startup, so, on typical Unix-alikes
295       like Linux and FreeBSD, this means that if the SBCL system turns out to
296       use  more  virtual  memory  than the system has available for it, other
297       processes tend to be killed randomly (!).
298
299       The compiler's handling of function return  values  unnecessarily  vio‐
300       lates  the  "declarations  are  assertions" principle that it otherwise
301       adheres to. Using PROCLAIM or DECLAIM to specify the return type  of  a
302       function causes the compiler to believe you without checking. Thus com‐
303       piling a file containing
304         (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
305         (DEFUN SOMETIMES (X) (ODDP X))
306         (DEFUN FOO (X) (IF (SOMETIMES X) 'THIS-TIME 'NOT-THIS-TIME))
307       then running (FOO 1) gives NOT-THIS-TIME, because the  compiler  relied
308       on the truth of the DECLAIM without checking it.
309
310       Some things are implemented very inefficiently.
311
312       -- Multidimensional arrays are inefficient, especially multidimensional
313          arrays of floating point numbers.
314
315       -- SBCL, like most (maybe all?) implementations of Common Lisp on stock
316          hardware,  has  trouble  passing floating point numbers around effi‐
317          ciently, because a floating point number, plus a few extra  bits  to
318          identify  its  type,  is larger than a machine word. (Thus, they get
319          "boxed" in heap-allocated storage, causing GC  overhead.)  Within  a
320          single compilation unit, or when doing built-in operations like SQRT
321          and AREF, or some special operations like structure  slot  accesses,
322          this  is  avoidable:  see the user manual for some efficiency hints.
323          But for general function calls across the boundaries of  compilation
324          units, passing the result of a floating point calculation as a func‐
325          tion argument (or returning a floating point result  as  a  function
326          value) is a fundamentally slow operation.
327

REPORTING BUGS

329       To  report  a  bug,  please send mail to the mailing lists sbcl-help or
330       sbcl-devel. You can find the complete mailing list addresses on the web
331       pages  at <http://sbcl.sourceforge.net/>; note that as a spam reduction
332       measure you must subscribe to the lists before you can post.  (You  may
333       also  find fancy SourceForge bug-tracking machinery there, but don't be
334       fooled. As of 2002-07-25 anyway, we don't actively monitor that machin‐
335       ery,  and it exists only because we haven't been able to figure out how
336       to turn it off.)
337
338       As with any software bug report, it's most helpful if you  can  provide
339       enough  information  to reproduce the symptoms reliably, and if you say
340       clearly what the symptoms are.  For example, "There seems to  be  some‐
341       thing  wrong  with TAN of very small negative arguments. When I execute
342       (TAN LEAST-NEGATIVE-SINGLE-FLOAT) interactively  on  sbcl-1.2.3  on  my
343       Linux 4.5 X86 box, I get an UNBOUND-VARIABLE error."
344
345

DIFFERENCES FROM CMU CL

347       SBCL  can  be built from scratch using a plain vanilla ANSI Common Lisp
348       system and a C compiler, and all of its properties are specified by the
349       version  of  the source code that it was created from. This clean boot‐
350       strappability was the immediate motivation for forking off of  the  CMU
351       CL  development tree. A variety of implementation differences are moti‐
352       vated by this design goal.
353
354       Maintenance work in SBCL since the fork has diverged somewhat from  the
355       maintenance work in CMU CL. Many but not all bug fixes and improvements
356       have been shared between  the  two  projects,  and  sometimes  the  two
357       projects disagree about what would be an improvement.
358
359       Most  extensions  supported  by  CMU  CL have been unbundled from SBCL,
360       including Motif support, the Hemlock editor,  search  paths,  the  WIRE
361       protocol, various user-level macros and functions (e.g.  LETF, ITERATE,
362       MEMQ, REQUIRED-ARGUMENT), and many others.
363
364       (Why doesn't SBCL support more extensions natively? Why drop all  those
365       nice  extensions  from  CMU  CL when the code already exists? This is a
366       frequently asked question on the mailing list. There are two  principal
367       reasons.  First, it's a design philosophy issue: arguably SBCL has done
368       its job by supplying a stable FFI, and the right design decision is  to
369       move  functionality  derived from that, like socket support, into sepa‐
370       rate libraries. Some of these are distributed with  SBCL  as  "contrib"
371       modules,  others are distributed as separate software packages by sepa‐
372       rate maintainers. Second, it's a practical decision  -  focusing  on  a
373       smaller  number  of  things  will,  we  hope, let us do a better job on
374       them.)
375
376

SUPPORT

378       Various information about SBCL is available at  <http://www.sbcl.org/>.
379       The mailing lists there are the recommended place to look for support.
380
381

AUTHORS

383       Dozens  of  people  have made substantial contributions to SBCL and its
384       subsystems, and to the CMU CL system on which it was  based,  over  the
385       years. See the CREDITS file in the distribution for more information.
386
387

ENVIRONMENT

389       SBCL_HOME This   variable   controls   where   files   like   "sbclrc",
390                 "sbcl.core", and the add-on "contrib"  systems  are  searched
391                 for.  If it is not set, then sbcl sets it from a compile-time
392                 default location which is  usually  /usr/local/lib/sbcl/  but
393                 may have been changed e.g. by a third-party packager.
394
395

FILES

397       sbcl   executable program containing some low-level runtime support and
398              a loader, used to read sbcl.core
399
400       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
405       sbclrc optional system-wide startup script, looked  for  in  $SBCL_HOME
406              then  /etc,  unless  overridden  by  the  --sysinit command line
407              option.
408
409       .sbclrc
410              optional per-user customizable startup script  (in  user's  home
411              directory, or as specified by  --userinit)
412
413

SEE ALSO

415       Full  SBCL  documentation  is maintained as a Texinfo manual. If it has
416       been installed, the command
417
418              info sbcl
419
420       should give you access  to  the  complete  manual.  Depending  on  your
421       installation it may also be available in HTML and PDF formats in e.g.
422
423              /usr/local/share/doc/sbcl/
424
425       See the SBCL homepage
426
427              <http://www.sbcl.org/>
428
429       for  more  information, including directions on how to subscribe to the
430       sbcl-devel and sbcl-help mailing-lists.
431
432
433
4347th Edition                         $Date$                             SBCL(1)
Impressum