# Swank Clojure

[Swank Clojure](http://github.com/technomancy/swank-clojure) is a
server that allows [SLIME](http://common-lisp.net/project/slime/) (the
Superior Lisp Interaction Mode for Emacs) to connect to Clojure
projects.

## Usage

Add Swank Clojure to your project as a development dependency to your
project. If you are using Leiningen, add it to your project.clj file
under :dev-dependencies:

    :dev-dependencies [[swank-clojure "1.2.0"]]

Once you run "lein deps" you can launch a swank server from the
command line:

    $ lein swank [PORT] [HOST]

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.2.0</version>
    </dependency>

Then you can launch a swank server like so:

    $ mvn -o clojure:swank

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

## Connecting with Slime

Install the "slime-repl" package [from ELPA](http://tromey.com/elpa)
using package.el[1]. When you perform the installation, you will see
warnings related to the byte-compilation of the packages. This is
**normal**; the packages will work just fine even if there are
problems byte-compiling it upon installation.

Then you should be able to connect to your Swank server:

    M-x slime-connect

It will prompt you for your host and port. It may also warn you that
your Slime version doesn't match your Swank version; this should be OK.

Having old versions of SLIME either manually installed or installed
using a system-wide package manager like apt-get may cause issues. If
you do have any manual configuration of SLIME, be sure to either
remove it or place it after package.el is initialized.

## Embedding

You can embed swank in your project, start the server from within your
own code, and connect via Emacs to that instance:

    (ns my-app
      (:use [swank.swank :as swank]))
    (swank/start-repl) ;; optionally takes a port argument

Then use M-x slime-connect to connect from within Emacs.

You can also start the server directly from the "java" command-line
launcher if you AOT-compile it and specify "swank.swank" as your main
class.

## Commands

Commonly-used SLIME commands:

* **M-TAB**: Autocomplete symbol at point
* **C-x C-e**: Eval the form under the point
* **C-c C-k**: Compile the current buffer
* **M-.**: Jump to the definition of a var
* **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

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

Note that Slime was designed to work with Common Lisp, which has a
distinction between interpreted code and compiled code. Clojure has no
such distinction, but many of the Slime commands retain parallel
load/compile commands that have the same effect in the context of
Clojure.

## Debug Repl

For now, see [Hugo Duncan's
blog](http://hugoduncan.org/post/2010/swank_clojure_gets_a_break_with_the_local_environment.xhtml)
for an explanation of this excellent feature. Further documentation to come.

## swank-clojure.el

TODO: explain

## Keeping Common Lisp

If you want to use SLIME with Common Lisp or another Lisp
implementation, add this to your Emacs config:

    (add-to-list 'slime-lisp-implementations '(sbcl ("sbcl")))

Then launch Slime with M-- M-x slime $LISP instead of just M-x slime.

## Community

The [mailing list](http://groups.google.com/group/swank-clojure) and
clojure channel on Freenode are the best places to bring up
questions/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. See [this post
on submitting good patches](http://technomancy.us/135) for some
tips. If you've got some time on your hands, reading this [style
guide](http://mumble.net/~campbell/scheme/style.txt) wouldn't hurt
either.

## License

Copyright (C) 2008-2010 Jeffrey Chu, Phil Hagelberg, Hugo Duncan, and
contributors

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

[1] - [ELPA](http://tromey.com/elpa/install.html) is the Emacs Lisp
  Package Archive. It brings a real package manager to Emacs.

Generated by Phil Hagelberg using scpaste at Sat May 15 20:50:48 2010. PDT. (raw)