First things first
To successfully work through this course, you need to do the following things:
- install Java
- install a sane editor: Light Table, Vim or Emacs
- install Git
- install Leiningen
- make sure to have a github account
- read very carefully the submission instructions
Clojure runs on JVM, so you need to have the Java JDK installed. On Linux this is easily done using the distribution’s package manager.
On Windows you need to download the latest JDK from Oracle’s site and install it. You also need to add the JDK bin directory to the Path. Right click Computer, select Properties, select Advanced system settings, select Environment Variables and Edit the Path to contain the
bin directory of the JDK installation usually found under
Program Files. Don’t hesitate to ask if you encounter any problems.
Your very own butler
Leiningen is a project management tool for Clojure projects. It handles various tasks related to projects, including building the project, declaring and fetching dependencies, opening an interactive session inside the project, and other such things.
Here’s the instructions for installing Leiningen in Linux:
In your home directory, create a directory called
binif it does not exist all ready.
cd ~ mkdir bin
Add this directory to your $PATH. If you are using Bash, put the following inside the file
~/.bashrc. If you are using some other shell, do this where you would normally do these kind of things. If you don’t know what shell you are using, you are using Bash.
~/.bashrcfile to apply the changes.
Download this script. Put it in the
~/bindirectory created in step 1
Make the script you just downloaded executable.
chmod +x ~/bin/lein
In any directory, issue the command
lein help. This will first download the rest of Leiningen. After the download is complete you get a list of services provided by Leiningen.
For Windows there is an installer that does all this for you. You only need to have Java installed.
The table below contains some important Leiningen commands.
|midje||Run all Midje tests.|
|repl||Open an interactive Clojure session.|
|new||Create a new Clojure project.|
To get more information about a command, run
lein help <command>.
The heart of every Leiningen project is the file
project.clj at the top level of the projects directory tree. It contains information about the projects name, version and dependecies among other things.
Git is an distributed version control system. A fancy name for a tool that keeps track of changes made to files under a directory tree. We use this tool to distribute pre-made Leiningen projects in which you can complete the exercises of every chapter. You also use Git to submit your answers. If you have any problems with Git, ask.
To install Git on Linux, use your distribution’s package manager. In Windows, point your browser to http://git-scm.com/, where you can find both the binaries and comprehensive documentation. On Windows it’s easiest to use the Git-bash that comes with Git.
There are three basic commands that you need to know to successfully submit exercises:
git clonewill clone you a local copy of a repository
git commit -a -m "message goes here"will add your changes into the git repository. The message should summarise what has changed.
git pushwill upload the changes previously commited to github
How to submit answers to exercises
At the start of every chapter, you should go to Github and fork the chapters repository. There will be a link to the appropriate repository at the beginning of every chapter. You then clone your own fork of the repository and start working with the exercises when you encounter them among the material. You create commits and maybe push them in to your own fork while working. You also run the tests with
lein midje to see if they pass.
When you want your answers graded, you push all of your work with
git push. You then go to Github and send a pull request. At this point, Travis kicks in. It runs the tests for your code and then comments on the pull request whether the tests passed or failed. A link is also provided to see the nitty-gritty details.
If you didn’t get all the tests to pass on the first go, don’t worry, you can try again. Just make modifications to the code, create a commit, and push. The pull request will be updated, Travis will rerun the tests and a new comment about the build status will be posted. You can keep trying as many times as you want.
Lets go through the first part of this process to be ready for the next chapter.
Go to the Github page of the repository of the next chapter. Here is the link.
Click the Fork-button near the top-right corner of the page. You will be asked to login if you haven’t done so already.
The Github page of your fork will open. This is the repository you want to clone. Click the button that says HTTP and copy the link from the box. Then issue the following command with your version of the link. Your Github login information will be requested.
git clone https://github.com/<my-account>/training-day.git
training-daywill be created. Go inside the directory and issue
lein midje. You should see output that tells you that every test in the project has failed.
cd training-day lein midje
lein midje, you can issue the command
lein midje :autotest
This starts a loop which runs the tests again every time you make changes to any of the projects files. A very handy feature, as running plain
lein midjehas a pretty long startup time.
You are now ready to start working with the exercises. Whenever you encounter an exercise in the material, open the file
src/training_day.cljand fill the appropriate function. Run
lein midjeoften to see if the tests pass.
As a lisp, Clojure requires some support from the text editor to be pleasant to write. Luckily a guy named Chris Granger has started a project to create The editor called Light Table. It’s still quite beta (you might encounter some bugs), but works nicely for your purposes during this course. Check it out. When in doubt, use this.
Light Table is more or less like an ordinary editor with some IDE like features. The thing that sets Light Table apart is the Instarepl. It is a tool in which you can write Clojure code, run it and instantly see the results. This is a great environment to test ideas and also to solve the exercises. Many think that working in the repl is one of the best things in Clojure developement.
When you open Light Table, you want to open your project.
View -> Workspace
- Open the directory of the project that you just cloned with Git
View -> Commands(shortcut Ctrl+Space)
- Search for
Connect: Add Connection
- Select Clojure
- Select the
project.cljfile in the directory of the cloned project
Optionally, if you have a larger monitor, you can split Light Table into two columns:
- Open the command bar
- Search for tabset
Tabset: Add a tabset
You can now move tabs between these tabsets by dragging them from one to another.
Finally, to start using Light Tables awesome instarepl, do the following:
- Using the command bar, search for instarepl
Instarepl: Open a clojure instarepl
- Light Table might ask you which connection you want the instarepl to use. Select the project you connected earlier to (
Now that you have an instarepl open, you can write some clojure to it, like
(+ 2 3). Finally, to use this instarepl to test your implementations in the exercise file, you need to
use the namespace. To do this, write
in the beginning of the instarepl window. Now you can, for example, evaluate
use row and in general use anything defined in the namespace you just used. For more information about Light Table, see the shortish docs page.
Not suprisingly, both Vim and Emacs have good plug-ins to work with Clojure. For the basics, one should install the clojure-mode from the Emacs package manager. For a more complete set of tools we can recommend Emacs Starter Kit. In Vim, VimClojure provides you with the necessary goodies. There is also a Clojure indentation plugin for Sublime Text if that is your poison of choice.