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.
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.
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:
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.)
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.
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
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=>