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 an implementation of ANSI Common Lisp, featuring a
  24 high-performance native compiler, native threads on several platforms,
  25 a socket interface, a source-level debugger, a statistical profiler,
  26 and much more.
  27
  28 It is free software, mostly in the public domain, but with some
  29 subsystems under BSD-style licenses which allow modification and reuse
  30 as long as credit is given. It is provided "as is", with no warranty
  31 of any kind.
  32
  33 For more information about license issues, see the COPYING file in
  34 the distribution. For more information about history, see the
  35 CREDITS file in the distribution.
  36
  37 .SH RUNNING SBCL
  38
  39 To run SBCL, type "sbcl". After startup messages a prompt
  40 ("\f(CR*\fR") appears. Enter a Lisp expression, and SBCL will read and
  41 execute it, print any values returned, give you another prompt, and
  42 wait for your next input.
  43
  44 \f(C
  45   $ sbcl
  46   ...[startup messages elided]...
  47   * (+ 1 2 3)
  48
  49   6
  50   * (quit)
  51 \fR
  52
  53 Most people like to run SBCL as a subprocess under Emacs. The Emacs
  54 "Slime" mode provides many convenient features, like command line
  55 editing, tab completion, and various kinds of coupling between Common
  56 Lisp source files and the interactive SBCL subprocess.
  57
  58 For information on creating "standalone executables" using SBCL, see
  59 \f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR in the User Manual.
  60
  61 .SH COMMAND LINE SYNTAX
  62
  63 For ordinary interactive use, no command line arguments should be
  64 necessary.
  65
  66 In order to understand the SBCL command line syntax, it is helpful to
  67 understand that the system is composed of two parts: a runtime
  68 environment, and the Common Lisp system it supports. Some command line
  69 arguments are processed during the initialization of the runtime, and
  70 some during the initialization of the Lisp system -- any remaining
  71 command line arguments are passed on to user code.
  72
  73 The overall command line syntax is:
  74 .TP 3
  75 .B sbcl [runtime options] \-\-end\-runtime\-options [toplevel options] \-\-end\-toplevel\-options [user options]
  76 .PP
  77
  78 Both \-\-end\-runtime\-options and \-\-end\-toplevel\-options are
  79 optional, and may be omitted. They are intended for use in situations
  80 where any command line options are under user control (eg. in batch
  81 files): by using them you can prevent options intended for your
  82 program being accidentally processed by SBCL.
  83
  84 Supported runtime options are
  85 .TP 3
  86 .B \-\-core <corefilename>
  87 Use the specified Lisp core file instead of the default. (See the FILES
  88 section for the standard core, or the system documentation for
  89 \f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR for information about how to create a
  90 custom core.) Note that if the Lisp core file is a user-created core
  91 file, it may run a nonstandard toplevel which does not recognize the
  92 standard toplevel options.
  93 .TP 3
  94 .B \-\-dynamic-space-size <megabytes>
  95 Size of the dynamic space reserved on startup in megabytes. Default value
  96 is platform dependent.
  97 .TP 3
  98 .B \-\-control-stack-size <megabytes>
  99 Size of control stack reserved for each thread in megabytes. Default value
 100 is 2.
 101 .TP 3
 102 .B \-\-noinform
 103 Suppress the printing of any banner or other informational message at
 104 startup. (This makes it easier to write Lisp programs which work
 105 cleanly in Unix pipelines. See also the "\-\-noprint" and
 106 "\-\-disable\-debugger" options.)
 107 .TP 3
 108 .B \-\-disable\-ldb
 109 Disable the low-level debugger. Only effective if SBCL is compiled with LDB.
 110 .TP 3
 111 .B \-\-lose\-on\-corruption
 112 There are some dangerous low level errors (for instance, control stack
 113 exhausted, memory fault) that (or whose handlers) can corrupt the
 114 image. By default SBCL prints a warning, then tries to continue and
 115 handle the error in Lisp, but this will not always work and SBCL may
 116 malfunction or even hang. With this option, upon encountering such an
 117 error SBCL will invoke ldb (if present and enabled) or else exit.
 118 .TP 3
 119 .B \-\-script <filename>
 120 As a runtime option equivalent to \-\-noinform \-\-disable\-ldb
 121 \-\-lose\-on\-corruption \-\-end\-toplevel\-options \-\-script
 122 <filename>. See the description of \-\-script as a toplevel option
 123 below.
 124 .TP 3
 125 .B \-\-help
 126 Print some basic information about SBCL, then exit.
 127 .TP 3
 128 .B \-\-version
 129 Print SBCL's version information, then exit.
 130 .PP
 131
 132 In the future, runtime options may be added to control behavior such
 133 as lazy allocation of memory.
 134
 135 Runtime options, including any \-\-end\-runtime\-options option,
 136 are stripped out of the command line before the
 137 Lisp toplevel logic gets a chance to see it.
 138
 139 The toplevel options supported by the standard SBCL core are
 140 .TP 3
 141 .B \-\-sysinit <filename>
 142 Load filename instead of the default system-wide initialization file.
 143 (See the FILES section.)
 144 .TP 3
 145 .B \-\-no\-sysinit
 146 Do not load a system-wide initialization file. If this option is
 147 given, the \-\-sysinit option is ignored.
 148 .TP 3
 149 .B \-\-userinit <filename>
 150 Load filename instead of the default user initialization file. (See
 151 the FILES section.)
 152 .TP 3
 153 .B \-\-no\-userinit
 154 Do not load a user initialization file. If this option is
 155 given, the \-\-userinit option is ignored.
 156 .TP 3
 157 .B \-\-eval <command>
 158 After executing any initialization file, but before starting the
 159 read-eval-print loop on standard input, read and evaluate the command
 160 given. More than one \-\-eval option can be used, and all will be read
 161 and executed, in the order they appear on the command line.
 162 .TP 3
 163 .B \-\-load <filename>
 164 This is equivalent to \-\-eval \(aq(load "<filename>")\(aq. The special
 165 syntax is intended to reduce quoting headaches when invoking SBCL
 166 from shell scripts.
 167 .TP 3
 168 .B \-\-noprint
 169 When ordinarily the toplevel "read-eval-print loop" would be executed,
 170 execute a "read-eval loop" instead, \fIi.e.\fR don't print a prompt and
 171 don't echo results. Combined with the \-\-noinform runtime option, this
 172 makes it easier to write Lisp "scripts" which work cleanly in Unix
 173 pipelines.
 174 .TP 3
 175 .B \-\-disable\-debugger
 176 By default when SBCL encounters an error, it enters the builtin
 177 debugger, allowing interactive diagnosis and possible intercession.
 178 This option disables the debugger, causing errors to print a backtrace
 179 and exit with status 1 instead -- which is a mode of operation better suited
 180 for batch processing. See the User Manual on \f(CRSB\-EXT:DISABLE\-DEBUGGER\fR for details.
 181 .TP 3
 182 .B \-\-script <filename>
 183 Implies \-\-no-sysinit \-\-no-userinit \-\-disable-debugger
 184 \-\-end\-toplevel\-options.
 185
 186 Causes the system to load the specified file and exit immediately
 187 afterwards, instead of entering the readl-eval-print loop. If the file
 188 begins with a shebang line, it is ignored.
 189 .PP
 190
 191 Regardless of the order in which toplevel options appear on the command
 192 line, the order of actions is:
 193
 194 .nr step 1 1
 195 .IP \n[step]. 3
 196 Debugger is disabled, if requested.
 197 .IP \n+[step].
 198 Any system initialization file is loaded, unless prohibited.
 199 .IP \n+[step].
 200 Any user initialization file is loaded, unless prohibited.
 201 .IP \n+[step].
 202 \-\-eval and \-\-load options are processed in the order given.
 203 .PP
 204
 205 Finally, either the read-eval-print loop is entered or the file
 206 specified with \-\-script option is loaded.
 207
 208 When running in the read-eval-print loop the system exits on end of
 209 file. Similarly, the system exits immediately after processing the
 210 file specified with \-\-script.
 211
 212 Note that when running SBCL with the \-\-core option, using a core
 213 file created by a user call to the
 214 \f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR, the toplevel options may be
 215 under the control of user code passed as arguments to
 216 \f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR. For this purpose, the
 217 \-\-end\-toplevel\-options option itself can be considered a toplevel
 218 option, \fIi.e.\fR the user core, at its option, may not support it.
 219
 220 In the standard SBCL startup sequence (\fIi.e.\fR with no user core
 221 involved) toplevel options and any \-\-end\-toplevel\-options option are
 222 stripped out of the command line argument list before user code gets a
 223 chance to see it.
 224
 225 .SH OVERVIEW
 226
 227 SBCL is derived from the CMU CL. (The name is intended to acknowledge
 228 the connection: steel and banking are the industries where Carnegie
 229 and Mellon made the big bucks.)
 230
 231 SBCL compiles by default: even functions entered in the
 232 read-eval-print loop are compiled to native code, unless the evaluator
 233 has been explicitly turned on. (Even today, some 30 years after the
 234 MacLisp compiler, people will tell you that Lisp is an interpreted
 235 language. Ignore them.)
 236
 237 SBCL aims for but has not completely achieved compliance with the ANSI
 238 standard for Common Lisp. More information about this is available in
 239 the BUGS section below.
 240
 241 SBCL also includes various non-ANSI extensions, described more fully
 242 in the User Manual.  Some of these are in the base system and others
 243 are "contrib" modules loaded on request using \f(CRREQUIRE\fR.  For
 244 example, to load the \f(CRSB\-BSD\-SOCKETS\fR module that provides
 245 TCP/IP connectivity,
 246 \f(CR
 247    * (require \(aqasdf)
 248    * (require \(aqsb\-bsd\-sockets)
 249 \fR
 250
 251 For more information, see the User Manual.
 252 .PP
 253
 254 .SH THE COMPILER
 255
 256 SBCL inherits from CMU CL the "Python" native code compiler. (Though
 257 we often avoid that name in order to avoid confusion with the
 258 scripting language also called Python.) This compiler is very clever
 259 about understanding the type system of Common Lisp and using it to
 260 optimize code, and about producing notes to let the user know when the
 261 compiler doesn't have enough type information to produce efficient
 262 code. It also tries (almost always successfully) to follow the unusual
 263 but very useful principle that "declarations are assertions", \fIi.e.\fR
 264 type declarations should be checked at runtime unless the user
 265 explicitly tells the system that speed is more important than safety.
 266
 267 The compiled code uses garbage collection to automatically manage
 268 memory. The garbage collector implementation varies considerably from
 269 CPU to CPU. In particular, on some CPUs the GC is nearly exact, while
 270 on others it's more conservative, and on some CPUs the GC is
 271 generational, while on others simpler stop and copy strategies are
 272 used.
 273
 274 For more information about the compiler, see the user manual.
 275
 276 .SH SYSTEM REQUIREMENTS
 277
 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 .SH KNOWN BUGS
 288
 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
 291 in 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
 296 to 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
 300 violates the "declarations are assertions" principle that it otherwise
 301 adheres to. Using \f(CRPROCLAIM\fR or \f(CRDECLAIM\fR to specify the
 302 return type of a function causes the compiler to believe you without
 303 checking. Thus compiling a file containing
 304 \f(CR
 305   (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
 306   (DEFUN SOMETIMES (X) (ODDP X))
 307   (DEFUN FOO (X) (IF (SOMETIMES X) \(aqTHIS\-TIME \(aqNOT\-THIS\-TIME))\fR
 308 .br
 309 then running \f(CR(FOO 1)\fR gives \f(CRNOT\-THIS\-TIME\fR, because
 310 the compiler relied on the truth of the \f(CRDECLAIM\fR without checking it.
 311
 312 Some things are implemented very inefficiently.
 313 .TP 3
 314 \--
 315 Multidimensional arrays are inefficient, especially
 316 multidimensional arrays of floating point numbers.
 317 .TP 3
 318 \--
 319 SBCL, like most (maybe all?) implementations of Common Lisp on stock
 320 hardware, has trouble passing floating point numbers around
 321 efficiently, because a floating point number, plus a few extra bits to
 322 identify its type, is larger than a machine word. (Thus, they get
 323 "boxed" in heap-allocated storage, causing GC overhead.) Within a
 324 single compilation unit, or when doing built-in operations like
 325 \f(CRSQRT\fR and \f(CRAREF\fR, or some special operations like
 326 structure slot accesses, this is avoidable: see the user manual for
 327 some efficiency hints. But for general function calls across the
 328 boundaries of compilation units, passing the result of a floating
 329 point calculation as a function argument (or returning a floating
 330 point result as a function value) is a fundamentally slow operation.
 331 .PP
 332
 333 .SH REPORTING BUGS
 334
 335 To report a bug, please send mail to the mailing lists sbcl-help or
 336 sbcl-devel. You can find the complete mailing list addresses on the
 337 web pages at <\f(CRhttp://sbcl.sourceforge.net/\fR>; note that as a
 338 spam reduction measure you must subscribe to the lists before you can
 339 post. (You may also find fancy SourceForge bug-tracking machinery
 340 there, but don't be fooled. As of 2002-07-25 anyway, we don't actively
 341 monitor that machinery, and it exists only because we haven't been
 342 able to figure out how to turn it off.)
 343
 344 As with any software bug report, it's most helpful if you can provide
 345 enough information to reproduce the symptoms reliably, and if you say
 346 clearly what the symptoms are.  For example, "There seems to be
 347 something wrong with TAN of very small negative arguments. When I
 348 execute \f(CR(TAN LEAST\-NEGATIVE\-SINGLE\-FLOAT)\fR interactively on
 349 sbcl-1.2.3 on my Linux 4.5 X86 box, I get an \f(CRUNBOUND\-VARIABLE\fR
 350 error."
 351
 352 .SH DIFFERENCES FROM CMU CL
 353
 354 SBCL can be built from scratch using a plain vanilla ANSI Common Lisp
 355 system and a C compiler, and all of its properties are specified by
 356 the version of the source code that it was created from. This clean
 357 bootstrappability was the immediate motivation for forking off of the
 358 CMU CL development tree. A variety of implementation differences are
 359 motivated by this design goal.
 360
 361 Maintenance work in SBCL since the fork has diverged somewhat from the
 362 maintenance work in CMU CL. Many but not all bug fixes and
 363 improvements have been shared between the two projects, and sometimes
 364 the two projects disagree about what would be an improvement.
 365
 366 Most extensions supported by CMU CL have been unbundled from SBCL,
 367 including Motif support, the Hemlock editor, search paths, the WIRE
 368 protocol, various user-level macros and functions (\fIe.g.\fR
 369 \f(CRLETF\fR, \f(CRITERATE\fR, \f(CRMEMQ\fR, \f(CRREQUIRED\-ARGUMENT\fR),
 370 and many others.
 371
 372 (Why doesn't SBCL support more extensions natively? Why drop all those
 373 nice extensions from CMU CL when the code already exists? This is a
 374 frequently asked question on the mailing list. There are two principal
 375 reasons. First, it's a design philosophy issue: arguably SBCL has done
 376 its job by supplying a stable FFI, and the right design decision is to
 377 move functionality derived from that, like socket support, into
 378 separate libraries. Some of these are distributed with SBCL as
 379 "contrib" modules, others are distributed as separate software
 380 packages by separate maintainers. Second, it's a practical decision -
 381 focusing on a smaller number of things will, we hope, let us do a
 382 better job on them.)
 383
 384 .SH SUPPORT
 385
 386 Various information about SBCL is available at
 387 <\f(CRhttp://www.sbcl.org/\fR>. The mailing lists there are the recommended
 388 place to look for support.
 389
 390 .SH AUTHORS
 391
 392 Dozens of people have made substantial contributions to SBCL and its
 393 subsystems, and to the CMU CL system on which it was based, over the
 394 years. See the CREDITS file in the distribution for more information.
 395
 396 .SH ENVIRONMENT
 397
 398 .TP 10n
 399 .BR SBCL_HOME
 400 This variable controls where files like "sbclrc", "sbcl.core", and the
 401 add-on "contrib" systems are searched for.  If it is not set, then
 402 sbcl sets it from a compile-time default location which is usually
 403 /usr/local/lib/sbcl/ but may have been changed \fIe.g.\fR by a third-party
 404 packager.
 405
 406 .SH FILES
 407
 408 .TP
 409 .I sbcl
 410 executable program containing some low-level runtime support and
 411 a loader, used to read sbcl.core
 412 .TP
 413 .I sbcl.core
 414 dumped memory image containing most of SBCL, to be loaded by
 415 the `sbcl' executable.  Looked for in $\f(CRSBCL_HOME\fR,
 416 unless overridden by the \f(CR\-\-core\fR option.
 417 .TP
 418 .I sbclrc
 419 optional system-wide startup script, looked for in $\f(CRSBCL_HOME\fR/sbclrc
 420 then /etc/sbclrc, unless overridden by the \f(CR\-\-sysinit\fR command line
 421 option.
 422 .TP
 423 .I .sbclrc
 424 optional per-user customizable startup script (in user's home
 425 directory, or as specified by  \f(CR\-\-userinit\fR)
 426
 427 .SH SEE ALSO
 428
 429 Full SBCL documentation is maintained as a Texinfo manual. If is has
 430 been installed, the command
 431 .IP
 432 .B info sbcl
 433 .PP
 434 should give you access to the complete manual. Depending on your
 435 installation it may also be available in HTML and PDF formats in eg.
 436 .IP
 437 .B /usr/local/share/doc/sbcl/
 438 .PP
 439 See the SBCL homepage
 440 .IP
 441 .B <\f(CRhttp://www.sbcl.org/\fR>
 442 .PP
 443 for more information, including directions on how to subscribe to the
 444 sbcl\-devel and sbcl\-help mailing-lists.