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
70 SBCL doesn't come with built-in support for shebang-line execution,
71 but this can be provided with a shell trampoline, or by dispatching
72 from initialization files (@pxref{Unix-style Command Line Protocol} for
77 @comment node-name, next, previous, up
78 @section Stopping SBCL
83 * Saving a Core Image::
88 @comment node-name, next, previous, up
91 SBCL can be stopped at any time by calling @code{sb-ext:quit},
92 optionally returning a specified numeric value to the calling process.
93 See notes in @ref{Threading} about the interaction between this
96 @include fun-sb-ext-quit.texinfo
99 @comment node-name, next, previous, up
100 @subsection End of File
102 By default SBCL also exits on end of input, caused either by user
103 pressing @kbd{Control-D} on an attached terminal, or end of input when
104 using SBCL as part of a shell pipeline.
106 @node Saving a Core Image
107 @comment node-name, next, previous, up
108 @subsection Saving a Core Image
110 SBCL has the ability to save its state as a file for later
111 execution. This functionality is important for its bootstrapping
112 process, and is also provided as an extension to the user.
114 @include fun-sb-ext-save-lisp-and-die.texinfo
115 @include var-sb-ext-star-save-hooks-star.texinfo
117 To facilitate distribution of SBCL applications using external
118 resources, the filesystem location of the SBCL core file being used is
121 @include var-sb-ext-star-core-pathname-star.texinfo
124 @comment node-name, next, previous, up
125 @subsection Exit on Errors
127 SBCL can also be configured to exit if an unhandled error occurs,
128 which is mainly useful for acting as part of a shell pipeline; doing
129 so under most other circumstances would mean giving up large parts of
130 the flexibility and robustness of Common Lisp. See @ref{Debugger Entry}.
132 @node Command Line Options
133 @comment node-name, next, previous, up
134 @section Command Line Options
136 @c FIXME: This is essentially cut-and-paste from the manpage
137 @c What should probably be done is generate both this and the
138 @c man-page from ``sbcl --help'' output.
140 Command line options can be considered an advanced topic; for ordinary
141 interactive use, no command line arguments should be necessary.
143 In order to understand the command line argument syntax for SBCL, it
144 is helpful to understand that the SBCL system is implemented as two
145 components, a low-level runtime environment written in C and a
146 higher-level system written in Common Lisp itself. Some command line
147 arguments are processed during the initialization of the low-level
148 runtime environment, some command line arguments are processed during
149 the initialization of the Common Lisp system, and any remaining
150 command line arguments are passed on to user code.
152 The full, unambiguous syntax for invoking SBCL at the command line is:
154 @command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-options}*
156 For convenience, the @code{--end-runtime-options} and
157 @code{--end-toplevel-options} elements can be omitted. Omitting these
158 elements can be convenient when you are running the program
159 interactively, and you can see that no ambiguities are possible with
160 the option values you are using. Omitting these elements is probably a
161 bad idea for any batch file where any of the options are under user
162 control, since it makes it impossible for SBCL to detect erroneous
163 command line input, so that erroneous command line arguments will be
164 passed on to the user program even if they was intended for the
165 runtime system or the Lisp system.
172 @node Runtime Options
173 @comment node-name, next, previous, up
174 @subsection Runtime Options
178 @item --core @var{corefilename}
179 Run the specified Lisp core file instead of the default. Note that if
180 the Lisp core file is a user-created core file, it may run a
181 nonstandard toplevel which does not recognize the standard toplevel
184 @item --dynamic-space-size @var{megabytes}
185 Size of the dynamic space reserved on startup in megabytes. Default
186 value is platform dependent.
188 @item --control-stack-size @var{megabytes}
189 Size of control stack reserved for each thread in megabytes. Default
193 Suppress the printing of any banner or other informational message at
194 startup. This makes it easier to write Lisp programs which work
195 cleanly in Unix pipelines. See also the @code{--noprint} and
196 @code{--disable-debugger} options.
199 Print some basic information about SBCL, then exit.
202 Print SBCL's version information, then exit.
206 In the future, runtime options may be added to control behaviour such
207 as lazy allocation of memory.
209 Runtime options, including any --end-runtime-options option, are
210 stripped out of the command line before the Lisp toplevel logic gets a
213 @node Toplevel Options
214 @comment node-name, next, previous, up
215 @subsection Toplevel Options
219 @item --sysinit @var{filename}
220 Load filename instead of the default system initialization file
221 (@pxref{System Initialization File}.)
224 Don't load a system-wide initialization file. If this option is given,
225 the @code{--sysinit} option is ignored.
227 @item --userinit @var{filename}
228 Load filename instead of the default user initialization file
229 (@pxref{User Initialization File}.)
232 Don't load a user initialization file. If this option is given,
233 the @code{--userinit} option is ignored.
235 @item --eval @var{command}
236 After executing any initialization file, but before starting the
237 read-eval-print loop on standard input, read and evaluate the com-
238 mand given. More than one @code{--eval} option can be used, and all
239 will be read and executed, in the order they appear on the command
242 @item --load @var{filename}
243 This is equivalent to @code{--eval '(load "@var{filename}")'}. The
244 special syntax is intended to reduce quoting headaches when invoking
245 SBCL from shell scripts.
248 When ordinarily the toplevel "read-eval-print loop" would be exe-
249 cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
250 and don't echo results. Combined with the @code{--noinform} runtime
251 option, this makes it easier to write Lisp "scripts" which work
252 cleanly in Unix pipelines.
254 @item --disable-debugger
255 This is equivalent to @code{--eval '(sb-ext:disable-debugger)'}.
256 @xref{Debugger Entry}.
261 @node Initialization Files
262 @comment node-name, next, previous, up
263 @section Initialization Files
265 This section covers initialization files processed at startup, which
266 can be used to customize the lisp environment.
269 * System Initialization File::
270 * User Initialization File::
271 * Initialization File Semantics::
272 * Initialization Examples::
275 @node System Initialization File
276 @comment node-name, next, previous, up
277 @subsection System Initialization File
279 Site-wide startup script. Unless overridden with the command line
280 option @code{--sysinit} defaults to @file{@env{SBCL_HOME}/sbclrc}, or
281 if that doesn't exist to @file{/etc/sbclrc}.
283 No system initialization file is required.
285 @node User Initialization File
286 @comment node-name, next, previous, up
287 @subsection User Initialization File
289 Per-user startup script. Unless overridden with the command line
290 option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
292 No user initialization file is required.
294 @node Initialization File Semantics
295 @comment node-name, next, previous, up
296 @subsection Initialization File Semantics
298 SBCL processes initialization files with @code{read} and @code{eval},
299 not @code{load}; hence initialization files can be used to set startup
300 @code{*package*} and @code{*readtable*}, and for proclaiming a global
303 @node Initialization Examples
304 @comment node-name, next, previous, up
305 @subsection Initialization Examples
307 Some examples of what you may consider doing in the initialization
311 * Unix-style Command Line Protocol::
312 * Automatic Recompilation of Stale Fasls::
315 @node Unix-style Command Line Protocol
316 @comment node-name, next, previous, up
317 @subsubsection Unix-style Command Line Protocol
318 @vindex sb-ext:*posix-argv*
321 Standard Unix tools that are interpreters follow a common command line
322 protocol that is necessary to work with ``shebang scripts''. SBCL
323 doesn't do this by default, but adding the following snippet to an
324 initialization file does the trick:
327 ;;; If the first user-processable command-line argument is a filename,
328 ;;; disable the debugger, load the file handling shebang-line and quit.
329 (let ((script (and (second *posix-argv*)
330 (probe-file (second *posix-argv*)))))
332 ;; Handle shebang-line
333 (set-dispatch-macro-character #\# #\!
334 (lambda (stream char arg)
335 (declare (ignore char arg))
338 (setf *invoke-debugger-hook*
339 (lambda (condition hook)
340 (declare (ignore hook))
341 ;; Uncomment to get backtraces on errors
342 ;; (sb-debug:backtrace 20)
343 (format *error-output* "Error: ~A~%" condition)
349 Example file (@file{hello.lisp}):
352 #!/usr/local/bin/sbcl --noinform
353 (write-line "Hello, World!")
365 This is SBCL 0.8.13.70, an implementation of ANSI Common Lisp.
366 More information about SBCL is available at <http://www.sbcl.org/>.
368 SBCL is free software, provided as is, with absolutely no warranty.
369 It is mostly in the public domain; some portions are provided under
370 BSD-style licenses. See the CREDITS and COPYING files in the
371 distribution for more information.
376 @node Automatic Recompilation of Stale Fasls
377 @comment node-name, next, previous, up
378 @subsubsection Automatic Recompilation of Stale Fasls
380 SBCL fasl-format is at current stage of development undergoing
381 non-backwards compatible changes fairly often. The following snippet
382 handles recompilation automatically for ASDF-based systems.
387 ;;; If a fasl was stale, try to recompile and load (once).
388 (defmethod asdf:perform :around ((o asdf:load-op)
389 (c asdf:cl-source-file))
390 (handler-case (call-next-method o c)
391 ;; If a fasl was stale, try to recompile and load (once).
392 (sb-ext:invalid-fasl ()
393 (asdf:perform (make-instance 'asdf:compile-op) c)
394 (call-next-method))))
397 @node Initialization and Exit Hooks
398 @comment node-name, next, previous, up
399 @section Initialization and Exit Hooks
401 SBCL provides hooks into the system initialization and exit.
403 @include var-sb-ext-star-init-hooks-star.texinfo
404 @include var-sb-ext-star-exit-hooks-star.texinfo