remove myself as a provider of official support
[sbcl.git] / doc / manual / start-stop.texinfo
index 320a8b6..ece3c90 100644 (file)
@@ -1,12 +1,13 @@
 @node Starting and Stopping
 @comment  node-name,  next,  previous,  up
 @node Starting and Stopping
 @comment  node-name,  next,  previous,  up
-@chapter Starting and Stoppping
+@chapter Starting and Stopping
 
 @menu
 * Starting SBCL::               
 * Stopping SBCL::               
 * Command Line Options::        
 * Initialization Files::        
 
 @menu
 * Starting SBCL::               
 * Stopping SBCL::               
 * Command Line Options::        
 * Initialization Files::        
+* Initialization and Exit Hooks::  
 @end menu
 
 @node Starting SBCL
 @end menu
 
 @node Starting SBCL
@@ -29,7 +30,6 @@ You should end up in the toplevel @dfn{REPL} (read, eval, print
 -loop), where you can interact with SBCL by typing expressions.
 
 @smallexample
 -loop), where you can interact with SBCL by typing expressions.
 
 @smallexample
-@cartouche
 $ sbcl
 This is SBCL 0.8.13.60, an implementation of ANSI Common Lisp.
 More information about SBCL is available at <http://www.sbcl.org/>.
 $ sbcl
 This is SBCL 0.8.13.60, an implementation of ANSI Common Lisp.
 More information about SBCL is available at <http://www.sbcl.org/>.
@@ -43,7 +43,6 @@ distribution for more information.
 4
 * (quit)
 $
 4
 * (quit)
 $
-@end cartouche
 @end smallexample
 
 See also @ref{Command Line Options} and @ref{Stopping SBCL}.
 @end smallexample
 
 See also @ref{Command Line Options} and @ref{Stopping SBCL}.
@@ -67,12 +66,30 @@ Integration}.
 @node Shebang Scripts
 @comment  node-name,  next,  previous,  up
 @subsection Shebang Scripts
 @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
 
 @node Stopping SBCL
 @comment  node-name,  next,  previous,  up
@@ -81,6 +98,7 @@ an example.)
 @menu
 * Quit::                        
 * End of File::                 
 @menu
 * Quit::                        
 * End of File::                 
+* Saving a Core Image::         
 * Exit on Errors::              
 @end menu
 
 * Exit on Errors::              
 @end menu
 
@@ -103,6 +121,29 @@ By default SBCL also exits on end of input, caused either by user
 pressing @kbd{Control-D} on an attached terminal, or end of input when
 using SBCL as part of a shell pipeline.
 
 pressing @kbd{Control-D} on an attached terminal, or end of input when
 using SBCL as part of a shell pipeline.
 
+@node Saving a Core Image
+@comment  node-name,  next,  previous,  up
+@subsection Saving a Core Image
+
+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.
+
+@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.
+
+@include var-sb-ext-star-core-pathname-star.texinfo
 
 @node Exit on Errors
 @comment  node-name,  next,  previous,  up
 
 @node Exit on Errors
 @comment  node-name,  next,  previous,  up
@@ -111,9 +152,7 @@ using SBCL as part of a shell pipeline.
 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
 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{Customization
-Hooks for Users}.
-
+the flexibility and robustness of Common Lisp. See @ref{Debugger Entry}.
 
 @node Command Line Options
 @comment  node-name,  next,  previous,  up
 
 @node Command Line Options
 @comment  node-name,  next,  previous,  up
@@ -167,12 +206,65 @@ the Lisp core file is a user-created core file, it may run a
 nonstandard toplevel which does not recognize the standard toplevel
 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 --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
+@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 --help
 Print some basic information about SBCL, then exit.
 
@@ -181,7 +273,7 @@ Print SBCL's version information, then exit.
 
 @end table
 
 
 @end table
 
-In the future, runtime options may be added to control behavior such
+In the future, runtime options may be added to control behaviour such
 as lazy allocation of memory.
 
 Runtime options, including any --end-runtime-options option, are
 as lazy allocation of memory.
 
 Runtime options, including any --end-runtime-options option, are
@@ -196,23 +288,25 @@ chance to see it.
 
 @item --sysinit @var{filename}
 Load filename instead of the default system initialization file
 
 @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{Initialization Files}.)
+
+@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
 
 @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{Initialization Files}.)
+
+@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
 
 @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
 
 @item --load @var{filename}
 This is equivalent to @code{--eval '(load "@var{filename}")'}. The
@@ -227,143 +321,76 @@ option, this makes it easier to write Lisp "scripts" which work
 cleanly in Unix pipelines.
 
 @item --disable-debugger
 cleanly in Unix pipelines.
 
 @item --disable-debugger
-This is equivalent to @code{--eval '(sb-ext:disable-debugger)'}.
-@xref{Customization Hooks for Users}.
+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.
+
+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.
+
+In either case, if there is an unhandled error (eg. 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 eg. safely
+piping output from SBCL to @code{head -n1} or similar.
 
 @end table
 
 
 @end table
 
-
 @node Initialization Files
 @comment  node-name,  next,  previous,  up
 @section Initialization Files
 
 @node Initialization Files
 @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.
-
-@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}.
+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.
 
 
-No system initialization file is required.
+@itemize @w{}
+@item
+@strong{System Initialization File}
 
 
-@node User Initialization File
-@comment  node-name,  next,  previous,  up
-@subsection User Initialization File
+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}.
 
 
-Per-user startup script. Unless overridden with the command line
-option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
+The system initialization file is intended for system administrators
+and software packagers to configure locations of installed third party
+modules, etc.
 
 
-No user initialization file is required.
+@item
+@strong{User Initialization File}
 
 
-@node Initialization File Semantics
-@comment  node-name,  next,  previous,  up
-@subsection Initialization File Semantics
+Defaults to @file{@env{$HOME}/.sbclrc}. Can be overridden with the
+command line option @code{--userinit} or @code{--no-userinit}.
 
 
-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.
+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.
 
 
-This is considered a bug and liable to change in the future.
+@end itemize
 
 
-@node Initialization Examples
-@comment  node-name,  next,  previous,  up
-@subsection Initialization Examples
-
-Some examples of what you may consider doing in the initialization
-files follow.
-
-@menu
-* Unix-style Command Line Protocol::  
-* Automatic Recompilation of Stale Fasls::  
-@end menu
+Neither initialization file is required.
 
 
-@node Unix-style Command Line Protocol
+@node Initialization and Exit Hooks
 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up
-@subsubsection Unix-style Command Line Protocol
-
-Standard Unix tools that are interpeters 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 (probe-file (second sb-ext:*posix-argv*))))
-  (when script
-    ;; Handle the possible shebang-line
-    (set-dispatch-macro-character #\# #\!
-                                 (lambda (stream char arg)
-                                   (declare (ignore char arg))
-                                   (read-line stream)))
-    ;; Disable debugger
-    (setf sb-ext:*invoke-debugger-hook* 
-          (lambda (condition hook)
-            (declare (ignore hook))
-            (format *error-output* "Error: ~A~%" condition)
-            (quit :unix-status 1)))
-    (load script)
-    (quit)))
-@end lisp
-
-Example file (@file{hello.lisp}):
-
-@lisp
-#!/usr/local/bin/sbcl --noinform
-(write-line "Hello, World!")
-@end lisp
+@section Initialization and Exit Hooks
 
 
-Usage examples:
+SBCL provides hooks into the system initialization and exit.
 
 
-@smallexample
-@cartouche
-$ ./hello.lisp
-Hello, World!
-@end cartouche
-@end smallexample
+@include var-sb-ext-star-init-hooks-star.texinfo
+@include var-sb-ext-star-exit-hooks-star.texinfo
 
 
-@smallexample
-@cartouche
-$ 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 cartouche
-@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)
-    (sb-ext:invalid-fasl error ()
-     (asdf:perform (make-instance 'asdf:compile-op) c)
-     (call-next-method))))
-@end lisp