Leiningen

Our project will rely heavily on Leiningen, a build and task tool for Clojure. Leiningen allows us to easily maintain our application's dependencies, assists us in common tasks such as database migrations, running tests, producing binaries (jars and wars), and a plethora of other things. Leiningen is akin to Java's build tool Maven (http://maven.apache.org), and Ruby's Rake (http://github.com/jimweirich/rake). As Leiningen's web page (http://leiningen.org) concisely puts it: for automating Clojure projects without setting your hair on fire.

If you haven't already installed Leiningen 2.x, head over to http://leiningen.org/#install and follow the four simple instructions. It will take just 60 seconds, and the world of Clojure will become your oyster.

Note

After you've installed Leiningen, you'll have access to a new command in your terminal, lein. Invoking this command will invoke Leiningen.

Using Leiningen

The basic makeup of a Leiningen task can be summarized as follows:

# lein $TASK $TASK_ARGUMENTS

In the preceding shell pseudo-command, we invoke Leiningen using its binary. The lein $TASK argument is the Leiningen task we want to execute (such as install, jar, etc.), and $TASK_ARGUMENTS is any information required for that task to do its job, including additional subtasks and the arguments for a given subtask. You can see a full list of the available tasks in Leiningen by executing the following command:

# lein --help

You can also view the help content for a specific Leiningen task by executing the following command:

# lein help $TASK

You can use these commands whenever you need to know how to do something in Leiningen.

Generating the application

Leiningen can generate an application skeleton (or scaffolding) from a plethora of different templates. There's a template for nearly everything such as clojurescript projects, web applications (of course), and much more.

To generate a new application, we use the new Leiningen task whose basic syntax is as follows:

# lein new [$TEMPLATE_NAME] $PROJECT_NAME

The new task expects, at a minimum, a name for the project ($PROJECT_NAME). Optionally, we can provide a specific template to use ($TEMPLATE_NAME). If we don't specify a template, then lein will use the default template, which is a general template for developing libraries.

For our project we'll use the Luminus template, an excellent template for web applications. Luminus generates a project and wires in the libraries to support pretty much every aspect of web development including sessions, cookies, route handling, and template rendering.

Tip

At the time of this writing, the Luminus template was at version 1.16.7. To ensure the code examples in this book work, you can force Leiningen to use a specific version of Luminus by modifying Leiningen's profiles.clj file (typically found in your home directory, in a folder called .lein) to include the specific version of Luminus. For example:

:user {:plugins [[luminus/lein-template "1.16.7"]]}

This modification will ensure that version 1.16.7 of the Luminus template is used when generating a Luminus-based application.

Just try the following command:

# lein new luminus hipstr
>> Generating a lovely new luminus project named hipstr…

Tip

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub.com/support and register to have the files e-mailed directly to you.

The preceding command will generate a fully runnable application in a directory called hipstr. You can run the application by using cd hipstr to enter into the hipstr directory and then execute the following command:

# lein ring server
>>(Retrieving im/chit/cronj/1.0.1/cronj-1.0.1.pom from clojars)
>>…a whole bunch of Retrieving…
>>…and other output…
>>Started server on port 3000

In the preceding command line, the lein ring server command updates our class path with the dependencies required to compile and run the app. It then launches the development server (an embedded Jetty server) and starts serving on port 3000. Lastly, it launches our default web browser and navigates to the root page.

Note

In the preceding example, ring is the Leiningen task, and server is the ring subtask. You can view a full list of ring subtasks by entering the lein help ring command in your terminal.

The subsequent output of lein ring server is a series of debug statements that lets us know what the heck is going on during the startup process. Any generated exceptions or problems that occur while attempting to launch the application will be emitted as part of this output.

Getting help

If anything doesn't go as planned, or you're stumped and confused, feel free to check the Luminus documentation at http://www.luminusweb.net. You can also get some help from people in the Luminus community (https://groups.google.com/forum/?fromgroups#!forum/luminusweb) or the Ring community (https://groups.google.com/forum/?fromgroups#!forum/ring-clojure). Of course, there's always the Clojure group on Google Groups (https://groups.google.com/forum/).