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