1.0.10.27: Change unportable find option "-path"
[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 @end menu
11
12 @node Starting SBCL
13 @comment  node-name,  next,  previous,  up
14 @section Starting SBCL
15
16 @menu
17 * Running from Shell::          
18 * Running from Emacs::          
19 * Shebang Scripts::             
20 @end menu
21
22 @node Running from Shell
23 @comment  node-name,  next,  previous,  up
24 @subsection From Shell to Lisp
25
26 To run SBCL type @command{sbcl} at the command line.
27
28 You should end up in the toplevel @dfn{REPL} (read, eval, print
29 -loop), where you can interact with SBCL by typing expressions.
30
31 @smallexample
32 $ sbcl
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/>.
35
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.
40 * (+ 2 2)
41
42 4
43 * (quit)
44 $
45 @end smallexample
46
47 See also @ref{Command Line Options} and @ref{Stopping SBCL}.
48
49 @node Running from Emacs
50 @comment  node-name,  next,  previous,  up
51 @subsection Running from Emacs
52
53 To run SBCL as an inferior-lisp from Emacs in your @file{.emacs} do
54 something like:
55
56 @lisp
57 ;;; The SBCL binary and command-line arguments
58 (setq inferior-lisp-program "/usr/local/bin/sbcl --noinform")
59 @end lisp
60
61 For more information on using SBCL with Emacs, see @ref{Editor
62 Integration}.
63
64
65 @node Shebang Scripts
66 @comment  node-name,  next,  previous,  up
67 @subsection Shebang Scripts
68
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
72 an example.)
73
74
75 @node Stopping SBCL
76 @comment  node-name,  next,  previous,  up
77 @section Stopping SBCL
78
79 @menu
80 * Quit::                        
81 * End of File::
82 * Saving a Core Image::              
83 * Exit on Errors::
84 @end menu
85
86 @node Quit
87 @comment  node-name,  next,  previous,  up
88 @subsection Quit
89
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
93 feature and sessions.
94
95 @include fun-sb-ext-quit.texinfo
96
97 @node End of File
98 @comment  node-name,  next,  previous,  up
99 @subsection End of File
100
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.
104
105 @node Saving a Core Image
106 @comment  node-name,  next,  previous,  up
107 @subsection Saving a Core Image
108
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.  
112
113 @include fun-sb-ext-save-lisp-and-die.texinfo
114
115 To facilitate distribution of SBCL applications using external
116 resources, the filesystem location of the SBCL core file being used is
117 available from Lisp.
118
119 @include var-sb-ext-star-core-pathname-star.texinfo
120
121 @node Exit on Errors
122 @comment  node-name,  next,  previous,  up
123 @subsection Exit on Errors
124
125 SBCL can also be configured to exit if an unhandled error occurs,
126 which is mainly useful for acting as part of a shell pipeline; doing
127 so under most other circumstances would mean giving up large parts of
128 the flexibility and robustness of Common Lisp. See @ref{Debugger Entry}.
129
130 @node Command Line Options
131 @comment  node-name,  next,  previous,  up
132 @section Command Line Options
133
134 @c FIXME: This is essentially cut-and-paste from the manpage
135 @c What should probably be done is generate both this and the
136 @c man-page from ``sbcl --help'' output.
137
138 Command line options can be considered an advanced topic; for ordinary
139 interactive use, no command line arguments should be necessary.
140
141 In order to understand the command line argument syntax for SBCL, it
142 is helpful to understand that the SBCL system is implemented as two
143 components, a low-level runtime environment written in C and a
144 higher-level system written in Common Lisp itself. Some command line
145 arguments are processed during the initialization of the low-level
146 runtime environment, some command line arguments are processed during
147 the initialization of the Common Lisp system, and any remaining
148 command line arguments are passed on to user code.
149
150 The full, unambiguous syntax for invoking SBCL at the command line is:
151
152 @command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-options}*
153
154 For convenience, the @code{--end-runtime-options} and
155 @code{--end-toplevel-options} elements can be omitted. Omitting these
156 elements can be convenient when you are running the program
157 interactively, and you can see that no ambiguities are possible with
158 the option values you are using. Omitting these elements is probably a
159 bad idea for any batch file where any of the options are under user
160 control, since it makes it impossible for SBCL to detect erroneous
161 command line input, so that erroneous command line arguments will be
162 passed on to the user program even if they was intended for the
163 runtime system or the Lisp system.
164
165 @menu
166 * Runtime Options::             
167 * Toplevel Options::            
168 @end menu
169
170 @node Runtime Options
171 @comment  node-name,  next,  previous,  up
172 @subsection Runtime Options
173
174 @table @code
175
176 @item --core @var{corefilename}
177 Run the specified Lisp core file instead of the default. Note that if
178 the Lisp core file is a user-created core file, it may run a
179 nonstandard toplevel which does not recognize the standard toplevel
180 options.
181
182 @item --dynamic-space-size @var{megabytes}
183 Size of the dynamic space reserved on startup in megabytes. Default
184 value is platform dependent.
185
186 @item --noinform
187 Suppress the printing of any banner or other informational message at
188 startup. This makes it easier to write Lisp programs which work
189 cleanly in Unix pipelines. See also the @code{--noprint} and
190 @code{--disable-debugger} options.
191
192 @item --help
193 Print some basic information about SBCL, then exit.
194
195 @item --version
196 Print SBCL's version information, then exit.
197
198 @end table
199
200 In the future, runtime options may be added to control behaviour such
201 as lazy allocation of memory.
202
203 Runtime options, including any --end-runtime-options option, are
204 stripped out of the command line before the Lisp toplevel logic gets a
205 chance to see it.
206
207 @node Toplevel Options
208 @comment  node-name,  next,  previous,  up
209 @subsection Toplevel Options
210
211 @table @code
212
213 @item --sysinit @var{filename}
214 Load filename instead of the default system initialization file
215 (@pxref{System Initialization File}.)
216
217 @item --no-sysinit
218 Don't load a system-wide initialization file.  If this option is given,
219 the @code{--sysinit} option is ignored.
220
221 @item --userinit @var{filename}
222 Load filename instead of the default user initialization file
223 (@pxref{User Initialization File}.)
224
225 @item --no-userinit
226 Don't load a user initialization file.  If this option is given,
227 the @code{--userinit} option is ignored.
228
229 @item --eval @var{command}
230 After executing any initialization file, but before starting the
231 read-eval-print loop on standard input, read and evaluate the com-
232 mand given. More than one @code{--eval} option can be used, and all
233 will be read and executed, in the order they appear on the command
234 line.
235
236 @item --load @var{filename}
237 This is equivalent to @code{--eval '(load "@var{filename}")'}. The
238 special syntax is intended to reduce quoting headaches when invoking
239 SBCL from shell scripts.
240
241 @item --noprint
242 When ordinarily the toplevel "read-eval-print loop" would be exe-
243 cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
244 and don't echo results. Combined with the @code{--noinform} runtime
245 option, this makes it easier to write Lisp "scripts" which work
246 cleanly in Unix pipelines.
247
248 @item --disable-debugger
249 This is equivalent to @code{--eval '(sb-ext:disable-debugger)'}.
250 @xref{Debugger Entry}.
251
252 @end table
253
254
255 @node Initialization Files
256 @comment  node-name,  next,  previous,  up
257 @section Initialization Files
258
259 This section covers initialization files processed at startup, which
260 can be used to customize the lisp environment.
261
262 @menu
263 * System Initialization File::  
264 * User Initialization File::    
265 * Initialization File Semantics::  
266 * Initialization Examples::     
267 @end menu
268
269 @node System Initialization File
270 @comment  node-name,  next,  previous,  up
271 @subsection System Initialization File
272
273 Site-wide startup script. Unless overridden with the command line
274 option @code{--sysinit} defaults to @file{@env{SBCL_HOME}/sbclrc}, or
275 if that doesn't exist to @file{/etc/sbclrc}.
276
277 No system initialization file is required.
278
279 @node User Initialization File
280 @comment  node-name,  next,  previous,  up
281 @subsection User Initialization File
282
283 Per-user startup script. Unless overridden with the command line
284 option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
285
286 No user initialization file is required.
287
288 @node Initialization File Semantics
289 @comment  node-name,  next,  previous,  up
290 @subsection Initialization File Semantics
291
292 SBCL processes initialization files with @code{read} and @code{eval},
293 not @code{load}; hence initialization files can be used to set startup
294 @code{*package*} and @code{*readtable*}, and for proclaiming a global
295 optimization policy.
296
297 @node Initialization Examples
298 @comment  node-name,  next,  previous,  up
299 @subsection Initialization Examples
300
301 Some examples of what you may consider doing in the initialization
302 files follow.
303
304 @menu
305 * Unix-style Command Line Protocol::  
306 * Automatic Recompilation of Stale Fasls::  
307 @end menu
308
309 @node Unix-style Command Line Protocol
310 @comment  node-name,  next,  previous,  up
311 @subsubsection Unix-style Command Line Protocol
312
313 Standard Unix tools that are interpreters follow a common command line
314 protocol that is necessary to work with ``shebang scripts''. SBCL
315 doesn't do this by default, but adding the following snippet to an
316 initialization file does the trick:
317
318 @lisp
319 ;;; If the first user-processable command-line argument is a filename,
320 ;;; disable the debugger, load the file handling shebang-line and quit.
321 (let ((script (and (second *posix-argv*) 
322                    (probe-file (second *posix-argv*)))))
323    (when script
324       ;; Handle shebang-line
325       (set-dispatch-macro-character #\# #\!
326                                     (lambda (stream char arg)
327                                        (declare (ignore char arg))
328                                        (read-line stream)))
329       ;; Disable debugger
330       (setf *invoke-debugger-hook* 
331             (lambda (condition hook)
332               (declare (ignore hook))
333               ;; Uncomment to get backtraces on errors
334               ;; (sb-debug:backtrace 20)
335               (format *error-output* "Error: ~A~%" condition)
336               (quit)))
337       (load script)
338       (quit)))
339 @end lisp
340
341 Example file (@file{hello.lisp}):
342
343 @lisp
344 #!/usr/local/bin/sbcl --noinform
345 (write-line "Hello, World!")
346 @end lisp
347
348 Usage examples:
349
350 @smallexample
351 $ ./hello.lisp
352 Hello, World!
353 @end smallexample
354
355 @smallexample
356 $ sbcl hello.lisp
357 This is SBCL 0.8.13.70, an implementation of ANSI Common Lisp.
358 More information about SBCL is available at <http://www.sbcl.org/>.
359
360 SBCL is free software, provided as is, with absolutely no warranty.
361 It is mostly in the public domain; some portions are provided under
362 BSD-style licenses.  See the CREDITS and COPYING files in the
363 distribution for more information.
364 Hello, World!
365 @end smallexample
366
367
368 @node Automatic Recompilation of Stale Fasls
369 @comment  node-name,  next,  previous,  up
370 @subsubsection Automatic Recompilation of Stale Fasls
371
372 SBCL fasl-format is at current stage of development undergoing
373 non-backwards compatible changes fairly often. The following snippet
374 handles recompilation automatically for ASDF-based systems.
375
376 @lisp
377 (require :asdf)
378
379 ;;; If a fasl was stale, try to recompile and load (once). 
380 (defmethod asdf:perform :around ((o asdf:load-op) 
381                                  (c asdf:cl-source-file))
382    (handler-case (call-next-method o c)
383       ;; If a fasl was stale, try to recompile and load (once).
384       (sb-ext:invalid-fasl ()
385          (asdf:perform (make-instance 'asdf:compile-op) c)
386          (call-next-method))))
387 @end lisp