Starting and Stopping
*********************

Starting SBCL
=============

From Shell to Lisp
------------------

To run SBCL type sbcl at the command line.

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

     $ 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
     * (quit)
     $

See also Command Line Options and Stopping SBCL.

Running from Emacs
------------------

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

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

For more information on using SBCL with Emacs, see Editor Integration.

Shebang Scripts
---------------

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 --script command line option.

Example file (hello.lisp):

     #!/usr/local/bin/sbcl --script
     (write-line "Hello, World!")

Usage examples:

     $ ./hello.lisp
     Hello, World!

     $ sbcl --script hello.lisp
     Hello, World!

Stopping SBCL
=============

Quit
----

SBCL can be stopped at any time by calling sb-ext:quit, optionally returning a specified numeric value to the calling process. See notes in Threading about the interaction between this feature and sessions.

     [file fun-sb-ext-quit.texinfo not included]

End of File
-----------

By default SBCL also exits on end of input, caused either by user pressing Control-D on an attached terminal, or end of input when using SBCL as part of a shell pipeline.

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.

     [file fun-sb-ext-save-lisp-and-die.texinfo not included]
     [file var-sb-ext-star-save-hooks-star.texinfo not included]

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.

     [file var-sb-ext-star-sysinit-pathname-function-star.texinfo not included]
     [file var-sb-ext-star-userinit-pathname-function-star.texinfo not included]

To facilitate distribution of SBCL applications using external resources, the filesystem location of the SBCL core file being used is available from Lisp.

     [file var-sb-ext-star-core-pathname-star.texinfo not included]

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

Command Line Options
====================

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:

sbcl RUNTIME-OPTION* --end-runtime-options TOPLEVEL-OPTION* --end-toplevel-options USER-OPTIONS*

For convenience, the --end-runtime-options and --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.

Runtime Options
---------------

--core 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.

--dynamic-space-size MEGABYTES
     Size of the dynamic space reserved on startup in megabytes. Default value is platform dependent.

--control-stack-size MEGABYTES
     Size of control stack reserved for each thread in megabytes. Default value is 2.

--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 --noprint and --disable-debugger options.

--disable-ldb
     Disable the low-level debugger. Only effective if SBCL is compiled with LDB.

--lose-on-corruption
     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.

--script FILENAME
     As a runtime option this is equivalent to --noinform --disable-ldb --lose-on-corruption --end-runtime-options --script FILENAME. See the description of --script as a toplevel option below. If there are no other commandline arguments following --script, the filename argument can be omitted.

--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.

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

--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.

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

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

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.

Toplevel Options
----------------

--sysinit FILENAME
     Load filename instead of the default system initialization file (see Initialization Files.)

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

--userinit FILENAME
     Load filename instead of the default user initialization file (see Initialization Files.)

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

--eval 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 --eval option can be used, and all will be read and executed, in the order they appear on the command line.

--load FILENAME
     This is equivalent to --eval '(load "FILENAME")'. The special syntax is intended to reduce quoting headaches when invoking SBCL from shell scripts.

--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 --noinform runtime option, this makes it easier to write Lisp "scripts" which work cleanly in Unix pipelines.

--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 --eval and --load options. See sb-ext:disable-debugger for details. See Debugger Entry.

--script FILENAME
     Implies --no-userinit --no-sysinit --disable-debugger --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 not ignored.

     In either case, if there is an unhandled error (eg. 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 eg. safely piping output from SBCL to head -n1 or similar.

Initialization Files
====================

SBCL processes initialization files with read and eval, not load; hence initialization files can be used to set startup *package* and *readtable*, and for proclaiming a global optimization policy.

  System Initialization File

     Defaults to $SBCL_HOME/sbclrc, or if that doesn't exist to /etc/sbclrc. Can be overridden with the command line option --sysinit or --no-sysinit.

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

  User Initialization File

     Defaults to $HOME/.sbclrc. Can be overridden with the command line option --userinit or --no-userinit.

     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 (see FASL Format), etc.

Neither initialization file is required.

Initialization and Exit Hooks
=============================

SBCL provides hooks into the system initialization and exit.

     [file var-sb-ext-star-init-hooks-star.texinfo not included]
     [file var-sb-ext-star-exit-hooks-star.texinfo not included]