doc/manual/start-stop.texinfo

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