@chapter Starting and Stopping
@menu
-* Starting SBCL::
-* Stopping SBCL::
-* Command Line Options::
-* Initialization Files::
+* Starting SBCL::
+* Stopping SBCL::
+* Command Line Options::
+* Initialization Files::
+* Initialization and Exit Hooks::
@end menu
@node Starting SBCL
@section Starting SBCL
@menu
-* Running from Shell::
-* Running from Emacs::
-* Shebang Scripts::
+* Running from Shell::
+* Running from Emacs::
+* Shebang Scripts::
@end menu
@node Running from Shell
@node Shebang Scripts
@comment node-name, next, previous, up
@subsection Shebang Scripts
+@vindex sb-ext:*posix-argv*
+@vindex *posix-argv*
-SBCL doesn't come with built-in support for shebang-line execution,
-but this can be provided with a shell trampoline, or by dispatching
-from initialization files (@pxref{Unix-style Command Line Protocol} for
-an example.)
+Standard Unix tools that are interpreters follow a common command line
+protocol that is necessary to work with ``shebang scripts''. SBCL supports
+this via the @code{--script} command line option.
+
+Example file (@file{hello.lisp}):
+
+@lisp
+#!/usr/local/bin/sbcl --script
+(write-line "Hello, World!")
+@end lisp
+
+Usage examples:
+
+@smallexample
+$ ./hello.lisp
+Hello, World!
+@end smallexample
+@smallexample
+$ sbcl --script hello.lisp
+Hello, World!
+@end smallexample
@node Stopping SBCL
@comment node-name, next, previous, up
@section Stopping SBCL
@menu
-* Quit::
+* Quit::
* End of File::
-* Saving a Core Image::
+* Saving a Core Image::
* Exit on Errors::
@end menu
SBCL has the ability to save its state as a file for later
execution. This functionality is important for its bootstrapping
-process, and is also provided as an extension to the user.
+process, and is also provided as an extension to the user.
@include fun-sb-ext-save-lisp-and-die.texinfo
+@include var-sb-ext-star-save-hooks-star.texinfo
+
+To facilitate distribution of SBCL applications using external
+resources, the filesystem location of the SBCL core file being used is
+available from Lisp.
+
+@include var-sb-ext-star-core-pathname-star.texinfo
@node Exit on Errors
@comment node-name, next, previous, up
SBCL can also be configured to exit if an unhandled error occurs,
which is mainly useful for acting as part of a shell pipeline; doing
so under most other circumstances would mean giving up large parts of
-the flexibility and robustness of Common Lisp. See @ref{Starting the
-Debugger}.
-
+the flexibility and robustness of Common Lisp. See @ref{Debugger Entry}.
@node Command Line Options
@comment node-name, next, previous, up
runtime system or the Lisp system.
@menu
-* Runtime Options::
-* Toplevel Options::
+* Runtime Options::
+* Toplevel Options::
@end menu
@node Runtime Options
nonstandard toplevel which does not recognize the standard toplevel
options.
+@item --dynamic-space-size @var{megabytes}
+Size of the dynamic space reserved on startup in megabytes. Default
+value is platform dependent.
+
+@item --control-stack-size @var{megabytes}
+Size of control stack reserved for each thread in megabytes. Default
+value is 2.
+
@item --noinform
Suppress the printing of any banner or other informational message at
startup. This makes it easier to write Lisp programs which work
cleanly in Unix pipelines. See also the @code{--noprint} and
@code{--disable-debugger} options.
+@item --disable-ldb
+Disable the low-level debugger. Only effective if SBCL is compiled
+with LDB.
+
+@item --lose-on-corruption
+There are some dangerous low level errors (for instance, control stack
+exhausted, memory fault) that (or whose handlers) can corrupt the
+image. By default SBCL prints a warning, then tries to continue and
+handle the error in Lisp, but this will not always work and SBCL may
+malfunction or even hang. With this option, upon encountering such an
+error SBCL will invoke ldb (if present and enabled) or else exit.
+
+@item --script @var{filename}
+As a runtime option this is equivalent to @code{--noinform}
+@code{--disable-ldb} @code{--lose-on-corruption}
+@code{--end-runtime-options} @code{--script} @var{filename}. See the
+description of @code{--script} as a toplevel option below.
+
@item --help
Print some basic information about SBCL, then exit.
@item --sysinit @var{filename}
Load filename instead of the default system initialization file
-(@pxref{System Initialization File}.) There is no special option to
-cause no system initialization file to be read, but on a Unix
-system ``@code{"--sysinit /dev/null}'' can be used to achieve the same
-effect.
+(@pxref{System Initialization File}.)
+
+@item --no-sysinit
+Don't load a system-wide initialization file. If this option is given,
+the @code{--sysinit} option is ignored.
@item --userinit @var{filename}
Load filename instead of the default user initialization file
-(@pxref{User Initialization File}.) There is no special option to
-cause no user initialization file to be read, but ``@code{--userinit
-/dev/null}'' can be used to achieve the same effect.
+(@pxref{User Initialization File}.)
+
+@item --no-userinit
+Don't load a user initialization file. If this option is given,
+the @code{--userinit} option is ignored.
@item --eval @var{command}
After executing any initialization file, but before starting the
cleanly in Unix pipelines.
@item --disable-debugger
-This is equivalent to @code{--eval '(sb-ext:disable-debugger)'}.
-@xref{Starting the Debugger}.
+By default when SBCL encounters an error, it enters the builtin
+debugger, allowing interactive diagnosis and possible intercession.
+This option disables the debugger, causing errors to print a backtrace
+and exit with status 1 instead. When given, this option takes effect
+before loading of initialization files or processing @code{--eval} and
+@code{--load} options. See @code{sb-ext:disable-debugger} for details.
+@xref{Debugger Entry}.
+
+@item --script @var{filename}
+Implies @code{--no-userinit} @code{--no-sysinit}
+@code{--disable-debugger} @code{--end-toplevel-options}.
+
+Causes the system to load the specified file instead of entering the
+read-eval-print-loop, and exit afterwards. If the file begins with a
+shebang line, it is ignored.
@end table
@comment node-name, next, previous, up
@section Initialization Files
-This section covers initialization files loaded at startup, which can
-be used to customize the lisp environment.
+This section covers initialization files processed at startup, which
+can be used to customize the lisp environment.
@menu
-* System Initialization File::
-* User Initialization File::
-* Initialization File Semantics::
-* Initialization Examples::
+* System Initialization File::
+* User Initialization File::
+* Initialization File Semantics::
+* Initialization Examples::
@end menu
@node System Initialization File
@comment node-name, next, previous, up
@subsection Initialization File Semantics
-SBCL uses @code{load} to process its initialization files, which
-has the unfortunate effect of preventing users from changing the
-default startup @code{*package*}, and setting a default optimization
-policy.
-
-This is considered a bug and liable to change in the future.
+SBCL processes initialization files with @code{read} and @code{eval},
+not @code{load}; hence initialization files can be used to set startup
+@code{*package*} and @code{*readtable*}, and for proclaiming a global
+optimization policy.
@node Initialization Examples
@comment node-name, next, previous, up
files follow.
@menu
-* Unix-style Command Line Protocol::
-* Automatic Recompilation of Stale Fasls::
+* Automatic Recompilation of Stale Fasls::
@end menu
-@node Unix-style Command Line Protocol
-@comment node-name, next, previous, up
-@subsubsection Unix-style Command Line Protocol
-
-Standard Unix tools that are interpreters follow a common command line
-protocol that is necessary to work with ``shebang scripts''. SBCL
-doesn't do this by default, but adding the following snippet to an
-initialization file does the trick:
-
-@lisp
-;;; If the first user-processable command-line argument is a filename,
-;;; disable the debugger, load the file handling shebang-line and quit.
-(let ((script (and (second *posix-argv*)
- (probe-file (second *posix-argv*)))))
- (when script
- ;; Handle shebang-line
- (set-dispatch-macro-character #\# #\!
- (lambda (stream char arg)
- (declare (ignore char arg))
- (read-line stream)))
- ;; Disable debugger
- (setf *invoke-debugger-hook*
- (lambda (condition hook)
- (declare (ignore hook))
- ;; Uncomment to get backtraces on errors
- ;; (sb-debug:backtrace 20)
- (format *error-output* "Error: ~A~%" condition)
- (quit)))
- (load script)
- (quit)))
-@end lisp
-
-Example file (@file{hello.lisp}):
-
-@lisp
-#!/usr/local/bin/sbcl --noinform
-(write-line "Hello, World!")
-@end lisp
-
-Usage examples:
-
-@smallexample
-$ ./hello.lisp
-Hello, World!
-@end smallexample
-
-@smallexample
-$ sbcl hello.lisp
-This is SBCL 0.8.13.70, an implementation of ANSI Common Lisp.
-More information about SBCL is available at <http://www.sbcl.org/>.
-
-SBCL is free software, provided as is, with absolutely no warranty.
-It is mostly in the public domain; some portions are provided under
-BSD-style licenses. See the CREDITS and COPYING files in the
-distribution for more information.
-Hello, World!
-@end smallexample
-
-
@node Automatic Recompilation of Stale Fasls
@comment node-name, next, previous, up
@subsubsection Automatic Recompilation of Stale Fasls
@lisp
(require :asdf)
-;;; If a fasl was stale, try to recompile and load (once).
-(defmethod asdf:perform :around ((o asdf:load-op)
+;;; If a fasl was stale, try to recompile and load (once).
+(defmethod asdf:perform :around ((o asdf:load-op)
(c asdf:cl-source-file))
(handler-case (call-next-method o c)
;; If a fasl was stale, try to recompile and load (once).
(asdf:perform (make-instance 'asdf:compile-op) c)
(call-next-method))))
@end lisp
+
+@node Initialization and Exit Hooks
+@comment node-name, next, previous, up
+@section Initialization and Exit Hooks
+
+SBCL provides hooks into the system initialization and exit.
+
+@include var-sb-ext-star-init-hooks-star.texinfo
+@include var-sb-ext-star-exit-hooks-star.texinfo
+
projects / sbcl.git / blobdiff