% 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.


Text Editor Setup
=================

If you'd like to use GNU Emacs, see my [10-minute Emacs + Clojure
guide](/clojure/10-minute-emacs-for-clojure.html), or else the
["Clojure with Emacs" guide at the clojure-doc.org
site](http://clojure-doc.org/articles/tutorials/emacs.html).

If you'd like to use Emacs, Vim, or Eclipse, see their respective
[tutorials at
clojure-doc](http://clojure-doc.org/articles/content.html#tutorials).

For an easy-to-use GUI editor, maybe try jEdit or some of the other
tools list at <http://clojure.org/community/resources>.



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](standalone-scripts.html) 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](http://leiningen.org/index.html) ("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](libs-management-and-use.html).

> There's also a tool called [boot](http://boot-clj.com/), 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:

~~~bash
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.)


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:

~~~clojure
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](distributing-apps.html).



A library project example
-------------------------

To create a Clojure library:

~~~{.bash}
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:

~~~{.clojure}
(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
~~~



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=>
~~~