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{System Initialization File}.)
 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{User Initialization File}.)
 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 com-
 275 mand given. More than one @code{--eval} option can be used, and all
 276 will be read and executed, in the order they appear on the command
 277 line.
 278
 279 @item --load @var{filename}
 280 This is equivalent to @code{--eval '(load "@var{filename}")'}. The
 281 special syntax is intended to reduce quoting headaches when invoking
 282 SBCL from shell scripts.
 283
 284 @item --noprint
 285 When ordinarily the toplevel "read-eval-print loop" would be exe-
 286 cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
 287 and don't echo results. Combined with the @code{--noinform} runtime
 288 option, this makes it easier to write Lisp "scripts" which work
 289 cleanly in Unix pipelines.
 290
 291 @item --disable-debugger
 292 By default when SBCL encounters an error, it enters the builtin
 293 debugger, allowing interactive diagnosis and possible intercession.
 294 This option disables the debugger, causing errors to print a backtrace
 295 and exit with status 1 instead. When given, this option takes effect
 296 before loading of initialization files or processing @code{--eval} and
 297 @code{--load} options. See @code{sb-ext:disable-debugger} for details.
 298 @xref{Debugger Entry}.
 299
 300 @item --script @var{filename}
 301 Implies @code{--no-userinit} @code{--no-sysinit}
 302 @code{--disable-debugger} @code{--end-toplevel-options}.
 303
 304 Causes the system to load the specified file instead of entering the
 305 read-eval-print-loop, and exit afterwards. If the file begins with a
 306 shebang line, it is ignored.
 307
 308 @end table
 309
 310
 311 @node Initialization Files
 312 @comment  node-name,  next,  previous,  up
 313 @section Initialization Files
 314
 315 This section covers initialization files processed at startup, which
 316 can be used to customize the lisp environment.
 317
 318 @menu
 319 * System Initialization File::
 320 * User Initialization File::
 321 * Initialization File Semantics::
 322 * Initialization Examples::
 323 @end menu
 324
 325 @node System Initialization File
 326 @comment  node-name,  next,  previous,  up
 327 @subsection System Initialization File
 328
 329 Site-wide startup script. Unless overridden with the command line
 330 option @code{--sysinit} defaults to @file{@env{SBCL_HOME}/sbclrc}, or
 331 if that doesn't exist to @file{/etc/sbclrc}.
 332
 333 No system initialization file is required.
 334
 335 @node User Initialization File
 336 @comment  node-name,  next,  previous,  up
 337 @subsection User Initialization File
 338
 339 Per-user startup script. Unless overridden with the command line
 340 option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
 341
 342 No user initialization file is required.
 343
 344 @node Initialization File Semantics
 345 @comment  node-name,  next,  previous,  up
 346 @subsection Initialization File Semantics
 347
 348 SBCL processes initialization files with @code{read} and @code{eval},
 349 not @code{load}; hence initialization files can be used to set startup
 350 @code{*package*} and @code{*readtable*}, and for proclaiming a global
 351 optimization policy.
 352
 353 @node Initialization Examples
 354 @comment  node-name,  next,  previous,  up
 355 @subsection Initialization Examples
 356
 357 Some examples of what you may consider doing in the initialization
 358 files follow.
 359
 360 @menu
 361 * Automatic Recompilation of Stale Fasls::
 362 @end menu
 363
 364 @node Automatic Recompilation of Stale Fasls
 365 @comment  node-name,  next,  previous,  up
 366 @subsubsection Automatic Recompilation of Stale Fasls
 367
 368 SBCL fasl-format is at current stage of development undergoing
 369 non-backwards compatible changes fairly often. The following snippet
 370 handles recompilation automatically for ASDF-based systems.
 371
 372 @lisp
 373 (require :asdf)
 374
 375 ;;; If a fasl was stale, try to recompile and load (once).
 376 (defmethod asdf:perform :around ((o asdf:load-op)
 377                                  (c asdf:cl-source-file))
 378    (handler-case (call-next-method o c)
 379       ;; If a fasl was stale, try to recompile and load (once).
 380       (sb-ext:invalid-fasl ()
 381          (asdf:perform (make-instance 'asdf:compile-op) c)
 382          (call-next-method))))
 383 @end lisp
 384
 385 @node Initialization and Exit Hooks
 386 @comment  node-name,  next,  previous,  up
 387 @section Initialization and Exit Hooks
 388
 389 SBCL provides hooks into the system initialization and exit.
 390
 391 @include var-sb-ext-star-init-hooks-star.texinfo
 392 @include var-sb-ext-star-exit-hooks-star.texinfo
 393