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