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