1.0.23.55: three stale bugs

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

diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo
index de0589e..be2a88a 100644 (file)
--- a/doc/manual/start-stop.texinfo
+++ b/doc/manual/start-stop.texinfo
@@ -3,10 +3,11 @@
 @chapter Starting and Stopping
 
 @menu
 @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
 @end menu
 
 @node Starting SBCL

@@ -14,9 +15,9 @@
 @section Starting SBCL
 
 @menu
 @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
 @end menu
 
 @node Running from Shell

@@ -65,21 +66,40 @@ 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 sb-ext:*posix-argv*
+@vindex *posix-argv*
+
+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

 
 

-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.)
+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
 
 @node Stopping SBCL
 @comment  node-name,  next,  previous,  up
 @section Stopping SBCL
 
 @menu

-* Quit::                        
+* Quit::

 * End of File::
 * End of File::

-* Saving a Core Image::              
+* Saving a Core Image::

 * Exit on Errors::
 @end menu
 
 * Exit on Errors::
 @end menu
 

@@ -108,9 +128,10 @@ using SBCL as part of a shell pipeline.
 
 SBCL has the ability to save its state as a file for later
 execution. This functionality is important for its bootstrapping
 
 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 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
 
 To facilitate distribution of SBCL applications using external
 resources, the filesystem location of the SBCL core file being used is

@@ -163,8 +184,8 @@ passed on to the user program even if they was intended for the
 runtime system or the Lisp system.
 
 @menu
 runtime system or the Lisp system.
 
 @menu

-* Runtime Options::             
-* Toplevel Options::            
+* Runtime Options::
+* Toplevel Options::

 @end menu
 
 @node Runtime Options
 @end menu
 
 @node Runtime Options

@@ -183,12 +204,21 @@ options.
 Size of the dynamic space reserved on startup in megabytes. Default
 value is platform dependent.
 
 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 --script @var{filename}
+As a runtime option this is equivalent to @code{--noinform}
+@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.
 

@@ -246,9 +276,22 @@ 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)'}.
+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}.
 
 @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
 
 

@@ -260,10 +303,10 @@ This section covers initialization files processed at startup, which
 can be used to customize the lisp environment.
 
 @menu
 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
 @end menu
 
 @node System Initialization File

@@ -302,71 +345,9 @@ Some examples of what you may consider doing in the initialization
 files follow.
 
 @menu
 files follow.
 
 @menu

-* Unix-style Command Line Protocol::  
-* Automatic Recompilation of Stale Fasls::  
+* Automatic Recompilation of Stale Fasls::

 @end menu
 
 @end menu
 

-@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*
-
-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
 @node Automatic Recompilation of Stale Fasls
 @comment  node-name,  next,  previous,  up
 @subsubsection Automatic Recompilation of Stale Fasls

@@ -378,8 +359,8 @@ handles recompilation automatically for ASDF-based systems.
 @lisp
 (require :asdf)
 
 @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).
                                  (c asdf:cl-source-file))
    (handler-case (call-next-method o c)
       ;; If a fasl was stale, try to recompile and load (once).

@@ -387,3 +368,13 @@ handles recompilation automatically for ASDF-based systems.
          (asdf:perform (make-instance 'asdf:compile-op) c)
          (call-next-method))))
 @end lisp
          (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
+