Ubuntu Manpage: SBCL -- Steel Bank Common Lisp

NAME

       SBCL -- Steel Bank Common Lisp

DESCRIPTION

       SBCL  is  an  implementation  of  ANSI  Common Lisp, featuring a high-performance native compiler, native
       threads on several platforms, a socket interface, a source-level debugger, a  statistical  profiler,  and
       much more.

       It is free software, mostly in the public domain, but with some subsystems under BSD-style licenses which
       allow  modification and reuse as long as credit is given. It is provided "as is", with no warranty of any
       kind.

       For more information about license issues, see the COPYING file in the distribution. For more information
       about history, see the CREDITS file in the distribution.

RUNNING SBCL

       To run SBCL, type "sbcl". After startup messages a prompt ("*") appears. Enter  a  Lisp  expression,  and
       SBCL will read and execute it, print any values returned, give you another prompt, and wait for your next
       input.

         $ sbcl
         ...[startup messages elided]...
         * (+ 1 2 3)

         6
         * (exit)

       Most people like to run SBCL as a subprocess under Emacs. The Emacs "Slime" mode provides many convenient
       features,  like  command  line editing, tab completion, and various kinds of coupling between Common Lisp
       source files and the interactive SBCL subprocess.

       For information on creating "standalone executables" using SBCL, see SB-EXT:SAVE-LISP-AND-DIE in the User
       Manual.

COMMAND LINE SYNTAX

       For ordinary interactive use, no command line arguments should be necessary.

       In order to understand the SBCL command line syntax, it is helpful  to  understand  that  the  system  is
       composed  of  two parts: a runtime environment, and the Common Lisp system it supports. Some command line
       arguments are processed during the initialization of the runtime, and some during the  initialization  of
       the Lisp system -- any remaining command line arguments are passed on to user code.

       The overall command line syntax is:

       sbcl [runtime options] --end-runtime-options [toplevel options] --end-toplevel-options [user options]

       Both --end-runtime-options and --end-toplevel-options are optional, and may be omitted. They are intended
       for  use  in  situations  where any command line options are under user control (e.g. in batch files): by
       using them you can prevent options intended for your program being accidentally processed by SBCL.

       Supported runtime options are

       --core <corefilename>
          Use the specified Lisp core file instead of the default. (See the FILES section for the standard core,
          or the system documentation for SB-EXT:SAVE-LISP-AND-DIE for information about how to create a  custom
          core.)  Note that if the Lisp core file is a user-created core file, it may run a nonstandard toplevel
          which does not recognize the standard toplevel options.

       --dynamic-space-size <megabytes>
          Size of the dynamic space reserved on startup in megabytes. Default value is platform dependent.

       --control-stack-size <megabytes>
          Size of control stack reserved for each thread in megabytes. Default value is 2.

       --noinform
          Suppress the printing of any banner or other informational message at startup. (This makes  it  easier
          to  write  Lisp  programs  which  work  cleanly  in  Unix  pipelines.  See  also  the  "--noprint" and
          "--disable-debugger" options.)

       --disable-ldb
          Disable the low-level debugger. Only effective if SBCL is compiled with LDB.

       --lose-on-corruption
          There are some dangerous low level errors (for instance, control stack exhausted, memory  fault)  that
          (or  whose  handlers)  can corrupt the image. By default SBCL prints a warning, then tries to continue
          and handle the error in Lisp, but this will not always work and SBCL may  malfunction  or  even  hang.
          With  this  option,  upon  encountering such an error SBCL will invoke ldb (if present and enabled) or
          else exit.

       --script <filename>
          As a runtime option equivalent to --noinform --disable-ldb --lose-on-corruption  --end-runtime-options
          --script <filename>. See the description of --script as a toplevel option below.

       --merge-core-pages
          When  platform  support  is present, provide hints to the operating system that identical pages may be
          shared between processes until they are written to. This can be useful to reduce the memory  usage  on
          systems  with  multiple  SBCL processes started from similar but differently-named core files, or from
          compressed cores. Without platform support, do nothing.

       --no-merge-core-pages
          Ensures that no sharing hint is provided to the operating system.

       --default-merge-core-pages
          Reverts the sharing hint policy to the default: only compressed cores  trigger  hinting.  Uncompressed
          cores are mapped directly from the core file, which is usually enough to ensure sharing.

       --help
          Print some basic information about SBCL, then exit.

       --version
          Print SBCL's version information, then exit.

       In the future, runtime options may be added to control behavior such as lazy allocation of memory.

       Runtime  options, including any --end-runtime-options option, are stripped out of the command line before
       the Lisp toplevel logic gets a chance to see it.

       The toplevel options supported by the standard SBCL core are

       --sysinit <filename>
          Load filename instead of the default system-wide initialization file.  (See the FILES section.)

       --no-sysinit
          Do not load a system-wide initialization file. If this  option  is  given,  the  --sysinit  option  is
          ignored.

       --userinit <filename>
          Load filename instead of the default user initialization file. (See the FILES section.)

       --no-userinit
          Do not load a user initialization file. If this option is given, the --userinit option is ignored.

       --eval <command>
          After  executing  any  initialization  file,  but before starting the read-eval-print loop on standard
          input, read and evaluate the command given. More than one --eval option can be used, and all  will  be
          read and executed, in the order they appear on the command line.

       --load <filename>
          This  is  equivalent to --eval '(load "<filename>")'. The special syntax is intended to reduce quoting
          headaches when invoking SBCL from shell scripts.

       --noprint
          When ordinarily the toplevel "read-eval-print loop" would be  executed,  execute  a  "read-eval  loop"
          instead,  i.e.  don't  print  a  prompt  and  don't echo results. Combined with the --noinform runtime
          option, this makes it easier to write Lisp "scripts" which work cleanly in Unix pipelines.

       --disable-debugger
          By default when SBCL encounters an  error,  it  enters  the  builtin  debugger,  allowing  interactive
          diagnosis  and  possible  intercession.   This option disables the debugger, causing errors to print a
          backtrace and exit with status 1 instead -- which is a mode  of  operation  better  suited  for  batch
          processing. See the User Manual on SB-EXT:DISABLE-DEBUGGER for details.

       --quit
          At  the  end  of  toplevel option processing, exit SBCL with a successful code of zero.  Note that the
          effect of this option is delayed until after toplevel options following this one.

       --non-interactive
          This option disables the read-eval-print loop for both exceptional and non-exceptional reasons.  It is
          short for --disable-debugger and --quit in combination and is useful for batch uses where the  special
          option processing implied by --script is not desired.

       --script <filename>
          Implies --no-sysinit --no-userinit --disable-debugger --end-toplevel-options.

          Causes  the system to load the specified file and exit immediately afterwards, instead of entering the
          read-eval-print loop. If the file begins with a shebang line, it is ignored.

       Regardless of the order in which toplevel options appear on the command line, the order of actions is:

       1. Debugger is disabled, if requested.

       2. Any system initialization file is loaded, unless prohibited.

       3. Any user initialization file is loaded, unless prohibited.

       4. --eval and --load options are processed in the order given.

       Finally, either the read-eval-print loop is entered or the file specified with --script option is loaded.

       When running in the read-eval-print loop the system exits on end of file.  Similarly,  the  system  exits
       immediately after processing the file specified with --script.

       Note  that  when  running  SBCL  with  the --core option, using a core file created by a user call to the
       SB-EXT:SAVE-LISP-AND-DIE, the toplevel options may be under the control of user code passed as  arguments
       to SB-EXT:SAVE-LISP-AND-DIE. For this purpose, the --end-toplevel-options option itself can be considered
       a toplevel option, i.e. the user core, at its option, may not support it.

       In  the  standard  SBCL  startup  sequence  (i.e.  with  no  user core involved) toplevel options and any
       --end-toplevel-options option are stripped out of the command line argument list before user code gets  a
       chance to see it.

OVERVIEW

       SBCL  is  derived from the CMU CL. (The name is intended to acknowledge the connection: steel and banking
       are the industries where Carnegie and Mellon made the big bucks.)

       SBCL compiles by default: even functions entered in the read-eval-print loop are compiled to native code,
       unless the evaluator has been explicitly turned  on.  (Even  today,  some  30  years  after  the  MacLisp
       compiler, people will tell you that Lisp is an interpreted language. Ignore them.)

       SBCL  aims  for  but  has not completely achieved compliance with the ANSI standard for Common Lisp. More
       information about this is available in the BUGS section below.

       SBCL also includes various non-ANSI extensions, described more fully in the User Manual.  Some  of  these
       are in the base system and others are "contrib" modules loaded on request using REQUIRE.  For example, to
       load the SB-BSD-SOCKETS module that provides TCP/IP connectivity,
          * (require 'asdf)
          * (require 'sb-bsd-sockets)

       For more information, see the User Manual.

THE COMPILER

       SBCL inherits from CMU CL the "Python" native code compiler. (Though we often avoid that name in order to
       avoid  confusion  with  the  scripting  language  also called Python.) This compiler is very clever about
       understanding the type system of Common Lisp and using it to optimize code, and about producing notes  to
       let  the  user  know when the compiler doesn't have enough type information to produce efficient code. It
       also  tries  (almost  always  successfully)  to  follow  the  unusual  but  very  useful  principle  that
       "declarations  are  assertions",  i.e.   type  declarations  should be checked at runtime unless the user
       explicitly tells the system that speed is more important than safety.

       The compiled code  uses  garbage  collection  to  automatically  manage  memory.  The  garbage  collector
       implementation  varies  considerably from CPU to CPU. In particular, on some CPUs the GC is nearly exact,
       while on others it's more conservative, and on some CPUs the GC is generational, while on others  simpler
       stop and copy strategies are used.

       For more information about the compiler, see the user manual.

SYSTEM REQUIREMENTS

       SBCL  currently  runs on X86 (Linux, FreeBSD, OpenBSD, and NetBSD), X86-64 (Linux), Alpha (Linux, Tru64),
       PPC (Linux, Darwin/MacOS X), SPARC (Linux and Solaris 2.x), and MIPS (Linux). For  information  on  other
       ongoing and possible ports, see the sbcl-devel mailing list, and/or the web site.

       SBCL  requires on the order of 16Mb RAM to run on X86 systems, though all but the smallest programs would
       be happier with 32Mb or more.

KNOWN BUGS

       This section attempts to list the most serious and long-standing bugs.  For  more  detailed  and  current
       information on bugs, see the BUGS file in the distribution.

       It  is  possible to get in deep trouble by exhausting heap memory.  The SBCL system overcommits memory at
       startup, so, on typical Unix-alikes like Linux and FreeBSD, this means that if the SBCL system turns  out
       to  use  more  virtual  memory  than  the  system has available for it, other processes tend to be killed
       randomly (!).

       The  compiler's  handling  of  function  return  values  unnecessarily  violates  the  "declarations  are
       assertions"  principle that it otherwise adheres to. Using PROCLAIM or DECLAIM to specify the return type
       of a function causes the compiler to believe you without checking. Thus compiling a file containing
         (DECLAIM (FTYPE (FUNCTION (T) NULL) SOMETIMES))
         (DEFUN SOMETIMES (X) (ODDP X))
         (DEFUN FOO (X) (IF (SOMETIMES X) 'THIS-TIME 'NOT-THIS-TIME))
       then running (FOO 1) gives NOT-THIS-TIME, because the compiler relied on the truth of the DECLAIM without
       checking it.

       Some things are implemented very inefficiently.

       -- Multidimensional arrays are inefficient, especially multidimensional arrays of floating point numbers.

       -- SBCL, like most (maybe all?) implementations of Common Lisp on stock  hardware,  has  trouble  passing
          floating  point  numbers around efficiently, because a floating point number, plus a few extra bits to
          identify its type, is larger than a machine word. (Thus, they get "boxed" in  heap-allocated  storage,
          causing  GC  overhead.)  Within a single compilation unit, or when doing built-in operations like SQRT
          and AREF, or some special operations like structure slot accesses, this is  avoidable:  see  the  user
          manual  for some efficiency hints. But for general function calls across the boundaries of compilation
          units, passing the result of a floating point calculation as  a  function  argument  (or  returning  a
          floating point result as a function value) is a fundamentally slow operation.

REPORTING BUGS

       To report a bug, please send mail to the mailing lists sbcl-help or sbcl-devel. You can find the complete
       mailing  list addresses on the web pages at <http://sbcl.sourceforge.net/>; note that as a spam reduction
       measure you must subscribe to the lists before you can post. (You may also find  fancy  SourceForge  bug-
       tracking  machinery  there,  but don't be fooled. As of 2002-07-25 anyway, we don't actively monitor that
       machinery, and it exists only because we haven't been able to figure out how to turn it off.)

       As with any software bug report, it's most helpful if you can provide enough information to reproduce the
       symptoms reliably, and if you say clearly what the  symptoms  are.   For  example,  "There  seems  to  be
       something    wrong    with    TAN   of   very   small   negative   arguments.   When   I   execute   (TAN
       LEAST-NEGATIVE-SINGLE-FLOAT)  interactively  on  sbcl-1.2.3  on  my  Linux  4.5  X86  box,   I   get   an
       UNBOUND-VARIABLE error."

DIFFERENCES FROM CMU CL

SBCL can be built from scratch using a plain vanilla ANSI Common Lisp system and a C compiler, and all of
its properties are specified by the version of the source code that it was created from. This clean
bootstrappability was the immediate motivation for forking off of the CMU CL development tree. A variety
of implementation differences are motivated by this design goal.

Maintenance work in SBCL since the fork has diverged somewhat from the maintenance work in CMU CL. Many
but not all bug fixes and improvements have been shared between the two projects, and sometimes the two
projects disagree about what would be an improvement.

Most extensions supported by CMU CL have been unbundled from SBCL, including Motif support, the Hemlock
editor, search paths, the WIRE protocol, various user-level macros and functions (e.g. LETF, ITERATE,
MEMQ, REQUIRED-ARGUMENT), and many others.

(Why doesn't SBCL support more extensions natively? Why drop all those nice extensions from CMU CL when
the code already exists? This is a frequently asked question on the mailing list. There are two principal
reasons. First, it's a design philosophy issue: arguably SBCL has done its job by supplying a stable FFI,
and the right design decision is to move functionality derived from that, like socket support, into
separate libraries. Some of these are distributed with SBCL as "contrib" modules, others are distributed
as separate software packages by separate maintainers. Second, it's a practical decision - focusing on a
smaller number of things will, we hope, let us do a better job on them.)

SUPPORT

       Various  information  about  SBCL is available at <http://www.sbcl.org/>. The mailing lists there are the
       recommended place to look for support.

AUTHORS

       Dozens of people have made substantial contributions to SBCL and its subsystems, and to the CMU CL system
       on which it was based, over the years. See the CREDITS file in the distribution for more information.

ENVIRONMENT

       SBCL_HOME This variable controls where files like "sbclrc", "sbcl.core", and the add-on "contrib" systems
                 are searched for.  If it is not set, then sbcl sets it from  a  compile-time  default  location
                 which is usually /usr/local/lib/sbcl/ but may have been changed e.g. by a third-party packager.

FILES

       sbcl   executable program containing some low-level runtime support and a loader, used to read sbcl.core

       sbcl.core
              dumped memory image containing most of SBCL, to be loaded by the `sbcl' executable.  Looked for in
              $SBCL_HOME, unless overridden by the --core option.

       sbclrc optional  system-wide  startup  script,  looked  for in $SBCL_HOME/sbclrc then /etc/sbclrc, unless
              overridden by the --sysinit command line option.

       .sbclrc
              optional per-user customizable startup script (in  user's  home  directory,  or  as  specified  by
              --userinit)