X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fstart-stop.texinfo;h=a4e1e5519d00c7891cff421cc23649a6c1e896bf;hb=b1b43e74be3d133bd1edf7d17adb607f8290331f;hp=86c1956d32ccc89919515bf8c78112859c8ed6fc;hpb=b0a7abdf2bd6f2d66fcce97196024cdb0e1a1886;p=sbcl.git diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo index 86c1956..a4e1e55 100644 --- a/doc/manual/start-stop.texinfo +++ b/doc/manual/start-stop.texinfo @@ -7,6 +7,7 @@ * Stopping SBCL:: * Command Line Options:: * Initialization Files:: +* Initialization and Exit Hooks:: @end menu @node Starting SBCL @@ -40,7 +41,7 @@ distribution for more information. * (+ 2 2) 4 -* (quit) +* (exit) $ @end smallexample @@ -65,34 +66,51 @@ 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 @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 -@node Quit +@node Exit @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. -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 @@ -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 -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 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 @@ -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. +@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. 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. @@ -208,23 +287,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 @@ -232,149 +313,83 @@ special syntax is intended to reduce quoting headaches when invoking 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 -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}. -@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. -@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. +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. -@menu -* System Initialization File:: -* User Initialization File:: -* Initialization File Semantics:: -* Initialization Examples:: -@end menu +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. -@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. +@end table -@node Initialization File Semantics +@node Initialization Files @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. -@node Initialization Examples -@comment node-name, next, previous, up -@subsection Initialization Examples +@itemize @w{} +@item +@strong{System Initialization File} -Some examples of what you may consider doing in the initialization -files follow. +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}. -@menu -* Unix-style Command Line Protocol:: -* Automatic Recompilation of Stale Fasls:: -@end menu +The system initialization file is intended for system administrators +and software packagers to configure locations of installed third party +modules, etc. -@node Unix-style Command Line Protocol -@comment node-name, next, previous, up -@subsubsection Unix-style Command Line Protocol +@item +@strong{User 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{$HOME}/.sbclrc}. Can be overridden with the +command line option @code{--userinit} or @code{--no-userinit}. -@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 +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. -Example file (@file{hello.lisp}): +@end itemize -@lisp -#!/usr/local/bin/sbcl --noinform -(write-line "Hello, World!") -@end lisp +Neither initialization file is required. -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 . - -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 +@node Initialization and Exit Hooks @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