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.
+subprocess, but can be somewhat fragile because it tries to be so
+clever and intimate in its interactions with the Lisp subprocess. In
+case of ilisp problems, running SBCL in the Emacs "shell" mode can a
+useful substitute.
.SH OVERVIEW
after the MacLisp compiler, people will tell you that Lisp is an
interpreted language. Ignore them.)
-SBCL aims for but has not yet reached compliance with the ANSI
-standard for Common Lisp. More information on this is available in the
-BUGS section below.
+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.
(Why doesn't SBCL support more extensions? Why drop all those nice
extensions from CMU CL when the code already exists? This is a
-frequently asked question on the mailing list. In other cases, it's a
+frequently asked question on the mailing list. In some cases, 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,
.SH THE COMPILER
-SBCL is essentially a compiler-only implementation of Lisp. All
+SBCL is essentially a compiler-only implementation of Common Lisp. All
nontrivial Lisp code is compiled to native machine code before being
executed, even when the Lisp code is typed interactively at the
"interpreter" prompt.
SBCL inherits from CMU CL the "Python" native code compiler. (Though
-we've essentially dropped 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
+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 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).
+The compiler reportedly produces pretty good code for modern CPU
+architectures which have lots of registers, but its code for the X86
+is marred by many 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).
The compiled code uses garbage collection to automatically
manage memory. The garbage collector implementation varies considerably
.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.
+section for the standard core, or the system documentation for
+SB-INT: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.
.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.)
+startup. (This makes it easier to write Lisp programs which work
+cleanly in Unix pipelines. See also the "--noprint" and
+"--disable-debugger" options.)
+.TP 3
+.B --help
+Print some basic information about SBCL, then exit.
+.TP 3
+.B --version
+Print SBCL's version information, then exit.
.PP
In the future, runtime options may be added to control behavior such
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
+The toplevel options supported by the standard SBCL core are
.TP 3
.B --sysinit <filename>
Load filename instead of the default system-wide initialization file.
.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.
+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.
.TP 3
.B --load <filename>
This is equivalent to --eval '(load "<filename>")'. The special
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.
+makes it easier to write Lisp "scripts" which work cleanly in Unix
+pipelines.
.TP 3
-.B --noprogrammer
+.B --disable-debugger
+This is equivalent to --eval '(sb-ext:disable-debugger)'.
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.
+behavior for that situation. This is implemented by modifying special
+variables: 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. Because it is implemented by modifying special variables,
+its effects persist in .core files created by SB-EXT:SAVE-LISP-AND-DIE.
+(If you want to undo its effects, see the SB-EXT:ENABLE-DEBUGGER
+command.)
.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.
+any --eval commands are read and 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
.SH SYSTEM REQUIREMENTS
-Unlike its distinguished ancestor CMU CL, SBCL currently runs only on
-X86 (Linux, FreeBSD, and OpenBSD), Alpha (Linux), and SPARC (Linux).
+SBCL currently runs on
+X86 (Linux, FreeBSD, and OpenBSD), Alpha (Linux, Tru64), PPC
+(Linux) and SPARC (Linux and Solaris 2.x).
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.
+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.
.SH ENVIRONMENT
.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.
+/usr/lib/sbcl/sbcl.core and /usr/local/lib/sbcl/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
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
+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
(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.
+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.
.TP 3
\--
Multidimensional arrays are inefficient, especially
-multidimensional arrays of floating point numbers
+multidimensional arrays of floating point numbers.
.TP 3
\--
The DYNAMIC-EXTENT declaration isn't implemented at all, not even
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
+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 a floating point
-number as a function argument (or returning a floating point
-number as a function value) is a fundamentally slow operation.
+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.
.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,
.SH REPORTING BUGS
-To report a bug, please send mail to sbcl-help@lists.sourceforge.net
-or sbcl-devel@lists.sourceforge.net.
+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/>. (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. 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."
+(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
<http://sbcl.sourceforge.net/>. The mailing lists there are the
recommended place to look for support.
+.SH FILES
+
+.TP
+.I sbcl
+executable program containing some low-level runtime support and
+a loader, used to read sbcl.core
+.TP
+.I sbcl.core
+dumped memory image containing most of SBCL, to be loaded by
+the 'sbcl' executable
+.TP
+.I sbclrc
+optional system-wide startup script (in an etc-ish system
+configuration file directory)
+.TP
+.I .sbclrc
+optional per-user customizable startup script (in user's home directory)
+
.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.
+years. See the CREDITS file in the distribution for more information.
projects / sbcl.git / blobdiff