Yank DO-TARGET-TNS out of FIND-OK-TARGET-OFFSET
[sbcl.git] / 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.