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

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 (see Unix-style Command Line Protocol for an example.)

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]

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 Starting the Debugger.

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.

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

--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 System Initialization File.) There is no special option to cause no system initialization file to be read, but on a Unix system ``"--sysinit /dev/null'' can be used to achieve the same effect.

--userinit FILENAME
     Load filename instead of the default user initialization file (see User Initialization File.) There is no special option to cause no user initialization file to be read, but ``--userinit /dev/null'' can be used to achieve the same effect.

--eval 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 --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
     This is equivalent to --eval '(sb-ext:disable-debugger)'. See Starting the Debugger.

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

This section covers initialization files loaded at startup, which can be used to customize the lisp environment.

System Initialization File
--------------------------

Site-wide startup script. Unless overridden with the command line option --sysinit defaults to SBCL_HOME/sbclrc, or if that doesn't exist to /etc/sbclrc.

No system initialization file is required.

User Initialization File
------------------------

Per-user startup script. Unless overridden with the command line option --userinit defaults to HOME/.sbclrc.

No user initialization file is required.

Initialization File Semantics
-----------------------------

SBCL uses load to process its initialization files, which has the unfortunate effect of preventing users from changing the default startup *package*, and setting a default optimization policy.

This is considered a bug and liable to change in the future.

Initialization Examples
-----------------------

Some examples of what you may consider doing in the initialization files follow.

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:

     ;;; 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)))

Example file (hello.lisp):

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

Usage examples:

     $ ./hello.lisp
     Hello, World!

     $ 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 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!

Automatic Recompilation of Stale Fasls
......................................

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.

     (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))))