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