Don't hardcode the number of gencgc generations.
[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 * (exit)
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 @sbext{@earmuffs{posix-argv}}
70
71 Standard Unix tools that are interpreters follow a common command line
72 protocol that is necessary to work with ``shebang scripts''. SBCL supports
73 this via the @code{--script} command line option.
74
75 Example file (@file{hello.lisp}):
76
77 @lisp
78 #!/usr/local/bin/sbcl --script
79 (write-line "Hello, World!")
80 @end lisp
81
82 Usage examples:
83
84 @smallexample
85 $ ./hello.lisp
86 Hello, World!
87 @end smallexample
88
89 @smallexample
90 $ sbcl --script hello.lisp
91 Hello, World!
92 @end smallexample
93
94 @node Stopping SBCL
95 @comment  node-name,  next,  previous,  up
96 @section Stopping SBCL
97
98 @menu
99 * Exit::
100 * End of File::                 
101 * Saving a Core Image::         
102 * Exit on Errors::              
103 @end menu
104
105 @node Exit
106 @comment  node-name,  next,  previous,  up
107 @subsection Exit
108
109 SBCL can be stopped at any time by calling @code{sb-ext:exit},
110 optionally returning a specified numeric value to the calling process.
111 See @ref{Threading} for information about terminating individual threads.
112
113 @include fun-sb-ext-exit.texinfo
114
115 @node End of File
116 @comment  node-name,  next,  previous,  up
117 @subsection End of File
118
119 By default SBCL also exits on end of input, caused either by user
120 pressing @kbd{Control-D} on an attached terminal, or end of input when
121 using SBCL as part of a shell pipeline.
122
123 @node Saving a Core Image
124 @comment  node-name,  next,  previous,  up
125 @subsection Saving a Core Image
126
127 SBCL has the ability to save its state as a file for later
128 execution. This functionality is important for its bootstrapping
129 process, and is also provided as an extension to the user.
130
131 @include fun-sb-ext-save-lisp-and-die.texinfo
132 @include var-sb-ext-star-save-hooks-star.texinfo
133
134 In cases where the standard initialization files have already been loaded
135 into the saved core, and alternative ones should be used (or none at all),
136 SBCL allows customizing the initfile pathname computation.
137
138 @include var-sb-ext-star-sysinit-pathname-function-star.texinfo
139 @include var-sb-ext-star-userinit-pathname-function-star.texinfo
140
141 To facilitate distribution of SBCL applications using external
142 resources, the filesystem location of the SBCL core file being used is
143 available from Lisp.
144
145 @include var-sb-ext-star-core-pathname-star.texinfo
146
147 @node Exit on Errors
148 @comment  node-name,  next,  previous,  up
149 @subsection Exit on Errors
150
151 SBCL can also be configured to exit if an unhandled error occurs,
152 which is mainly useful for acting as part of a shell pipeline; doing
153 so under most other circumstances would mean giving up large parts of
154 the flexibility and robustness of Common Lisp. See @ref{Debugger Entry}.
155
156 @node Command Line Options
157 @comment  node-name,  next,  previous,  up
158 @section Command Line Options
159
160 @c FIXME: This is essentially cut-and-paste from the manpage
161 @c What should probably be done is generate both this and the
162 @c man-page from ``sbcl --help'' output.
163
164 Command line options can be considered an advanced topic; for ordinary
165 interactive use, no command line arguments should be necessary.
166
167 In order to understand the command line argument syntax for SBCL, it
168 is helpful to understand that the SBCL system is implemented as two
169 components, a low-level runtime environment written in C and a
170 higher-level system written in Common Lisp itself. Some command line
171 arguments are processed during the initialization of the low-level
172 runtime environment, some command line arguments are processed during
173 the initialization of the Common Lisp system, and any remaining
174 command line arguments are passed on to user code.
175
176 The full, unambiguous syntax for invoking SBCL at the command line is:
177
178 @command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-options}*
179
180 For convenience, the @code{--end-runtime-options} and
181 @code{--end-toplevel-options} elements can be omitted. Omitting these
182 elements can be convenient when you are running the program
183 interactively, and you can see that no ambiguities are possible with
184 the option values you are using. Omitting these elements is probably a
185 bad idea for any batch file where any of the options are under user
186 control, since it makes it impossible for SBCL to detect erroneous
187 command line input, so that erroneous command line arguments will be
188 passed on to the user program even if they was intended for the
189 runtime system or the Lisp system.
190
191 @menu
192 * Runtime Options::             
193 * Toplevel Options::            
194 @end menu
195
196 @node Runtime Options
197 @comment  node-name,  next,  previous,  up
198 @subsection Runtime Options
199
200 @table @code
201
202 @item --core @var{corefilename}
203 Run the specified Lisp core file instead of the default. Note that if
204 the Lisp core file is a user-created core file, it may run a
205 nonstandard toplevel which does not recognize the standard toplevel
206 options.
207
208 @item --dynamic-space-size @var{megabytes}
209 Size of the dynamic space reserved on startup in megabytes. Default
210 value is platform dependent.
211
212 @item --control-stack-size @var{megabytes}
213 Size of control stack reserved for each thread in megabytes. Default
214 value is 2.
215
216 @item --noinform
217 Suppress the printing of any banner or other informational message at
218 startup. This makes it easier to write Lisp programs which work
219 cleanly in Unix pipelines. See also the @code{--noprint} and
220 @code{--disable-debugger} options.
221
222 @item --disable-ldb
223 @cindex ldb
224 @cindex ldb, disabling
225 @cindex disabling ldb
226 Disable the low-level debugger. Only effective if SBCL is compiled
227 with LDB.
228
229 @item --lose-on-corruption
230 @cindex ldb
231 There are some dangerous low level errors (for instance, control stack
232 exhausted, memory fault) that (or whose handlers) can corrupt the
233 image. By default SBCL prints a warning, then tries to continue and
234 handle the error in Lisp, but this will not always work and SBCL may
235 malfunction or even hang. With this option, upon encountering such an
236 error SBCL will invoke ldb (if present and enabled) or else exit.
237
238
239 @item --script @var{filename}
240 As a runtime option this is equivalent to @code{--noinform}
241 @code{--disable-ldb} @code{--lose-on-corruption}
242 @code{--end-runtime-options} @code{--script} @var{filename}. See the
243 description of @code{--script} as a toplevel option below. If there
244 are no other commandline arguments following @code{--script}, the
245 filename argument can be omitted.
246
247
248 @item --merge-core-pages
249 When platform support is present, provide hints to the operating system
250 that identical pages may be shared between processes until they are
251 written to.  This can be useful to reduce the memory usage on systems
252 with multiple SBCL processes started from similar but differently-named
253 core files, or from compressed cores.  Without platform support, do
254 nothing.
255
256
257 @item --no-merge-core-pages
258 Ensures that no sharing hint is provided to the operating system.
259
260
261 @item --default-merge-core-pages
262 Reverts the sharing hint policy to the default: only compressed cores
263 trigger hinting.  Uncompressed cores are mapped directly from the core
264 file, which is usually enough to ensure sharing.
265
266
267 @item --help
268 Print some basic information about SBCL, then exit.
269
270 @item --version
271 Print SBCL's version information, then exit.
272
273 @end table
274
275 In the future, runtime options may be added to control behaviour such
276 as lazy allocation of memory.
277
278 Runtime options, including any --end-runtime-options option, are
279 stripped out of the command line before the Lisp toplevel logic gets a
280 chance to see it.
281
282 @node Toplevel Options
283 @comment  node-name,  next,  previous,  up
284 @subsection Toplevel Options
285
286 @table @code
287
288 @item --sysinit @var{filename}
289 Load filename instead of the default system initialization file
290 (@pxref{Initialization Files}.)
291
292 @item --no-sysinit
293 Don't load a system-wide initialization file.  If this option is given,
294 the @code{--sysinit} option is ignored.
295
296 @item --userinit @var{filename}
297 Load filename instead of the default user initialization file
298 (@pxref{Initialization Files}.)
299
300 @item --no-userinit
301 Don't load a user initialization file.  If this option is given,
302 the @code{--userinit} option is ignored.
303
304 @item --eval @var{command}
305 After executing any initialization file, but before starting the
306 read-eval-print loop on standard input, read and evaluate the command
307 given. More than one @code{--eval} option can be used, and all will be
308 read and executed, in the order they appear on the command line.
309
310 @item --load @var{filename}
311 This is equivalent to @code{--eval '(load "@var{filename}")'}. The
312 special syntax is intended to reduce quoting headaches when invoking
313 SBCL from shell scripts.
314
315 @item --noprint
316 When ordinarily the toplevel "read-eval-print loop" would be executed,
317 execute a "read-eval loop" instead, i.e. don't print a prompt and
318 don't echo results. Combined with the @code{--noinform} runtime
319 option, this makes it easier to write Lisp "scripts" which work
320 cleanly in Unix pipelines.
321
322 @item --disable-debugger
323 By default when SBCL encounters an error, it enters the builtin
324 debugger, allowing interactive diagnosis and possible intercession.
325 This option disables the debugger, causing errors to print a backtrace
326 and exit with status 1 instead. When given, this option takes effect
327 before loading of initialization files or processing @code{--eval} and
328 @code{--load} options. See @code{sb-ext:disable-debugger} for details.
329 @xref{Debugger Entry}.
330
331 @item --script @var{filename}
332 Implies @code{--no-userinit} @code{--no-sysinit}
333 @code{--disable-debugger} @code{--end-toplevel-options}.
334
335 Causes the system to load the specified file instead of entering the
336 read-eval-print-loop, and exit afterwards. If the file begins with a
337 shebang line, it is ignored.
338
339 If there are no other command line arguments following, the filename
340 can be omitted: this causes the script to be loaded from standard
341 input instead. Shebang lines in standard input script are currently
342 @emph{not} ignored.
343
344 In either case, if there is an unhandled error (e.g. end of file, or a
345 broken pipe) on either standard input, standard output, or standard
346 error, the script silently exits with code 0. This allows e.g. safely
347 piping output from SBCL to @code{head -n1} or similar.
348
349 @end table
350
351 @node Initialization Files
352 @comment  node-name,  next,  previous,  up
353 @section Initialization Files
354
355 SBCL processes initialization files with @code{read} and @code{eval},
356 not @code{load}; hence initialization files can be used to set startup
357 @code{*package*} and @code{*readtable*}, and for proclaiming a global
358 optimization policy.
359
360 @itemize @w{}
361 @item
362 @strong{System Initialization File}
363
364 Defaults to @file{@env{$SBCL_HOME}/sbclrc}, or if that doesn't exist to
365 @file{/etc/sbclrc}. Can be overridden with the command line option
366 @code{--sysinit} or @code{--no-sysinit}.
367
368 The system initialization file is intended for system administrators
369 and software packagers to configure locations of installed third party
370 modules, etc.
371
372 @item
373 @strong{User Initialization File}
374
375 Defaults to @file{@env{$HOME}/.sbclrc}. Can be overridden with the
376 command line option @code{--userinit} or @code{--no-userinit}.
377
378 The user initialization file is intended for personal customizations,
379 such as loading certain modules at startup, defining convenience
380 functions to use in the REPL, handling automatic recompilation
381 of FASLs (@pxref{FASL Format}), etc.
382
383 @end itemize
384
385 Neither initialization file is required.
386
387 @node Initialization and Exit Hooks
388 @comment  node-name,  next,  previous,  up
389 @section Initialization and Exit Hooks
390
391 SBCL provides hooks into the system initialization and exit.
392
393 @include var-sb-ext-star-init-hooks-star.texinfo
394 @include var-sb-ext-star-exit-hooks-star.texinfo
395