cd07851b5fdac33dd400026c2eaff329d781598e
[sbcl.git] / doc / manual / start-stop.texinfo
1 @node Starting and Stopping
2 @comment  node-name,  next,  previous,  up
3 @chapter Starting and Stopping
4
5 @menu
6 * Starting SBCL::               
7 * Stopping SBCL::               
8 * Command Line Options::        
9 * Initialization Files::        
10 * Initialization and Exit Hooks::  
11 @end menu
12
13 @node Starting SBCL
14 @comment  node-name,  next,  previous,  up
15 @section Starting SBCL
16
17 @menu
18 * Running from Shell::          
19 * Running from Emacs::          
20 * Shebang Scripts::             
21 @end menu
22
23 @node Running from Shell
24 @comment  node-name,  next,  previous,  up
25 @subsection From Shell to Lisp
26
27 To run SBCL type @command{sbcl} at the command line.
28
29 You should end up in the toplevel @dfn{REPL} (read, eval, print
30 -loop), where you can interact with SBCL by typing expressions.
31
32 @smallexample
33 $ sbcl
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/>.
36
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.
41 * (+ 2 2)
42
43 4
44 * (quit)
45 $
46 @end smallexample
47
48 See also @ref{Command Line Options} and @ref{Stopping SBCL}.
49
50 @node Running from Emacs
51 @comment  node-name,  next,  previous,  up
52 @subsection Running from Emacs
53
54 To run SBCL as an inferior-lisp from Emacs in your @file{.emacs} do
55 something like:
56
57 @lisp
58 ;;; The SBCL binary and command-line arguments
59 (setq inferior-lisp-program "/usr/local/bin/sbcl --noinform")
60 @end lisp
61
62 For more information on using SBCL with Emacs, see @ref{Editor
63 Integration}.
64
65
66 @node Shebang Scripts
67 @comment  node-name,  next,  previous,  up
68 @subsection Shebang Scripts
69 @vindex sb-ext:*posix-argv*
70 @vindex *posix-argv*
71
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.
75
76 Example file (@file{hello.lisp}):
77
78 @lisp
79 #!/usr/local/bin/sbcl --script
80 (write-line "Hello, World!")
81 @end lisp
82
83 Usage examples:
84
85 @smallexample
86 $ ./hello.lisp
87 Hello, World!
88 @end smallexample
89
90 @smallexample
91 $ sbcl --script hello.lisp
92 Hello, World!
93 @end smallexample
94
95 @node Stopping SBCL
96 @comment  node-name,  next,  previous,  up
97 @section Stopping SBCL
98
99 @menu
100 * Quit::                        
101 * End of File::                 
102 * Saving a Core Image::         
103 * Exit on Errors::              
104 @end menu
105
106 @node Quit
107 @comment  node-name,  next,  previous,  up
108 @subsection Quit
109
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.
114
115 @include fun-sb-ext-quit.texinfo
116
117 @node End of File
118 @comment  node-name,  next,  previous,  up
119 @subsection End of File
120
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.
124
125 @node Saving a Core Image
126 @comment  node-name,  next,  previous,  up
127 @subsection Saving a Core Image
128
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.
132
133 @include fun-sb-ext-save-lisp-and-die.texinfo
134 @include var-sb-ext-star-save-hooks-star.texinfo
135
136 To facilitate distribution of SBCL applications using external
137 resources, the filesystem location of the SBCL core file being used is
138 available from Lisp.
139
140 @include var-sb-ext-star-core-pathname-star.texinfo
141
142 @node Exit on Errors
143 @comment  node-name,  next,  previous,  up
144 @subsection Exit on Errors
145
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}.
150
151 @node Command Line Options
152 @comment  node-name,  next,  previous,  up
153 @section Command Line Options
154
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.
158
159 Command line options can be considered an advanced topic; for ordinary
160 interactive use, no command line arguments should be necessary.
161
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.
170
171 The full, unambiguous syntax for invoking SBCL at the command line is:
172
173 @command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-options}*
174
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.
185
186 @menu
187 * Runtime Options::             
188 * Toplevel Options::            
189 @end menu
190
191 @node Runtime Options
192 @comment  node-name,  next,  previous,  up
193 @subsection Runtime Options
194
195 @table @code
196
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
201 options.
202
203 @item --dynamic-space-size @var{megabytes}
204 Size of the dynamic space reserved on startup in megabytes. Default
205 value is platform dependent.
206
207 @item --control-stack-size @var{megabytes}
208 Size of control stack reserved for each thread in megabytes. Default
209 value is 2.
210
211 @item --noinform
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.
216
217 @item --disable-ldb
218 Disable the low-level debugger. Only effective if SBCL is compiled
219 with LDB.
220
221 @item --lose-on-corruption
222 There are some dangerous low level errors (for instance, control stack
223 exhausted, memory fault) that (or whose handlers) can corrupt the
224 image. By default SBCL prints a warning, then tries to continue and
225 handle the error in Lisp, but this will not always work and SBCL may
226 malfunction or even hang. With this option, upon encountering such an
227 error SBCL will invoke ldb (if present and enabled) or else exit.
228
229 @item --script @var{filename}
230 As a runtime option this is equivalent to @code{--noinform}
231 @code{--disable-ldb} @code{--lose-on-corruption}
232 @code{--end-runtime-options} @code{--script} @var{filename}. See the
233 description of @code{--script} as a toplevel option below.
234
235 @item --help
236 Print some basic information about SBCL, then exit.
237
238 @item --version
239 Print SBCL's version information, then exit.
240
241 @end table
242
243 In the future, runtime options may be added to control behaviour such
244 as lazy allocation of memory.
245
246 Runtime options, including any --end-runtime-options option, are
247 stripped out of the command line before the Lisp toplevel logic gets a
248 chance to see it.
249
250 @node Toplevel Options
251 @comment  node-name,  next,  previous,  up
252 @subsection Toplevel Options
253
254 @table @code
255
256 @item --sysinit @var{filename}
257 Load filename instead of the default system initialization file
258 (@pxref{Initialization Files}.)
259
260 @item --no-sysinit
261 Don't load a system-wide initialization file.  If this option is given,
262 the @code{--sysinit} option is ignored.
263
264 @item --userinit @var{filename}
265 Load filename instead of the default user initialization file
266 (@pxref{Initialization Files}.)
267
268 @item --no-userinit
269 Don't load a user initialization file.  If this option is given,
270 the @code{--userinit} option is ignored.
271
272 @item --eval @var{command}
273 After executing any initialization file, but before starting the
274 read-eval-print loop on standard input, read and evaluate the command
275 given. More than one @code{--eval} option can be used, and all will be
276 read and executed, in the order they appear on the command line.
277
278 @item --load @var{filename}
279 This is equivalent to @code{--eval '(load "@var{filename}")'}. The
280 special syntax is intended to reduce quoting headaches when invoking
281 SBCL from shell scripts.
282
283 @item --noprint
284 When ordinarily the toplevel "read-eval-print loop" would be exe-
285 cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
286 and don't echo results. Combined with the @code{--noinform} runtime
287 option, this makes it easier to write Lisp "scripts" which work
288 cleanly in Unix pipelines.
289
290 @item --disable-debugger
291 By default when SBCL encounters an error, it enters the builtin
292 debugger, allowing interactive diagnosis and possible intercession.
293 This option disables the debugger, causing errors to print a backtrace
294 and exit with status 1 instead. When given, this option takes effect
295 before loading of initialization files or processing @code{--eval} and
296 @code{--load} options. See @code{sb-ext:disable-debugger} for details.
297 @xref{Debugger Entry}.
298
299 @item --script @var{filename}
300 Implies @code{--no-userinit} @code{--no-sysinit}
301 @code{--disable-debugger} @code{--end-toplevel-options}.
302
303 Causes the system to load the specified file instead of entering the
304 read-eval-print-loop, and exit afterwards. If the file begins with a
305 shebang line, it is ignored.
306
307 @end table
308
309 @node Initialization Files
310 @comment  node-name,  next,  previous,  up
311 @section Initialization Files
312
313 SBCL processes initialization files with @code{read} and @code{eval},
314 not @code{load}; hence initialization files can be used to set startup
315 @code{*package*} and @code{*readtable*}, and for proclaiming a global
316 optimization policy.
317
318 @itemize @w{}
319 @item
320 @strong{System Initialization File}
321
322 Defaults to @file{@env{$SBCL_HOME}/sbclrc}, or if that doesn't exist to
323 @file{/etc/sbclrc}. Can be overridden with the command line option
324 @code{--sysinit} or @code{--no-sysinit}.
325
326 The system initialization file is intended for system administrators
327 and software packagers to configure locations of installed third party
328 modules, etc.
329
330 @item
331 @strong{User Initialization File}
332
333 Defaults to @file{@env{$HOME}/.sbclrc}. Can be overridden with the
334 command line option @code{--userinit} or @code{--no-userinit}.
335
336 The user initialization file is intended for personal customizations,
337 such as loading certain modules at startup, defining convenience
338 functions to use in the REPL, handling automatic recompilation
339 of FASLs (@pxref{FASL Format}), etc.
340
341 @end itemize
342
343 Neither initialization file is required.
344
345 @node Initialization and Exit Hooks
346 @comment  node-name,  next,  previous,  up
347 @section Initialization and Exit Hooks
348
349 SBCL provides hooks into the system initialization and exit.
350
351 @include var-sb-ext-star-init-hooks-star.texinfo
352 @include var-sb-ext-star-exit-hooks-star.texinfo
353