package local nicknames

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

diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo
index 1e4811f..a4e1e55 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

@@ -40,7 +41,7 @@ distribution for more information.
 * (+ 2 2)
 
 4
 * (+ 2 2)
 
 4

-* (quit)
+* (exit)

 $
 @end smallexample
 
 $
 @end smallexample
 

@@ -65,34 +66,51 @@ 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
 @section Stopping SBCL
 
 @menu
 
 @node Stopping SBCL
 @comment  node-name,  next,  previous,  up
 @section Stopping SBCL
 
 @menu

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

 @end menu
 
 @end menu
 

-@node Quit
+@node Exit

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

-@subsection Quit
+@subsection Exit

 
 

-SBCL can be stopped at any time by calling @code{sb-ext:quit},
+SBCL can be stopped at any time by calling @code{sb-ext:exit},

 optionally returning a specified numeric value to the calling process.
 optionally returning a specified numeric value to the calling process.

-See notes in @ref{Threading} about the interaction between this
-feature and sessions.
+See @ref{Threading} for information about terminating individual threads.

 
 

-@include fun-sb-ext-quit.texinfo
+@include fun-sb-ext-exit.texinfo

 
 @node End of File
 @comment  node-name,  next,  previous,  up
 
 @node End of File
 @comment  node-name,  next,  previous,  up

@@ -108,9 +126,17 @@ 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
+
+In cases where the standard initialization files have already been loaded
+into the saved core, and alternative ones should be used (or none at all),
+SBCL allows customizing the initfile pathname computation.
+
+@include var-sb-ext-star-sysinit-pathname-function-star.texinfo
+@include var-sb-ext-star-userinit-pathname-function-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 +205,65 @@ 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. If there
+are no other commandline arguments following @code{--script}, the
+filename argument can be omitted.
+
+
+@item --merge-core-pages
+When platform support is present, provide hints to the operating system
+that identical pages may be shared between processes until they are
+written to.  This can be useful to reduce the memory usage on systems
+with multiple SBCL processes started from similar but differently-named
+core files, or from compressed cores.  Without platform support, do
+nothing.
+
+
+@item --no-merge-core-pages
+Ensures that no sharing hint is provided to the operating system.
+
+
+@item --default-merge-core-pages
+Reverts the sharing hint policy to the default: only compressed cores
+trigger hinting.  Uncompressed cores are mapped directly from the core
+file, which is usually enough to ensure sharing.
+
+

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

@@ -208,7 +287,7 @@ 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}.)
+(@pxref{Initialization Files}.)

 
 @item --no-sysinit
 Don't load a system-wide initialization file.  If this option is given,
 
 @item --no-sysinit
 Don't load a system-wide initialization file.  If this option is given,

@@ -216,7 +295,7 @@ 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}.)
+(@pxref{Initialization Files}.)

 
 @item --no-userinit
 Don't load a user initialization file.  If this option is given,
 
 @item --no-userinit
 Don't load a user initialization file.  If this option is given,

@@ -224,10 +303,9 @@ 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

@@ -235,149 +313,83 @@ special syntax is intended to reduce quoting headaches when invoking
 SBCL from shell scripts.
 
 @item --noprint
 SBCL from shell scripts.
 
 @item --noprint

-When ordinarily the toplevel "read-eval-print loop" would be exe-
-cuted, execute a "read-eval loop" instead, i.e. don't print a prompt
-and don't echo results. Combined with the @code{--noinform} runtime
+When ordinarily the toplevel "read-eval-print loop" would be executed,
+execute a "read-eval loop" instead, i.e. don't print a prompt and
+don't echo results. Combined with the @code{--noinform} runtime

 option, this makes it easier to write Lisp "scripts" which work
 cleanly in Unix pipelines.
 
 @item --disable-debugger
 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)'}.
+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
-
-
-@node Initialization Files
-@comment  node-name,  next,  previous,  up
-@section Initialization Files
+@item --script @var{filename}
+Implies @code{--no-userinit} @code{--no-sysinit}
+@code{--disable-debugger} @code{--end-toplevel-options}.

 
 

-This section covers initialization files processed at startup, which
-can be used to customize the lisp environment.
+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.

 
 

-@menu
-* System Initialization File::  
-* User Initialization File::    
-* Initialization File Semantics::  
-* Initialization Examples::     
-@end menu
+If there are no other command line arguments following, the filename
+can be omitted: this causes the script to be loaded from standard
+input instead. Shebang lines in standard input script are currently
+@emph{not} ignored.

 
 

-@node System Initialization File
-@comment  node-name,  next,  previous,  up
-@subsection System Initialization File
+In either case, if there is an unhandled error (e.g. end of file, or a
+broken pipe) on either standard input, standard output, or standard
+error, the script silently exits with code 0. This allows e.g. safely
+piping output from SBCL to @code{head -n1} or similar.

 
 

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

 
 

-@node Initialization File Semantics
+@node Initialization Files

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

-@subsection Initialization File Semantics
+@section Initialization Files

 
 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
-
-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
+@itemize @w{}
+@item
+@strong{System Initialization File}

 
 

-Example file (@file{hello.lisp}):
+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
-#!/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