1 @node Starting and Stopping
2 @comment node-name, next, previous, up
3 @chapter Starting and Stopping
8 * Command Line Options::
9 * Initialization Files::
10 * Initialization and Exit Hooks::
14 @comment node-name, next, previous, up
15 @section Starting SBCL
18 * Running from Shell::
19 * Running from Emacs::
23 @node Running from Shell
24 @comment node-name, next, previous, up
25 @subsection From Shell to Lisp
27 To run SBCL type @command{sbcl} at the command line.
29 You should end up in the toplevel @dfn{REPL} (read, eval, print
30 -loop), where you can interact with SBCL by typing expressions.
34 This is SBCL 0.8.13.60, an implementation of ANSI Common Lisp.
35 More information about SBCL is available at <http://www.sbcl.org/>.
37 SBCL is free software, provided as is, with absolutely no warranty.
38 It is mostly in the public domain; some portions are provided under
39 BSD-style licenses. See the CREDITS and COPYING files in the
40 distribution for more information.
48 See also @ref{Command Line Options} and @ref{Stopping SBCL}.
50 @node Running from Emacs
51 @comment node-name, next, previous, up
52 @subsection Running from Emacs
54 To run SBCL as an inferior-lisp from Emacs in your @file{.emacs} do
58 ;;; The SBCL binary and command-line arguments
59 (setq inferior-lisp-program "/usr/local/bin/sbcl --noinform")
62 For more information on using SBCL with Emacs, see @ref{Editor
67 @comment node-name, next, previous, up
68 @subsection Shebang Scripts
69 @vindex @sbext{@earmuffs{posix-argv}}
71 Standard Unix tools that are interpreters follow a common command line
72 protocol that is necessary to work with ``shebang scripts''. SBCL supports
73 this via the @code{--script} command line option.
75 Example file (@file{hello.lisp}):
78 #!/usr/local/bin/sbcl --script
79 (write-line "Hello, World!")
90 $ sbcl --script hello.lisp
95 @comment node-name, next, previous, up
96 @section Stopping SBCL
101 * Saving a Core Image::
106 @comment node-name, next, previous, up
109 SBCL can be stopped at any time by calling @code{sb-ext:quit},
110 optionally returning a specified numeric value to the calling process.
111 See notes in @ref{Threading} about the interaction between this
112 feature and sessions.
114 @include fun-sb-ext-quit.texinfo
117 @comment node-name, next, previous, up
118 @subsection End of File
120 By default SBCL also exits on end of input, caused either by user
121 pressing @kbd{Control-D} on an attached terminal, or end of input when
122 using SBCL as part of a shell pipeline.
124 @node Saving a Core Image
125 @comment node-name, next, previous, up
126 @subsection Saving a Core Image
128 SBCL has the ability to save its state as a file for later
129 execution. This functionality is important for its bootstrapping
130 process, and is also provided as an extension to the user.
132 @include fun-sb-ext-save-lisp-and-die.texinfo
133 @include var-sb-ext-star-save-hooks-star.texinfo
135 In cases where the standard initialization files have already been loaded
136 into the saved core, and alternative ones should be used (or none at all),
137 SBCL allows customizing the initfile pathname computation.
139 @include var-sb-ext-star-sysinit-pathname-function-star.texinfo
140 @include var-sb-ext-star-userinit-pathname-function-star.texinfo
142 To facilitate distribution of SBCL applications using external
143 resources, the filesystem location of the SBCL core file being used is
146 @include var-sb-ext-star-core-pathname-star.texinfo
149 @comment node-name, next, previous, up
150 @subsection Exit on Errors
152 SBCL can also be configured to exit if an unhandled error occurs,
153 which is mainly useful for acting as part of a shell pipeline; doing
154 so under most other circumstances would mean giving up large parts of
155 the flexibility and robustness of Common Lisp. See @ref{Debugger Entry}.
157 @node Command Line Options
158 @comment node-name, next, previous, up
159 @section Command Line Options
161 @c FIXME: This is essentially cut-and-paste from the manpage
162 @c What should probably be done is generate both this and the
163 @c man-page from ``sbcl --help'' output.
165 Command line options can be considered an advanced topic; for ordinary
166 interactive use, no command line arguments should be necessary.
168 In order to understand the command line argument syntax for SBCL, it
169 is helpful to understand that the SBCL system is implemented as two
170 components, a low-level runtime environment written in C and a
171 higher-level system written in Common Lisp itself. Some command line
172 arguments are processed during the initialization of the low-level
173 runtime environment, some command line arguments are processed during
174 the initialization of the Common Lisp system, and any remaining
175 command line arguments are passed on to user code.
177 The full, unambiguous syntax for invoking SBCL at the command line is:
179 @command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-options}*
181 For convenience, the @code{--end-runtime-options} and
182 @code{--end-toplevel-options} elements can be omitted. Omitting these
183 elements can be convenient when you are running the program
184 interactively, and you can see that no ambiguities are possible with
185 the option values you are using. Omitting these elements is probably a
186 bad idea for any batch file where any of the options are under user
187 control, since it makes it impossible for SBCL to detect erroneous
188 command line input, so that erroneous command line arguments will be
189 passed on to the user program even if they was intended for the
190 runtime system or the Lisp system.
197 @node Runtime Options
198 @comment node-name, next, previous, up
199 @subsection Runtime Options
203 @item --core @var{corefilename}
204 Run the specified Lisp core file instead of the default. Note that if
205 the Lisp core file is a user-created core file, it may run a
206 nonstandard toplevel which does not recognize the standard toplevel
209 @item --dynamic-space-size @var{megabytes}
210 Size of the dynamic space reserved on startup in megabytes. Default
211 value is platform dependent.
213 @item --control-stack-size @var{megabytes}
214 Size of control stack reserved for each thread in megabytes. Default
218 Suppress the printing of any banner or other informational message at
219 startup. This makes it easier to write Lisp programs which work
220 cleanly in Unix pipelines. See also the @code{--noprint} and
221 @code{--disable-debugger} options.
225 @cindex ldb, disabling
226 @cindex disabling ldb
227 Disable the low-level debugger. Only effective if SBCL is compiled
230 @item --lose-on-corruption
232 There are some dangerous low level errors (for instance, control stack
233 exhausted, memory fault) that (or whose handlers) can corrupt the
234 image. By default SBCL prints a warning, then tries to continue and
235 handle the error in Lisp, but this will not always work and SBCL may
236 malfunction or even hang. With this option, upon encountering such an
237 error SBCL will invoke ldb (if present and enabled) or else exit.
240 @item --script @var{filename}
241 As a runtime option this is equivalent to @code{--noinform}
242 @code{--disable-ldb} @code{--lose-on-corruption}
243 @code{--end-runtime-options} @code{--script} @var{filename}. See the
244 description of @code{--script} as a toplevel option below. If there
245 are no other commandline arguments following @code{--script}, the
246 filename argument can be omitted.
249 Print some basic information about SBCL, then exit.
252 Print SBCL's version information, then exit.
256 In the future, runtime options may be added to control behaviour such
257 as lazy allocation of memory.
259 Runtime options, including any --end-runtime-options option, are
260 stripped out of the command line before the Lisp toplevel logic gets a
263 @node Toplevel Options
264 @comment node-name, next, previous, up
265 @subsection Toplevel Options
269 @item --sysinit @var{filename}
270 Load filename instead of the default system initialization file
271 (@pxref{Initialization Files}.)
274 Don't load a system-wide initialization file. If this option is given,
275 the @code{--sysinit} option is ignored.
277 @item --userinit @var{filename}
278 Load filename instead of the default user initialization file
279 (@pxref{Initialization Files}.)
282 Don't load a user initialization file. If this option is given,
283 the @code{--userinit} option is ignored.
285 @item --eval @var{command}
286 After executing any initialization file, but before starting the
287 read-eval-print loop on standard input, read and evaluate the command
288 given. More than one @code{--eval} option can be used, and all will be
289 read and executed, in the order they appear on the command line.
291 @item --load @var{filename}
292 This is equivalent to @code{--eval '(load "@var{filename}")'}. The
293 special syntax is intended to reduce quoting headaches when invoking
294 SBCL from shell scripts.
297 When ordinarily the toplevel "read-eval-print loop" would be exe-
298 cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
299 and don't echo results. Combined with the @code{--noinform} runtime
300 option, this makes it easier to write Lisp "scripts" which work
301 cleanly in Unix pipelines.
303 @item --disable-debugger
304 By default when SBCL encounters an error, it enters the builtin
305 debugger, allowing interactive diagnosis and possible intercession.
306 This option disables the debugger, causing errors to print a backtrace
307 and exit with status 1 instead. When given, this option takes effect
308 before loading of initialization files or processing @code{--eval} and
309 @code{--load} options. See @code{sb-ext:disable-debugger} for details.
310 @xref{Debugger Entry}.
312 @item --script @var{filename}
313 Implies @code{--no-userinit} @code{--no-sysinit}
314 @code{--disable-debugger} @code{--end-toplevel-options}.
316 Causes the system to load the specified file instead of entering the
317 read-eval-print-loop, and exit afterwards. If the file begins with a
318 shebang line, it is ignored.
320 If there are no other command line arguments following, the filename
321 can be omitted: this causes the script to be loaded from standard
322 input instead. Shebang lines in standard input script are currently
325 In either case, if there is an unhandled error (eg. end of file, or a
326 broken pipe) on either standard input, standard output, or standard
327 error, the script silently exits with code 0. This allows eg. safely
328 piping output from SBCL to @code{head -n1} or similar.
332 @node Initialization Files
333 @comment node-name, next, previous, up
334 @section Initialization Files
336 SBCL processes initialization files with @code{read} and @code{eval},
337 not @code{load}; hence initialization files can be used to set startup
338 @code{*package*} and @code{*readtable*}, and for proclaiming a global
343 @strong{System Initialization File}
345 Defaults to @file{@env{$SBCL_HOME}/sbclrc}, or if that doesn't exist to
346 @file{/etc/sbclrc}. Can be overridden with the command line option
347 @code{--sysinit} or @code{--no-sysinit}.
349 The system initialization file is intended for system administrators
350 and software packagers to configure locations of installed third party
354 @strong{User Initialization File}
356 Defaults to @file{@env{$HOME}/.sbclrc}. Can be overridden with the
357 command line option @code{--userinit} or @code{--no-userinit}.
359 The user initialization file is intended for personal customizations,
360 such as loading certain modules at startup, defining convenience
361 functions to use in the REPL, handling automatic recompilation
362 of FASLs (@pxref{FASL Format}), etc.
366 Neither initialization file is required.
368 @node Initialization and Exit Hooks
369 @comment node-name, next, previous, up
370 @section Initialization and Exit Hooks
372 SBCL provides hooks into the system initialization and exit.
374 @include var-sb-ext-star-init-hooks-star.texinfo
375 @include var-sb-ext-star-exit-hooks-star.texinfo