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 @vindex sb-ext:*posix-argv*
 313 @vindex *posix-argv*
 314
 315 Standard Unix tools that are interpreters follow a common command line
 316 protocol that is necessary to work with ``shebang scripts''. SBCL
 317 doesn't do this by default, but adding the following snippet to an
 318 initialization file does the trick:
 319
 320 @lisp
 321 ;;; If the first user-processable command-line argument is a filename,
 322 ;;; disable the debugger, load the file handling shebang-line and quit.
 323 (let ((script (and (second *posix-argv*)
 324                    (probe-file (second *posix-argv*)))))
 325    (when script
 326       ;; Handle shebang-line
 327       (set-dispatch-macro-character #\# #\!
 328                                     (lambda (stream char arg)
 329                                        (declare (ignore char arg))
 330                                        (read-line stream)))
 331       ;; Disable debugger
 332       (setf *invoke-debugger-hook*
 333             (lambda (condition hook)
 334               (declare (ignore hook))
 335               ;; Uncomment to get backtraces on errors
 336               ;; (sb-debug:backtrace 20)
 337               (format *error-output* "Error: ~A~%" condition)
 338               (quit)))
 339       (load script)
 340       (quit)))
 341 @end lisp
 342
 343 Example file (@file{hello.lisp}):
 344
 345 @lisp
 346 #!/usr/local/bin/sbcl --noinform
 347 (write-line "Hello, World!")
 348 @end lisp
 349
 350 Usage examples:
 351
 352 @smallexample
 353 $ ./hello.lisp
 354 Hello, World!
 355 @end smallexample
 356
 357 @smallexample
 358 $ sbcl hello.lisp
 359 This is SBCL 0.8.13.70, an implementation of ANSI Common Lisp.
 360 More information about SBCL is available at <http://www.sbcl.org/>.
 361
 362 SBCL is free software, provided as is, with absolutely no warranty.
 363 It is mostly in the public domain; some portions are provided under
 364 BSD-style licenses.  See the CREDITS and COPYING files in the
 365 distribution for more information.
 366 Hello, World!
 367 @end smallexample
 368
 369
 370 @node Automatic Recompilation of Stale Fasls
 371 @comment  node-name,  next,  previous,  up
 372 @subsubsection Automatic Recompilation of Stale Fasls
 373
 374 SBCL fasl-format is at current stage of development undergoing
 375 non-backwards compatible changes fairly often. The following snippet
 376 handles recompilation automatically for ASDF-based systems.
 377
 378 @lisp
 379 (require :asdf)
 380
 381 ;;; If a fasl was stale, try to recompile and load (once).
 382 (defmethod asdf:perform :around ((o asdf:load-op)
 383                                  (c asdf:cl-source-file))
 384    (handler-case (call-next-method o c)
 385       ;; If a fasl was stale, try to recompile and load (once).
 386       (sb-ext:invalid-fasl ()
 387          (asdf:perform (make-instance 'asdf:compile-op) c)
 388          (call-next-method))))
 389 @end lisp