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