1 @node Starting and Stopping
2 @comment node-name, next, previous, up
3 @chapter Starting and Stopping
8 * Command Line Options::
9 * Initialization Files::
13 @comment node-name, next, previous, up
14 @section Starting SBCL
17 * Running from Shell::
18 * Running from Emacs::
22 @node Running from Shell
23 @comment node-name, next, previous, up
24 @subsection From Shell to Lisp
26 To run SBCL type @command{sbcl} at the command line.
28 You should end up in the toplevel @dfn{REPL} (read, eval, print
29 -loop), where you can interact with SBCL by typing expressions.
33 This is SBCL 0.8.13.60, an implementation of ANSI Common Lisp.
34 More information about SBCL is available at <http://www.sbcl.org/>.
36 SBCL is free software, provided as is, with absolutely no warranty.
37 It is mostly in the public domain; some portions are provided under
38 BSD-style licenses. See the CREDITS and COPYING files in the
39 distribution for more information.
47 See also @ref{Command Line Options} and @ref{Stopping SBCL}.
49 @node Running from Emacs
50 @comment node-name, next, previous, up
51 @subsection Running from Emacs
53 To run SBCL as an inferior-lisp from Emacs in your @file{.emacs} do
57 ;;; The SBCL binary and command-line arguments
58 (setq inferior-lisp-program "/usr/local/bin/sbcl --noinform")
61 For more information on using SBCL with Emacs, see @ref{Editor
66 @comment node-name, next, previous, up
67 @subsection Shebang Scripts
69 SBCL doesn't come with built-in support for shebang-line execution,
70 but this can be provided with a shell trampoline, or by dispatching
71 from initialization files (@pxref{Unix-style Command Line Protocol} for
76 @comment node-name, next, previous, up
77 @section Stopping SBCL
82 * Saving a Core Image::
87 @comment node-name, next, previous, up
90 SBCL can be stopped at any time by calling @code{sb-ext:quit},
91 optionally returning a specified numeric value to the calling process.
92 See notes in @ref{Threading} about the interaction between this
95 @include fun-sb-ext-quit.texinfo
98 @comment node-name, next, previous, up
99 @subsection End of File
101 By default SBCL also exits on end of input, caused either by user
102 pressing @kbd{Control-D} on an attached terminal, or end of input when
103 using SBCL as part of a shell pipeline.
105 @node Saving a Core Image
106 @comment node-name, next, previous, up
107 @subsection Saving a Core Image
109 SBCL has the ability to save its state as a file for later
110 execution. This functionality is important for its bootstrapping
111 process, and is also provided as an extension to the user.
113 @include fun-sb-ext-save-lisp-and-die.texinfo
116 @comment node-name, next, previous, up
117 @subsection Exit on Errors
119 SBCL can also be configured to exit if an unhandled error occurs,
120 which is mainly useful for acting as part of a shell pipeline; doing
121 so under most other circumstances would mean giving up large parts of
122 the flexibility and robustness of Common Lisp. See @ref{Debugger Entry}.
124 @node Command Line Options
125 @comment node-name, next, previous, up
126 @section Command Line Options
128 @c FIXME: This is essentially cut-and-paste from the manpage
129 @c What should probably be done is generate both this and the
130 @c man-page from ``sbcl --help'' output.
132 Command line options can be considered an advanced topic; for ordinary
133 interactive use, no command line arguments should be necessary.
135 In order to understand the command line argument syntax for SBCL, it
136 is helpful to understand that the SBCL system is implemented as two
137 components, a low-level runtime environment written in C and a
138 higher-level system written in Common Lisp itself. Some command line
139 arguments are processed during the initialization of the low-level
140 runtime environment, some command line arguments are processed during
141 the initialization of the Common Lisp system, and any remaining
142 command line arguments are passed on to user code.
144 The full, unambiguous syntax for invoking SBCL at the command line is:
146 @command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-options}*
148 For convenience, the @code{--end-runtime-options} and
149 @code{--end-toplevel-options} elements can be omitted. Omitting these
150 elements can be convenient when you are running the program
151 interactively, and you can see that no ambiguities are possible with
152 the option values you are using. Omitting these elements is probably a
153 bad idea for any batch file where any of the options are under user
154 control, since it makes it impossible for SBCL to detect erroneous
155 command line input, so that erroneous command line arguments will be
156 passed on to the user program even if they was intended for the
157 runtime system or the Lisp system.
164 @node Runtime Options
165 @comment node-name, next, previous, up
166 @subsection Runtime Options
170 @item --core @var{corefilename}
171 Run the specified Lisp core file instead of the default. Note that if
172 the Lisp core file is a user-created core file, it may run a
173 nonstandard toplevel which does not recognize the standard toplevel
177 Suppress the printing of any banner or other informational message at
178 startup. This makes it easier to write Lisp programs which work
179 cleanly in Unix pipelines. See also the @code{--noprint} and
180 @code{--disable-debugger} options.
183 Print some basic information about SBCL, then exit.
186 Print SBCL's version information, then exit.
190 In the future, runtime options may be added to control behaviour such
191 as lazy allocation of memory.
193 Runtime options, including any --end-runtime-options option, are
194 stripped out of the command line before the Lisp toplevel logic gets a
197 @node Toplevel Options
198 @comment node-name, next, previous, up
199 @subsection Toplevel Options
203 @item --sysinit @var{filename}
204 Load filename instead of the default system initialization file
205 (@pxref{System Initialization File}.) There is no special option to
206 cause no system initialization file to be read, but on a Unix
207 system ``@code{"--sysinit /dev/null}'' can be used to achieve the same
210 @item --userinit @var{filename}
211 Load filename instead of the default user initialization file
212 (@pxref{User Initialization File}.) There is no special option to
213 cause no user initialization file to be read, but ``@code{--userinit
214 /dev/null}'' can be used to achieve the same effect.
216 @item --eval @var{command}
217 After executing any initialization file, but before starting the
218 read-eval-print loop on standard input, read and evaluate the com-
219 mand given. More than one @code{--eval} option can be used, and all
220 will be read and executed, in the order they appear on the command
223 @item --load @var{filename}
224 This is equivalent to @code{--eval '(load "@var{filename}")'}. The
225 special syntax is intended to reduce quoting headaches when invoking
226 SBCL from shell scripts.
229 When ordinarily the toplevel "read-eval-print loop" would be exe-
230 cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
231 and don't echo results. Combined with the @code{--noinform} runtime
232 option, this makes it easier to write Lisp "scripts" which work
233 cleanly in Unix pipelines.
235 @item --disable-debugger
236 This is equivalent to @code{--eval '(sb-ext:disable-debugger)'}.
237 @xref{Debugger Entry}.
242 @node Initialization Files
243 @comment node-name, next, previous, up
244 @section Initialization Files
246 This section covers initialization files processed at startup, which
247 can be used to customize the lisp environment.
250 * System Initialization File::
251 * User Initialization File::
252 * Initialization File Semantics::
253 * Initialization Examples::
256 @node System Initialization File
257 @comment node-name, next, previous, up
258 @subsection System Initialization File
260 Site-wide startup script. Unless overridden with the command line
261 option @code{--sysinit} defaults to @file{@env{SBCL_HOME}/sbclrc}, or
262 if that doesn't exist to @file{/etc/sbclrc}.
264 No system initialization file is required.
266 @node User Initialization File
267 @comment node-name, next, previous, up
268 @subsection User Initialization File
270 Per-user startup script. Unless overridden with the command line
271 option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
273 No user initialization file is required.
275 @node Initialization File Semantics
276 @comment node-name, next, previous, up
277 @subsection Initialization File Semantics
279 SBCL processes initialization files with @code{read} and @code{eval},
280 not @code{load}; hence initialization files can be used to set startup
281 @code{*package*} and @code{*readtable*}, and for proclaiming a global
284 @node Initialization Examples
285 @comment node-name, next, previous, up
286 @subsection Initialization Examples
288 Some examples of what you may consider doing in the initialization
292 * Unix-style Command Line Protocol::
293 * Automatic Recompilation of Stale Fasls::
296 @node Unix-style Command Line Protocol
297 @comment node-name, next, previous, up
298 @subsubsection Unix-style Command Line Protocol
300 Standard Unix tools that are interpreters follow a common command line
301 protocol that is necessary to work with ``shebang scripts''. SBCL
302 doesn't do this by default, but adding the following snippet to an
303 initialization file does the trick:
306 ;;; If the first user-processable command-line argument is a filename,
307 ;;; disable the debugger, load the file handling shebang-line and quit.
308 (let ((script (and (second *posix-argv*)
309 (probe-file (second *posix-argv*)))))
311 ;; Handle shebang-line
312 (set-dispatch-macro-character #\# #\!
313 (lambda (stream char arg)
314 (declare (ignore char arg))
317 (setf *invoke-debugger-hook*
318 (lambda (condition hook)
319 (declare (ignore hook))
320 ;; Uncomment to get backtraces on errors
321 ;; (sb-debug:backtrace 20)
322 (format *error-output* "Error: ~A~%" condition)
328 Example file (@file{hello.lisp}):
331 #!/usr/local/bin/sbcl --noinform
332 (write-line "Hello, World!")
344 This is SBCL 0.8.13.70, an implementation of ANSI Common Lisp.
345 More information about SBCL is available at <http://www.sbcl.org/>.
347 SBCL is free software, provided as is, with absolutely no warranty.
348 It is mostly in the public domain; some portions are provided under
349 BSD-style licenses. See the CREDITS and COPYING files in the
350 distribution for more information.
355 @node Automatic Recompilation of Stale Fasls
356 @comment node-name, next, previous, up
357 @subsubsection Automatic Recompilation of Stale Fasls
359 SBCL fasl-format is at current stage of development undergoing
360 non-backwards compatible changes fairly often. The following snippet
361 handles recompilation automatically for ASDF-based systems.
366 ;;; If a fasl was stale, try to recompile and load (once).
367 (defmethod asdf:perform :around ((o asdf:load-op)
368 (c asdf:cl-source-file))
369 (handler-case (call-next-method o c)
370 ;; If a fasl was stale, try to recompile and load (once).
371 (sb-ext:invalid-fasl ()
372 (asdf:perform (make-instance 'asdf:compile-op) c)
373 (call-next-method))))