[sbcl.git] / doc / sbcl.1

.\" -*- Mode: Text -*-
.\"
.\" man page introduction to SBCL
.\"
.\" SBCL, including this man page, is derived from CMU Common Lisp, of
.\" which it was said (ca. 1991)
.\"   **********************************************************************
.\"   This code was written as part of the CMU Common Lisp project at
.\"   Carnegie Mellon University, and has been placed in the public domain.
.\"   If you want to use this code or any part of CMU Common Lisp, please
.\"   contact Scott Fahlman or slisp-group@cs.cmu.edu.
.\"   **********************************************************************
.\" Most of SBCL, including this man page, is in the public domain. See
.\" COPYING in the distribution for more information.
.\"
.TH SBCL 1 "$Date$"
.AT 3
.SH NAME
SBCL -- "Steel Bank Common Lisp"

.SH DESCRIPTION

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

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.

.SH RUNNING SBCL

To run SBCL, type "sbcl" at the command line with no arguments. (SBCL
understands command line arguments, but you probably won't need to use
them unless you're a fairly advanced user, in which case you should
read the COMMAND LINE SYNTAX section, below.) You should see some
startup messages, then a prompt ("*"). Type a Lisp expression at the
prompt, and SBCL will read it, execute it, print the result, 
give you another prompt, and wait for your next input. E.g.
  * (+ 1 2 3)
  6
  *

Many people like to run SBCL, like other Lisp systems, as a subprocess
under Emacs. The Emacs "ilisp" 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.

.SH OVERVIEW

SBCL aims for but has not reached ANSI compliance.

SBCL compiles Common Lisp to native code, and is essentially a
"compiler-only" implementation of the ANSI standard. (Unlike earlier
versions of SBCL, byte compilation is no longer supported, and there
is only a vestigial interpreter. Thus, in particular,
COMPILED-FUNCTION-P is always equal to FUNCTIONP.)

SBCL uses a generational conservative garbage collector for some ports,
and a simple stop-and-copy garbage collector for other ports.

SBCL also includes some non-ANSI extensions, notably
  * Lispy extensions:
    ** CMU-CL-style safe implementation of type declarations:
       "Declarations are assertions."
    ** source level debugger
    ** profiler
    ** saving the state of the running SBCL process, producing a
       "core" file which can be restarted later
    ** Gray streams (overloadable CLOS classes whose instances can
       be used wherever ANSI streams can be used)
    ** weak pointers and finalization (which have unfortunately
       suffered from at least some code rot, e.g. weak hash tables
       don't work)
  * system interface extensions:
    ** calling out to C code (a.k.a. FFI, foreign function interface)
    ** some simple support for operations with a "scripting language" 
       flavor, e.g. reading POSIX argc and argv, or executing a 
       subprogram

.SH 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 internal implementation
differences are motivated by this.

Maintenance work in SBCL since the fork has diverged in various
details from the maintenance work in CMU CL. E.g. as of 2001-04-12,
SBCL was more ANSI-compliant than CMU CL in various details such as
support for PRINT-OBJECT and DESCRIBE-OBJECT, and SBCL's compiler was
substantially better than CMU CL's at optimizing operations on
non-simple vectors.

Most extensions supported by CMU CL are not supported in SBCL,
including Motif support, the Hemlock editor, search paths, the
low-level Unix interface, the WIRE protocol, multithreading support,
various user-level macros and functions (e.g. LETF, ITERATE, MEMQ,
REQUIRED-ARGUMENT), and many others.

SBCL has retained some extensions from parent CMU CL. Many of the
retained extensions are in these categories:
.TP 3
\--
things which might be in the new ANSI spec, e.g. weak pointers,
finalization, foreign function interface to C, and Gray streams
.TP 3
\--
things which are universally available in Unix scripting languages,
e.g. RUN-PROGRAM and POSIX argv and getenv
.TP 3
\--
hooks into the low level workings of the system which can be useful
for debugging, e.g. a list of functions to be run whenever GC occurs,
or parameters to modify compiler diagnostic output
.TP 3
\--
unportable performance hacks, e.g. TRULY-THE, FREEZE-TYPE, and PURIFY
.PP

There are also a few retained extensions which don't fall into
any particular category, e.g.
.TP 3
\--
the ability to save running Lisp images as executable files
.PP

Some of the retained extensions have new names and/or different
options than their CMU CL counterparts. For example, the SBCL function
which saves a Lisp image to disk and kills it is called
SAVE-LISP-AND-DIE instead of SAVE-LISP, and it supports fewer keyword
options than CMU CL's SAVE-LISP.

(Why doesn't SBCL support more extensions? Why the hell did I (WHN)
drop all those nice extensions from CMU CL when the code already
exists? This is a frequently asked question on the mailing list. The
answer is that they're hard to maintain, and I have enough on my hands
already. Also, in the case of some big and unquestionably useful
extensions, like sockets and Motif, I think that SBCL has done its job
by supplying the FFI, and that people who need, and understand, and
are motivated to maintain the functionality should supply it as a
separate library, which I'd be happy to distribute or link to on the
SBCL home page. Finally, in the case of multithreading, I do think it
belongs in the new ANSI spec, and it'd be a good feature to have, but
I didn't think the CMU CL implementation was sufficiently mature, and
it's such a complicated and far-reaching extension that I thought that
trying to fix it would interfere with the more urgent task of getting
basic ANSI support up to speed.)

.SH THE COMPILER

As noted above, SBCL is essentially a compiler-only implementation of
Lisp, with all nontrivial code being implemented by compilation, even
when you type it interactively at the "interpreter" prompt.

SBCL inherits from CMU CL the "Python" native code compiler. (Though
we've essentially dropped the name 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 CMU CL version of this compiler reportedly produces pretty good
code for modern CPU architectures which have lots of registers, but
its code for the X86 is marred by a lot of extra loads and stores to
stack-based temporary variables. Because of this, and because of the
extra levels of indirection in Common Lisp relative to C, the
performance of SBCL isn't going to impress people who are impressed by
small constant factors. However, even on the X86 it tends to be faster
than byte interpreted languages (and can be a lot faster).

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

.SH DOCUMENTATION

Currently, the documentation for the system is
.TP 3
\--
this man page
.TP 3
\--
the user manual
.TP 3
\--
doc strings and online help built into the SBCL executable
.PP

.SH COMMAND LINE SYNTAX

Command line syntax can be considered an advanced topic; for ordinary
interactive use, no command line arguments should be necessary.

In order to understand the command line argument syntax for SBCL, it
is helpful to understand that the SBCL system is implemented as two
components, a low-level runtime environment written in C and a
higher-level system written in Common Lisp itself. Some command line
arguments are processed during the initialization of the low-level
runtime environment, some command line arguments are processed during
the initialization of the Common Lisp system, and any remaining
command line arguments are passed on to user code.

The full, unambiguous syntax for invoking SBCL at the command line is
.TP 3
.B sbcl [runtime options] --end-runtime-options [toplevel options] --end-toplevel-options [user options]
.PP

For convenience, the --end-runtime-options and --end-toplevel-options
elements can be omitted. Omitting these elements can be convenient
when you are running the program interactively, and you can see that
no ambiguities are possible with the option values you are using.
Omitting these elements is probably a bad idea for any batch file
where any of the options are under user control, since it makes it
impossible for SBCL to detect erroneous command line input, so that
erroneous command line arguments will be passed on to the user program
even if they was intended for the runtime system or the Lisp system.

Supported runtime options are
.TP 3
.B --core <corefilename>
Run the specified Lisp core file instead of the default. (See the FILES
section.) 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.
.TP 3
.B --noinform
Suppress the printing of any banner or other informational message at
startup. (This makes it easier to write Lisp programs which work in
Unix pipelines. See also the "--noprogrammer" and "--noprint" options.)
.PP

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.

Supported toplevel options for the standard SBCL core are
.TP 3
.B --sysinit <filename>
Load filename instead of the default system-wide initialization file.
(See the FILES section.) There is no special option to cause no
system-wide initialization file to be read, but on a Unix system
"--sysinit /dev/null" can be used to achieve the same effect.
.TP 3
.B --userinit <filename>
Load filename instead of the default user initialization file. (See
the FILES section.) There is no special option to cause no user
initialization file to be read, but on a Unix system "--userinit
/dev/null" can be used to achieve the same effect.
.TP 3
.B --eval <command>
After executing any initialization file, but before starting the
read-eval-print loop on standard input, evaluate the command given.
More than one --eval option can be used, and all will be executed, in
the order they appear on the command line.
.TP 3
.B --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 in Unix pipelines.
.TP 3
.B --noprogrammer
By default, a Common Lisp system tries to ask the programmer for help
when it gets in trouble (by printing a debug prompt on *DEBUG-IO*).
However, this is not useful behavior for a system running with no
programmer available, and this option tries to set up more appropriate
behavior for that situation. Thus we set *DEBUG-IO* to send its
output to *ERROR-OUTPUT*, and to raise an error if any input is
requested from it; and we set *DEBUGGER-HOOK* to output a backtrace,
then exit the process with a failure code.
.PP

Regardless of the order in which --sysinit, --userinit, and --eval
options appear on the command line, the sysinit file, if it exists, is
loaded first; then the userinit file, if it exists, is loaded; then
any --eval commands are executed in sequence; then the read-eval-print
loop is started on standard input. At any step, error conditions or
commands such as SB-EXT:QUIT can cause execution to be terminated
before proceeding to subsequent steps.

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.

.SH SYSTEM REQUIREMENTS

Unlike its distinguished ancestor CMU CL, SBCL currently runs only on X86
(Linux, FreeBSD, and OpenBSD) and Alpha (Linux). For information on 
other ongoing 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. 

.SH ENVIRONMENT

.TP 10n
.BR SBCL_HOME
If this variable is set, it overrides the default directories for
files like "sbclrc" and "sbcl.core", so that instead of being searched
for in e.g. /etc/, /usr/local/etc/, /usr/lib/, and /usr/local/lib/, they
are searched for only in the directory named by SBCL_HOME. This is
intended to support users who wish to use their own version of SBCL
instead of the version which is currently installed as the system
default.
.PP

.SH FILES

/usr/lib/sbcl.core and /usr/local/lib/sbcl.core are the standard
locations for the standard SBCL core, unless overridden by the SBCL_HOME
variable.

/etc/sbclrc and /usr/local/etc/sbclrc are the standard locations for
system-wide SBCL initialization files, unless overridden by the
SBCL_HOME variable or the --sysinit command line option.

$HOME/.sbclrc is the standard location for a user's SBCL
initialization file, unless overridden by the --userinit
command line option.

.SH 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
memory. To plagiarize a sadly apt description of a language not
renowned for the production of bulletproof software, "[The current
SBCL implementation of] Common Lisp makes it harder for you to shoot
yourself in the foot, but when you do, the entire universe explodes."
.TP 3
\--
The system doesn't deal well with stack overflow. (It tends to cause
a segmentation fault instead of being caught cleanly.)
.TP 3
\--
Like CMU CL, the SBCL system overcommits memory at startup. 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 (!).
.PP

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
never compiled code to check the declaration.

Some things are implemented very inefficiently.
.TP 3
\--
Multidimensional arrays are inefficient, especially
multidimensional arrays of floating point numbers
.TP 3
\--
The DYNAMIC-EXTENT declaration isn't implemented at all, not even
for &REST lists or upward closures, so such constructs always allocate
their temporary storage from the heap, causing GC overhead.
.TP 3
\--
CLOS isn't particularly efficient. (In part, CLOS is so dynamic
that it's slow for fundamental reasons, but beyond that, the
SBCL implementation of CLOS doesn't do some important known
optimizations.)
.TP 3
\--
SBCL, like most implementations of Common Lisp, has trouble
passing floating point numbers around efficiently, because
they're 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 a floating point
number as a function argument (or returning a floating point
number as a function value) is a fundamentally slow operation.
.PP

There are still some nagging pre-ANSIisms, notably
.TP 3
\--
CLOS (based on the PCL reference implementation) is incompletely
integrated into the system, so that e.g. SB-PCL::FIND-CLASS is a
different function than CL::FIND-CLASS. (In practice, you need to
be a pretty advanced user before this is a serious problem, and
by then you can usually work around it, but it's still distasteful.
It's arguably the outstanding "This should be fixed by version 1.0"
issue.)
.TP 3
--
The ANSI-recommended idiom for creating a function which is only
sometimes expanded inline,
(DECLAIM (INLINE F))
(DEFUN F ...)
(DECLAIM (NOTINLINE F)),
doesn't do what you'd expect. (Instead, you have to declare the
function as SB-EXT:MAYBE-INLINE to get the desired effect.)
.TP 3
\--
There are several nonconforming bits of type syntax. E.g. (1) The type
FOO is strictly equivalent to (FOO), so e.g. the type OR is treated as
the type (OR), i.e. the empty type. This is the way that the ancestral
code worked, and even though ANSI specifically forbids it, it hasn't
been fixed yet. (2) The symbol * is the name of a type similar to T.
(It's used as part of the implementation of compound types like (ARRAY
* 1) and (CONS * *). In a strict ANSI implementation, * would not be
the name of a type, but instead just a symbol which is recognized and
handled specially by certain type expanders.)
.PP

.SH REPORTING BUGS

To report a bug, please send mail to sbcl-help@lists.sourceforge.net
or sbcl-devel@lists.sourceforge.net.

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. E.g. "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."

.SH SUPPORT

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

.SH 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.