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