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 sb-ext:*posix-argv*
72 Standard Unix tools that are interpreters follow a common command line
73 protocol that is necessary to work with ``shebang scripts''. SBCL supports
74 this via the @code{--script} command line option.
76 Example file (@file{hello.lisp}):
79 #!/usr/local/bin/sbcl --script
80 (write-line "Hello, World!")
91 $ sbcl --script hello.lisp
96 @comment node-name, next, previous, up
97 @section Stopping SBCL
102 * Saving a Core Image::
107 @comment node-name, next, previous, up
110 SBCL can be stopped at any time by calling @code{sb-ext:quit},
111 optionally returning a specified numeric value to the calling process.
112 See notes in @ref{Threading} about the interaction between this
113 feature and sessions.
115 @include fun-sb-ext-quit.texinfo
118 @comment node-name, next, previous, up
119 @subsection End of File
121 By default SBCL also exits on end of input, caused either by user
122 pressing @kbd{Control-D} on an attached terminal, or end of input when
123 using SBCL as part of a shell pipeline.
125 @node Saving a Core Image
126 @comment node-name, next, previous, up
127 @subsection Saving a Core Image
129 SBCL has the ability to save its state as a file for later
130 execution. This functionality is important for its bootstrapping
131 process, and is also provided as an extension to the user.
133 @include fun-sb-ext-save-lisp-and-die.texinfo
134 @include var-sb-ext-star-save-hooks-star.texinfo
136 To facilitate distribution of SBCL applications using external
137 resources, the filesystem location of the SBCL core file being used is
140 @include var-sb-ext-star-core-pathname-star.texinfo
143 @comment node-name, next, previous, up
144 @subsection Exit on Errors
146 SBCL can also be configured to exit if an unhandled error occurs,
147 which is mainly useful for acting as part of a shell pipeline; doing
148 so under most other circumstances would mean giving up large parts of
149 the flexibility and robustness of Common Lisp. See @ref{Debugger Entry}.
151 @node Command Line Options
152 @comment node-name, next, previous, up
153 @section Command Line Options
155 @c FIXME: This is essentially cut-and-paste from the manpage
156 @c What should probably be done is generate both this and the
157 @c man-page from ``sbcl --help'' output.
159 Command line options can be considered an advanced topic; for ordinary
160 interactive use, no command line arguments should be necessary.
162 In order to understand the command line argument syntax for SBCL, it
163 is helpful to understand that the SBCL system is implemented as two
164 components, a low-level runtime environment written in C and a
165 higher-level system written in Common Lisp itself. Some command line
166 arguments are processed during the initialization of the low-level
167 runtime environment, some command line arguments are processed during
168 the initialization of the Common Lisp system, and any remaining
169 command line arguments are passed on to user code.
171 The full, unambiguous syntax for invoking SBCL at the command line is:
173 @command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-options}*
175 For convenience, the @code{--end-runtime-options} and
176 @code{--end-toplevel-options} elements can be omitted. Omitting these
177 elements can be convenient when you are running the program
178 interactively, and you can see that no ambiguities are possible with
179 the option values you are using. Omitting these elements is probably a
180 bad idea for any batch file where any of the options are under user
181 control, since it makes it impossible for SBCL to detect erroneous
182 command line input, so that erroneous command line arguments will be
183 passed on to the user program even if they was intended for the
184 runtime system or the Lisp system.
191 @node Runtime Options
192 @comment node-name, next, previous, up
193 @subsection Runtime Options
197 @item --core @var{corefilename}
198 Run the specified Lisp core file instead of the default. Note that if
199 the Lisp core file is a user-created core file, it may run a
200 nonstandard toplevel which does not recognize the standard toplevel
203 @item --dynamic-space-size @var{megabytes}
204 Size of the dynamic space reserved on startup in megabytes. Default
205 value is platform dependent.
207 @item --control-stack-size @var{megabytes}
208 Size of control stack reserved for each thread in megabytes. Default
212 Suppress the printing of any banner or other informational message at
213 startup. This makes it easier to write Lisp programs which work
214 cleanly in Unix pipelines. See also the @code{--noprint} and
215 @code{--disable-debugger} options.
217 @item --script @var{filename}
218 As a runtime option this is equivalent to @code{--noinform}
219 @code{--end-runtime-options} @code{--script} @var{filename}. See the
220 description of @code{--script} as a toplevel option below.
223 Print some basic information about SBCL, then exit.
226 Print SBCL's version information, then exit.
230 In the future, runtime options may be added to control behaviour such
231 as lazy allocation of memory.
233 Runtime options, including any --end-runtime-options option, are
234 stripped out of the command line before the Lisp toplevel logic gets a
237 @node Toplevel Options
238 @comment node-name, next, previous, up
239 @subsection Toplevel Options
243 @item --sysinit @var{filename}
244 Load filename instead of the default system initialization file
245 (@pxref{System Initialization File}.)
248 Don't load a system-wide initialization file. If this option is given,
249 the @code{--sysinit} option is ignored.
251 @item --userinit @var{filename}
252 Load filename instead of the default user initialization file
253 (@pxref{User Initialization File}.)
256 Don't load a user initialization file. If this option is given,
257 the @code{--userinit} option is ignored.
259 @item --eval @var{command}
260 After executing any initialization file, but before starting the
261 read-eval-print loop on standard input, read and evaluate the com-
262 mand given. More than one @code{--eval} option can be used, and all
263 will be read and executed, in the order they appear on the command
266 @item --load @var{filename}
267 This is equivalent to @code{--eval '(load "@var{filename}")'}. The
268 special syntax is intended to reduce quoting headaches when invoking
269 SBCL from shell scripts.
272 When ordinarily the toplevel "read-eval-print loop" would be exe-
273 cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
274 and don't echo results. Combined with the @code{--noinform} runtime
275 option, this makes it easier to write Lisp "scripts" which work
276 cleanly in Unix pipelines.
278 @item --disable-debugger
279 By default when SBCL encounters an error, it enters the builtin
280 debugger, allowing interactive diagnosis and possible intercession.
281 This option disables the debugger, causing errors to print a backtrace
282 and exit with status 1 instead. When given, this option takes effect
283 before loading of initialization files or processing @code{--eval} and
284 @code{--load} options. See @code{sb-ext:disable-debugger} for details.
285 @xref{Debugger Entry}.
287 @item --script @var{filename}
288 Implies @code{--no-userinit} @code{--no-sysinit}
289 @code{--disable-debugger} @code{--end-toplevel-options}.
291 Causes the system to load the specified file instead of entering the
292 read-eval-print-loop, and exit afterwards. If the file begins with a
293 shebang line, it is ignored.
298 @node Initialization Files
299 @comment node-name, next, previous, up
300 @section Initialization Files
302 This section covers initialization files processed at startup, which
303 can be used to customize the lisp environment.
306 * System Initialization File::
307 * User Initialization File::
308 * Initialization File Semantics::
309 * Initialization Examples::
312 @node System Initialization File
313 @comment node-name, next, previous, up
314 @subsection System Initialization File
316 Site-wide startup script. Unless overridden with the command line
317 option @code{--sysinit} defaults to @file{@env{SBCL_HOME}/sbclrc}, or
318 if that doesn't exist to @file{/etc/sbclrc}.
320 No system initialization file is required.
322 @node User Initialization File
323 @comment node-name, next, previous, up
324 @subsection User Initialization File
326 Per-user startup script. Unless overridden with the command line
327 option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
329 No user initialization file is required.
331 @node Initialization File Semantics
332 @comment node-name, next, previous, up
333 @subsection Initialization File Semantics
335 SBCL processes initialization files with @code{read} and @code{eval},
336 not @code{load}; hence initialization files can be used to set startup
337 @code{*package*} and @code{*readtable*}, and for proclaiming a global
340 @node Initialization Examples
341 @comment node-name, next, previous, up
342 @subsection Initialization Examples
344 Some examples of what you may consider doing in the initialization
348 * Automatic Recompilation of Stale Fasls::
351 @node Automatic Recompilation of Stale Fasls
352 @comment node-name, next, previous, up
353 @subsubsection Automatic Recompilation of Stale Fasls
355 SBCL fasl-format is at current stage of development undergoing
356 non-backwards compatible changes fairly often. The following snippet
357 handles recompilation automatically for ASDF-based systems.
362 ;;; If a fasl was stale, try to recompile and load (once).
363 (defmethod asdf:perform :around ((o asdf:load-op)
364 (c asdf:cl-source-file))
365 (handler-case (call-next-method o c)
366 ;; If a fasl was stale, try to recompile and load (once).
367 (sb-ext:invalid-fasl ()
368 (asdf:perform (make-instance 'asdf:compile-op) c)
369 (call-next-method))))
372 @node Initialization and Exit Hooks
373 @comment node-name, next, previous, up
374 @section Initialization and Exit Hooks
376 SBCL provides hooks into the system initialization and exit.
378 @include var-sb-ext-star-init-hooks-star.texinfo
379 @include var-sb-ext-star-exit-hooks-star.texinfo