1# Swank Clojure 2 3[Swank Clojure](http://github.com/technomancy/swank-clojure) is a 4server that allows [SLIME](http://common-lisp.net/project/slime/) (the 5Superior Lisp Interaction Mode for Emacs) to connect to Clojure 6projects. To use it you must launch a swank server, then connect to it 7from within Emacs. 8 9## Usage 10 11Add Swank Clojure to your project as a development dependency to your 12project. If you are using Leiningen, add it to your project.clj file 13under :dev-dependencies: 14 15 :dev-dependencies [[swank-clojure "1.2.1"]] 16 17Once you run "lein deps" you can launch a swank server from the 18command line: 19 20 $ lein swank [PORT=4005] [HOST=localhost] 21 22Note that the lein-swank plugin now comes with Swank Clojure; it does 23not need to be specified as a separate dependency any more. 24 25If you're using Maven, add this to your pom.xml under the 26\<dependencies\> section: 27 28 <dependency> 29 <groupId>swank-clojure</groupId> 30 <artifactId>swank-clojure</artifactId> 31 <version>1.2.1</version> 32 </dependency> 33 34Then you can launch a swank server like so: 35 36 $ mvn -o clojure:swank 37 38Note that due to a bug in clojure-maven-plugin, you currently cannot 39include it as a test-scoped dependency; it must be compile-scoped. You 40also cannot change the port from Maven; it's hard-coded to 4005. 41 42## Connecting with SLIME 43 44Install the "slime-repl" package [from ELPA](http://tromey.com/elpa) 45using package.el. When you perform the installation, you will see 46warnings related to the byte-compilation of the packages. This is 47**normal**; the packages will work just fine even if there are 48problems byte-compiling it upon installation. 49 50Then you should be able to connect to the swank server you launched: 51 52 M-x slime-connect 53 54It will prompt you for your host (usually localhost) and port. It may 55also warn you that your SLIME version doesn't match your Swank 56version; this should be OK. 57 58Having old versions of SLIME either manually installed or installed 59using a system-wide package manager like apt-get may cause issues. 60 61## SLIME Commands 62 63Commonly-used SLIME commands: 64 65* **M-TAB**: Autocomplete symbol at point 66* **C-x C-e**: Eval the form under the point 67* **C-c C-k**: Compile the current buffer 68* **M-.**: Jump to the definition of a var 69* **C-c S-i**: Inspect a value 70* **C-c C-m**: Macroexpand the call under the point 71* **C-c C-d C-d**: Look up documentation for a var 72* **C-c C-z**: Switch from a Clojure buffer to the repl buffer 73* **C-c M-p**: Switch the repl namespace to match the current buffer 74* **C-c C-w c**: List all callers of a given function 75 76Pressing "v" on a stack trace a debug buffer will jump to the file and 77line referenced by that frame if possible. 78 79Note that SLIME was designed to work with Common Lisp, which has a 80distinction between interpreted code and compiled code. Clojure has no 81such distinction, but many of the SLIME commands retain parallel 82load/compile commands that have the same effect in the context of 83Clojure. 84 85## Embedding 86 87You can embed Swank Clojure in your project, start the server from 88within your own code, and connect via Emacs to that instance: 89 90 (ns my-app 91 (:use [swank.swank :as swank])) 92 (swank/start-repl) ;; optionally takes a port argument 93 94Then use M-x slime-connect to connect from within Emacs. 95 96You can also start the server directly from the "java" command-line 97launcher if you AOT-compile it and specify "swank.swank" as your main 98class. 99 100## Debug Repl 101 102For now, see [Hugo Duncan's 103blog](http://hugoduncan.org/post/2010/swank_clojure_gets_a_break_with_the_local_environment.xhtml) 104for an explanation of this excellent feature. Further documentation to come. 105 106## swank-clojure.el 107 108Previous versions of Swank Clojure bundled an Elisp library called 109swank-clojure.el that provided ways to launch your swank server from 110within your Emacs process. While swank-clojure is still distributed 111with the project, it's a much more error-prone way of doing things 112than the method outlined above. 113 114If you have configured your Emacs to use M-x swank-clojure-project 115then it should still work, but it's not recommended for new users. 116 117## Community 118 119The [mailing list](http://groups.google.com/group/swank-clojure) and 120clojure channel on Freenode are the best places to bring up 121questions/issues. 122 123Contributions are preferred as either Github pull requests or using 124"git format-patch". Please use standard indentation with no tabs, 125trailing whitespace, or lines longer than 80 columns. See [this post 126on submitting good patches](http://technomancy.us/135) for some 127tips. If you've got some time on your hands, reading this [style 128guide](http://mumble.net/~campbell/scheme/style.txt) wouldn't hurt 129either. 130 131## License 132 133Copyright (C) 2008-2010 Jeffrey Chu, Phil Hagelberg, Hugo Duncan, and 134contributors 135 136Licensed under the EPL. (See the file COPYING.) 137