1.0.28.51: better MAKE-ARRAY transforms

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

diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo
index 86c1956..cd07851 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,31 @@ 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*

 
 

-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

@@ -78,9 +98,9 @@ an example.)
 
 @menu
 * Quit::                        
 
 @menu
 * Quit::                        

-* End of File::
-* Saving a Core Image::              
-* Exit on Errors::
+* End of File::                 
+* Saving a Core Image::         
+* Exit on Errors::              

 @end menu
 
 @node Quit
 @end menu
 
 @node Quit

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

@@ -179,12 +200,38 @@ 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
+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 --help
 Print some basic information about SBCL, then exit.
 

@@ -208,23 +255,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

@@ -239,142 +288,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)'}.
+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}.
 

-@end table
+@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

 
 @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 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}.
-
-No system initialization file is required.
-
-@node User Initialization File
-@comment  node-name,  next,  previous,  up
-@subsection User Initialization File
-
-Per-user startup script. Unless overridden with the command line
-option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
-
-No user initialization file is required.
-
-@node Initialization File Semantics
-@comment  node-name,  next,  previous,  up
-@subsection Initialization File Semantics
-

 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.
 
 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
-
-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
-
-@node Unix-style Command Line Protocol
-@comment  node-name,  next,  previous,  up
-@subsubsection Unix-style Command Line Protocol
+@itemize @w{}
+@item
+@strong{System 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{$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}.

 
 

-@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 system initialization file is intended for system administrators
+and software packagers to configure locations of installed third party
+modules, etc.

 
 

-Usage examples:
+@item
+@strong{User Initialization File}

 
 

-@smallexample
-$ ./hello.lisp
-Hello, World!
-@end smallexample
+Defaults to @file{@env{$HOME}/.sbclrc}. Can be overridden with the
+command line option @code{--userinit} or @code{--no-userinit}.

 
 

-@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/>.
+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.

 
 

-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
+@end itemize

 
 

+Neither initialization file is required.

 
 

-@node Automatic Recompilation of Stale Fasls
+@node Initialization and Exit Hooks

 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up

-@subsubsection Automatic Recompilation of Stale Fasls
+@section Initialization and Exit Hooks

 
 

-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.
+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

 
 

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