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(CR
  45   $ sbcl
  46   ...[startup messages elided]...
  47   * (+ 1 2 3)
  48
  49   6
  50   * (exit)
  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 (e.g. 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\-runtime\-options \-\-script
 122 <filename>. See the description of \-\-script as a toplevel option
 123 below.
 124 .TP 3
 125 .B \-\-merge\-core\-pages
 126 When platform support is present, provide hints to the operating
 127 system that identical pages may be shared between processes until they
 128 are written to. This can be useful to reduce the memory usage on
 129 systems with multiple SBCL processes started from similar but
 130 differently\-named core files, or from compressed cores. Without
 131 platform support, do nothing.
 132 .TP 3
 133 .B \-\-no-merge\-core\-pages
 134 Ensures that no sharing hint is provided to the operating system.
 135 .TP 3
 136 .B \-\-default\-merge\-core\-pages
 137 Reverts the sharing hint policy to the default: only compressed cores
 138 trigger hinting. Uncompressed cores are mapped directly from the core
 139 file, which is usually enough to ensure sharing.
 140 .TP 3
 141 .B \-\-help
 142 Print some basic information about SBCL, then exit.
 143 .TP 3
 144 .B \-\-version
 145 Print SBCL's version information, then exit.
 146 .PP
 147
 148 In the future, runtime options may be added to control behavior such
 149 as lazy allocation of memory.
 150
 151 Runtime options, including any \-\-end\-runtime\-options option,
 152 are stripped out of the command line before the
 153 Lisp toplevel logic gets a chance to see it.
 154
 155 The toplevel options supported by the standard SBCL core are
 156 .TP 3
 157 .B \-\-sysinit <filename>
 158 Load filename instead of the default system-wide initialization file.
 159 (See the FILES section.)
 160 .TP 3
 161 .B \-\-no\-sysinit
 162 Do not load a system-wide initialization file. If this option is
 163 given, the \-\-sysinit option is ignored.
 164 .TP 3
 165 .B \-\-userinit <filename>
 166 Load filename instead of the default user initialization file. (See
 167 the FILES section.)
 168 .TP 3
 169 .B \-\-no\-userinit
 170 Do not load a user initialization file. If this option is
 171 given, the \-\-userinit option is ignored.
 172 .TP 3
 173 .B \-\-eval <command>
 174 After executing any initialization file, but before starting the
 175 read-eval-print loop on standard input, read and evaluate the command
 176 given. More than one \-\-eval option can be used, and all will be read
 177 and executed, in the order they appear on the command line.
 178 .TP 3
 179 .B \-\-load <filename>
 180 This is equivalent to \-\-eval \(aq(load "<filename>")\(aq. The special
 181 syntax is intended to reduce quoting headaches when invoking SBCL
 182 from shell scripts.
 183 .TP 3
 184 .B \-\-noprint
 185 When ordinarily the toplevel "read-eval-print loop" would be executed,
 186 execute a "read-eval loop" instead, \fIi.e.\fR don't print a prompt and
 187 don't echo results. Combined with the \-\-noinform runtime option, this
 188 makes it easier to write Lisp "scripts" which work cleanly in Unix
 189 pipelines.
 190 .TP 3
 191 .B \-\-disable\-debugger
 192 By default when SBCL encounters an error, it enters the builtin
 193 debugger, allowing interactive diagnosis and possible intercession.
 194 This option disables the debugger, causing errors to print a backtrace
 195 and exit with status 1 instead -- which is a mode of operation better suited
 196 for batch processing. See the User Manual on \f(CRSB\-EXT:DISABLE\-DEBUGGER\fR for details.
 197 .TP 3
 198 .B \-\-quit
 199 At the end of toplevel option processing, exit SBCL with a successful
 200 code of zero.  Note that the effect of this option is delayed until after
 201 toplevel options following this one.
 202 .TP 3
 203 .B \-\-non-interactive
 204 This option disables the read-eval-print loop for both exceptional and
 205 non-exceptional reasons.  It is short for --disable-debugger and --quit in
 206 combination and is useful for batch uses where the special option processing
 207 implied by --script is not desired.
 208 .TP 3
 209 .B \-\-script <filename>
 210 Implies \-\-no-sysinit \-\-no-userinit \-\-disable-debugger
 211 \-\-end\-toplevel\-options.
 212
 213 Causes the system to load the specified file and exit immediately
 214 afterwards, instead of entering the read-eval-print loop. If the file
 215 begins with a shebang line, it is ignored.
 216 .PP
 217
 218 Regardless of the order in which toplevel options appear on the command
 219 line, the order of actions is:
 220
 221 .nr step 1 1
 222 .IP \n[step]. 3
 223 Debugger is disabled, if requested.
 224 .IP \n+[step].
 225 Any system initialization file is loaded, unless prohibited.
 226 .IP \n+[step].
 227 Any user initialization file is loaded, unless prohibited.
 228 .IP \n+[step].
 229 \-\-eval and \-\-load options are processed in the order given.
 230 .PP
 231
 232 Finally, either the read-eval-print loop is entered or the file
 233 specified with \-\-script option is loaded.
 234
 235 When running in the read-eval-print loop the system exits on end of
 236 file. Similarly, the system exits immediately after processing the
 237 file specified with \-\-script.
 238
 239 Note that when running SBCL with the \-\-core option, using a core
 240 file created by a user call to the
 241 \f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR, the toplevel options may be
 242 under the control of user code passed as arguments to
 243 \f(CRSB\-EXT:SAVE\-LISP\-AND\-DIE\fR. For this purpose, the
 244 \-\-end\-toplevel\-options option itself can be considered a toplevel
 245 option, \fIi.e.\fR the user core, at its option, may not support it.
 246
 247 In the standard SBCL startup sequence (\fIi.e.\fR with no user core
 248 involved) toplevel options and any \-\-end\-toplevel\-options option are
 249 stripped out of the command line argument list before user code gets a
 250 chance to see it.
 251
 252 .SH OVERVIEW
 253
 254 SBCL is derived from the CMU CL. (The name is intended to acknowledge
 255 the connection: steel and banking are the industries where Carnegie
 256 and Mellon made the big bucks.)
 257
 258 SBCL compiles by default: even functions entered in the
 259 read-eval-print loop are compiled to native code, unless the evaluator
 260 has been explicitly turned on. (Even today, some 30 years after the
 261 MacLisp compiler, people will tell you that Lisp is an interpreted
 262 language. Ignore them.)
 263
 264 SBCL aims for but has not completely achieved compliance with the ANSI
 265 standard for Common Lisp. More information about this is available in
 266 the BUGS section below.
 267
 268 SBCL also includes various non-ANSI extensions, described more fully
 269 in the User Manual.  Some of these are in the base system and others
 270 are "contrib" modules loaded on request using \f(CRREQUIRE\fR.  For
 271 example, to load the \f(CRSB\-BSD\-SOCKETS\fR module that provides
 272 TCP/IP connectivity,
 273 \f(CR
 274    * (require \(aqasdf)
 275    * (require \(aqsb\-bsd\-sockets)
 276 \fR
 277
 278 For more information, see the User Manual.
 279 .PP
 280
 281 .SH THE COMPILER
 282
 283 SBCL inherits from CMU CL the "Python" native code compiler. (Though
 284 we often avoid that name in order to avoid confusion with the
 285 scripting language also called Python.) This compiler is very clever
 286 about understanding the type system of Common Lisp and using it to
 287 optimize code, and about producing notes to let the user know when the
 288 compiler doesn't have enough type information to produce efficient
 289 code. It also tries (almost always successfully) to follow the unusual
 290 but very useful principle that "declarations are assertions", \fIi.e.\fR
 291 type declarations should be checked at runtime unless the user
 292 explicitly tells the system that speed is more important than safety.
 293
 294 The compiled code uses garbage collection to automatically manage
 295 memory. The garbage collector implementation varies considerably from
 296 CPU to CPU. In particular, on some CPUs the GC is nearly exact, while
 297 on others it's more conservative, and on some CPUs the GC is
 298 generational, while on others simpler stop and copy strategies are
 299 used.
 300
 301 For more information about the compiler, see the user manual.
 302
 303 .SH SYSTEM REQUIREMENTS
 304
 305 SBCL currently runs on X86 (Linux, FreeBSD, OpenBSD, and NetBSD),
 306 X86-64 (Linux), Alpha (Linux, Tru64), PPC (Linux, Darwin/MacOS X),
 307 SPARC (Linux and Solaris 2.x), and MIPS (Linux). For information on
 308 other ongoing and possible ports, see the sbcl\-devel mailing list,
 309 and/or the web site.
 310
 311 SBCL requires on the order of 16Mb RAM to run on X86 systems, though
 312 all but the smallest programs would be happier with 32Mb or more.
 313
 314 .SH KNOWN BUGS
 315
 316 This section attempts to list the most serious and long-standing bugs.
 317 For more detailed and current information on bugs, see the BUGS file
 318 in the distribution.
 319
 320 It is possible to get in deep trouble by exhausting heap memory.  The
 321 SBCL system overcommits memory at startup, so, on typical Unix-alikes
 322 like Linux and FreeBSD, this means that if the SBCL system turns out
 323 to use more virtual memory than the system has available for it, other
 324 processes tend to be killed randomly (!).
 325
 326 The compiler's handling of function return values unnecessarily
 327 violates the "declarations are assertions" principle that it otherwise
 328 adheres to. Using \f(CRPROCLAIM\fR or \f(CRDECLAIM\fR to specify the
 329 return type of a function causes the compiler to believe you without
 330 checking. Thus compiling a file containing
 331 \f(CR
 332   (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
 333   (DEFUN SOMETIMES (X) (ODDP X))
 334   (DEFUN FOO (X) (IF (SOMETIMES X) \(aqTHIS\-TIME \(aqNOT\-THIS\-TIME))\fR
 335 .br
 336 then running \f(CR(FOO 1)\fR gives \f(CRNOT\-THIS\-TIME\fR, because
 337 the compiler relied on the truth of the \f(CRDECLAIM\fR without checking it.
 338
 339 Some things are implemented very inefficiently.
 340 .TP 3
 341 \--
 342 Multidimensional arrays are inefficient, especially
 343 multidimensional arrays of floating point numbers.
 344 .TP 3
 345 \--
 346 SBCL, like most (maybe all?) implementations of Common Lisp on stock
 347 hardware, has trouble passing floating point numbers around
 348 efficiently, because a floating point number, plus a few extra bits to
 349 identify its type, is larger than a machine word. (Thus, they get
 350 "boxed" in heap-allocated storage, causing GC overhead.) Within a
 351 single compilation unit, or when doing built-in operations like
 352 \f(CRSQRT\fR and \f(CRAREF\fR, or some special operations like
 353 structure slot accesses, this is avoidable: see the user manual for
 354 some efficiency hints. But for general function calls across the
 355 boundaries of compilation units, passing the result of a floating
 356 point calculation as a function argument (or returning a floating
 357 point result as a function value) is a fundamentally slow operation.
 358 .PP
 359
 360 .SH REPORTING BUGS
 361
 362 To report a bug, please send mail to the mailing lists sbcl-help or
 363 sbcl-devel. You can find the complete mailing list addresses on the
 364 web pages at <\f(CRhttp://sbcl.sourceforge.net/\fR>; note that as a
 365 spam reduction measure you must subscribe to the lists before you can
 366 post. (You may also find fancy SourceForge bug-tracking machinery
 367 there, but don't be fooled. As of 2002-07-25 anyway, we don't actively
 368 monitor that machinery, and it exists only because we haven't been
 369 able to figure out how to turn it off.)
 370
 371 As with any software bug report, it's most helpful if you can provide
 372 enough information to reproduce the symptoms reliably, and if you say
 373 clearly what the symptoms are.  For example, "There seems to be
 374 something wrong with TAN of very small negative arguments. When I
 375 execute \f(CR(TAN LEAST\-NEGATIVE\-SINGLE\-FLOAT)\fR interactively on
 376 sbcl-1.2.3 on my Linux 4.5 X86 box, I get an \f(CRUNBOUND\-VARIABLE\fR
 377 error."
 378
 379 .SH DIFFERENCES FROM CMU CL
 380
 381 SBCL can be built from scratch using a plain vanilla ANSI Common Lisp
 382 system and a C compiler, and all of its properties are specified by
 383 the version of the source code that it was created from. This clean
 384 bootstrappability was the immediate motivation for forking off of the
 385 CMU CL development tree. A variety of implementation differences are
 386 motivated by this design goal.
 387
 388 Maintenance work in SBCL since the fork has diverged somewhat from the
 389 maintenance work in CMU CL. Many but not all bug fixes and
 390 improvements have been shared between the two projects, and sometimes
 391 the two projects disagree about what would be an improvement.
 392
 393 Most extensions supported by CMU CL have been unbundled from SBCL,
 394 including Motif support, the Hemlock editor, search paths, the WIRE
 395 protocol, various user-level macros and functions (\fIe.g.\fR
 396 \f(CRLETF\fR, \f(CRITERATE\fR, \f(CRMEMQ\fR, \f(CRREQUIRED\-ARGUMENT\fR),
 397 and many others.
 398
 399 (Why doesn't SBCL support more extensions natively? Why drop all those
 400 nice extensions from CMU CL when the code already exists? This is a
 401 frequently asked question on the mailing list. There are two principal
 402 reasons. First, it's a design philosophy issue: arguably SBCL has done
 403 its job by supplying a stable FFI, and the right design decision is to
 404 move functionality derived from that, like socket support, into
 405 separate libraries. Some of these are distributed with SBCL as
 406 "contrib" modules, others are distributed as separate software
 407 packages by separate maintainers. Second, it's a practical decision -
 408 focusing on a smaller number of things will, we hope, let us do a
 409 better job on them.)
 410
 411 .SH SUPPORT
 412
 413 Various information about SBCL is available at
 414 <\f(CRhttp://www.sbcl.org/\fR>. The mailing lists there are the recommended
 415 place to look for support.
 416
 417 .SH AUTHORS
 418
 419 Dozens of people have made substantial contributions to SBCL and its
 420 subsystems, and to the CMU CL system on which it was based, over the
 421 years. See the CREDITS file in the distribution for more information.
 422
 423 .SH ENVIRONMENT
 424
 425 .TP 10n
 426 .BR SBCL_HOME
 427 This variable controls where files like "sbclrc", "sbcl.core", and the
 428 add-on "contrib" systems are searched for.  If it is not set, then
 429 sbcl sets it from a compile-time default location which is usually
 430 /usr/local/lib/sbcl/ but may have been changed \fIe.g.\fR by a third-party
 431 packager.
 432
 433 .SH FILES
 434
 435 .TP
 436 .I sbcl
 437 executable program containing some low-level runtime support and
 438 a loader, used to read sbcl.core
 439 .TP
 440 .I sbcl.core
 441 dumped memory image containing most of SBCL, to be loaded by
 442 the `sbcl' executable.  Looked for in $\f(CRSBCL_HOME\fR,
 443 unless overridden by the \f(CR\-\-core\fR option.
 444 .TP
 445 .I sbclrc
 446 optional system-wide startup script, looked for in $\f(CRSBCL_HOME\fR/sbclrc
 447 then /etc/sbclrc, unless overridden by the \f(CR\-\-sysinit\fR command line
 448 option.
 449 .TP
 450 .I .sbclrc
 451 optional per-user customizable startup script (in user's home
 452 directory, or as specified by  \f(CR\-\-userinit\fR)
 453
 454 .SH SEE ALSO
 455
 456 Full SBCL documentation is maintained as a Texinfo manual. If is has
 457 been installed, the command
 458 .IP
 459 .B info sbcl
 460 .PP
 461 should give you access to the complete manual. Depending on your
 462 installation it may also be available in HTML and PDF formats in e.g.
 463 .IP
 464 .B /usr/local/share/doc/sbcl/
 465 .PP
 466 See the SBCL homepage
 467 .IP
 468 .B <\f(CRhttp://www.sbcl.org/\fR>
 469 .PP
 470 for more information, including directions on how to subscribe to the
 471 sbcl\-devel and sbcl\-help mailing-lists.