Development Environment
John Gabriele
For a spartan set-up, for now, to rapidly get you going, I suggest just using a text editor and a terminal window or two. Details below.
Note: Later, you will likely want to use a more productive setup, where you’ll have access to the repl from within your editor. But for now, we’ll walk before we run.
1 Text Editor Setup
If you’d like to use GNU Emacs, see my 10-minute Emacs + Clojure guide, or else the “Clojure with Emacs” guide at the clojure-doc.org site.
If you’d like to use Emacs, Vim, or Eclipse, see their respective tutorials at clojure-doc.
For an easy-to-use GUI editor, maybe try jEdit or some of the other tools list at http://clojure.org/community/resources.
2 Clojure Projects
Whenever you want to start writing a Clojure application or library, it’s most common to first create a new project for it.
Aside: You can also create a self-contained Clojure program in its own single source code file, like a shell script. That is covered later, in the Standalone Scripts chapter. For now though, we’ll discuss the customary way of creating a Clojure program, which is to create a project for it.
A project is just a directory (named after the project) which should contain:
- a project.clj file,
- a README.md file,
- a subdirectory containing your source code,
- a subdirectory containing tests,
- a subdirectory containing docs, and
- usually, some other sundry files (ex. LICENSE.txt, NEWS.md, etc.).
The tool that’s used to create and manage Clojure projects is called Leiningen (“line-ing-en”), or just “lein” for short (which is also the name of the Leiningen command-line program). We’ll discuss lein in greater detail in a later chapter.
There’s also a tool called boot, not discussed further in this guide.
To start tinkering around with some Clojure code, we first need to install Leiningen and then use it to create a little project within which to work.
Create a ~/bin dir if you don’t already have one, and make sure it’s on your $PATH. Install lein (as described on its website) like so:
cd ~/bin
wget https://raw.github.com/technomancy/leiningen/stable/bin/lein
chmod +x lein
lein version # It will download and install dependencies.
(Lein’s self-install will create ~/.lein and ~/.m2 directories.)
2.1 An app project example
Create a new project for an application program like so:
$ cd ~/temp
$ lein new app my-app
Generating a project called my-app based on the 'app' template.
$ cd my-app
Open project.clj in your editor and — to keep our future output filenames down to a reasonable length ☺ — change the version string from “0.1.0-SNAPSHOT” to just “0.1.0”.
Open up src/my_app/core.clj in your editor as well.
Note: for your project directory, and in your source code, you use the hyphen (here, “my-app”), but — due to requirements of the underlying Java platform — corresponding subdirectory names below the project directory must instead use an underscore (“my_app”).
The src/my_app/core.clj -main
function is just what it looks like; your program’s main entry point. Back in your terminal, from your project directory, start up a repl and call -main
:
$ lein repl
... {snip version info}
my-app.core=> (-main)
Hello, World!
nil
Over in your editor, change that “Hello, World!” text to something else and save the file. Now back in the repl, manually reload the file and run -main
again to see your changes:
my-app.core=> (require 'my-app.core :reload)
nil
my-app.core=> (-main)
Hello, You!
nil
Quit the repl using Ctrl-d and run your program using lein like so:
$ lein run
When you’re happy with your app, package it up into an executable jar file and copy the resulting jar to your ~/bin directory:
$ lein uberjar
...
$ cp target/uberjar/my-app-0.1.0-standalone.jar ~/bin
Run it from anywhere, using the java
command, like any other executable jar file:
$ java -jar ~/bin/my-app-0.1.0-standalone.jar
Hello, You!
You can now send just that jar file to a friend and they should be able to run it likewise (as long as they have Java installed)! ☺
To make it even easier to run your Clojure app from the command line, see distributing apps.
2.2 A library project example
To create a Clojure library:
cd ~/temp
lein new default my-lib # Or `lein new my-lib` for short.
cd my-lib
In your editor, open src/my_lib/core.clj and between the (ns my-lib.core)
and the (defn foo ...)
expressions, add your own function:
(defn my-func
"Docstring for my-func."
[x]
(* x x))
Save the file. Back in the terminal, start up a repl and try out that new function:
$ lein repl
...
user=> (require 'my-lib.core)
nil
user=> (ns my-lib.core)
nil
my-lib.core=> (my-func 3)
9
In my-func
, change the “*
” to a “+
”, then reload and try out your changes:
my-lib.core=> (require 'my-lib.core :reload)
nil
my-lib.core=> (my-func 3)
6
3 A REPL without a project
Incidentally, anytime you want to fire up a repl — say, for reading docstrings or for just trying things out — you can do so outside of and without need of a project. For example:
$ cd ~/temp # Not a lein project dir.
$ lein repl
...
user=>