\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename slime.info @settitle The Superior Lisp Interaction Mode for Emacs @dircategory Emacs @direntry * SLIME: (slime). Superior Lisp Interaction Mode for Emacs. @end direntry @c %**end of header @set EDITION 2.0 @c @set UPDATED @today{} @set UPDATED @code{$Date: 2007/01/27 18:42:35 $} @set TITLE SLIME User Manual @settitle @value{TITLE}, version @value{EDITION} @titlepage @title @value{TITLE} @titlefont{version @value{EDITION}} @sp 2 @image{slime-small} @sp 4 @subtitle Compiled: @value{UPDATED} @end titlepage @c Written by Luke Gorrie. @c @c Additional contributions: Jeff Cunningham, @c @c This file has been placed in the public domain. @macro SLIME @acronym{SLIME} @end macro @macro SLDB @acronym{SLDB} @end macro @macro REPL @acronym{REPL} @end macro @macro CVS @acronym{CVS} @end macro @macro kbditem{key, command} @item \key\ @code{\command\}@* @end macro @macro kbdanchor{key, command} @anchor{\command\} @item \key\ @code{\command\}@* @end macro @macro kbdanchorc{key, command, comment} @anchor{\command\} @item \key\ @code{\command\} @i{\comment\}@* @end macro @macro kbdindex{key, command} @item \key\ @xref{\command\}. @end macro @macro fcnanchor{name} @anchor{\name\} @item M-x @code{\name\}@* @end macro @macro fcnindex{name} @item \name\ @xref{\name\}. @end macro @c @setchapternewpage off @contents @c ----------------------- @node Top, Introduction, (dir), (dir) @ifinfo @top SLIME @SLIME{} is the ``Superior Lisp Interaction Mode for Emacs''. This is the manual for version 1.2. @end ifinfo @menu * Introduction:: * Getting started:: * slime-mode:: * REPL:: * Debugger:: * Extras:: * Customization:: * Tips and Tricks:: * Credits:: * Index to Functions:: @end menu @c ----------------------- @node Introduction, Getting started, Top, Top @chapter Introduction @SLIME{} is the ``Superior Lisp Interaction Mode for Emacs.'' @SLIME{} extends Emacs with new support for interactive programming in Common Lisp. The features are centered around @code{slime-mode}, an Emacs minor-mode that complements the standard @code{lisp-mode}. While @code{lisp-mode} supports editing Lisp source files, @code{slime-mode} adds support for interacting with a running Common Lisp process for compilation, debugging, documentation lookup, and so on. The @code{slime-mode} programming environment follows the example of Emacs's native Emacs Lisp environment. We have also included good ideas from similar systems (such as @acronym{ILISP}) and some new ideas of our own. @SLIME{} is constructed from two parts: a user-interface written in Emacs Lisp, and a supporting server program written in Common Lisp. The two sides are connected together with a socket and communicate using an @acronym{RPC}-like protocol. The Lisp server is primarily written in portable Common Lisp. The required implementation-specific functionality is specified by a well-defined interface and implemented separately for each Lisp implementation. This makes @SLIME{} readily portable. @c ----------------------- @node Getting started, slime-mode, Introduction, Top @chapter Getting started This chapter tells you how to get @SLIME{} up and running. @menu * Platforms:: * Downloading:: * Installation:: * Running:: @end menu @c ----------------------- @node Platforms, Downloading, Getting started, Getting started @section Supported Platforms @SLIME{} supports a wide range of operating systems and Lisp implementations. @SLIME{} runs on Unix systems, Mac OSX, and Microsoft Windows. GNU Emacs versions 20 and 21 and XEmacs version 21 are supported. The supported Lisp implementations, roughly ordered from the best-supported, are: @itemize @bullet @item CMU Common Lisp (@acronym{CMUCL}), 18e or newer @item Steel Bank Common Lisp (@acronym{SBCL}), latest official release @item OpenMCL, version 0.14.3 or newer @item LispWorks, version 4.3 or newer @item Allegro Common Lisp (@acronym{ACL}), version 6 or newer @item @acronym{CLISP}, version 2.33.2 or newer @item Armed Bear Common Lisp (@acronym{ABCL}) @item Corman Common Lisp (@acronym{CCL}), version 2.51 or newer with the patches from @url{http://www.grumblesmurf.org/lisp/corman-patches}) @item Scieneer Common Lisp (@acronym{SCL}), version 1.2.7 or newer @end itemize Most features work uniformly across implementations, but some are prone to variation. These include the precision of placing compiler-note annotations, @acronym{XREF} support, and fancy debugger commands (like ``restart frame''). @c ----------------------- @node Downloading, Installation, Platforms, Getting started @section Downloading SLIME You can choose between using a released version of @SLIME{} or accessing our @CVS{} repository directly. You can download the latest released version from our website: @url{http://www.common-lisp.net/project/slime/} We recommend that users who participate in the @code{slime-devel} mailing list use the @CVS{} version of the code. @menu * CVS:: * CVS Incantations:: @end menu @c ----------------------- @node CVS, CVS Incantations, Downloading, Downloading @subsection Downloading from CVS @SLIME{} is available from the @CVS{} repository on @file{common-lisp.net}. You have the option to use either the very latest code or the tagged @code{FAIRLY-STABLE} snapshot. The latest version tends to have more features and fewer bugs than the @code{FAIRLY-STABLE} version, but it can be unstable during times of major surgery. As a rule-of-thumb recommendation we suggest that if you follow the @code{slime-devel} mailing list then you're better off with the latest version (we'll send a note when it's undergoing major hacking). If you don't follow the mailing list you won't know the status of the latest code, so tracking @code{FAIRLY-STABLE} or using a released version is the safe option. If you checkout from @CVS{} then remember to @code{cvs update} occasionally. Improvements are continually being committed, and the @code{FAIRLY-STABLE} tag is moved forward from time to time (about once per month). @menu * CVS Incantations:: @end menu @c ----------------------- @node CVS Incantations, , CVS, Downloading @subsection CVS incantations To download @SLIME{} you first configure your @code{CVSROOT} and login to the repository. @example export CVSROOT=:pserver:anonymous@@common-lisp.net:/project/slime/cvsroot cvs login @end example @emph{(The password is @code{anonymous})} The latest version can then be checked out with: @example cvs checkout slime @end example Or the @code{FAIRLY-STABLE} version can be checked out with: @example cvs checkout -rFAIRLY-STABLE slime @end example If you want to find out what's new since the version you're currently running, you can diff the local @file{ChangeLog} against the repository version: @example cvs diff -rHEAD ChangeLog # or: -rFAIRLY-STABLE @end example @c ----------------------- @node Installation, Running, Downloading, Getting started @section Installation With a Lisp implementation that can be started from the command-line, installation just requires a few lines in your @file{~/.emacs}: @example (setq inferior-lisp-program "@emph{the path to your Lisp system}") (add-to-list 'load-path "@emph{the path of your @file{slime} directory}") (require 'slime) (slime-setup) @end example @iftex The snippet above also appears in the @file{README} file. You can copy&paste it from there, but remember to fill in the appropriate paths. @end iftex We recommend not loading the @acronym{ILISP} package into Emacs if you intend to use @SLIME{}. Doing so will add a lot of extra bindings to the keymap for Lisp source files that may be confusing and may not work correctly for a Lisp process started by @SLIME{}. @c ----------------------- @node Running, , Installation, Getting started @section Running SLIME @SLIME{} is started with the Emacs command @kbd{M-x slime}. This uses the @code{inferior-lisp} package to start a Lisp process, loads and starts the Lisp-side server (known as ``Swank''), and establishes a socket connection between Emacs and Lisp. Finally a @REPL{} buffer is created where you can enter Lisp expressions for evaluation. At this point @SLIME{} is up and running and you can start exploring. You can restart the @code{inferior-lisp} process using the function: @table @kbd @fcnanchor{slime-restart-inferior-lisp} @end table @c ----------------------- @node slime-mode, REPL, Getting started, Top @c @chapter @code{slime-mode} @chapter Using slime-mode @SLIME{}'s commands are provided via @code{slime-mode}, a minor-mode used in conjunction with Emacs's @code{lisp-mode}. This chapter describes the @code{slime-mode} and its relatives. @menu * User-interface conventions:: * Key bindings:: * Commands:: * Semantic indentation:: * Reader conditionals:: @end menu @c ----------------------- @node User-interface conventions, Key bindings, slime-mode, slime-mode @section User-interface conventions To use @SLIME{} comfortably it is important to understand a few ``global'' user-interface characteristics. The most important principles are described in this section. @menu * Temporary buffers:: * Inferior-lisp:: * Multithreading:: @end menu @c ----------------------- @node Temporary buffers, Inferior-lisp, User-interface conventions, User-interface conventions @subsection Temporary buffers Some @SLIME{} commands create temporary buffers to display their results. Although these buffers usually have their own special-purpose major-modes, certain conventions are observed throughout. Temporary buffers can be dismissed by pressing @kbd{q}. This kills the buffer and restores the window configuration as it was before the buffer was displayed. Temporary buffers can also be killed with the usual commands like @code{kill-buffer}, in which case the previous window configuration won't be restored. Pressing @kbd{RET} is supposed to ``do the most obvious useful thing.'' For instance, in an apropos buffer this prints a full description of the symbol at point, and in an @acronym{XREF} buffer it displays the source code for the reference at point. This convention is inherited from Emacs's own buffers for apropos listings, compilation results, etc. Temporary buffers containing Lisp symbols use @code{slime-mode} in addition to any special mode of their own. This makes the usual @SLIME{} commands available for describing symbols, looking up function definitions, and so on. @c ----------------------- @node Inferior-lisp, Multithreading, Temporary buffers, User-interface conventions @subsection @code{*inferior-lisp*} buffer @SLIME{} internally uses the @code{inferior-lisp} package to start Lisp processes. This has a few user-visible consequences, some good and some not-so-terribly. To avoid confusion it is useful to understand the interactions. The buffer @code{*inferior-lisp*} contains the Lisp process's own top-level. This direct access to Lisp is useful for troubleshooting, and some degree of @SLIME{} integration is available using the @code{inferior-slime-mode}. However, in normal use we recommend using the fully-integrated @SLIME{} @REPL{} and ignoring the @code{*inferior-lisp*} buffer. An unfortunate property of @code{inferior-lisp} is it inserts some commands of its own directly into the @code{lisp-mode} keymap, such that they aren't easily disabled. This makes Lisp source buffers slightly schizophrenic, having both @SLIME{} and @code{inferior-lisp} commands bound to keys and operating independently. @SLIME{} overrides most key bindings, so in practice you are unlikely to accidentally use an @code{inferior-lisp} command. If you do find a command that pops up the @code{*inferior-lisp*} buffer, that command doesn't belong to @SLIME{}, and you should probably lookup our equivalent. @c ----------------------- @node Multithreading, , Inferior-lisp, User-interface conventions @subsection Multithreading If the Lisp system supports multithreading, SLIME spawns a new thread for each request, e.g., @kbd{C-x C-e} creates a new thread to evaluate the expression. An exception to this rule are requests from the @REPL{}: all commands entered in the @REPL{} buffer are evaluated in a dedicated @REPL{} thread. Some complications arise with multithreading and special variables. Non-global special bindings are thread-local, e.g., changing the value of a let bound special variable in one thread has no effect on the binding of the variables with the same name in other threads. This makes it sometimes difficult to change the printer or reader behaviour for new threads. The variable @code{swank:*default-worker-thread-bindings*} was introduced for such situtuations: instead of modifying the global value of a variable, add a binding the @code{swank:*default-worker-thread-bindings*}. E.g., with the following code, new threads will read floating point values as doubles by default: @example (push '(*read-default-float-format* . double-float) swank:*default-worker-thread-bindings*). @end example @c ----------------------- @node Key bindings, Commands, User-interface conventions, slime-mode @section Key bindings @quotation @i{``Are you deliberately spiting Emacs's brilliant online help facilities? The gods will be angry!''} @end quotation @noindent This is a brilliant piece of advice. The Emacs online help facilities are your most immediate, up-to-date and complete resource for keybinding information. They are your friends: @table @kbd @kbdanchorc{C-h k , describe-key, ``What does this key do?''} Describes current function bound to @kbd{} for focus buffer. @kbdanchorc{C-h b, describe-bindings, ``Exactly what bindings are available?''} Lists the current key-bindings for the focus buffer. @kbdanchorc{C-h m, describe-mode, ``Tell me all about this mode''} Shows all the available major mode keys, then the minor mode keys, for the modes of the focus buffer. @kbdanchorc{C-h l, view-lossage, ``Woah@comma{} what key chord did I just do?''} Shows you the literal sequence of keys you've pressed in order. @kbdanchorc{ l, , ``What starts with?''} Lists all keybindings that begin with @code{} for the focus buffer mode. @end table @emph{Note:} In this documentation the designation @kbd{C-h} is a @dfn{cannonical key} which might actually mean Ctrl-h, or F1, or whatever you have @code{help-command} bound to in your @code{.emacs}. Here is a common situation: @example (global-set-key [f1] 'help-command) (global-set-key "\C-h" 'delete-backward-char) @end example @noindent In this situation everywhere you see @kbd{C-h} in the documentation you would substitute @kbd{F1}. In general we try to make our key bindings fit with the overall Emacs style. We also have the following somewhat unusual convention of our own: when entering a three-key sequence, the final key can be pressed either with control or unmodified. For example, the @code{slime-describe-symbol} command is bound to @kbd{C-c C-d d}, but it also works to type @kbd{C-c C-d C-d}. We're simply binding both key sequences because some people like to hold control for all three keys and others don't, and with the two-key prefix we're not afraid of running out of keys. There is one exception to this rule, just to trip you up. We never bind @kbd{C-h} anywhere in a key sequence, so @kbd{C-c C-d C-h} doesn't do the same thing as @kbd{C-c C-d h}. This is because Emacs has a built-in default so that typing a prefix followed by @kbd{C-h} will display all bindings starting with that prefix, so @kbd{C-c C-d C-h} will actually list the bindings for all documentation commands. This feature is just a bit too useful to clobber! You can assign or change default key bindings globally using the @code{global-set-key} function in your @file{~/.emacs} file like this: @example (global-set-key "\C-c s" 'slime-selector) @end example @noindent which binds @kbd{C-c s} to the function @code{slime-selector}. Alternatively, if you want to assign or change a key binding in just a particular slime mode, you can use the @code{global-set-key} function in your @file{~/.emacs} file like this: @example (define-key slime-repl-mode-map (kbd "C-c ;") 'slime-insert-balanced-comments) @end example @noindent which binds @kbd{C-c ;} to the function @code{slime-insert-balanced-comments} in the REPL buffer. @c ----------------------- @node Commands, Semantic indentation, Key bindings, slime-mode @section Commands @acronym{SLIME} commands are divided into the following general categories: @strong{Programming, Compilation, Evaluation, Recovery, Inspector, and Profiling}, discussed in separate sections below. There are also comprehensive indices to commands by function (@pxref{Index to Functions}). @menu * Programming:: * Compilation:: * Evaluation:: * Recovery:: * Inspector:: * Profiling:: * Other:: @end menu @c ----------------------- @node Programming, Compilation, , Commands @subsection Programming commands Programming commands are divided into the following categories: @strong{Completion, Documentation, Coss-reference, Finding definitions, Macro-expansion, and Disassembly}, discussed in separate sections below. @menu * Completion:: * Closure:: * Indentation:: * Documentation:: * Cross-reference:: * Finding definitions:: * Macro-expansion:: * Disassembly:: @end menu @c ----------------------- @node Completion, Closure, , Programming @subsubsection Completion commands Completion commands are used to complete a symbol or form based on what is already present at point. Classical completion assumes an exact prefix and gives choices only where branches may occur. Fuzzy completion tries harder. @table @kbd @anchor{slime-complete-symbol} @itemx M-TAB @item C-c C-i @item C-M-i @code{slime-complete-symbol}@* Complete the symbol at point. Note that three styles of completion are available in @SLIME{}, and the default differs from normal Emacs completion (@pxref{slime-complete-symbol-function}). @xref{Emacs-side customization}. @kbdanchor{C-c C-s, slime-complete-form} Looks up and inserts into the current buffer the argument list for the function at point, if there is one. More generally, the command completes an incomplete form with a template for the missing arguments. There is special code for discovering extra keywords of generic functions and for handling @code{make-instance} and @code{defmethod}. Examples: @example (subseq "abc" --inserts--> start [end]) (find 17 --inserts--> sequence :from-end from-end :test test :test-not test-not :start start :end end :key key) (find 17 '(17 18 19) :test #'= --inserts--> :from-end from-end :test-not test-not :start start :end end :key key) (defclass foo () ((bar :initarg :bar))) (defmethod print-object --inserts--> (object stream) body...) (defmethod initialize-instance :after ((object foo) &key blub)) (make-instance 'foo --inserts--> :bar bar :blub blub initargs...) @end example @kbdanchor{C-c M-i, slime-fuzzy-complete-symbol} Presents a list of likely completions to choose from for an abbreviation at point. This is a third completion method and it is very different from the more traditional completion to which @command{slime-complete-symbol} defaults. It attempts to complete a symbol all at once, instead of in pieces. For example, ``mvb'' will find ``@code{multiple-value-bind}'' and ``norm-df'' will find ``@code{least-positive-normalized-double-float}''. This can also be selected as the method of completion used for @code{slime-complete-symbol}. @fcnanchor{slime-fuzzy-completions-mode} @fcnanchor{slime-fuzzy-abort} @end table @c ----------------------- @node Closure, Indentation, Completion, Programming @subsubsection Closure commands Closure commands are used to fill in missing parenthesis. @table @kbd @kbdanchor{C-c C-q, slime-close-parens-at-point} Closes parentheses at point to complete the top-level-form by inserting ')' characters at until @code{beginning-of-defun} and @code{end-of-defun} execute without errors, or @code{slime-close-parens-limit} is exceeded. @kbdanchor{C-], slime-close-all-sexp} Balance parentheses of open s-expressions at point. Insert enough right-parentheses to balance unmatched left-parentheses. Delete extra left-parentheses. Reformat trailing parentheses Lisp-stylishly. If @code{REGION} is true, operate on the region. Otherwise operate on the top-level sexp before point. @end table @c ----------------------- @node Indentation, Documentation, Closure, Programming @subsubsection Indentation commands @table @kbd @kbdanchor{C-c M-q, slime-reindent-defun} Re-indents the current defun, or refills the current paragraph. If point is inside a comment block, the text around point will be treated as a paragraph and will be filled with @code{fill-paragraph}. Otherwise, it will be treated as Lisp code, and the current defun will be reindented. If the current defun has unbalanced parens, an attempt will be made to fix it before reindenting. @kbdanchor{C-M-q, indent-sexp} Indents the list immediately following point to match the level at point. When given a prefix argument, the text around point will always be treated as a paragraph. This is useful for filling docstrings." @end table @c ----------------------- @node Documentation, Cross-reference, Indentation, Programming @subsubsection Documentation commands @SLIME{}'s online documentation commands follow the example of Emacs Lisp. The commands all share the common prefix @kbd{C-c C-d} and allow the final key to be modified or unmodified (@pxref{Key bindings}.) @table @kbd @kbdanchor{SPC, slime-space} The space key inserts a space, but also looks up and displays the argument list for the function at point, if there is one. @kbdanchor{C-c C-d d, slime-describe-symbol} Describe the symbol at point. @kbdanchor{C-c C-f, slime-describe-function} Describe the function at point. @kbdanchor{C-c C-d a, slime-apropos} Perform an apropos search on Lisp symbol names for a regular expression match and display their documentation strings. By default the external symbols of all packages are searched. With a prefix argument you can choose a specific package and whether to include unexported symbols. @kbdanchor{C-c C-d z, slime-apropos-all} Like @code{slime-apropos} but also includes internal symbols by default. @kbdanchor{C-c C-d p, slime-apropos-package} Show apropos results of all symbols in a package. This command is for browsing a package at a high-level. With package-name completion it also serves as a rudimentary Smalltalk-ish image-browser. @kbdanchor{C-c C-d h, slime-hyperspec-lookup} Lookup the symbol at point in the @cite{Common Lisp Hyperspec}. This uses the familiar @file{hyperspec.el} to show the appropriate section in a web browser. The Hyperspec is found either on the Web or in @code{common-lisp-hyperspec-root}, and the browser is selected by @code{browse-url-browser-function}. Note: this is one case where @kbd{C-c C-d h} is @emph{not} the same as @kbd{C-c C-d C-h}. @kbdanchor{C-c C-d ~, common-lisp-hyperspec-format} Lookup a @emph{format character} in the @cite{Common Lisp Hyperspec}. @end table @c ----------------------- @node Cross-reference, Finding definitions, Documentation, Programming @subsubsection Cross-reference commands @SLIME{}'s cross-reference commands are based on the support provided by the Lisp system, which varies widely between Lisps. For systems with no built-in @acronym{XREF} support @SLIME{} queries a portable @acronym{XREF} package, which is taken from the @cite{CMU AI Repository} and bundled with @SLIME{}. Each command operates on the symbol at point, or prompts if there is none. With a prefix argument they always prompt. You can either enter the key bindings as shown here or with the control modified on the last key, @xref{Key bindings}. @table @kbd @kbdanchor{C-c C-w c, slime-who-calls} Show function callers. @kbdanchor{C-c C-w r, slime-who-references} Show references to global variable. @kbdanchor{C-c C-w b, slime-who-binds} Show bindings of a global variable. @kbdanchor{C-c C-w s, slime-who-sets} Show assignments to a global variable. @kbdanchor{C-c C-w m, slime-who-macroexpands} Show expansions of a macro. @fcnanchor{slime-who-specializes} Show all known methods specialized on a class. @fcnanchor{slime-goto-xref} Go to the cross-referenced location at point. @end table There are also ``List callers/callees'' commands. These operate by rummaging through function objects on the heap at a low-level to discover the call graph. They are only available with some Lisp systems, and are most useful as a fallback when precise @acronym{XREF} information is unavailable. @table @kbd @kbdanchor{C-c <, slime-list-callers} List callers of a function. @kbdanchor{C-c >, slime-list-callees} List callees of a function. @fcnanchor{slime-calls-who} Show all known functions called by the function SYMBOL. @end table @c ----------------------- @node Finding definitions, Macro-expansion, Cross-reference, Programming @subsubsection Finding definitions (``Meta-Point'' commands). The familiar @kbd{M-.} command is provided. For generic functions this command finds all methods, and with some systems it does other fancy things (like tracing structure accessors to their @code{DEFSTRUCT} definition). @table @kbd @kbdanchor{M-., slime-edit-definition} Go to the definition of the symbol at point. @anchor{slime-pop-find-definition-stack} @item M-, @itemx M-* @code{slime-pop-find-definition-stack} Go back to the point where @kbd{M-.} was invoked. This gives multi-level backtracking when @kbd{M-.} has been used several times. @kbdanchor{C-x 4 ., slime-edit-definition-other-window} Like @code{slime-edit-definition} but switchs to the other window to edit the definition in. @kbdanchor{C-x 5 ., slime-edit-definition-other-frame} Like @code{slime-edit-definition} but opens another frame to edit the definition in. @fcnanchor{slime-edit-definition-with-etags} Use an ETAGS table to find definition at point. @end table @c ----------------------- @node Macro-expansion, Disassembly, Finding definitions, Programming @subsubsection Macro-expansion commands @table @kbd @anchor{slime-macroexpand-1} @item C-c C-m @itemx C-c RET @code{slime-macroexpand-1}@* Macroexpand the expression at point once. If invoked with a prefix argument, use macroexpand instead of macroexpand-1. @kbdanchor{C-c M-m, slime-macroexpand-all} Fully macroexpand the expression at point. @kbdanchor{C-c C-t, slime-toggle-trace-fdefinition} Toggle tracing of the function at point. If invoked with a prefix argument, read additional information, like which particular method should be traced. @fcnanchor{slime-untrace-all} Untrace all functions. @end table For additional minor-mode commands and discussion, @pxref{slime-macroexpansion-minor-mode}. @c ----------------------- @node Disassembly, , Macro-expansion, Programming @subsubsection Disassembly commands @table @kbd @kbdanchor{C-c M-d, slime-disassemble-symbol} Disassemble the function definition of the symbol at point. @end table @c ----------------------- @c ----------------------- @node Compilation, Evaluation, Programming, Commands @subsection Compilation commands @SLIME{} has fancy commands for compiling functions, files, and packages. The fancy part is that notes and warnings offered by the Lisp compiler are intercepted and annotated directly onto the corresponding expressions in the Lisp source buffer. (Give it a try to see what this means.) @table @kbd @kbdanchor{C-c C-c, slime-compile-defun} Compile the top-level form at point. @cindex compiling functions @kbdanchor{C-c C-y, slime-call-defun} Insert a call to the function defined around point into the REPL. @kbdanchor{C-c C-k, slime-compile-and-load-file} Compile and load the current buffer's source file. @kbdanchor{C-c M-k, slime-compile-file} Compile (but don't load) the current buffer's source file. @kbdanchor{C-c C-l, slime-load-file} Load a source file and compile if necessary, without loading into a buffer.. @kbdanchor{C-c C-z, slime-switch-to-output-buffer} Select the output buffer, preferably in a different window. @fcnanchor{slime-compile-region} Compile region at point. @fcnanchor{slime-compiler-macroexpand} Display the compiler-macro expansion of sexp at point. @fcnanchor{slime-compiler-macroexpand-1} Display the compiler-macro expansion of sexp at point. @fcnanchor{slime-compiler-notes-default-action-or-show-details} Invoke the action at point, or show details. @fcnanchor{slime-compiler-notes-default-action-or-show-details/mouse} Invoke the action pointed at by the mouse, or show details. @fcnanchor{slime-compiler-notes-mode} @fcnanchor{slime-compiler-notes-quit} @fcnanchor{slime-compiler-notes-show-details} @end table The annotations are indicated as underlining on source forms. The compiler message associated with an annotation can be read either by placing the mouse over the text or with the selection commands below. @table @kbd @kbdanchor{M-n, slime-next-note} Move the point to the next compiler note and displays the note. @kbdanchor{M-p, slime-previous-note} Move the point to the previous compiler note and displays the note. @kbdanchor{C-c M-c, slime-remove-notes} Remove all annotations from the buffer. @end table @c ----------------------- @node Evaluation, Recovery, Compilation, Commands @subsection Evaluation commands These commands each evaluate a Lisp expression in a different way. By default they show their results in a message, but a prefix argument causes the results to be printed in the @REPL{} instead. @table @kbd @kbdanchor{C-M-x, slime-eval-defun} Evaluate the current toplevel form. Use @code{slime-re-evaluate-defvar} if the from starts with @code{(defvar}. @kbdanchor{C-x C-e, slime-eval-last-expression} Evaluate the expression before point. @end table If @kbd{C-M-x} or @kbd{C-x C-e} is given a numeric argument, it inserts the value into the current buffer at point, rather than displaying it in the echo area. @table @kbd @kbdanchor{C-c C-p, slime-pprint-eval-last-expression} Evaluate the expression before point and pretty-print the result. @kbdanchor{C-c C-r, slime-eval-region} Evaluate the region. @kbdanchor{C-x M-e, slime-eval-last-expression-display-output} Display output buffer and evaluate the expression preceding point. @kbdanchor{C-c :, slime-interactive-eval} Evaluate an expression read from the minibuffer. @kbdanchor{M-x, slime-scratch} Create a @file{*slime-scratch*} buffer. In this buffer you can enter Lisp expressions and evaluate them with @kbd{C-j}, like in Emacs's @file{*scratch*} buffer. @kbdanchor{C-c E, slime-edit-value} Edit the value of a setf-able form in a new buffer @file{*Edit
*}. The value is inserted into a temporary buffer for editing and then set in Lisp when committed with @code{slime-edit-value-commit}. @kbdanchor{C-c C-u, slime-undefine-function} Unbind symbol for function at point. @end table @c ----------------------- @node Recovery, Inspector, Evaluation, Commands @subsection Abort/Recovery commands @table @kbd @kbdanchor{C-c C-b, slime-interrupt} Interrupt Lisp (send @code{SIGINT}). @kbdanchor{C-c ~, slime-sync-package-and-default-directory} Synchronize the current package and working directory from Emacs to Lisp. @kbdanchor{C-c M-p, slime-repl-set-package} Set the current package of the @acronym{REPL}. @end table @c ----------------------- @node Inspector, Profiling, Recovery, Commands @subsection Inspector commands The @SLIME{} inspector is a very fancy Emacs-based alternative to the standard @code{INSPECT} function. The inspector presents objects in Emacs buffers using a combination of plain text, hyperlinks to related objects, and ``actions'' that can be selected to invoke Lisp code on the inspected object. For example, to present a generic function the inspector shows the documentation in plain text and presents each method with both a hyperlink to inspect the method object and a ``remove method'' action that you can invoke interactively. The inspector can easily be specialized for the objects in your own programs. For details see the the @code{inspect-for-emacs} generic function in @file{swank-backend.lisp}. @table @kbd @kbdanchor{C-c I, slime-inspect} Inspect the value of an expression entered in the minibuffer. @end table The standard commands available in the inspector are: @table @kbd @kbdanchor{RET, slime-inspector-operate-on-point} If point is on a value then recursivly call the inspcetor on that value. If point is on an action then call that action. @kbdanchor{d, slime-inspector-describe} Describe the slot at point. @kbdanchor{l, slime-inspector-pop} Go back to the previous object (return from @kbd{RET}). @kbdanchor{n, slime-inspector-next} The inverse of @kbd{l}. Also bound to @kbd{SPC}. @kbdanchor{q, slime-inspector-quit} Dismiss the inspector buffer. @kbdanchor{M-RET, slime-inspector-copy-down} Evaluate the value under point via the REPL (to set `*'). @end table @c ----------------------- @node Profiling, Other, Inspector, Commands @subsection Profiling commands @table @kbd @fcnanchor{slime-toggle-profile-fdefinition} Toggle profiling of a function. @fcnanchor{slime-profile-package} Profile all functions in a package. @fcnanchor{slime-unprofile-all} Unprofile all functions. @fcnanchor{slime-profile-report} Report profiler data. @fcnanchor{slime-profile-reset} Reset profiler data. @fcnanchor{slime-profiled-functions} Show list of currently profiled functions. @end table @c ----------------------- @node Other, , Profiling, Commands @subsection Shadowed Commands @table @kbd @kbdanchor{C-c C-a, slime-nop} This key-binding is shadowed from lisp-inf. @kbditem{C-c C-v, slime-nop} This key-binding is shadowed from lisp-inf. @end table @c ----------------------- @node Semantic indentation, Reader conditionals, Commands, slime-mode @section Semantic indentation @SLIME{} automatically discovers how to indent the macros in your Lisp system. To do this the Lisp side scans all the macros in the system and reports to Emacs all the ones with @code{&body} arguments. Emacs then indents these specially, putting the first arguments four spaces in and the ``body'' arguments just two spaces, as usual. This should ``just work.'' If you are a lucky sort of person you needn't read the rest of this section. To simplify the implementation, @SLIME{} doesn't distinguish between macros with the same symbol-name but different packages. This makes it fit nicely with Emacs's indentation code. However, if you do have several macros with the same symbol-name then they will all be indented the same way, arbitrarily using the style from one of their arglists. You can find out which symbols are involved in collisions with: @example (swank:print-indentation-lossage) @end example If a collision causes you irritation, don't have a nervous breakdown, just override the Elisp symbol's @code{common-lisp-indent-function} property to your taste. @SLIME{} won't override your custom settings, it just tries to give you good defaults. A more subtle issue is that imperfect caching is used for the sake of performance. @footnote{@emph{Of course} we made sure it was actually too slow before making the ugly optimization.} In an ideal world, Lisp would automatically scan every symbol for indentation changes after each command from Emacs. However, this is too expensive to do every time. Instead Lisp usually just scans the symbols whose home package matches the one used by the Emacs buffer where the request comes from. That is sufficient to pick up the indentation of most interactively-defined macros. To catch the rest we make a full scan of every symbol each time a new Lisp package is created between commands -- that takes care of things like new systems being loaded. You can use @kbd{M-x slime-update-indentation} to force all symbols to be scanned for indentation information. @c ----------------------- @node Reader conditionals, , Semantic indentation, slime-mode @section Reader conditional fontification @SLIME{} automatically evaluates reader-conditional expressions in source buffers and ``grays out'' code that will be skipped for the current Lisp connection. @c ----------------------- @node REPL, Debugger, slime-mode, Top @chapter REPL: the ``top level'' @SLIME{} uses a custom Read-Eval-Print Loop (@REPL{}, also known as a ``top level''). The @REPL{} user-interface is written in Emacs Lisp, which gives more Emacs-integration than the traditional @code{comint}-based Lisp interaction: @itemize @bullet @item Conditions signalled in @REPL{} expressions are debugged with @SLDB{}. @item Return values are distinguished from printed output by separate Emacs faces (colours). @item Emacs manages the @REPL{} prompt with markers. This ensures that Lisp output is inserted in the right place, and doesn't get mixed up with user input. @end itemize @menu * REPL commands:: * Input Navigation:: * Shortcuts:: @end menu @c ----------------------- @node REPL commands, Input Navigation, REPL, REPL @section REPL commands @table @kbd @kbdanchor{RET, slime-repl-return} Evaluate the current input in Lisp if it is complete. If incomplete, open a new line and indent. If a prefix argument is given then the input is evaluated without checking for completeness. @kbdanchor{C-RET, slime-repl-closing-return} Close any unmatched parenthesis and then evaluate the current input in Lisp. Also bound to @kbd{M-RET}. @kbdanchor{C-j, slime-repl-newline-and-indent} Open and indent a new line. @c @anchor{slime-interrupt} @kbditem{C-c C-c, slime-interrupt} Interrupt the Lisp process with @code{SIGINT}. @kbdanchor{C-c M-g, slime-quit} Quit slime. @kbdanchor{C-c C-o, slime-repl-clear-output} Remove the output and result of the previous expression from the buffer. @kbdanchor{C-c C-t, slime-repl-clear-buffer} Clear the entire buffer, leaving only a prompt. @end table @c ----------------------- @node Input Navigation, Shortcuts, REPL commands, REPL @section Input navigation @table @kbd @kbdanchor{C-a, slime-repl-bol} Go to the beginning of the line, but stop at the @REPL{} prompt. @anchor{slime-repl-next-input} @anchor{slime-repl-previous-input} @item M-n @itemx M-p @code{slime-repl-next-input, slime-repl-previous-input}@* Go to next/previous in command history. @anchor{slime-repl-next-matching-input} @anchor{slime-repl-previous-matching-input} @itemx M-s @itemx M-r @code{slime-repl-next-matching-input, slime-repl-previous-matching-input}@* Search forward/reverse through command history with regex @c @code{slime-repl-@{next,previous@}-input}@* @c @code{slime-repl-@{next,previous@}-matching-input}@* @c @code{comint}-style input history commands. @anchor{slime-repl-next-prompt} @anchor{slime-repl-previous-prompt} @item C-c C-n @itemx C-c C-p @code{slime-repl-next-prompt, slime-repl-previous-prompt}@* Move between the current and previous prompts in the @REPL{} buffer. @anchor{slime-repl-beginning-of-defun} @anchor{slime-repl-end-of-defun} @item C-M-a @itemx C-M-e @code{slime-repl-beginning-of-defun, slime-repl-end-of-defun} These commands are like @code{beginning-of-defun} and @code{end-of-defun}, but when used inside the @REPL{} input area they instead go directly to the beginning or the end, respectively. @end table @c ----------------------- @comment node-name, next, previous, up @node Shortcuts, , Input Navigation, REPL @section Shortcuts ``Shortcuts'' are a special set of @REPL{} commands that are invoked by name. To invoke a shortcut you first press @kbd{,} (comma) at the @REPL{} prompt and then enter the shortcut's name when prompted. Shortcuts deal with things like switching between directories and compiling and loading Lisp systems. The set of shortcuts is listed below, and you can also use the @code{help} shortcut to list them interactively. @table @kbd @item change-directory (aka !d, cd) Change the current directory. @item change-package (aka !p) Change the current package. @item compile-and-load (aka cl) Compile (if neccessary) and load a lisp file. @item compile-system Compile (but not load) an ASDF system. @item defparameter (aka !) Define a new global, special, variable. @item force-compile-system Recompile (but not load) an ASDF system. @item force-load-system Recompile and load an ASDF system. @item help (aka ?) Display the help. @item load-system Compile (as needed) and load an ASDF system. @item pop-directory (aka -d) Pop the current directory. @item pop-package (aka -p) Pop the top of the package stack. @item push-directory (aka +d, pushd) Push a new directory onto the directory stack. @item push-package (aka +p) Push a package onto the package stack. @item pwd Show the current directory. @item quit Quit the current Lisp. @item resend-form Resend the last form. @item restart-inferior-lisp Restart *inferior-lisp* and reconnect SLIME. @item sayoonara Quit all Lisps and close all SLIME buffers. @end table @c ----------------------- @node Debugger, Extras, REPL, Top @chapter SLDB: the SLIME debugger @SLIME{} has a custom Emacs-based debugger called @SLDB{}. Conditions signalled in the Lisp system invoke @SLDB{} in Emacs by way of the Lisp @code{*DEBUGGER-HOOK*}. @SLDB{} pops up a buffer when a condition is signalled. The buffer displays a description of the condition, a list of restarts, and a backtrace. Commands are offered for invoking restarts, examining the backtrace, and poking around in stack frames. @menu * Examining frames:: * Restarts:: * Frame Navigation:: * Miscellaneous:: @end menu @c ----------------------- @node Examining frames, Restarts, Debugger, Debugger @section Examining frames Commands for examining the stack frame at point. @table @kbd @kbdanchor{t, sldb-toggle-details} Toggle display of local variables and @code{CATCH} tags. @kbdanchor{v, sldb-show-source} View the frame's current source expression. The expression is presented in the Lisp source file's buffer. @kbdanchor{e, sldb-eval-in-frame} Evaluate an expression in the frame. The expression can refer to the available local variables in the frame. @kbdanchor{d, sldb-pprint-eval-in-frame} Evaluate an expression in the frame and pretty-print the result in a temporary buffer. @kbdanchor{D, sldb-disassemble} Disassemble the frame's function. Includes information such as the instruction pointer within the frame. @kbdanchor{i, sldb-inspect-in-frame} Inspect the result of evaluating an expression in the frame. @end table @c ----------------------- @node Restarts, Frame Navigation, Examining frames, Debugger @section Invoking restarts @table @kbd @kbdanchor{a, sldb-abort} Invoke the @code{ABORT} restart. @kbdanchor{q, sldb-quit} ``Quit'' -- @code{THROW} to a tag that the top-level @SLIME{} request-loop catches. @kbdanchor{c, sldb-continue} Invoke the @code{CONTINUE} restart. @item 0 ... 9 Invoke a restart by number. @end table Restarts can also be invoked by pressing @kbd{RET} or @kbd{Mouse-2} on them in the buffer. @c ----------------------- @node Frame Navigation, Miscellaneous, Restarts, Debugger @section Navigating between frames @table @kbd @item n @item p @code{sldb-down, sldb-up}@* Move between frames. @item M-n @item M-p @code{sldb-details-@{down,up@}}@* Move between frames ``with sugar'': hide the details of the original frame and display the details and source code of the next. Sugared motion makes you see the details and source code for the current frame only. @end table @c ----------------------- @node Miscellaneous, , Frame Navigation, Debugger @section Miscellaneous Commands @table @kbd @kbdanchor{r, sldb-restart-frame} Restart execution of the frame with the same arguments it was originally called with. (This command is not available in all implementations.) @kbdanchor{R, sldb-return-from-frame} Return from the frame with a value entered in the minibuffer. (This command is not available in all implementations.) @kbdanchor{s, sldb-step} Step to the next expression in the frame. (This command is not available in all implementations.) @kbdanchor{B, sldb-break-with-default-debugger} Exit @SLDB{} and debug the condition using the Lisp system's default debugger. @fcnanchor{in-sldb-face} Return STRING propertised with face sldb-NAME-face. @kbditem{C-c :, slime-interactive-eval} Evaluate an expression entered in the minibuffer. @end table @c ----------------------- @node Extras, Customization, Debugger, Top @chapter Extras @menu * slime-selector:: * slime-autodoc-mode:: * slime-macroexpansion-minor-mode:: * Multiple connections:: * Typeout frames:: @end menu @c ----------------------- @node slime-selector, slime-autodoc-mode, Extras, Extras @section @code{slime-selector} The @code{slime-selector} command is for quickly switching to important buffers: the @REPL{}, @SLDB{}, the Lisp source you were just hacking, etc. Once invoked the command prompts for a single letter to specify which buffer it should display. Here are some of the options: @table @kbd @item ? A help buffer listing all @code{slime-selectors}'s available buffers. @item r The @REPL{} buffer for the current @SLIME{} connection. @item d The most recently activated @SLDB{} buffer for the current connection. @item l The most recently visited @code{lisp-mode} source buffer. @item s The @code{*slime-scratch*} buffer. @xref{slime-scratch}. @end table @code{slime-selector} doesn't have a key binding by default but we suggest that you assign it a global one. You can bind it to @kbd{C-c s} like this: @example (global-set-key "\C-cs" 'slime-selector) @end example @noindent And then you can switch to the @REPL{} from anywhere with @kbd{C-c s r}. The macro @code{def-slime-selector-method} can be used to define new buffers for @code{slime-selector} to find. @c ----------------------- @node slime-autodoc-mode, slime-macroexpansion-minor-mode, slime-selector, Extras @section @code{slime-autodoc-mode} @table @kbd @kbditem{M-x, slime-autodoc-mode} Autodoc mode is an additional minor-mode for automatically showing information about symbols near the point. For function names the argument list is displayed, and for global variables, the value. This is a clone of @code{eldoc-mode} for Emacs Lisp. @end table The mode can be enabled by default in the @code{slime-setup} call of your @code{~/.emacs}: @example (slime-setup :autodoc t) @end example @c ----------------------- @node slime-macroexpansion-minor-mode, Multiple connections, slime-autodoc-mode, Extras @section slime-macroexpansion-minor-mode Within a slime macroexpansion buffer some extra commands are provided (these commands are always available but are only bound to keys in a macroexpansion buffer). @table @kbd @kbdanchor{C-c C-m, slime-macroexpand-1-inplace} Just like slime-macroexpand-1 but the original form is replaced with the expansion. @c @anchor{slime-macroexpand-1-inplace} @kbditem{g, slime-macroexpand-1-inplace} The last macroexpansion is performed again, the current contents of the macroexpansion buffer are replaced with the new expansion. @kbdanchor{q, slime-temp-buffer-quit} Close the expansion buffer. @end table @c ----------------------- @node Multiple connections, Typeout frames, slime-macroexpansion-minor-mode, Extras @section Multiple connections @SLIME{} is able to connect to multiple Lisp processes at the same time. The @kbd{M-x slime} command, when invoked with a prefix argument, will offer to create an additional Lisp process if one is already running. This is often convenient, but it requires some understanding to make sure that your @SLIME{} commands execute in the Lisp that you expect them to. Some buffers are tied to specific Lisp processes. Each Lisp connection has its own @acronym{REPL} buffer, and all expressions entered or @SLIME{} commands invoked in that buffer are sent to the associated connection. Other buffers created by @SLIME{} are similarly tied to the connections they originate from, including @SLDB{} buffers, apropos result listings, and so on. These buffers are the result of some interaction with a Lisp process, so commands in them always go back to that same process. Commands executed in other places, such as @code{slime-mode} source buffers, always use the ``default'' connection. Usually this is the most recently established connection, but this can be reassigned via the ``connection list'' buffer: @table @kbd @kbdanchor{C-c C-x c, slime-list-connections} Pop up a buffer listing the established connections. @kbdanchor{C-c C-x t, slime-list-threads} Pop up a buffer listing the current threads. @fcnanchor{slime-abort-connection} Abort the current connection. @fcnanchor{slime-restart-connection-at-point} @end table The buffer displayed by @code{slime-list-connections} gives a one-line summary of each connection. The summary shows the connection's serial number, the name of the Lisp implementation, and other details of the Lisp process. The current ``default'' connection is indicated with an asterisk. The commands available in the connection-list buffer are: @table @kbd @kbdanchor{RET, slime-goto-connection} Pop to the @acronym{REPL} buffer of the connection at point. @kbdanchor{d, slime-connection-list-make-default} Make the connection at point the ``default'' connection. It will then be used for commands in @code{slime-mode} source buffers. @kbdanchor{g, slime-update-connection-list} Update the connection list in the buffer. @kbditem{q, slime-temp-buffer-quit} Quit the connection list (kill buffer, restore window configuration). @fcnanchor{slime-connect} Connect to a running Swank server. @fcnanchor{slime-disconnect} Disconnect all connections. @fcnanchor{slime-connection-list-mode} Connection-list. @acronym{SLIME} Connection List Mode. @end table @c ----------------------- @node Typeout frames, , Multiple connections, Extras @section Typeout frames A ``typeout frame'' is a special Emacs frame which is used instead of the echo area (minibuffer) to display messages from @SLIME{} commands. This is an optional feature. The advantage of a typeout frame over the echo area is that it can hold more text, it can be scrolled, and its contents don't disappear when you press a key. All potentially long messages are sent to the typeout frame, such as argument lists, macro expansions, and so on. @table @kbd @fcnanchor{slime-ensure-typeout-frame} Ensure that a typeout frame exists, creating one if necessary. @end table If the typeout frame is closed then the echo area will be used again as usual. To have a typeout frame created automatically at startup you can add the @code{slime-connected-hook} to your @file{~/.emacs} file: @example (add-hook 'slime-connected-hook 'slime-ensure-typeout-frame) @end example @c ----------------------- @node Customization, Tips and Tricks, Extras, Top @chapter Customization @menu * Emacs-side customization:: * Lisp-side:: @end menu @c ----------------------- @node Emacs-side customization, Lisp-side, Customization, Customization @section Emacs-side The Emacs part of @SLIME{} can be configured with the Emacs @code{customize} system, just use @kbd{M-x customize-group slime RET}. Because the customize system is self-describing, we only cover a few important or obscure configuration options here in the manual. @table @code @item slime-truncate-lines The value to use for @code{truncate-lines} in line-by-line summary buffers popped up by @SLIME{}. This is @code{t} by default, which ensures that lines do not wrap in backtraces, apropos listings, and so on. It can however cause information to spill off the screen. @item slime-multiprocessing This should be set to @code{t} if you want to use multiprocessing (threads) in your Lisp system. It causes any necessary initialization to be performed during Lisp server startup. @anchor{slime-complete-symbol-function} @item slime-complete-symbol-function The function to use for completion of Lisp symbols. Three completion styles are available. The default @code{slime-complete-symbol*} performs completion ``in parallel'' over the hyphen-delimited sub-words of a symbol name. @footnote{This style of completion is modelled on @file{completer.el} by Chris McConnell. That package is bundled with @acronym{ILISP}.} Formally this means that ``@code{a-b-c}'' can complete to any symbol matching the regular expression ``@code{^a.*-b.*-c.*}'' (where ``dot'' matches anything but a hyphen). Examples give a more intuitive feeling: @itemize @bullet @item @code{m-v-b} completes to @code{multiple-value-bind}. @item @code{w-open} is ambiguous: it completes to either @code{with-open-file} or @code{with-open-stream}. The symbol is expanded to the longest common completion (@code{with-open-}) and the point is placed at the first point of ambiguity, which in this case is the end. @item @code{w--stream} completes to @code{with-open-stream}. @end itemize An alternative is @code{slime-simple-complete-symbol}, which completes in the usual Emacs way. Finally, there is @code{slime-fuzzy-complete-symbol}, which is quite different from both of the above and tries to find best matches to an abbreviated symbol. It also has its own key binding, defaulting to @kbd{C-c M-i}. @xref{slime-fuzzy-complete-symbol}, for more information. @item slime-filename-translations This variable controls filename translation between Emacs and the Lisp system. It is useful if you run Emacs and Lisp on separate machines which don't share a common file system or if they share the filessytem but have different layouts, as is the case with @acronym{SMB}-based file sharing. @item slime-net-coding-system If you want to transmit Unicode characters between Emacs and the Lisp system, you should customize this variable. E.g., if you use SBCL, you can set: @example (setq slime-net-coding-system 'utf-8-unix) @end example To actually display Unicode characters you also need appropriate fonts, otherwise the characters will be rendered as hollow boxes. If you are using Allegro CL and GNU Emacs, you can also use @code{emacs-mule-unix} as coding system. GNU Emacs has often nicer fonts for the latter encoding. @end table @menu * Hooks:: @end menu @c ----------------------- @node Hooks, , Emacs-side customization, Emacs-side customization @subsection Hooks @table @code @fcnanchor{slime-mode-hook} @item slime-mode-hook This hook is run each time a buffer enters @code{slime-mode}. It is most useful for setting buffer-local configuration in your Lisp source buffers. An example use is to enable @code{slime-autodoc-mode} (@xref{slime-autodoc-mode}.) @item slime-connected-hook This hook is run when @SLIME{} establishes a connection to a Lisp server. An example use is to create a Typeout frame (@xref{Typeout frames}.) @item sldb-hook This hook is run after @SLDB{} is invoked. The hook functions are called from the @SLDB{} buffer after it is initialized. An example use is to add @code{sldb-print-condition} to this hook, which makes all conditions debugged with @SLDB{} be recorded in the @REPL{} buffer. @end table @c ----------------------- @node Lisp-side, , Emacs-side customization, Customization @section Lisp-side (Swank) The Lisp server side of @SLIME{} (known as ``Swank'') offers several variables to configure. The initialization file @file{~/.swank.lisp} is automatically evaluated at startup and can be used to set these variables. @menu * Communication style:: * Other configurables:: @end menu @c ----------------------- @node Communication style, Other configurables, Lisp-side, Lisp-side @subsection Communication style The most important configurable is @code{SWANK:*COMMUNICATION-STYLE*}, which specifies the mechanism by which Lisp reads and processes protocol messages from Emacs. The choice of communication style has a global influence on @SLIME{}'s operation. The available communication styles are: @table @code @item NIL This style simply loops reading input from the communication socket and serves @SLIME{} protocol events as they arise. The simplicity means that the Lisp cannot do any other processing while under @SLIME{}'s control. @item :FD-HANDLER This style uses the classical Unix-style ``@code{select()}-loop.'' Swank registers the communication socket with an event-dispatching framework (such as @code{SERVE-EVENT} in @acronym{CMUCL} and @acronym{SBCL}) and receives a callback when data is available. In this style requests from Emacs are only detected and processed when Lisp enters the event-loop. This style is simple and predictable. @item :SIGIO This style uses @dfn{signal-driven I/O} with a @code{SIGIO} signal handler. Lisp receives requests from Emacs along with a signal, causing it to interrupt whatever it is doing to serve the request. This style has the advantage of responsiveness, since Emacs can perform operations in Lisp even while it is busy doing other things. It also allows Emacs to issue requests concurrently, e.g. to send one long-running request (like compilation) and then interrupt that with several short requests before it completes. The disadvantages are that it may conflict with other uses of @code{SIGIO} by Lisp code, and it may cause untold havoc by interrupting Lisp at an awkward moment. @item :SPAWN This style uses multiprocessing support in the Lisp system to execute each request in a separate thread. This style has similar properties to @code{:SIGIO}, but it does not use signals and all requests issued by Emacs can be executed in parallel. @end table The default request handling style is chosen according to the capabilities of your Lisp system. The general order of preference is @code{:SPAWN}, then @code{:SIGIO}, then @code{:FD-HANDLER}, with @code{NIL} as a last resort. You can check the default style by calling @code{SWANK-BACKEND:PREFERRED-COMMUNICATION-STYLE}. You can also override the default by setting @code{SWANK:*COMMUNICATION-STYLE*} in your Swank init file. @c ----------------------- @node Other configurables, , Communication style, Lisp-side @subsection Other configurables These Lisp variables can be configured via your @file{~/.swank.lisp} file: @table @code @item SWANK:*CONFIGURE-EMACS-INDENTATION* This variable controls whether indentation styles for @code{&body}-arguments in macros are discovered and sent to Emacs. It is enabled by default. @item SWANK:*GLOBALLY-REDIRECT-IO* When true this causes the standard streams (@code{*standard-output*}, etc) to be globally redirected to the @REPL{} in Emacs. When @code{NIL} (the default) these streams are only temporarily redirected to Emacs using dynamic bindings while handling requests. Note that @code{*standard-input*} is currently never globally redirected into Emacs, because it can interact badly with the Lisp's native @REPL{} by having it try to read from the Emacs one. @item SWANK:*GLOBAL-DEBUGGER* When true (the default) this causes @code{*DEBUGGER-HOOK*} to be globally set to @code{SWANK:SWANK-DEBUGGER-HOOK} and thus for @SLIME{} to handle all debugging in the Lisp image. This is for debugging multithreaded and callback-driven applications. @item SWANK:*SLDB-PRINTER-BINDINGS* @itemx SWANK:*MACROEXPAND-PRINTER-BINDINGS* @itemx SWANK:*SWANK-PPRINT-BINDINGS* These variables can be used to customize the printer in various situations. The values of the variables are association lists of printer variable names with the corresponding value. E.g., to enable the pretty printer for formatting backtraces in @SLDB{}, you can use: @example (push '(*print-pretty* . t) swank:*sldb-printer-bindings*). @end example @item SWANK:*USE-DEDICATED-OUTPUT-STREAM* This variable controls an optimization for sending printed output from Lisp to Emacs. When @code{t} a separate socket is established solely for Lisp to send printed output to Emacs through. Without the optimization it is necessary to send output in protocol-messages to Emacs which must then be decoded, and this doesn't always keep up if Lisp starts ``spewing'' copious output. @item SWANK:*DEDICATED-OUTPUT-STREAM-PORT* When @code{*USE-DEDICATED-OUTPUT-STREAM*} is @code{t} the stream will be opened on this port. The default value, @code{0}, means that the stream will be opened on some random port. @item SWANK:*LOG-EVENTS* Setting this variable to @code{t} causes all protocol messages exchanged with Emacs to be printed to @code{*TERMINAL-IO*}. This is useful for low-level debugging and for observing how @SLIME{} works ``on the wire.'' The output of @code{*TERMINAL-IO*} can be found in your Lisp system's own listener, usually in the buffer @code{*inferior-lisp*}. @end table @c ----------------------- @node Tips and Tricks, Credits, Customization, Top @chapter Tips and Tricks @menu * Connecting to a remote lisp:: * Global IO Redirection:: * Auto-SLIME:: @end menu @c ----------------------- @node Connecting to a remote lisp @section Connecting to a remote lisp One of the advantages of the way @SLIME{} is implemented is that we can easily run the Emacs side (slime.el) on one machine and the lisp backend (swank) on another. The basic idea is to start up lisp on the remote machine, load swank and wait for incoming slime connections. On the local machine we start up emacs and tell slime to connect to the remote machine. The details are a bit messier but the underlying idea is that simple. @menu * Setting up the lisp image:: * Setting up Emacs:: * Setting up pathname translations:: @end menu @c ----------------------- @node Setting up the lisp image @subsection Setting up the lisp image When you want to load swank without going through the normal, Emacs based, process just load the @file{swank-loader.lisp} file. Just execute @example (load "/path/to/swank-loader.lisp") @end example inside a running lisp image@footnote{@SLIME{} also provides an @acronym{ASDF} system definiton which does the same thing}. Now all we need to do is startup our swank server. The first example assumes we're using the default settings. @example (swank:create-server) @end example Since we're going to be tunneling our connection via ssh@footnote{there is a way to connect without an ssh tunnel, but it has the side-effect of giving the entire world access to your lisp image, so we're not going to talk about it} and we'll only have one port open we want to tell swank to not use an extra connection for output: @example (setf swank:*use-dedicated-output-stream* nil) @end example @c ----------------------- If you need to do anything particular (like be able to reconnect to swank after you're done), look into @code{swank:create-server}'s other arguments. Some of these arguments are @table @code @item :PORT Port number for the server to listen on (default: 4005). @item :STYLE See @xref{Communication style}. @item :DONT-CLOSE Boolean indicating if the server will continue to accept connections after the first one (default: @code{NIL}). For ``long-running'' lisp processes to which you want to be able to connect from time to time, specify @code{:dont-close t} @item :CODING-SYSTEM String designating the encoding to be used to communicate between the Emacs and Lisp. @end table So the more complete example will be @example (swank:create-server :port 4005 :dont-close t :coding-system "utf-8-unix") @end example On the emacs side you will use something like @example (setq slime-net-coding-system 'utf-8-unix) (slime-connect "127.0.0.1" 4005)) @end example to connect to this lisp image from the same machine. @node Setting up Emacs @subsection Setting up Emacs Now we need to create the tunnel between the local machine and the remote machine. @example ssh -L4005:127.0.0.1:4005 username@@remote.example.com @end example That ssh invocation creates an ssh tunnel between the port 4005 on our local machine and the port 4005 on the remote machine@footnote{By default swank listens for incoming connections on port 4005, had we passed a @code{:port} parameter to @code{swank:create-server} we'd be using that port number instead}. Finally we can start @SLIME{}: @example M-x slime-connect RET RET @end example The @kbd{RET RET} sequence just means that we want to use the default host (@code{127.0.0.1}) and the default port (@code{4005}). Even though we're connecting to a remote machine the ssh tunnel fools Emacs into thinking it's actually @code{127.0.0.1}. @c ----------------------- @node Setting up pathname translations @subsection Setting up pathname translations One of the main problems with running swank remotely is that Emacs assumes the files can be found using normal filenames. if we want things like @code{slime-compile-and-load-file} (@kbd{C-c C-k}) and @code{slime-edit-definition} (@kbd{M-.}) to work correctly we need to find a way to let our local Emacs refer to remote files. There are, mainly, two ways to do this. The first is to mount, using NFS or similar, the remote machine's hard disk on the local machine's file system in such a fashion that a filename like @file{/opt/project/source.lisp} refers to the same file on both machines. Unfortunetly NFS is usually slow, often buggy, and not always feasable, fortunetely we have an ssh connection and Emacs' @code{tramp-mode} can do the rest. What we do is teach Emacs how to take a filename on the remote machine and translate it into something that tramp can understand and access (and vice-versa). Assuming the remote machine's host name is @code{remote.example.com}, @code{cl:machine-instance} returns ``remote'' and we login as the user ``user'' we can use @SLIME{}'s built-in mechanism to setup the proper transaltions by simply doing: @example (push (slime-create-filename-translator :machine-instance "remote.example.com" :remote-host "remote" :username "user") slime-filename-translations) @end example @c ----------------------- @node Global IO Redirection @section Globally redirecting all IO to the REPL By default @SLIME{} does not change @code{*standard-output*} and friends outside of the @REPL{}. If you have any other threads which call @code{format}, @code{write-string}, etc. that output will be seen only in the @code{*inferior-lisp*} buffer or on the terminal, more often than not this is inconvenient. So, if you want code such as this: @example (run-in-new-thread (lambda () (write-line "In some random thread.~%" *standard-output*))) @end example to send its output to @SLIME{}'s repl buffer, as opposed to @code{*inferior-lisp*}, set @code{swank:*globally-redirect-io*} to T. Note that the value of this variable is only checked when swank accepts the connection so you should set it via @file{~/.swank.lisp}. Otherwise you will need to call @code{swank::globally-redirect-io-to-connection} yourself, but you shouldn't do that unless you know what you're doing. @c ----------------------- @node Auto-SLIME @section Connecting to SLIME automatically To make @SLIME{} connect to your lisp whenever you open a lisp file just add this to your @file{.emacs}: @example (add-hook 'slime-mode-hook (lambda () (unless (slime-connected-p) (save-excursion (slime))))) @end example @c ----------------------- @node Credits, Index to Functions, Tips and Tricks, Top @chapter Credits @emph{The soppy ending...} @unnumberedsec Hackers of the good hack @SLIME{} is an Extension of @acronym{SLIM} by Eric Marsden. At the time of writing, the authors and code-contributors of @SLIME{} are: @include contributors.texi ... not counting the bundled code from @file{hyperspec.el}, @cite{CLOCC}, and the @cite{CMU AI Repository}. Many people on the @code{slime-devel} mailing list have made non-code contributions to @SLIME{}. Life is hard though: you gotta send code to get your name in the manual. @code{:-)} @unnumberedsec Thanks! We're indebted to the good people of @code{common-lisp.net} for their hosting and help, and for rescuing us from ``Sourceforge hell.'' Implementors of the Lisps that we support have been a great help. We'd like to thank the @acronym{CMUCL} maintainers for their helpful answers, Craig Norvell and Kevin Layer at Franz providing Allegro CL licenses for @SLIME{} development, and Peter Graves for his help to get @SLIME{} running with @acronym{ABCL}. Most of all we're happy to be working with the Lisp implementors who've joined in the @SLIME{} development: Dan Barlow and Christophe Rhodes of @acronym{SBCL}, Gary Byers of OpenMCL, and Martin Simmons of LispWorks. Thanks also to Alain Picard and Memetrics for funding Martin's initial work on the LispWorks backend! @c ----------------------- @node Index to Functions, , Credits, Top @appendix Index to Functions These functions are all available (when relevant). To find the keybinding (if there is one) refer to the function description. @c Note to editors: @fcnindex{...} lines commented out below are place holders @c ---------------- @c They have yet to be documented @c Please feel free to add descriptions in the text where appropriate, add the @c appropriate anchors and uncomment them. @c @c [jkc] @table @code @fcnindex{common-lisp-hyperspec-format} @fcnindex{in-sldb-face} @fcnindex{sldb-abort} @c @fcnindex{sldb-activate} @c @fcnindex{sldb-add-face} @c @fcnindex{sldb-backward-frame} @c @fcnindex{sldb-beginning-of-backtrace} @c @fcnindex{sldb-break} @c @fcnindex{sldb-break-on-return} @fcnindex{sldb-break-with-default-debugger} @c @fcnindex{sldb-buffers} @c @fcnindex{sldb-catch-tags} @fcnindex{sldb-continue} @c @fcnindex{sldb-debugged-continuations} @c @fcnindex{sldb-default-action} @c @fcnindex{sldb-default-action/mouse} @c @fcnindex{sldb-delete-overlays} @c @fcnindex{sldb-details-down} @c @fcnindex{sldb-details-up} @fcnindex{sldb-disassemble} @c @fcnindex{sldb-dispatch-extras} @c @fcnindex{sldb-down} @c @fcnindex{sldb-end-of-backtrace} @fcnindex{sldb-eval-in-frame} @c @fcnindex{sldb-exit} @c @fcnindex{sldb-fetch-all-frames} @c @fcnindex{sldb-fetch-more-frames} @c @fcnindex{sldb-find-buffer} @c @fcnindex{sldb-format-reference-node} @c @fcnindex{sldb-format-reference-source} @c @fcnindex{sldb-forward-frame} @c @fcnindex{sldb-frame-details-visible-p} @c @fcnindex{sldb-frame-locals} @c @fcnindex{sldb-frame-number-at-point} @c @fcnindex{sldb-frame-region} @c @fcnindex{sldb-get-buffer} @c @fcnindex{sldb-get-default-buffer} @c @fcnindex{sldb-goto-last-frame} @c @fcnindex{sldb-help-summary} @c @fcnindex{sldb-hide-frame-details} @c @fcnindex{sldb-highlight-sexp} @c @fcnindex{sldb-insert-condition} @c @fcnindex{sldb-insert-frame} @c @fcnindex{sldb-insert-frames} @c @fcnindex{sldb-insert-locals} @c @fcnindex{sldb-insert-references} @c @fcnindex{sldb-insert-restarts} @c @fcnindex{sldb-inspect-condition} @fcnindex{sldb-inspect-in-frame} @c @fcnindex{sldb-inspect-var} @c @fcnindex{sldb-invoke-restart} @c @fcnindex{sldb-level} @c @fcnindex{sldb-list-catch-tags} @c @fcnindex{sldb-list-locals} @c @fcnindex{sldb-lookup-reference} @c @fcnindex{sldb-maybe-recenter-region} @c @fcnindex{sldb-mode-hook} @c @fcnindex{sldb-next} @c @fcnindex{sldb-out} @fcnindex{sldb-pprint-eval-in-frame} @c @fcnindex{sldb-previous-frame-number} @c @fcnindex{sldb-print-condition} @c @fcnindex{sldb-prune-initial-frames} @fcnindex{sldb-quit} @c @fcnindex{sldb-reference-properties} @c @fcnindex{sldb-restart-at-point} @fcnindex{sldb-restart-frame} @fcnindex{sldb-return-from-frame} @c @fcnindex{sldb-setup} @c @fcnindex{sldb-show-frame-details} @c @fcnindex{sldb-show-frame-source} @fcnindex{sldb-show-source} @fcnindex{sldb-step} @c @fcnindex{sldb-sugar-move} @fcnindex{sldb-toggle-details} @c @fcnindex{sldb-up} @c @fcnindex{sldb-var-number-at-point} @c @fcnindex{sldb-xemacs-emulate-point-entered-hook} @c @fcnindex{sldb-xemacs-post-command-hook} @c @fcnindex{inferior-slime-closing-return} @c @fcnindex{inferior-slime-indent-line} @c @fcnindex{inferior-slime-mode} @c @fcnindex{inferior-slime-return} @fcnindex{slime-abort-connection} @fcnindex{slime-apropos} @fcnindex{slime-apropos-all} @fcnindex{slime-apropos-package} @c @fcnindex{slime-arglist} @fcnindex{slime-autodoc-mode} @c @fcnindex{slime-autodoc-start-timer} @c @fcnindex{slime-background-activities-enabled-p} @c @fcnindex{slime-background-message} @c @fcnindex{slime-browse-classes} @c @fcnindex{slime-browse-xrefs} @fcnindex{slime-call-defun} @fcnindex{slime-calls-who} @c @fcnindex{slime-check-coding-system} @fcnindex{slime-close-all-sexp} @fcnindex{slime-close-parens-at-point} @fcnindex{slime-compile-and-load-file} @fcnindex{slime-compile-defun} @fcnindex{slime-compile-file} @fcnindex{slime-compile-region} @fcnindex{slime-compiler-macroexpand} @fcnindex{slime-compiler-macroexpand-1} @fcnindex{slime-compiler-notes-default-action-or-show-details} @fcnindex{slime-compiler-notes-default-action-or-show-details/mouse} @fcnindex{slime-compiler-notes-quit} @fcnindex{slime-compiler-notes-show-details} @fcnindex{slime-complete-form} @fcnindex{slime-complete-symbol} @fcnindex{slime-connect} @fcnindex{slime-connection-list-make-default} @fcnindex{slime-connection-list-mode} @c @fcnindex{slime-copy-presentation-at-point} @fcnindex{slime-describe-function} @fcnindex{slime-describe-symbol} @fcnindex{slime-disassemble-symbol} @fcnindex{slime-disconnect} @c @fcnindex{slime-documentation} @fcnindex{slime-edit-definition} @fcnindex{slime-edit-definition-other-frame} @fcnindex{slime-edit-definition-other-window} @fcnindex{slime-edit-definition-with-etags} @fcnindex{slime-edit-value} @c @fcnindex{slime-edit-value-commit} @c @fcnindex{slime-edit-value-mode} @fcnindex{slime-ensure-typeout-frame} @c @fcnindex{slime-eval-buffer} @fcnindex{slime-eval-defun} @fcnindex{slime-eval-last-expression} @fcnindex{slime-eval-last-expression-display-output} @c @fcnindex{slime-eval-print-last-expression} @fcnindex{slime-eval-region} @fcnindex{slime-fuzzy-abort} @fcnindex{slime-fuzzy-complete-symbol} @fcnindex{slime-fuzzy-completions-mode} @c @fcnindex{slime-fuzzy-next} @c @fcnindex{slime-fuzzy-prev} @c @fcnindex{slime-fuzzy-select} @c @fcnindex{slime-fuzzy-select/mouse} @fcnindex{slime-goto-connection} @fcnindex{slime-goto-xref} @c @fcnindex{slime-handle-repl-shortcut} @c @fcnindex{slime-highlight-notes} @fcnindex{slime-hyperspec-lookup} @c @fcnindex{slime-indent-and-complete-symbol} @c @fcnindex{slime-init-keymaps} @c @fcnindex{slime-insert-arglist} @c @fcnindex{slime-insert-balanced-comments} @fcnindex{slime-inspect} @fcnindex{slime-inspector-copy-down} @fcnindex{slime-inspector-describe} @fcnindex{slime-inspector-next} @c @fcnindex{slime-inspector-next-inspectable-object} @fcnindex{slime-inspector-quit} @c @fcnindex{slime-inspector-reinspect} @fcnindex{slime-interactive-eval} @fcnindex{slime-interrupt} @fcnindex{slime-list-callees} @fcnindex{slime-list-callers} @c @fcnindex{slime-list-compiler-notes} @fcnindex{slime-list-connections} @c @fcnindex{slime-list-repl-shortcuts} @fcnindex{slime-list-threads} @fcnindex{slime-load-file} @c @fcnindex{slime-load-system} @fcnindex{slime-macroexpand-1} @fcnindex{slime-macroexpand-1-inplace} @fcnindex{slime-macroexpand-all} @c @fcnindex{slime-make-default-connection} @c @fcnindex{slime-make-typeout-frame} @fcnindex{slime-mode} @c @fcnindex{slime-next-line/not-add-newlines} @c @fcnindex{slime-next-location} @fcnindex{slime-next-note} @fcnindex{slime-nop} @c @fcnindex{slime-ping} @fcnindex{slime-pop-find-definition-stack} @fcnindex{slime-pprint-eval-last-expression} @c @fcnindex{slime-presentation-menu} @c @fcnindex{slime-pretty-lambdas} @fcnindex{slime-previous-note} @fcnindex{slime-profile-package} @fcnindex{slime-profile-report} @fcnindex{slime-profile-reset} @fcnindex{slime-profiled-functions} @fcnindex{slime-quit} @c @fcnindex{slime-quit-connection-at-point} @c @fcnindex{slime-quit-lisp} @c @fcnindex{slime-re-evaluate-defvar} @c @fcnindex{slime-recompile-bytecode} @c @fcnindex{slime-register-lisp-implementation} @fcnindex{slime-reindent-defun} @c @fcnindex{slime-remove-balanced-comments} @fcnindex{slime-remove-notes} @c @fcnindex{slime-repl} @fcnindex{slime-repl-beginning-of-defun} @fcnindex{slime-repl-bol} @fcnindex{slime-repl-clear-buffer} @fcnindex{slime-repl-clear-output} @fcnindex{slime-repl-closing-return} @c @fcnindex{slime-repl-compile-and-load} @c @fcnindex{slime-repl-compile-system} @c @fcnindex{slime-repl-compile/force-system} @c @fcnindex{slime-repl-defparameter} @fcnindex{slime-repl-end-of-defun} @c @fcnindex{slime-repl-eol} @c @fcnindex{slime-repl-load-system} @c @fcnindex{slime-repl-load/force-system} @c @fcnindex{slime-repl-mode} @fcnindex{slime-repl-newline-and-indent} @fcnindex{slime-repl-next-input} @fcnindex{slime-repl-next-matching-input} @fcnindex{slime-repl-next-prompt} @c @fcnindex{slime-repl-pop-directory} @c @fcnindex{slime-repl-pop-packages} @fcnindex{slime-repl-previous-input} @fcnindex{slime-repl-previous-matching-input} @fcnindex{slime-repl-previous-prompt} @c @fcnindex{slime-repl-push-directory} @c @fcnindex{slime-repl-push-package} @c @fcnindex{slime-repl-read-break} @c @fcnindex{slime-repl-read-mode} @fcnindex{slime-repl-return} @fcnindex{slime-repl-set-package} @c @fcnindex{slime-repl-shortcut-help} @c @fcnindex{slime-reset} @fcnindex{slime-restart-connection-at-point} @fcnindex{slime-restart-inferior-lisp} @c @fcnindex{slime-restart-inferior-lisp-aux} @fcnindex{slime-scratch} @c @fcnindex{slime-select-lisp-implementation} @fcnindex{slime-selector} @c @fcnindex{slime-send-sigint} @c @fcnindex{slime-set-default-directory} @c @fcnindex{slime-set-package} @c @fcnindex{slime-show-xref} @fcnindex{slime-space} @c @fcnindex{slime-start-and-load} @fcnindex{slime-switch-to-output-buffer} @fcnindex{slime-sync-package-and-default-directory} @c @fcnindex{slime-temp-buffer-mode} @fcnindex{slime-temp-buffer-quit} @c @fcnindex{slime-thread-attach} @c @fcnindex{slime-thread-debug} @c @fcnindex{slime-thread-control-mode} @c @fcnindex{slime-thread-kill} @c @fcnindex{slime-thread-quit} @fcnindex{slime-toggle-profile-fdefinition} @fcnindex{slime-toggle-trace-fdefinition} @fcnindex{slime-undefine-function} @fcnindex{slime-unprofile-all} @fcnindex{slime-untrace-all} @fcnindex{slime-update-connection-list} @c @fcnindex{slime-update-indentation} ??? @fcnindex{slime-who-binds} @fcnindex{slime-who-calls} @fcnindex{slime-who-macroexpands} @fcnindex{slime-who-references} @fcnindex{slime-who-sets} @fcnindex{slime-who-specializes} @c @fcnindex{slime-xref-mode} @c @fcnindex{slime-xref-quit} @end table @bye