Repository files navigation

Swank Clojure is aserver that allows SLIME (the Superior Lisp Interaction Mode forEmacs) to connect to Clojure projects.

This project is no longer under active development.

New users are strongly encouraged to try outnrepl.el instead. If you needan advanced debugger,Ritz might bea better fit.

The simplest way is to just "jack in" from an existing projectusingLeiningen:

• Installclojure-mode either fromMarmalade or fromgit.
• Add[lein-swank "1.4.5"] to the:plugins section of eitherproject.clj or your user profile.
• From an Emacs buffer inside a project, invokeM-x clojure-jack-in

If you are still using a version of Leiningen older than 1.7.0, youwill need to dolein plugin install swank-clojure 1.4.3 instead.

That's all it takes; there are no extra install steps beyondclojure-mode on the Emacs side and theswank-clojure plugin on theLeiningen side. In particular, be sure youdon't have any otherversions of SLIME loaded; see "Troubleshooting" below.

Commonly-used SLIME commands:

• M-.: Jump to the definition of a var
• M-TAB orC-c TAB: Autocomplete symbol at point
• C-x C-e: Eval the form under the point
• C-c C-k: Compile the current buffer
• C-c C-l: Load current buffer and force required namespaces to reload
• C-M-x: Compile the whole top-level form under the point.
• C-c S-i: Inspect a value
• C-c C-m: Macroexpand the call under the point
• C-c C-d C-d: Look up documentation for a var
• C-c C-z: Switch from a Clojure buffer to the repl buffer
• C-c M-p: Switch the repl namespace to match the current buffer
• C-c C-w c: List all callers of a given function

Pressing "v" on a stack trace a debug buffer will jump to the file andline referenced by that frame if possible.

Note that SLIME was designed to work with Common Lisp, which has adistinction between interpreted code and compiled code. Clojure has nosuch distinction, so the load-file functionality is overloaded to add:reload-all behaviour.

There are other ways to use Swank for different specificcircumstances. For each of these methods you will have to install theslime and slime-repl Emacs Lisp libraries manually as outlined in"Connecting with SLIME" below.

If you just want a standalone swank server with no third-partylibraries, you can use the shell wrapper that Leiningen installs foryou:

$ lein plugin install swank-clojure 1.4.3$ ~/.lein/bin/swank-clojureM-x slime-connect

If you put~/.lein/bin on your$PATH it's even moreconvenient.

You can also start a swank server by hand from inside your project.You'll need to have installed usinglein plugin install, then launch the server from the shell:

$ lein swank # you can specify PORT and HOST optionally

If you're using Maven, add this to your pom.xml under the<dependencies> section:

    <dependency>      <groupId>swank-clojure</groupId>      <artifactId>swank-clojure</artifactId>      <version>1.4.3</version>    </dependency>

Then you can launch a swank server like so:

$ mvn clojure:swank

Note that due to a bug in clojure-maven-plugin, you currently cannotinclude it as a test-scoped dependency; it must be compile-scoped. Youalso cannot change the port from Maven; it's hard-coded to 4005.

You can embed Swank Clojure in your project, start the server fromwithin your own code, and connect via Emacs to that instance:

(nsmy-app  (:require [swank.swank]))(swank.swank/start-server);; optionally takes :host/:port keyword args

To make this work in production, swank-clojure needs to be in:dependencies in project.clj in addition to being installedas a user-level plugin. If you do this, you can also start the serverdirectly from thejava command-line launcher if you're using Clojure1.3 or newer:

$ java -cp my-project-standalone-1.0.0.jar clojure.main -m swank.swank

If you're not using theM-x clojure-jack-in method mentionedabove, you'll have to install SLIME yourself. The easiest way is touse package.el. If you are using Emacs 24 or theEmacs Starter Kit,then you have it already. If not, get itfrom Emacs's own repository.

Then add Marmalade as an archive source in your Emacs config:

(require'package)(add-to-list'package-archives'("marmalade"."https://marmalade-repo.org/packages/")t)(package-initialize)

Evaluate that, then runM-x package-refresh-contents topull in the latest source lists. Then you can doM-xpackage-install and chooseslime-repl.

When you perform the installation, you will see warnings related tothe byte-compilation of the packages. This isnormal; the packageswill work just fine even if there are problems byte-compiling it uponinstallation.

Then you should be able to connect to the swank server you launched:

M-x slime-connect

It will prompt you for your host (usually localhost) and port. It mayalso warn you that your SLIME version doesn't match your Swankversion; this should be OK.

To get syntax highlighting in your repl buffer, use this elisp:

(add-hook'slime-repl-mode-hook          (defunclojure-mode-slime-font-lock ()            (require'clojure-mode)            (let (font-lock-mode)              (clojure-mode-font-lock-setup))))

To get colors in stack traces, load the elisp insrc/swank/payload/slime-frame-colors.el inside Emacs and uselein swank $PORT localhost :colors? true to launch the swank server.

Currently having multiple versions of swank-clojure on the classpathcan cause issues when runninglein swank orlein jack-in. It'srecommended to not put swank-clojure in your:dev-dependencies butrunlein plugin install to have it installed globally for allprojects instead. This also means that people hacking on your projectwon't have to pull it in if they are not Emacs users.

It's also possible for some packages to pull in old versions ofswank-clojure transitively, so check thelib/ directory ifyou are having issues. In particular, Incanter is known to exhibitthis problem. Judicious use of:exclusions make it work:

:dependencies [[incanter"1.2.3":exclusions [swank-clojure]]]

Since swank-clojure 1.3.4, having versions of clj-stacktrace olderthan 0.2.1 in your project or user-level plugins will causeUnable to resolve symbol: pst-elem-str errors. Keep in mind that user-levelplugins in~/.lein/plugins are uberjars in Leiningen 1.x, so it'spossible that one of your plugins (such aslein-difftest beforeversion 1.3.7) contains an old clj-stacktrace even if it doesn't haveits own file there. Specifying a newer version should be enough ifyou're having trouble:

:dependencies [[clj-stacktrace"0.2.4"]]

Having old versions of SLIME installed either manually or using asystem-wide package manager like apt-get may cause issues. Also theofficial CVS version of SLIME is not supported; it often breakscompatibility with Clojure. In addition, theslime-clj packages areincompatible with swank-clojure.

It's possible to have Emacs configured for both Common Lisp andClojure if you defer loading of Slime until it's needed.This issuehas details on how that is done. It's not possible to have a singleinstance of Emacs connect to both though.

Swank-clojure and SLIME are only tested with GNU Emacs; forks such asAquamacs and XEmacs may work but are not officially supported.

On Mac OS X, Emacs sessions launched from the GUI don't always respectyour configured $PATH. If Emacs can't findlein, you may need togive it some help. The quickest way is probably to add this elisp toyour config:

(setenv"PATH" (shell-command-to-string"echo $PATH"))

When usingclojure-jack-in, standard out for the Leiningen processappears in the*swank* buffer, but the*out* var gets rebound to awriter that is able to redirect to the*slime-repl* buffer. So ingeneral most Clojure output will show up in your repl buffer justfine, but for output coming from Java libraries you may need to checkthe*swank* buffer.

If you are running Emacs from Cygwin, you'll need to add the following to your.emacs.d/init.el file:

(defuncyg-slime-to-lisp-translation (filename)  (replace-regexp-in-string"\n"""    (shell-command-to-string     (format"cygpath.exe --windows %s" filename))))(defuncyg-lisp-to-slime-translation (filename)  (replace-regexp-in-string"\n""" (shell-command-to-string     (format"cygpath.exe --unix %s filename"))))(setq slime-to-lisp-filename-function#'cyg-slime-to-lisp-translation)(setq lisp-to-slime-filename-function#'cyg-lisp-to-slime-translation)

This is required because the jvm runs as a normal Windows exe and usesWindows style paths rather than Cygwin unix style paths.

Swank Clojure is simply a server that communicates over the Slimeprotocol with an Emacs process. As such it runs in a JVM process,usually launched by Leiningen. Slime is a client that runs withinEmacs to communicate with Swank. You can start the two of themseparately as explained in "Connecting with SLIME" above, butM-x clojure-jack-in will send the elisp code for Slime to the Emacsprocess to ensure that it uses a version of Slime that is compatiblewith that version of Swank. Once the Swank server is finished loading,it sends a signal to Emacs to connect to it.

You can set repl-aware breakpoints usingswank.core/break.For now, seeHugo Duncan's blogfor an explanation of this excellent feature.

CDT (included inSwank Clojure since 1.4.0) is a more comprehensive debugging toolthat includes support for stepping, seting breakpoints, catchingexceptions, and eval clojure expressions in the context of the currentlexical scope.

Note that the CDT does not work with:eval-in-leiningen withoutextra manual configuration.

• unmap-ns command
• show method argument names in slime inspector (theoretically possible?)
• show better metadata on functions in inspector
• offer restarts for class/var not found exceptions (slamhound integration?)
• add elisp payload for cdt commands
• suppress false "warning: unabled to add tools.jar to classpath" message

Theswank-clojure mailing listand clojure channel on Freenode are the best places to bring upquestions/issues.

Contributions are preferred as either Github pull requests or using"git format-patch". Please use standard indentation with no tabs,trailing whitespace, or lines longer than 80 columns. Seethis poston submitting good patches for sometips. If you've got some time on your hands, reading thisstyleguide wouldn't hurteither.

Copyright © 2008-2012 Jeffrey Chu, Phil Hagelberg, Hugo Duncan, andcontributors

Licensed under the EPL. (See the file COPYING.)