X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fstart-stop.texinfo;h=6edab559975b55017b745d2508eab6e437cd7d62;hb=d84e1dbbbf11e76663cfaa0b1a5b7591f39f01b6;hp=8e9df470bfef80c52f6a35309828a29c1032ddbb;hpb=66973734ef6a395f2f0ca9e3a52111d41a0aed25;p=sbcl.git

diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo
index 8e9df47..6edab55 100644
--- a/doc/manual/start-stop.texinfo
+++ b/doc/manual/start-stop.texinfo
@@ -1,12 +1,13 @@
 @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::        
+* Initialization and Exit Hooks::  
 @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
-@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/>.
@@ -43,7 +43,6 @@ distribution for more information.
 4
 * (quit)
 $
-@end cartouche
 @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
+@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
@@ -81,6 +98,7 @@ an example.)
 @menu
 * Quit::                        
 * End of File::                 
+* Saving a Core Image::         
 * Exit on Errors::              
 @end menu
 
@@ -103,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.
 
+@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
@@ -111,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
-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
@@ -167,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.
 
+@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 --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.
 
@@ -181,7 +244,7 @@ Print SBCL's version information, then exit.
 
 @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
@@ -196,23 +259,25 @@ chance to see it.
 
 @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
-(@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
-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
@@ -227,144 +292,66 @@ option, this makes it easier to write Lisp "scripts" which work
 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.
 
 @end table
 
-
 @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
-@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 (and (second sb-ext:*posix-argv*)
-                   (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
-
-Usage examples:
-
-@smallexample
-@cartouche
-$ ./hello.lisp
-Hello, World!
-@end cartouche
-@end smallexample
-
-@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
+@section Initialization and Exit Hooks
 
+SBCL provides hooks into the system initialization and exit.
 
-@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.
+@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)
-    (sb-ext:invalid-fasl error ()
-     (asdf:perform (make-instance 'asdf:compile-op) c)
-     (call-next-method))))
-@end lisp