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