@chapter Starting and Stopping
@menu
-* Starting SBCL::
-* Stopping SBCL::
-* Command Line Options::
-* Initialization Files::
-* Initialization and Exit Hooks::
+* 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
* (+ 2 2)
4
-* (quit)
+* (exit)
$
@end smallexample
@node Shebang Scripts
@comment node-name, next, previous, up
@subsection Shebang Scripts
+@vindex @sbext{@earmuffs{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::
-* End of File::
-* Saving a Core Image::
-* Exit on Errors::
+* Exit::
+* End of File::
+* Saving a Core Image::
+* Exit on Errors::
@end menu
-@node Quit
+@node Exit
@comment node-name, next, previous, up
-@subsection Quit
+@subsection Exit
-SBCL can be stopped at any time by calling @code{sb-ext:quit},
+SBCL can be stopped at any time by calling @code{sb-ext:exit},
optionally returning a specified numeric value to the calling process.
-See notes in @ref{Threading} about the interaction between this
-feature and sessions.
+See @ref{Threading} for information about terminating individual threads.
-@include fun-sb-ext-quit.texinfo
+@include fun-sb-ext-exit.texinfo
@node End of File
@comment node-name, next, previous, up
@include fun-sb-ext-save-lisp-and-die.texinfo
@include var-sb-ext-star-save-hooks-star.texinfo
+In cases where the standard initialization files have already been loaded
+into the saved core, and alternative ones should be used (or none at all),
+SBCL allows customizing the initfile pathname computation.
+
+@include var-sb-ext-star-sysinit-pathname-function-star.texinfo
+@include var-sb-ext-star-userinit-pathname-function-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.
runtime system or the Lisp system.
@menu
-* Runtime Options::
-* Toplevel Options::
+* Runtime Options::
+* Toplevel Options::
@end menu
@node Runtime Options
cleanly in Unix pipelines. See also the @code{--noprint} and
@code{--disable-debugger} options.
+@item --disable-ldb
+@cindex ldb
+@cindex ldb, disabling
+@cindex disabling ldb
+Disable the low-level debugger. Only effective if SBCL is compiled
+with LDB.
+
+@item --lose-on-corruption
+@cindex ldb
+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. If there
+are no other commandline arguments following @code{--script}, the
+filename argument can be omitted.
+
+
+@item --merge-core-pages
+When platform support is present, provide hints to the operating system
+that identical pages may be shared between processes until they are
+written to. This can be useful to reduce the memory usage on systems
+with multiple SBCL processes started from similar but differently-named
+core files, or from compressed cores. Without platform support, do
+nothing.
+
+
+@item --no-merge-core-pages
+Ensures that no sharing hint is provided to the operating system.
+
+
+@item --default-merge-core-pages
+Reverts the sharing hint policy to the default: only compressed cores
+trigger hinting. Uncompressed cores are mapped directly from the core
+file, which is usually enough to ensure sharing.
+
+
@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}.)
+(@pxref{Initialization Files}.)
@item --no-sysinit
Don't load a system-wide initialization file. If this option is given,
@item --userinit @var{filename}
Load filename instead of the default user initialization file
-(@pxref{User Initialization File}.)
+(@pxref{Initialization Files}.)
@item --no-userinit
Don't load a user initialization file. If this option is given,
@item --eval @var{command}
After executing any initialization file, but before starting the
-read-eval-print loop on standard input, read and evaluate the com-
-mand given. More than one @code{--eval} option can be used, and all
-will be read and executed, in the order they appear on the command
-line.
+read-eval-print loop on standard input, read and evaluate the command
+given. More than one @code{--eval} option can be used, and all will be
+read and executed, in the order they appear on the command line.
@item --load @var{filename}
This is equivalent to @code{--eval '(load "@var{filename}")'}. The
SBCL from shell scripts.
@item --noprint
-When ordinarily the toplevel "read-eval-print loop" would be exe-
-cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
-and don't echo results. Combined with the @code{--noinform} runtime
+When ordinarily the toplevel "read-eval-print loop" would be executed,
+execute a "read-eval loop" instead, i.e. don't print a prompt and
+don't echo results. Combined with the @code{--noinform} runtime
option, this makes it easier to write Lisp "scripts" which work
cleanly in Unix pipelines.
@code{--load} options. See @code{sb-ext:disable-debugger} for details.
@xref{Debugger Entry}.
-@end table
-
-
-@node Initialization Files
-@comment node-name, next, previous, up
-@section Initialization Files
-
-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::
-@end menu
-
-@node System Initialization File
-@comment node-name, next, previous, up
-@subsection System Initialization File
-
-Site-wide startup script. Unless overridden with the command line
-option @code{--sysinit} defaults to @file{@env{SBCL_HOME}/sbclrc}, or
-if that doesn't exist to @file{/etc/sbclrc}.
+@item --script @var{filename}
+Implies @code{--no-userinit} @code{--no-sysinit}
+@code{--disable-debugger} @code{--end-toplevel-options}.
-No system initialization file is required.
+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.
-@node User Initialization File
-@comment node-name, next, previous, up
-@subsection User Initialization File
+If there are no other command line arguments following, the filename
+can be omitted: this causes the script to be loaded from standard
+input instead. Shebang lines in standard input script are currently
+@emph{not} ignored.
-Per-user startup script. Unless overridden with the command line
-option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
+In either case, if there is an unhandled error (e.g. end of file, or a
+broken pipe) on either standard input, standard output, or standard
+error, the script silently exits with code 0. This allows e.g. safely
+piping output from SBCL to @code{head -n1} or similar.
-No user initialization file is required.
+@end table
-@node Initialization File Semantics
+@node Initialization Files
@comment node-name, next, previous, up
-@subsection Initialization File Semantics
+@section Initialization Files
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
-@subsection Initialization Examples
+@itemize @w{}
+@item
+@strong{System Initialization File}
-Some examples of what you may consider doing in the initialization
-files follow.
+Defaults to @file{@env{$SBCL_HOME}/sbclrc}, or if that doesn't exist to
+@file{/etc/sbclrc}. Can be overridden with the command line option
+@code{--sysinit} or @code{--no-sysinit}.
-@menu
-* Unix-style Command Line Protocol::
-* Automatic Recompilation of Stale Fasls::
-@end menu
+The system initialization file is intended for system administrators
+and software packagers to configure locations of installed third party
+modules, etc.
-@node Unix-style Command Line Protocol
-@comment node-name, next, previous, up
-@subsubsection Unix-style Command Line Protocol
-@vindex sb-ext:*posix-argv*
-@vindex *posix-argv*
+@item
+@strong{User Initialization File}
-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:
+Defaults to @file{@env{$HOME}/.sbclrc}. Can be overridden with the
+command line option @code{--userinit} or @code{--no-userinit}.
-@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
+The user initialization file is intended for personal customizations,
+such as loading certain modules at startup, defining convenience
+functions to use in the REPL, handling automatic recompilation
+of FASLs (@pxref{FASL Format}), etc.
-Usage examples:
+@end itemize
-@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
-
-SBCL fasl-format is at current stage of development undergoing
-non-backwards compatible changes fairly often. The following snippet
-handles recompilation automatically for ASDF-based systems.
-
-@lisp
-(require :asdf)
-
-;;; 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).
- (sb-ext:invalid-fasl ()
- (asdf:perform (make-instance 'asdf:compile-op) c)
- (call-next-method))))
-@end lisp
+Neither initialization file is required.
@node Initialization and Exit Hooks
@comment node-name, next, previous, up
projects / sbcl.git / blobdiff