1.0.43.2: remove bashishm from source-distribution.sh

[sbcl.git] / doc / manual / start-stop.texinfo

diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo
index aca62d8..6edab55 100644 (file)
--- a/doc/manual/start-stop.texinfo
+++ b/doc/manual/start-stop.texinfo
@@ -7,6 +7,7 @@
 * Stopping SBCL::               
 * Command Line Options::        
 * Initialization Files::        
 * Stopping SBCL::               
 * Command Line Options::        
 * Initialization Files::        

+* Initialization and Exit Hooks::  

 @end menu
 
 @node Starting SBCL
 @end menu
 
 @node Starting SBCL

@@ -65,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

@@ -79,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
 

@@ -101,6 +121,22 @@ 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
+
+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

@@ -109,9 +145,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{Starting the
-Debugger}.
-
+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

@@ -165,12 +199,43 @@ 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.
+

 @item --help
 Print some basic information about SBCL, then exit.
 
 @item --help
 Print some basic information about SBCL, then exit.
 

@@ -194,23 +259,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

@@ -225,141 +292,66 @@ 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{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
 
 
 @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}.
-
-No system initialization file is required.
-
-@node User Initialization File
-@comment  node-name,  next,  previous,  up
-@subsection User Initialization File
+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.

 
 

-Per-user startup script. Unless overridden with the command line
-option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
+@itemize @w{}
+@item
+@strong{System Initialization File}

 
 

-No user initialization file is required.
+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}.

 
 

-@node Initialization File Semantics
-@comment  node-name,  next,  previous,  up
-@subsection Initialization File Semantics
+The system initialization file is intended for system administrators
+and software packagers to configure locations of installed third party
+modules, etc.

 
 

-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.
+@item
+@strong{User Initialization File}

 
 

-This is considered a bug and liable to change in the future.
+Defaults to @file{@env{$HOME}/.sbclrc}. Can be overridden with the
+command line option @code{--userinit} or @code{--no-userinit}.

 
 

-@node Initialization Examples
-@comment  node-name,  next,  previous,  up
-@subsection Initialization Examples
+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.

 
 

-Some examples of what you may consider doing in the initialization
-files follow.
+@end itemize

 
 

-@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
+@section Initialization and Exit Hooks

 
 

-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:
+SBCL provides hooks into the system initialization and exit.

 
 

-@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}):
+@include var-sb-ext-star-init-hooks-star.texinfo
+@include var-sb-ext-star-exit-hooks-star.texinfo

 
 

-@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
-
-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