2.1 Supported Platforms

SLY supports a wide range of operating systems and Lisp implementations. SLY runs on Unix systems, Mac OSX, and Microsoft Windows. GNU Emacs versions 24.4 and above are supported. XEmacs or Emacs 23 are notably not supported.

The supported Lisp implementations, roughly ordered from the best-supported, are:

• CMU Common Lisp (CMUCL), 19d or newer
• Steel Bank Common Lisp (SBCL), 1.0 or newer
• Clozure Common Lisp (CCL), version 1.3 or newer
• LispWorks, version 4.3 or newer
• Allegro Common Lisp (ACL), version 6 or newer
• CLISP, version 2.35 or newer
• Armed Bear Common Lisp (ABCL)
• Scieneer Common Lisp (SCL), version 1.2.7 or newer
• Embedded Common Lisp (ECL)
• ManKai Common Lisp (MKCL)
• Clasp

Most features work uniformly across implementations, but some are prone to variation. These include the precision of placing compiler-note annotations, XREF support, and fancy debugger commands (like “restart frame”).

2.2 Downloading SLY

By far the easiest method for getting SLY up and running is using Emacs’ package system configured to the popular MELPA repository. This snippet of code should already be in your configuration:

(add-to-list 'package-archives
             '("melpa" . "https://melpa.org/packages/"))
(package-initialize)

You should now be able to issue the command M-x package-install, choose sly and have it be downloaded and installed automatically. If you don’t find it in the list, ensure you run M-x package-refresh-contents first.

In other situations, such as when developing SLY itself, you can access the Git repository directly:

git clone https://github.com/joaotavora/sly.git

If you want to hack on SLY, use Github’s fork functionality and submit a pull request. Be sure to first read the CONTRIBUTING.md file first.

2.3 Basic setup

If you installed SLY from MELPA, it is quite possible that you don’t need any more configuration, provided that SLY can find a suitable Lisp executable in your PATH environment variable.

Otherwise, you need to tell it where a Lisp program can be found, so customize the variable inferior-lisp-program (see Defcustom variables) or add a line like this one to your ~/.emacs or ~/.emacs.d/init.el (see Emacs Init File).

(setq inferior-lisp-program "/opt/sbcl/bin/sbcl")

After evaluating this, you should be able to execute M-x sly and be greeted with a REPL.

If you cloned from the Git repository, you’ll have to add a couple of more lines to your initialization file configuration:

(add-to-list 'load-path "~/dir/to/cloned/sly")
(require 'sly-autoloads)

2.4 Running SLY

SLY can either ask Emacs to start its own Lisp subprocesss or connect to a running process on a local or remote machine.

The first alternative is more common for local development and is started via M-x sly. The “inferior” Lisp process thus started is told to load the Lisp-side server known as “Slynk” and then a socket connection is established between Emacs and Lisp. Finally a REPL buffer is created where you can enter Lisp expressions for evaluation.

The second alternative uses M-x sly-connect. This assumes that that a Slynk server is running on some local or remote host, and listening on a given port. M-x sly-connect prompts the user for these values, and upon connection the REPL is established.

2.5 Basic customization

A big part of Emacs, and Emacs’s extensions, are its near-infinite customization possibilities. SLY is no exception, because it runs on both Emacs and the Lisp process, there are layers of Emacs-side customization and Lisp-side customization. But don’t be put off by this! SLY tries hard to provide sensible defaults that don’t “hide” any fanciness beneath layers of complicated code, so that even a setup with no customization at all exposes SLY’s most important functionality.

Emacs-side customization is usually done via Emacs-lisp code snippets added to the user’s initialization file, usually $HOME/.emacs or $HOME/.emacs.d/init.el (see Emacs Init File).

90% of Emacs-lisp customization happens in either “keymaps” or “hooks” (see Emacs-side). Still on the Emacs side, there is also a separate interface, appropriately called customize (or sometimes just custom), that uses a nicer UI with mouse-clickable buttons to set some special variables. See See Defcustom variables.

Lisp-side customization is done exclusively via Common Lisp code snippets added to the user’s $HOME/.slynkrc file. See See Lisp-side (Slynk).

As a preview, take this simple example of a frequently customized part of SLY: its keyboard shortcuts, known as “keybindings”. In the following snippet M-h is added to sly-prefix-map thus yielding C-c M-h as a shortcut to the sly-documentation-lookup command.

(eval-after-load 'sly
  `(define-key sly-prefix-map (kbd "M-h") 'sly-documentation-lookup))

2.6 Multiple Lisps

By default, the command M-x sly starts the program specified with inferior-lisp-program, a variable that you can customize (see Defcustom variables). However, if you invoke M-x sly with a prefix argument, meaning you type C-u M-x sly then Emacs prompts for the program which should be started instead.

If you need to do this frequently or if the command involves long filenames it’s more convenient to set the sly-lisp-implementations variable in your initialization file (see Emacs Init File). For example here we define two programs:

(setq sly-lisp-implementations
      '((cmucl ("cmucl" "-quiet"))
        (sbcl ("/opt/sbcl/bin/sbcl") :coding-system utf-8-unix)))

Now, if you invoke SLY with a negative prefix argument, M-- M-x sly, you can select a program from that list. When called without a prefix, either the name specified in sly-default-lisp, or the first item of the list will be used. The elements of the list should look like

(NAME (PROGRAM PROGRAM-ARGS...) &key CODING-SYSTEM INIT INIT-FUNCTION ENV)

NAME

is a symbol and is used to identify the program.

PROGRAM

is the filename of the program. Note that the filename can contain spaces.

PROGRAM-ARGS

is a list of command line arguments.

CODING-SYSTEM

the coding system for the connection. (see sly-net-coding-system)x

INIT

should be a function which takes two arguments: a filename and a character encoding. The function should return a Lisp expression as a string which instructs Lisp to start the Slynk server and to write the port number to the file. At startup, SLY starts the Lisp process and sends the result of this function to Lisp’s standard input. As default, sly-init-command is used. An example is shown in Loading Slynk faster.

INIT-FUNCTION

should be a function which takes no arguments. It is called after the connection is established. (See also sly-connected-hook.)

ENV

specifies a list of environment variables for the subprocess. E.g.

(sbcl-cvs ("/home/me/sbcl-cvs/src/runtime/sbcl"
           "--core" "/home/me/sbcl-cvs/output/sbcl.core")
          :env ("SBCL_HOME=/home/me/sbcl-cvs/contrib/"))

initializes SBCL_HOME in the subprocess.

4.1 Evaluating code

These commands each evaluate a Common Lisp expression in a different way. Usually they mimic commands for evaluating Emacs Lisp code. By default they show their results in the echo area, but a prefix argument C-u inserts the results into the current buffer, while a negative prefix argument M-- sends them to the kill ring.

C-x C-e ¶

M-x sly-eval-last-expression

Evaluate the expression before point and show the result in the echo area.

C-M-x ¶

M-x sly-eval-defun

Evaluate the current toplevel form and show the result in the echo area. ‘C-M-x’ treats ‘defvar’ expressions specially. Normally, evaluating a ‘defvar’ expression does nothing if the variable it defines already has a value. But ‘C-M-x’ unconditionally resets the variable to the initial value specified in the ‘defvar’ expression. This special feature is convenient for debugging Lisp programs.

If C-M-x or C-x C-e is given a numeric argument, it inserts the value into the current buffer, rather than displaying it in the echo area.

C-c : ¶

M-x sly-interactive-eval

Evaluate an expression read from the minibuffer.

C-c C-r ¶

M-x sly-eval-region

Evaluate the region.

C-c C-p ¶

M-x sly-pprint-eval-last-expression

Evaluate the expression before point and pretty-print the result in a fresh buffer.

C-c E ¶

M-x sly-edit-value

Edit the value of a setf-able form in a new buffer *Edit <form>*. The value is inserted into a temporary buffer for editing and then set in Lisp when committed with C-c C-c.

C-c C-u ¶

M-x sly-undefine-function

Undefine the function, with fmakunbound, for the symbol at point.

M-x sly-remove-method ¶

Remove a specific method of a generic function at point.

4.2 Compiling functions and files

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

C-c C-c ¶

M-x sly-compile-defun

Compile the top-level form at point. The region blinks shortly to give some feedback which part was chosen.

With (positive) prefix argument the form is compiled with maximal debug settings (C-u C-c C-c). With negative prefix argument it is compiled for speed (M-- C-c C-c). If a numeric argument is passed set debug or speed settings to it depending on its sign.

The code for the region is executed after compilation. In principle, the command writes the region to a file, compiles that file, and loads the resulting code.

This compilation may arm stickers (see Stickers).

C-c C-k ¶

M-x sly-compile-and-load-file

Compile and load the current buffer’s source file. If the compilation step fails, the file is not loaded. It’s not always easy to tell whether the compilation failed: occasionally you may end up in the debugger during the load step.

With (positive) prefix argument the file is compiled with maximal debug settings (C-u C-c C-k). With negative prefix argument it is compiled for speed (M-- C-c C-k). If a numeric argument is passed set debug or speed settings to it depending on its sign.

This compilation may arm stickers (see Stickers).

C-c M-k ¶

M-x sly-compile-file

Compile (but don’t load) the current buffer’s source file.

C-c C-l ¶

M-x sly-load-file

Load a Lisp file. This command uses the Common Lisp LOAD function.

M-x sly-compile-region ¶

Compile the selected region.

This compilation may arm stickers (see Stickers).

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.

M-n ¶

M-x sly-next-note

Move the point to the next compiler note and displays the note.

M-p ¶

M-x sly-previous-note

Move the point to the previous compiler note and displays the note.

C-c M-c ¶

M-x sly-remove-notes

Remove all annotations from the buffer.

C-x ` ¶

M-x next-error

Visit the next-error message. This is not actually a SLY command but SLY creates a hidden buffer so that most of the Compilation mode commands (See (emacs)Compilation Mode) work similarly for Lisp as for batch compilers.

4.3 Autodoc

SLY automatically shows information about symbols near the point. For function names the argument list is displayed, and for global variables, the value. Autodoc is implemented by means of eldoc-mode of Emacs.

M-x sly-arglist NAME ¶

Show the argument list of the function NAME.

M-x sly-autodoc-mode ¶

Toggles autodoc-mode on or off according to the argument, and toggles the mode when invoked without argument.

M-x sly-autodoc-manually ¶

Like sly-autodoc, but when called twice, or after sly-autodoc was already automatically called, display multiline arglist.

If sly-autodoc-use-multiline-p is set to non-nil, allow long autodoc messages to resize echo area display.

autodoc-mode is a SLY extension and can be turned off if you so wish (see Extensions)

4.4 Semantic indentation

SLY 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 &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, SLY 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:

(slynk:print-indentation-lossage)

If a collision causes you irritation, don’t have a nervous breakdown, just override the Elisp symbol’s sly-common-lisp-indent-function property to your taste. SLY 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. ¹

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 M-x sly-update-indentation to force all symbols to be scanned for indentation information.

4.5 Reader conditional fontification

SLY automatically evaluates reader-conditional expressions, like #+linux, in source buffers and “grays out” code that will be skipped for the current Lisp connection.

4.6 Macro-expansion commands

C-c C-m ¶

M-x sly-expand-1

Macroexpand (or compiler-macroexpand) the expression at point once. If invoked with a prefix argument use macroexpand instead or macroexpand-1 (or compiler-macroexpand instead of compiler-macroexpand-1).

M-x sly-macroexpand-1 ¶

Macroexpand the expression at point once. If invoked with a prefix argument, use macroexpand instead of macroexpand-1.

C-c M-m ¶

M-x sly-macroexpand-all

Fully macroexpand the expression at point.

M-x sly-compiler-macroexpand-1 ¶

Display the compiler-macro expansion of sexp at point.

M-x sly-compiler-macroexpand ¶

Repeatedly expand compiler macros of sexp at point.

M-x sly-format-string-expand ¶

Expand the format-string at point and display it. With prefix arg, or if no string at point, prompt the user for a string to expand.

Within a sly macroexpansion buffer some extra commands are provided (these commands are always available but are only bound to keys in a macroexpansion buffer).

C-c C-m ¶

M-x sly-macroexpand-1-inplace

Just like sly-macroexpand-1 but the original form is replaced with the expansion.

g ¶

M-x sly-macroexpand-1-inplace

The last macroexpansion is performed again, the current contents of the macroexpansion buffer are replaced with the new expansion.

q ¶

M-x sly-temp-buffer-quit

Close the expansion buffer.

C-_ ¶

M-x sly-macroexpand-undo

Undo last macroexpansion operation.

5.1 Finding definitions

One of the most used keybindings across all of SLY is the familiar M-. binding for sly-edit-definition.

Here’s the gist of it: when pressed with the cursor over a symbol name, that symbol’s name definition is looked up by the Lisp process, thus producing a Lisp source location, which might be a file, or a file-less buffer. For convenience, a type of “breadcrumb” is left behind at the original location where M-. was pressed, so that another keybinding M-, takes the user back to the original location. Thus multiple M-. trace a path through lisp sources that can be traced back with an equal number of M-,.

M-. ¶

M-x sly-edit-definition

Go to the definition of the symbol at point.

M-, ¶

M-*

M-x sly-pop-find-definition-stack

Go back to the point where M-. was invoked. This gives multi-level backtracking when M-. has been used several times.

C-x 4 . ¶

M-x sly-edit-definition-other-window

Like sly-edit-definition but switches to the other window to edit the definition in.

C-x 5 . ¶

M-x sly-edit-definition-other-frame

Like sly-edit-definition but opens another frame to edit the definition in.

The behaviour of the M-. binding is sometimes affected by the type of symbol you are giving it.

• For single functions or variables, M-. immediately switches the current window’s buffer and position to the target defun or defvar.
• For symbols with more than one associated definition, say, generic functions, the same M-. finds all methods and presents these results in separate window displaying a special *sly-xref* buffer (see Cross-referencing).

5.2 Cross-referencing

Finding and presenting the definition of a function is actually the most elementary aspect of broader cross-referencing facilities framework in SLY. There are other types of questions about the source code relations that you can ask the Lisp process.²

The following keybindings behave much like the M-. keybinding (see Finding definitions): when pressed as is they make a query about the symbol at point, but with a C-u prefix argument they prompt the user for a symbol. Importantly, they always popup a transient *sly-xref* buffer in a different window.

M-? ¶

M-x sly-edit-uses

Find all the references to this symbol, whatever the type of that reference.

C-c C-w C-c ¶

M-x sly-who-calls

Show function callers.

C-c C-w C-w ¶

M-x sly-calls-who

Show all known callees.

C-c C-w C-r ¶

M-x sly-who-references

Show references to global variable.

C-c C-w C-b ¶

M-x sly-who-binds

Show bindings of a global variable.

C-c C-w C-s ¶

M-x sly-who-sets

Show assignments to a global variable.

C-c C-w C-m ¶

M-x sly-who-macroexpands

Show expansions of a macro.

M-x sly-who-specializes ¶

Show all known methods specialized on a class.

There are two further “List callers/callees” commands that 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 XREF information is unavailable.

C-c < ¶

M-x sly-list-callers

List callers of a function.

C-c > ¶

M-x sly-list-callees

List callees of a function.

In the resulting *sly-xref* buffer, these commands are available:

RET ¶

M-x sly-show-xref

Show definition at point in the other window. Do not leave the *sly-xref buffer.

Space ¶

M-x sly-goto-xref

Show definition at point in the other window and close the *sly-xref buffer.

C-c C-c ¶

M-x sly-recompile-xref

Recompile definition at point. Uses prefix arguments like sly-compile-defun.

C-c C-k ¶

M-x sly-recompile-all-xrefs

Recompile all definitions. Uses prefix arguments like sly-compile-defun.

5.3 Auto-completion

Completion commands are used to complete a symbol or form based on what is already present at point. Emacs has many completion mechanisms that SLY tries to mimic as much as possible.

SLY provides two styles of completion. The choice between them happens in the Emacs customization variable see sly-complete-symbol-function, which can be set to two values, or methods:

1. sly-flex-completions This method is speculative. It assumes that the letters you’ve already typed aren’t necessarily an exact prefix of the symbol you’re thinking of. Therefore, any possible completion that contains these letters, in the order that you have typed them, is potentially a match. Completion matches are then sorted according to a score that should reflect the probability that you really meant that them.

   Flex completion implies that the package-qualification needed to access some symbols is automatically discovered for you. However, to avoid searching too many symbols unnecessarily, this method makes some minimal assumptions that you can override: it assumes, for example, that you don’t normally want to complete to fully qualified internal symbols, but will do so if it finds two consecutive colons (::) in your initial pattern. Similarly, it assumes that if you start a completion on a word starting :, you must mean a keyword (a symbol from the keyword package.)

   Here are the top results for some typical searches.

   CL-USER> (quiloa<TAB>)         ->  (ql:quickload)
   CL-USER> (mvbind<TAB>)         ->  (multiple-value-bind)
   CL-USER> (scan<TAB>)           ->  (ppcre:scan)
   CL-USER> (p::scan<TAB>)        ->  (ppcre::scanner)
   CL-USER> (setf locadirs<TAB>)  ->  (setf ql:*local-project-directories*)
   CL-USER> foobar                ->  asdf:monolithic-binary-op
   

2. sly-simple-completions This method uses “classical” completion on an exact prefix. Although poorer, this is simpler, more predictable and closer to the default Emacs completion method. You type a prefix for a symbol reference and SLY let’s you choose from symbols whose beginnings match it exactly.

As an enhancement in SLY over Emacs’ built-in completion styles, when the *sly-completions* buffer pops up, some keybindings are momentarily diverted to it:

C-n ¶

<down>

M-x sly-next-completion

Select the next completion.

C-p ¶

<up>

M-x sly-prev-completion

Select the previous completion.

tab ¶

RET

M-x sly-choose-completion

Choose the currently selected completion and enter it at point.

As soon as the user selects a completion or gives up by pressing C-g or moves out of the symbol being completed, the *sly-completions* buffer is closed.

5.4 Interactive objects

In many buffers and modes in SLY, there are snippets of text that represent objects “living” in the Lisp process connected to SLY. These regions are known in SLY as interactive values or objects. You can tell these objects from regular text by their distinct “face”, is Emacs parlance for text colour, or decoration. Another way to check if bit of text is an interactive object is to hover above it with the mouse and right-click (<mouse-3>) it: a context menu will appear listing actions that you can take on that object.

Depending on the mode, different actions may be active for different types of objects. Actions can also be invoked using keybindings active only when the cursor is on the button.

M-RET, ``Copy to REPL''

Copy the object to the main REPL (see REPL output and see REPL backreferences).

M-S-RET, ``Copy call to REPL''

An experimental feature. On some backtrace frames in the Debugger (see The SLY-DB Debugger) and Trace Dialog (see Trace Dialog), copy the object to the main REPL. That’s meta-shift-return, by the way, there’s no capital “S”.

.,''Go To Source''

For function symbols, debugger frames, or traced function calls, go to the Lisp source, much like with M-..

v,''Show Source''

For function symbols, debugger frames, or traced function calls, show the Lisp source in another window, but don’t switch to it.

p,''Pretty Print''

Pretty print the object in a separate buffer, much like sly-pprint-eval-last-expression.

i,''Inspect''

Inspect the object in a separate inspector buffer (see The Inspector).

d,''Describe''

Describe the object in a separate buffer using Lisp’s CL:DESCRIBE.

5.5 Documentation commands

SLY’s online documentation commands follow the example of Emacs Lisp. The commands all share the common prefix C-c C-d and allow the final key to be modified or unmodified (see Keybindings.)

M-x sly-info ¶

This command should land you in an electronic version of this very manual that you can read inside Emacs.

C-c C-d C-d ¶

M-x sly-describe-symbol

Describe the symbol at point.

C-c C-d C-f ¶

M-x sly-describe-function

Describe the function at point.

C-c C-d C-a ¶

M-x sly-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.

C-c C-d C-z ¶

M-x sly-apropos-all

Like sly-apropos but also includes internal symbols by default.

C-c C-d C-p ¶

M-x sly-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.

C-c C-d C-h ¶

M-x sly-hyperspec-lookup

Lookup the symbol at point in the Common Lisp Hyperspec. This uses the familiar hyperspec.el to show the appropriate section in a web browser. The Hyperspec is found either on the Web or in common-lisp-hyperspec-root, and the browser is selected by browse-url-browser-function.

Note: this is one case where C-c C-d h is not the same as C-c C-d C-h.

C-c C-d ~ ¶

M-x hyperspec-lookup-format

Lookup a format character in the Common Lisp Hyperspec.

C-c C-d # ¶

M-x hyperspec-lookup-reader-macro

Lookup a reader macro in the Common Lisp Hyperspec.

5.6 Multiple connections

SLY is able to connect to multiple Lisp processes at the same time. The M-x sly 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 SLY commands execute in the Lisp that you expect them to.

Some SLY buffers are tied to specific Lisp processes. It’s easy read that from the buffer’s name which will usually be *sly-<something> for <connection>*, where connection is the name of the connection.

Each Lisp connection has its own main REPL buffer (see The REPL: the “top level”), and all expressions entered or SLY commands invoked in that buffer are sent to the associated connection. Other buffers created by SLY are similarly tied to the connections they originate from, including SLY-DB buffers (see The SLY-DB Debugger), 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 sly-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:

C-c C-x c ¶

M-x sly-list-connections

Pop up a buffer listing the established connections.

C-c C-x n ¶

M-x sly-next-connection

Switch to the next Lisp connection by cycling through all connections.

C-c C-x p ¶

M-x sly-prev-connection

Switch to the previous Lisp connection by cycling through all connections.

The buffer displayed by sly-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:

RET ¶

M-x sly-goto-connection

Pop to the REPL buffer of the connection at point.

d ¶

M-x sly-connection-list-make-default

Make the connection at point the “default” connection. It will then be used for commands in sly-mode source buffers.

g ¶

M-x sly-update-connection-list

Update the connection list in the buffer.

q ¶

M-x sly-temp-buffer-quit

Quit the connection list (kill buffer, restore window configuration).

R ¶

M-x sly-restart-connection-at-point

Restart the Lisp process for the connection at point.

M-x sly-connect ¶

Connect to a running Slynk server. With prefix argument, asks if all connections should be closed first.

M-x sly-disconnect ¶

Disconnect all connections.

M-x sly-abort-connection ¶

Abort the current attempt to connect.

5.7 Disassembly commands

C-c M-d ¶

M-x sly-disassemble-symbol

Disassemble the function definition of the symbol at point.

C-c C-t ¶

M-x sly-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.

M-x sly-untrace-all ¶

Untrace all functions.

5.8 Abort/Recovery commands

C-c C-b ¶

M-x sly-interrupt

Interrupt Lisp (send SIGINT).

M-x sly-restart-inferior-lisp ¶

Restart the inferior-lisp process.

C-c ~ ¶

M-x sly-mrepl-sync

Synchronize the current package and working directory from Emacs to Lisp.

M-x sly-cd ¶

Set the current directory of the Lisp process. This also changes the current directory of the REPL buffer.

M-x sly-pwd ¶

Print the current directory of the Lisp process.

5.9 Temporary buffers

Some SLY 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 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 kill-buffer, in which case the previous window configuration won’t be restored.

Pressing 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 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 sly-mode in addition to any special mode of their own. This makes the usual SLY commands available for describing symbols, looking up function definitions, and so on.

Initial focus of those “description” buffers depends on the variable sly-description-autofocus. If nil (the default), description buffers do not receive focus automatically, and vice versa.

5.10 Multi-threading

If the Lisp system supports multi-threading, SLY spawns a new thread for each request, e.g., 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.

You can see a listing of the threads for the current connection with the command M-x sly-list-threads, or C-c C-x t. This pops open a *sly-threads* buffer, where some keybindings to control threads are active, if you know what you are doing. The most useful is probably k to kill a thread, but type C-h m in that buffer to get a full listing.

Some complications arise with multi-threading 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 slynk:*default-worker-thread-bindings* was introduced for such situations: instead of modifying the global value of a variable, add a binding the slynk:*default-worker-thread-bindings*. E.g., with the following code, new threads will read floating point values as doubles by default:

(push '(*read-default-float-format* . double-float)
       slynk:*default-worker-thread-bindings*).

6.1 The REPL: the “top level”

SLY uses a custom Read-Eval-Print Loop (REPL, also known as a “top level”, or listener):

• Conditions signalled in REPL expressions are debugged with the integrated SLY debugger.
• Return values are interactive values (see Interactive objects) distinguished from printed output by separate Emacs faces (colors).
• Output from the Lisp process is inserted in the right place, and doesn’t get mixed up with user input.
• Multiple REPLs are possible in the same Lisp connection. This is useful for performing quick one-off experiments in different packages or directories without disturbing the state of an existing REPL.
• The REPL is a central hub for much of SLY’s functionality, since objects examined in the inspector (see The Inspector), debugger (see The SLY-DB Debugger), and other extensions can be returned there.

Switching to the REPL from anywhere in a SLY buffer is a very common task. One way to do it is to find the *sly-mrepl...* buffer in Emacs’s buffer list, but there are other ways to reach a REPL.

C-c C-z ¶

M-x sly-mrepl

Start or select an existing main REPL buffer.

M-x sly-mrepl-new ¶

Start a new secondary REPL session, prompting for a nickname.

C-c ~ ¶

M-x sly-mrepl-sync

Go to the REPL, switching package and default directory as applicable. More precisely the Lisp variables *package* and *default-pathname-defaults* are affected by the location where the command was issued. In a specific position of a .lisp file, for instance the current package and that file’s directory are chosen.

• REPL commands
• REPL output
• REPL backreferences

; Cleared REPL history
CL-USER> (values 'a 'b 'c)
A
B
C
CL-USER> (list #v0)
(A)
CL-USER> (list #v0:1 #v0:2)
(B C)
CL-USER> (append #v1:0 #v2:0)
(A B C)
CL-USER>

6.2 The Inspector

The SLY inspector is a Emacs-based alternative to the standard INSPECT function. The inspector presents objects in Emacs buffers using a combination of plain text, hyperlinks to related objects.

The inspector can easily be specialized for the objects in your own programs. For details see the inspect-for-emacs generic function in slynk-backend.lisp.

C-c I ¶

M-x sly-inspect

Inspect the value of an expression entered in the minibuffer.

The standard commands available in the inspector are:

RET ¶

M-x sly-inspector-operate-on-point

If point is on a value then recursively call the inspector on that value. If point is on an action then call that action.

D ¶

M-x sly-inspector-describe-inspectee

Describe the slot at point.

e ¶

M-x sly-inspector-eval

Evaluate an expression in the context of the inspected object. The variable * will be bound to the inspected object.

v ¶

M-x sly-inspector-toggle-verbose

Toggle between verbose and terse mode. Default is determined by ‘slynk:*inspector-verbose*’.

l ¶

M-x sly-inspector-pop

Go back to the previous object (return from RET).

n ¶

M-x sly-inspector-next

The inverse of l. Also bound to SPC.

g ¶

M-x sly-inspector-reinspect

Reinspect.

h ¶

M-x sly-inspector-history

Show the previously inspected objects.

q ¶

M-x sly-inspector-quit

Dismiss the inspector buffer.

> ¶

M-x sly-inspector-fetch-all

Fetch all inspector contents and go to the end.

M-RET ¶

M-x sly-mrepl-copy-part-to-repl

Store the value under point in the variable ‘*’. This can then be used to access the object in the REPL.

TAB, M-x forward-button ¶

S-TAB, M-x backward-button

Jump to the next and previous inspectable object respectively.

6.3 The SLY-DB Debugger

SLY has a custom Emacs-based debugger called SLY-DB. Conditions signalled in the Lisp system invoke SLY-DB in Emacs by way of the Lisp *DEBUGGER-HOOK*.

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

• Examining frames
• Invoking restarts
• Navigating between frames
• Miscellaneous Commands

6.4 Trace Dialog

The SLY Trace Dialog, in package sly-trace-dialog, is a tracing facility, similar to Common Lisp’s trace, but interactive rather than purely textual.

You use it just like you would regular trace: after tracing a function, calling it causes interesting information about that particular call to be reported.

However, instead of printing the trace results to the the *trace-output* stream (usually the REPL), the SLY Trace Dialog collects and stores them in your Lisp environment until, on user’s request, they are fetched into Emacs and displayed in a dialog-like interactive view.

After starting up SLY, SLY’s Trace Dialog installs a Trace menu in the menu-bar of any sly-mode buffer and adds two new commands, with respective key-bindings:

C-c C-t ¶

M-x sly-trace-dialog-toggle-trace

If point is on a symbol name, toggle tracing of its function definition. If point is not on a symbol, prompt user for a function.

With a C-u prefix argument, and if your lisp implementation allows it, attempt to decipher lambdas, methods and other complicated function signatures.

The function is traced for the SLY Trace Dialog only, i.e. it is not found in the list returned by Common Lisp’s trace.

C-c T ¶

M-x sly-trace-dialog

Pop to the interactive Trace Dialog buffer associated with the current connection (see Multiple connections).

Consider the (useless) program:

(defun foo (n) (if (plusp n) (* n (bar (1- n))) 1))
(defun bar (n) (if (plusp n) (* n (foo (1- n))) 1))

After tracing both foo and bar with C-c M-t, calling call (foo 2) and moving to the trace dialog with C-c T, we are presented with this buffer.

Traced specs (2)                                  [refresh]
                                                  [untrace all]
  [untrace] common-lisp-user::bar
  [untrace] common-lisp-user::foo

Trace collection status (3/3)                     [refresh]
                                                  [clear]

   0 - common-lisp-user::foo
     | > 2
     | < 2
   1 `--- common-lisp-user::bar
        | > 1
        | < 1
   2    `-- common-lisp-user::foo
             > 0
             < 1

The dialog is divided into sections displaying the functions already traced, the trace collection progress and the actual trace tree that follow your program’s logic. The most important key-bindings in this buffer are:

g ¶

M-x sly-trace-dialog-fetch-status

Update information on the trace collection and traced specs.

G ¶

M-x sly-trace-dialog-fetch-traces

Fetch the next batch of outstanding (not fetched yet) traces. With a C-u prefix argument, repeat until no more outstanding traces.

C-k ¶

M-x sly-trace-dialog-clear-fetched-traces

Prompt for confirmation, then clear all traces, both fetched and outstanding.

The arguments and return values below each entry are interactive buttons. Clicking them opens the inspector (see The Inspector). Invoking M-RET (sly-trace-dialog-copy-down-to-repl) returns them to the REPL for manipulation (see The REPL: the “top level”). The number left of each entry indicates its absolute position in the calling order, which might differ from display order in case multiple threads call the same traced function.

sly-trace-dialog-hide-details-mode hides arguments and return values so you can concentrate on the calling logic. Additionally, sly-trace-dialog-autofollow-mode will automatically display additional detail about an entry when the cursor moves over it.

6.5 Stickers

SLY Stickers, implemented as the sly-stickers contrib (see Extensions), is a tool for “live” code annotations. It’s an alternative to the print or break statements you add to your code when debugging.

Contrary to these techniques, “stickers” are non-intrusive, meaning that saving your file doesn’t save your debug code along with it.

Here’s the general workflow:

• In Lisp source files, using C-c C-s C-s or M-x sly-stickers-dwim places a sticker on any Lisp form. Stickers can exist inside other stickers.
  
  
• Stickers are “armed” when a definition or a file is compiled with the familiar C-c C-c (M-x sly-compile-defun) or C-c C-k (M-x sly-compile-file) commands. An armed sticker changes color from the default grey background to a blue background.
  
  

From this point on, when the Lisp code is executed, the results of evaluating the underlying forms are captured in the Lisp side. Stickers help you examine your program’s behaviour in three ways:

1. C-c C-s C-r (or M-x sly-stickers-replay) interactively walks the user through recordings in the order that they occurred. In the created *sly-stickers-replay* buffer, type h for a list of keybindings active in that buffer.
   
   
2. To step through stickers as your code is executed, ensure that “breaking stickers” are enabled via M-x sly-stickers-toggle-break-on-stickers. Whenever a sticker-covered expression is reached, the debugger comes up with useful restarts and interactive for the values produced. You can tweak this behaviour by setting the Lisp-side variable SLYNK-STICKERS:*BREAK-ON-STICKERS* to a list with the elements :before and :after, making SLY break before a sticker, after it, or both.
   
   
3. C-c C-s S (M-x sly-stickers-fetch) populates the sticker overlay with the latest captured results, called “recordings”. If a sticker has captured any recordings, it will turn green, otherwise it will turn red. A sticker whose Lisp expression has caused a non-local exit, will be also be marked with a special face.
   
   

At any point, stickers can be removed with the same sly-stickers-dwim keybinding, by placing the cursor at the beginning of a sticker. Additionally adding prefix arguments to sly-stickers-dwim increase its scope, so C-u C-c C-s C-s will remove all stickers from the current function and C-u C-u C-c C-s C-s will remove all stickers from the current file.

Stickers can be nested inside other stickers, so it is possible to record the value of an expression inside another expression which is also annotated.

Stickers are interactive parts just like any other part in SLY that represents Lisp-side objects, so they can be inspected and returned to the REPL, for example. To move through the stickers with the keyboard use the existing keybindings to move through compilation notes (M-p and M-n) or use C-c C-s p and C-c C-s n (sly-stickers-prev-sticker and sly-stickers-next-sticker).

There are some caveats when using SLY Stickers:

• Stickers on unevaluated forms (such as let variable bindings, or other constructs) are rejected, though the function is still compiled as usual. To let the user know about this, these stickers remain grey, and are marked as “disarmed”. A message also appears in the echo area.
• Stickers placed on expressions inside backquoted expressions in macros are always armed, even though they may come to provoke a runtime error when the macro’s expansion is run. Think of this when setting a sticker inside a macro definition.

7.1 Emacs-side

• Keybindings
• Keymaps
• Defcustom variables
• Hooks

(eval-after-load 'sly
  `(define-key sly-prefix-map (kbd "M-h") 'sly-documentation-lookup))

(eval-after-load 'sly-mrepl
   `(define-key sly-mrepl-mode-map (kbd "C-c C-k")
                'sly-mrepl-clear-recent-output))

7.2 Lisp-side (Slynk)

The Lisp server side of SLY (known as “Slynk”) offers several variables to configure. The initialization file ~/.slynk.lisp is automatically evaluated at startup and can be used to set these variables.

• Communication style
• Other configurables

8.1 Connecting to a remote Lisp

One of the advantages of the way SLY is implemented is that we can easily run the Emacs side (sly.el and friends) on one machine and the Lisp backend (Slynk) on another. The basic idea is to start up Lisp on the remote machine, load Slynk and wait for incoming SLY connections. On the local machine we start up Emacs and tell SLY to connect to the remote machine. The details are a bit messier but the underlying idea is that simple.

• Setting up the Lisp image
• Setting up Emacs
• Setting up pathname translations

(push #p"/path/to/sly/slynk/" ASDF:*CENTRAL-REGISTRY*)
(asdf:require-system :slynk)

(slynk:create-server)

(slynk:create-server :port 4006  :dont-close t)

(setf slynk:*use-dedicated-output-stream* nil)

ssh -L4005:localhost:4005 youruser@remote.example.com

M-x sly-connect RET RET

(add-to-list 'sly-filename-translations
             (sly-create-filename-translator
              :machine-instance "remote"
              :remote-host "remote.example.com"
              :username "user"))

8.2 Loading Slynk faster

In this section, a technique to load Slynk faster on South Bank Common Lisp (SBCL) is presented. Similar setups should also work for other Lisp implementations.

A pre-canned solution that automates this technique was developed by Pierre Neidhardt.

For SBCL, we recommend that you create a custom core file with socket support and POSIX bindings included because those modules take the most time to load. To create such a core, execute the following steps:

shell$ sbcl
* (mapc 'require '(sb-bsd-sockets sb-posix sb-introspect sb-cltl2 asdf))
* (save-lisp-and-die "sbcl.core-for-sly")

After that, add something like this to your ~/.emacs or ~/.emacs.d/init.el (see Emacs Init File):

(setq sly-lisp-implementations '((sbcl ("sbcl" "--core"
      "sbcl.core-for-sly"))))

For maximum startup speed you can include the Slynk server directly in a core file. The disadvantage of this approach is that the setup is a bit more involved and that you need to create a new core file when you want to update SLY or SBCL. The steps to execute are:

shell$ sbcl
* (load ".../sly/slynk-loader.lisp")
* (slynk-loader:dump-image "sbcl.core-with-slynk")

Then add this to the Emacs initializion file:

(setq sly-lisp-implementations
      '((sbcl ("sbcl" "--core" "sbcl.core-with-slynk")
              :init (lambda (port-file _)
                      (format "(slynk:start-server %S)\n" port-file)))))

8.3 Connecting to SLY automatically

To make SLY connect to your lisp whenever you open a lisp file just add this to your ~/.emacs or ~/.emacs.d/init.el (see Emacs Init File):

(add-hook 'sly-mode-hook
          (lambda ()
            (unless (sly-connected-p)
              (save-excursion (sly)))))

8.4 REPLs and “Game Loops”

When developing Common Lisp video games or graphical applications, a REPL (see The REPL: the “top level”) is just as useful as anywhere else. But it is often the case that one needs to control exactly the timing of REPL requests and ensure they do not interfere with the “game loop”. In other situations, the choice of communication style (see Communication style) to the Slynk server may invalidate simultaneous multi-threaded operation of REPL and game loop.

Instead of giving up on the REPL or using a complicated solution, SLY’s REPL can be built into your game loop by using a couple of Slynk Common Lisp functions, SLYNK-MREPL:SEND-PROMPT and SLYNK:PROCESS-REQUESTS.

(defun my-repl-aware-game-loop ()
  (loop initially
          (princ "Starting our game")
          (slynk-mrepl:send-prompt)
        for i from 0
        do (with-simple-restart (abort "Skip rest of this game loop iteration")
             (when (zerop (mod i 10))
               (fresh-line)
               (princ "doing high-priority 3D game loop stuff"))
             (sleep 0.1)
             ;; When you're ready to serve a potential waiting 
             ;; REPL request, just do this non-blocking thing:
             (with-simple-restart (abort "Abort this game REPL evaluation")
               (slynk:process-requests t)))))

Note that this function is to be called from the REPL, and will enter kind of “sub-REPL” inside it. It’ll likely “just work” in this situation. However, if you need you need to call this from anywhere else (like, say, another thread), you must additionally arrange for the variable SLYNK-API:*CHANNEL* to be bound to the value it is bound to in whatever SLY REPL you wish to interact with your game.

8.5 Controlling SLY from outside Emacs

If your application has a non-SLY, non-Emacs user interface (graphical or otherwise), you can use it to exert some control over SLY functionality, such as its REPL (see The REPL: the “top level”) and inspector (see The Inspector). This requires that you first set, in Emacs, variable sly-enable-evaluate-in-emacs to non-nil. As the name suggests, it lets outside Slynk servers evaluate code in your Elisp runtime. It is set to nil by default for security purposes.

Once you’ve done that, you can call SLYNK-MREPL:COPY-TO-REPL-IN-EMACS from your CL code with some objects you’d like to manipulate in the REPL. Then you can have this code run from some UI event handler:

(lambda ()
  (slynk-mrepl:copy-to-repl-in-emacs
     (list 42 'foo)
     :blurb "Just a forty-two and a foo"))

And see those objects pop up in your REPL for inspection and manipulation.

You can also use the functions SLYNK:INSPECT-IN-EMACS, SLYNK:ED-IN-EMACS, and in general, any exported function ending in IN-EMACS. See their docstrings for details.

9.1 Loading and unloading “on the fly”

We recommend that you setup the sly-contribs variable before starting SLY via M-x sly, but if you want to enable more contribs after you that, you can set new sly-contribs variable to another value and call M-x sly-setup or M-x sly-enable-contrib. Note this though:

• If you’ve removed contribs from the list they won’t be unloaded automatically.
• If you have more than one SLY connection currently active, you must manually repeat the sly-setup step for each of them.

Short of restarting Emacs, a reasonable way of unloading contribs is by calling an Emacs Lisp function whose name is obtained by adding -unload to the contrib’s name, for every contrib you wish to unload. So, to remove sly-mrepl, you must call sly-mrepl-unload. Because the unload function will only, if ever, unload the Emacs Lisp side of the contrib, you may also need to restart your lisps.

9.2 More contribs

• TRAMP
• Scratch Buffer