0.8.20.13: document current initialization file semantics

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

diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo
index 53f34d1..f16bfca 100644 (file)
--- a/doc/manual/start-stop.texinfo
+++ b/doc/manual/start-stop.texinfo
@@ -1,6 +1,6 @@
 @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::               
 
 @menu
 * Starting SBCL::               

@@ -29,7 +29,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 +42,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}.

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

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

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

@@ -103,6 +102,15 @@ 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

 
 @node Exit on Errors
 @comment  node-name,  next,  previous,  up
 
 @node Exit on Errors
 @comment  node-name,  next,  previous,  up

@@ -111,9 +119,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

@@ -181,7 +187,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

@@ -228,7 +234,7 @@ cleanly in Unix pipelines.
 
 @item --disable-debugger
 This is equivalent to @code{--eval '(sb-ext:disable-debugger)'}.
 
 @item --disable-debugger
 This is equivalent to @code{--eval '(sb-ext:disable-debugger)'}.

-@xref{Customization Hooks for Users}.
+@xref{Debugger Entry}.

 
 @end table
 
 
 @end table
 

@@ -237,8 +243,8 @@ This is equivalent to @code{--eval '(sb-ext:disable-debugger)'}.
 @comment  node-name,  next,  previous,  up
 @section 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.
+This section covers initialization files processed at startup, which
+can be used to customize the lisp environment.

 
 @menu
 * System Initialization File::  
 
 @menu
 * System Initialization File::  

@@ -270,12 +276,10 @@ No user initialization file is required.
 @comment  node-name,  next,  previous,  up
 @subsection Initialization File Semantics
 
 @comment  node-name,  next,  previous,  up
 @subsection Initialization File Semantics
 

-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.
-
-This is considered a bug and liable to change in the future.
+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
 
 @node Initialization Examples
 @comment  node-name,  next,  previous,  up

@@ -293,7 +297,7 @@ files follow.
 @comment  node-name,  next,  previous,  up
 @subsubsection Unix-style Command Line Protocol
 
 @comment  node-name,  next,  previous,  up
 @subsubsection Unix-style Command Line Protocol
 

-Standard Unix tools that are interpeters follow a common command line
+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:
 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:

@@ -301,22 +305,24 @@ 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.
 @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)))
+(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}):
 @end lisp
 
 Example file (@file{hello.lisp}):

@@ -329,14 +335,11 @@ Example file (@file{hello.lisp}):
 Usage examples:
 
 @smallexample
 Usage examples:
 
 @smallexample

-@cartouche

 $ ./hello.lisp
 Hello, World!
 $ ./hello.lisp
 Hello, World!

-@end cartouche

 @end smallexample
 
 @smallexample
 @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 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/>.

@@ -346,7 +349,6 @@ 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!
 BSD-style licenses.  See the CREDITS and COPYING files in the
 distribution for more information.
 Hello, World!

-@end cartouche

 @end smallexample
 
 
 @end smallexample
 
 

@@ -362,10 +364,11 @@ handles recompilation automatically for ASDF-based systems.
 (require :asdf)
 
 ;;; If a fasl was stale, try to recompile and load (once). 
 (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))))
+(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
 @end lisp