1 @node Starting and Stopping
2 @comment node-name, next, previous, up
3 @chapter Starting and Stoppping
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.
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.
49 See also @ref{Command Line Options} and @ref{Stopping SBCL}.
51 @node Running from Emacs
52 @comment node-name, next, previous, up
53 @subsection Running from Emacs
55 To run SBCL as an inferior-lisp from Emacs in your @file{.emacs} do
59 ;;; The SBCL binary and command-line arguments
60 (setq inferior-lisp-program "/usr/local/bin/sbcl --noinform")
63 For more information on using SBCL with Emacs, see @ref{Editor
68 @comment node-name, next, previous, up
69 @subsection Shebang Scripts
71 SBCL doesn't come with built-in support for shebang-line execution,
72 but this can be provided with a shell trampoline, or by dispatching
73 from initialization files (@pxref{Unix-style Command Line Protocol} for
78 @comment node-name, next, previous, up
79 @section Stopping SBCL
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.
108 @comment node-name, next, previous, up
109 @subsection Exit on Errors
111 SBCL can also be configured to exit if an unhandled error occurs,
112 which is mainly useful for acting as part of a shell pipeline; doing
113 so under most other circumstances would mean giving up large parts of
114 the flexibility and robustness of Common Lisp. See @ref{Customization
118 @node Command Line Options
119 @comment node-name, next, previous, up
120 @section Command Line Options
122 @c FIXME: This is essentially cut-and-paste from the manpage
123 @c What should probably be done is generate both this and the
124 @c man-page from ``sbcl --help'' output.
126 Command line options can be considered an advanced topic; for ordinary
127 interactive use, no command line arguments should be necessary.
129 In order to understand the command line argument syntax for SBCL, it
130 is helpful to understand that the SBCL system is implemented as two
131 components, a low-level runtime environment written in C and a
132 higher-level system written in Common Lisp itself. Some command line
133 arguments are processed during the initialization of the low-level
134 runtime environment, some command line arguments are processed during
135 the initialization of the Common Lisp system, and any remaining
136 command line arguments are passed on to user code.
138 The full, unambiguous syntax for invoking SBCL at the command line is:
140 @command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-options}*
142 For convenience, the @code{--end-runtime-options} and
143 @code{--end-toplevel-options} elements can be omitted. Omitting these
144 elements can be convenient when you are running the program
145 interactively, and you can see that no ambiguities are possible with
146 the option values you are using. Omitting these elements is probably a
147 bad idea for any batch file where any of the options are under user
148 control, since it makes it impossible for SBCL to detect erroneous
149 command line input, so that erroneous command line arguments will be
150 passed on to the user program even if they was intended for the
151 runtime system or the Lisp system.
158 @node Runtime Options
159 @comment node-name, next, previous, up
160 @subsection Runtime Options
164 @item --core @var{corefilename}
165 Run the specified Lisp core file instead of the default. Note that if
166 the Lisp core file is a user-created core file, it may run a
167 nonstandard toplevel which does not recognize the standard toplevel
171 Suppress the printing of any banner or other informational message at
172 startup. This makes it easier to write Lisp programs which work
173 cleanly in Unix pipelines. See also the @code{--noprint} and
174 @code{--disable-debugger} options.
177 Print some basic information about SBCL, then exit.
180 Print SBCL's version information, then exit.
184 In the future, runtime options may be added to control behavior such
185 as lazy allocation of memory.
187 Runtime options, including any --end-runtime-options option, are
188 stripped out of the command line before the Lisp toplevel logic gets a
191 @node Toplevel Options
192 @comment node-name, next, previous, up
193 @subsection Toplevel Options
197 @item --sysinit @var{filename}
198 Load filename instead of the default system initialization file
199 (@pxref{System Initialization File}.) There is no special option to
200 cause no system initialization file to be read, but on a Unix
201 system ``@code{"--sysinit /dev/null}'' can be used to achieve the same
204 @item --userinit @var{filename}
205 Load filename instead of the default user initialization file
206 (@pxref{User Initialization File}.) There is no special option to
207 cause no user initialization file to be read, but ``@code{--userinit
208 /dev/null}'' can be used to achieve the same effect.
210 @item --eval @var{command}
211 After executing any initialization file, but before starting the
212 read-eval-print loop on standard input, read and evaluate the com-
213 mand given. More than one @code{--eval} option can be used, and all
214 will be read and executed, in the order they appear on the command
217 @item --load @var{filename}
218 This is equivalent to @code{--eval '(load "@var{filename}")'}. The
219 special syntax is intended to reduce quoting headaches when invoking
220 SBCL from shell scripts.
223 When ordinarily the toplevel "read-eval-print loop" would be exe-
224 cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
225 and don't echo results. Combined with the @code{--noinform} runtime
226 option, this makes it easier to write Lisp "scripts" which work
227 cleanly in Unix pipelines.
229 @item --disable-debugger
230 This is equivalent to @code{--eval '(sb-ext:disable-debugger)'}.
231 @xref{Customization Hooks for Users}.
236 @node Initialization Files
237 @comment node-name, next, previous, up
238 @section Initialization Files
240 This section covers initialization files loaded at startup, which can
241 be used to customize the lisp environment.
244 * System Initialization File::
245 * User Initialization File::
246 * Initialization File Semantics::
247 * Initialization Examples::
250 @node System Initialization File
251 @comment node-name, next, previous, up
252 @subsection System Initialization File
254 Site-wide startup script. Unless overridden with the command line
255 option @code{--sysinit} defaults to @file{@env{SBCL_HOME}/sbclrc}, or
256 if that doesn't exist to @file{/etc/sbclrc}.
258 No system initialization file is required.
260 @node User Initialization File
261 @comment node-name, next, previous, up
262 @subsection User Initialization File
264 Per-user startup script. Unless overridden with the command line
265 option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
267 No user initialization file is required.
269 @node Initialization File Semantics
270 @comment node-name, next, previous, up
271 @subsection Initialization File Semantics
273 SBCL uses @code{load} to process its initialization files, which
274 has the unfortunate effect of preventing users from changing the
275 default startup @code{*package*}, and setting a default optimization
278 This is considered a bug and liable to change in the future.
280 @node Initialization Examples
281 @comment node-name, next, previous, up
282 @subsection Initialization Examples
284 Some examples of what you may consider doing in the initialization
288 * Unix-style Command Line Protocol::
289 * Automatic Recompilation of Stale Fasls::
292 @node Unix-style Command Line Protocol
293 @comment node-name, next, previous, up
294 @subsubsection Unix-style Command Line Protocol
296 Standard Unix tools that are interpeters follow a common command line
297 protocol that is necessary to work with ``shebang scripts''. SBCL
298 doesn't do this by default, but adding the following snippet to an
299 initialization file does the trick:
302 ;;; If the first user-processable command-line argument is a filename,
303 ;;; disable the debugger, load the file handling shebang-line and quit.
304 (let ((script (probe-file (second sb-ext:*posix-argv*))))
306 ;; Handle the possible shebang-line
307 (set-dispatch-macro-character #\# #\!
308 (lambda (stream char arg)
309 (declare (ignore char arg))
312 (setf sb-ext:*invoke-debugger-hook*
313 (lambda (condition hook)
314 (declare (ignore hook))
315 (format *error-output* "Error: ~A~%" condition)
316 (quit :unix-status 1)))
321 Example file (@file{hello.lisp}):
324 #!/usr/local/bin/sbcl --noinform
325 (write-line "Hello, World!")
340 This is SBCL 0.8.13.70, an implementation of ANSI Common Lisp.
341 More information about SBCL is available at <http://www.sbcl.org/>.
343 SBCL is free software, provided as is, with absolutely no warranty.
344 It is mostly in the public domain; some portions are provided under
345 BSD-style licenses. See the CREDITS and COPYING files in the
346 distribution for more information.
352 @node Automatic Recompilation of Stale Fasls
353 @comment node-name, next, previous, up
354 @subsubsection Automatic Recompilation of Stale Fasls
356 SBCL fasl-format is at current stage of development undergoing
357 non-backwards compatible changes fairly often. The following snippet
358 handles recompilation automatically for ASDF-based systems.
363 ;;; If a fasl was stale, try to recompile and load (once).
364 (defmethod asdf:perform :around ((o asdf:load-op) (c asdf:cl-source-file))
365 (handler-case (call-next-method o c)
366 (sb-ext:invalid-fasl error ()
367 (asdf:perform (make-instance 'asdf:compile-op) c)
368 (call-next-method))))