Proper error messages instead of "foo" and "bar"

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

@node Starting and Stopping
@comment  node-name,  next,  previous,  up
@chapter Starting and Stopping

@menu
* Starting SBCL::
* Stopping SBCL::
* Command Line Options::
* Initialization Files::
* Initialization and Exit Hooks::
@end menu

@node Starting SBCL
@comment  node-name,  next,  previous,  up
@section Starting SBCL

@menu
* Running from Shell::
* Running from Emacs::
* Shebang Scripts::
@end menu

@node Running from Shell
@comment  node-name,  next,  previous,  up
@subsection From Shell to Lisp

To run SBCL type @command{sbcl} at the command line.

You should end up in the toplevel @dfn{REPL} (read, eval, print
-loop), where you can interact with SBCL by typing expressions.

@smallexample
$ 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 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.
* (+ 2 2)

4
* (exit)
$
@end smallexample

See also @ref{Command Line Options} and @ref{Stopping SBCL}.

@node Running from Emacs
@comment  node-name,  next,  previous,  up
@subsection Running from Emacs

To run SBCL as an inferior-lisp from Emacs in your @file{.emacs} do
something like:

@lisp
;;; The SBCL binary and command-line arguments
(setq inferior-lisp-program "/usr/local/bin/sbcl --noinform")
@end lisp

For more information on using SBCL with Emacs, see @ref{Editor
Integration}.


@node Shebang Scripts
@comment  node-name,  next,  previous,  up
@subsection Shebang Scripts
@vindex @sbext{@earmuffs{posix-argv}}

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
* Exit::
* End of File::
* Saving a Core Image::
* Exit on Errors::
@end menu

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

SBCL can be stopped at any time by calling @code{sb-ext:exit},
optionally returning a specified numeric value to the calling process.
See @ref{Threading} for information about terminating individual threads.

@include fun-sb-ext-exit.texinfo

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

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

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
available from Lisp.

@include var-sb-ext-star-core-pathname-star.texinfo

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

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{Debugger Entry}.

@node Command Line Options
@comment  node-name,  next,  previous,  up
@section Command Line Options

@c FIXME: This is essentially cut-and-paste from the manpage
@c What should probably be done is generate both this and the
@c man-page from ``sbcl --help'' output.

Command line options can be considered an advanced topic; for ordinary
interactive use, no command line arguments should be necessary.

In order to understand the command line argument syntax for SBCL, it
is helpful to understand that the SBCL system is implemented as two
components, a low-level runtime environment written in C and a
higher-level system written in Common Lisp itself. Some command line
arguments are processed during the initialization of the low-level
runtime environment, some command line arguments are processed during
the initialization of the Common Lisp system, and any remaining
command line arguments are passed on to user code.

The full, unambiguous syntax for invoking SBCL at the command line is:

@command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-options}*

For convenience, the @code{--end-runtime-options} and
@code{--end-toplevel-options} elements can be omitted. Omitting these
elements can be convenient when you are running the program
interactively, and you can see that no ambiguities are possible with
the option values you are using. Omitting these elements is probably a
bad idea for any batch file where any of the options are under user
control, since it makes it impossible for SBCL to detect erroneous
command line input, so that erroneous command line arguments will be
passed on to the user program even if they was intended for the
runtime system or the Lisp system.

@menu
* Runtime Options::
* Toplevel Options::
@end menu

@node Runtime Options
@comment  node-name,  next,  previous,  up
@subsection Runtime Options

@table @code

@item --core @var{corefilename}
Run the specified Lisp core file instead of the default. Note that if
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 command line 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. By default only compressed cores trigger hinting.

@item --no-merge-core-pages
Ensures that no sharing hint is provided to the operating system.

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

@item --version
Print SBCL's version information, then exit.

@end table

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
stripped out of the command line before the Lisp toplevel logic gets a
chance to see it.

@node Toplevel Options
@comment  node-name,  next,  previous,  up
@subsection Toplevel Options

@table @code

@item --sysinit @var{filename}
Load filename instead of the default system initialization file
(@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{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 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
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 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
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.

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.

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.

@end table

@node Initialization Files
@comment  node-name,  next,  previous,  up
@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.

@table @strong

@item System Initialization File
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} (@pxref{Toplevel Options}).

The system initialization file is intended for system administrators
and software packagers to configure locations of installed third party
modules, etc.

@item User Initialization File
Defaults to @file{@env{$HOME}/.sbclrc}. Can be overridden with the
command line option @code{--userinit} or @code{--no-userinit}
(@pxref{Toplevel Options}).

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.

@end table

Neither initialization file is required.

@node Initialization and Exit Hooks
@comment  node-name,  next,  previous,  up
@section Initialization and Exit Hooks

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