Getting Started

Welcome to Clojure!

Check out Learn Clojure, Resources, or Books to learn the language! If you have questions, you can search or ask at the official forum Ask Clojure.

Dependencies

Clojure requires Java. Clojure officially supports Java LTS releases (currently Java 8 and Java 11), but also tries to ensure interim versions work as well. You can use any Java installation, whether it’s a commercial release from Oracle or an open source version based on OpenJDK (like adoptopenjdk).

The Clojure tools require that either the java command is on the path or that the JAVA_HOME environment variable is set.

Clojure installer and CLI tools

Clojure provides command line tools that can be used to start a Clojure repl, use Clojure and Java libraries, and start Clojure programs.

Follow these instructions to install the latest release of the clj and clojure tools:

Installation on Mac via Homebrew

Install the command line tools with brew from the clojure/tools tap:

If you’ve already installed this way in the past, you can upgrade to the latest release with:

Installation on Linux

To install with the Linux script installer:

Ensure that the following dependencies are installed: bash , curl , rlwrap , and Java .

Use the linux-install script to download and run the install, which will create the executables /usr/local/bin/clj , /usr/local/bin/clojure , and the directory /usr/local/lib/clojure :

Custom location

To install to a custom location (like /opt/infrastructure/clojure ), use the option —prefix :

Extend the MANPATH in /etc/man_db.conf to include the manual pages:

The linux-install script can be removed after installation.

Installation on Windows

An early release version of clj on Windows is available at clj on Windows. Please provide feedback on Ask Clojure or Clojurians slack in #clj-on-windows.

Other versions

See the changelog for version history and the Clojure tap for info on installing older versions or newer prereleases instead.

Other ways to run Clojure

Local build

Most Clojure users use Clojure jars downloaded from the Maven central repository (by the tools above or other Clojure build tools). However, you can also build Clojure from source with necessary dependent jars into a single executable jar (requires Git, Java, and Maven):

Then start the REPL with the local jar (note this will not work with the jars in Maven as they do not include dependencies):

Learning Clojure/Installation

As of writing, Clojure lacks a standard installer for Windows, and a few packages exist for popular *nix Operating Systems. Although, all examples presented work exactly the same across all systems, regardless of what type of installation you choose.

Contents

Base Installation [ edit | edit source ]

A Base Installation is a minimal install that provides all of the capabilities of the Clojure language, but without a GUI or additional interfaces for assistance. Installation with this method has several low level tasks that are not difficult to perform, but may seem difficult to those that have never manually installed a program on a system before.

Steps [ edit | edit source ]

First you should confirm that the Java VM is installed on your machine. This can be easily checked by going to a terminal and typing java -version . If it returns something about your java version, you should be set. If it does not, then you will need to download the Java VM from the Java website [1] .

After you’ve confirmed that Java is installed on your machine, obtain the most recent version of Clojure from the main Clojure website [1]. This book was written and tested for Clojure version 1.2 (Stable). The file you have downloaded will be a zip file containing several files which are explained in detail in the section Source Install. The file we want is clojure.jar .

Take this file and extract it to any directory of your choice. As this point, you will have a successful installation of Clojure on your machine! All you need to do is to open a command window and type change your directory to where you extracted clojure.jar and type java -jar clojure.jar and you’ll be greeted with the Clojure REPL.

Mind you, this is a lot of work just to start Clojure, so we will create a script for each OS that will run the program with a single command and also add this program to the PATH, making the program easily accessible for execution at any time.

Windows Configuration [ edit | edit source ]

First, we need to create a script to run Clojure without the excessive typing. This tutorial assumes that you unzipped clojure.jar to C:\Development\Learning Clojure, and that the below bat file is named clj.bat The below script does just that.

Let’s break this down into blocks.

The first few lines that begin with rem are comments. They’re present to serve as a reminder of how this bat file works. The next block says that you do not want to see the output of this bat file. This removes command line «noise» when you start Clojure. The next block defines where you installed Clojure and prepares the arguments for when we launch it. Note that the CLOJURE_JAR variable is written in quotes. This is because Java recognizes a space as an end of argument. Thus, without the quotes, the Java command will try to run C:\Development\Learning, which is invalid.

Finally, we have a conditional. The conditional checks to see if there was an argument passed (in our case a clj file). If one was not passed, we will run Clojure’s REPL. If one was passed, we will run the passed clj file and also pass any additional arguments to the script.

So we now have our clj.bat which we can run Clojure from easily. Now let’s add it to our PATH so that we can execute Clojure from any directory on your system.

This can be done by the following.

1. Click Start
2. Right Click My Computer
3. Select Properties
4. Click the Advanced tab
5. Click on Environment Variables

If you wish to install this just for the current user, Underneath the «Variables for User» frame, find PATH. If PATH doesn’t already exist, click the new button. You’ll be greeted with a popup window with the variable name and arguments. For the arguments field, add C:\Development\Learning Clojure. If some value already exists, go to the very beginning and type the same thing, immediately following with a semicolon. Finally click Ok on the Variable Properties screen and Ok again on the Environment Variables Screen.

If you wish to install this for every user on your system, locate the PATH variable underneath the System Variables and perform the same steps as above.

At this point, your system should be set up to run Clojure from any directory. To try it out, click on Start, Run, and then type in clj. You should be greeted with the Clojure REPL.

Leiningen on windows [ edit | edit source ]

Leiningen is a automating tool for clojure. Like Maven for Java, it provides easy and configurable environment for compilation, execution and distribution functionality. It also provides standard convention and project structure. You can download leiningen from https://github.com/technomancy/leiningen, it comes with a batch file and wget.exe for downloading rest of the tool. Site’s github page has the details on installation and usage.

Linux/OSX Configuration [ edit | edit source ]

Linux and OSX users follow a similar scripting process to the Windows setup. Below is the script needed to run Clojure:

You should now mark the file as executable by typing chmod a+x clj.bat , and add this directory to your path. This can be done either by a static link to /usr/bin or changing the value of PATH in your .bashrc.

You should now be able to run the Clojure REPL by typing clj at the command prompt.

Integrated Development Environments (IDE) [ edit | edit source ]

Clojure has a few IDEs that makes development easier by providing additional features and utilities. The first and foremost benefit to using an IDE for development is having an all-in-one package. The IDE is your editor, it is your compiler, and it is your build system. The second benefit is that external tools become available, such as source version control systems like Mercurial, Git, and Subversion. Also, IDEs generally make learning a language easier and faster, because most tasks are standardized.

There’s also some problems with using IDEs. Using an IDE typically results in a vendor lock-in. If you’ve written code in one particular IDE, you’re not likely to switch to another. Another problem is that IDEs provide a lot of functionality, but sometimes restricts you in areas, such as choosing between Make, Maven, and Leiningen for your build system.

As of writing, there are three major IDEs for Clojure, all which work across Windows, Linux, and OSX.

Enclojure (Netbeans) [ edit | edit source ]

Enclojure is a Netbeans sponsored project which covers a wide array of features.

Counter Clockwise (Eclipse) [ edit | edit source ]

Counter Clockwise is a Eclipse plugin which brings a different look at how Clojure could be integrated into an IDE.

Swank Clojure (Emacs) [ edit | edit source ]

Swank Clojure is a clone of the venerable Slime interface for programming Lisp in Emacs.

These instructions come from: http://riddell.us/ClojureSwankLeiningenWithEmacsOnLinux.html, however that location is not a wiki and there are small fixes that it needs, so I’m copying what was there with those small fixes.

What follows is a description of how to get up and running in Ubuntu.

NOTE: If using Lucid Lynx (10.04) or later (and possibly some earlier versions), you will need to first change the apt-get repository so that sun-java6-jdk is available:

$ sudo add-apt-repository «deb http://archive.canonical.com/ maverick partner»

(where «maverick» is the adjective descriptor of your ubuntu version («lucid» for lucid lynx, «maverick» for maverick meerkat, etc.))

$ sudo apt-get update

• Test Clojure, Gentlemen, start your REPLs.

Configure Bash Start-up Script

clojure-contrib contains a bash script called clj-env-dir for starting clojure with various options. Edit your

/.bashrc file to configure this script.

The last line added to the file above sets an alias to the clj-env-dir script. This example uses clj but it could be set to anything.

See the file at

/opt/clojure-contrib/launchers/bash/clj-env-dir for options.

Add JLine support

Download JLine from http://jline.sourceforge.net/ and unzip and copy jar to the

Add jline.ConsoleRunner to the last line in

/opt/clojure-contrib/launchers/bash/clj-env-dir to add JLine functionality.

To test the new script and verify access to the clojure-contrib library, open a new terminal window and try this:

If any other jars are needed either copy or link them to the

Add the following to .bashrc.

Execute the leiningen script.

Add these specifics to the .emacs file.

Create a test project.

Add the following:

Save and exit the file.

Open a new terminal and open the generated file in emacs:

Connect to the running swank server:

Add some code to the file:

And then at the end of the line, evaluate:

The output will show the configured jar files and their associated paths on the Java classpath.

Lastly, compile the file:

Source Install [ edit | edit source ]

Installation on windows is slightly complicated if you have never modified environment variables or dealt with command-line operations. You will need either the Sun JDK or OpenJDK packages installed on your computer, and you will also need to have Maven installed before attempting this process.

bpringe / Getting Started with Clojure on Windows.md

Getting Started with Clojure on Windows

Clojure is an amazingly powerful language. Using it (and watching Rich Hickey videos) has changed the way I think about programming, and the way I code in general. Once I learned the basics of the language, which was a relatively quick process, I fell in love and couldn’t look back. I hope this post can help others who are new to Clojure get up and running quickly and painlessly.

This post is opinionated in the sense that I’ll suggest certain tools to help those who are new to this scene get on their feet. The things you’ll need are:

• Leiningen (pronounced LINE-ing-en) — This is like a package manager, build tool, task manager, and more in one tool. Think npm or nuget, but with more capabilities. There is at least one other build tool for Clojure (boot), but Leiningen is the most widely used.
• JDK — Clojure runs on Java. Throw out any qualms you may have about Java, we aren’t coding in Java (though we can through Clojure, and sometimes that can be useful).
• IDE — I use Visual Studio Code as my editor, with the Calva extension for Clojure support, so this is what we’ll use in this post.

We can actually install those first two in one go with Chocolatey, a package manager for Windows. I’ve installed these other ways before, and this way was the most frictionless.

Install Leiningen and the JDK

First, if you don’t already have Chocolatey installed, follow the installation instructions at chocolatey.org. Once it’s installed, open a Powershell or CMD terminal with admin priviledges and run the following:

You’ll notice the Chocolatey package installs the OpenJDK and Leiningen. Let’s start a REPL (read, eval, print loop).

Note: If you see a message that ‘java’ is not recognized as a command, close your terminal and reopen it, then try again.

You should see something beautiful like the following:

Clojure awaits you. Let’s try simple addition:

Now we’re in business! Hit ctrl+D to exit the REPL. Let’s get our editor set up.

Calva and VS Code

If you don’t already have VS Code, go ahead and install it. Then let’s create a project with lein. In your terminal, run:

This will create a project in a new directory named clojure-project . Let’s open that directory in VS Code.

Now that we have this fresh new Clojure project, let’s install Calva. In VS Code, go to Extensions and search «Calva» — install it. Now open the core.clj file in the src/clojure_project directory of your project, and hit the shortcut keys ctrl+alt+c, ctrl+alt+j to run the Calva jack-in command, select Leiningen as the project type when prompted. This starts a project REPL and connects Calva to it, and gives you a sweet REPL window in VS Code to work in. This is a souped-up version of what you saw in your terminal.

• Note: Before we continue, I want to point out a setting that I find very convenient in Calva that I suggest you turn on now, at least for the rest of this tutorial. Go into your VS Code Settings, then go to Extensions -> Calva and check the box next to «Eval On Save.» This will ensure your code is compiled as you save your file, so you can immediately try it out in your REPL.

Notice at the top of your core.clj file that you’re in the clojure-project.core namespace ( ns is the namespace function). All Clojure functions and vars live inside of namespaces, and usually code is organized as one namespace per file. The namespace your REPL started in is the user namespace. Let’s switch it to the clojure-project.core namespace so we can run code from that namespace/file. Type the shortcut keys ctrl+alt+c, ctrl+alt+n to switch the the current namespace (of the opened file).

You should see the prompt in your REPL window changed to clojure-project.core=> , indicating that your REPL is now in that namespace. Calva was also nice enough to compile that namespace when we switched to it, so let’s run that foo function that was generated by Leiningen. In your REPL, type:

Then hit alt+enter . You can also just hit enter if your cursor is at the end of the line. You should see that it printed the message from the function. Change the contents of the message, save the file, and run foo again in your REPL. You should see the changes. Pretty fast development cycle, right? It makes working in Clojure a pretty fun experience.

Using Comment Forms for Testing

Another useful thing you can do is eval the current form (expression inside parentheses), or the top level form, which is another command, and have the result either printed inside your editor as an annotation or you can send the form to the REPL window to be evaluated. This is useful to quickly run a small bit of code from the editor as you’re developing.

Something I sometimes do when testing code, is use Clojure’s comment function to create a comment block, then add all my test calls inside the comment block. This way the function calls won’t occur on file save (if Eval On Save is turned on), and I can send them one by one to the REPL, or evaluate them in the editor. Then when I return later I have the sequence of calls saved in a file. It’s not something I would leave in prod code, but it’s useful for development.

I encourage you to try out Calva’s many different commands. Hit ctrl+shift+p and type «calva» to see a list of all its commands.

If you’re unfamiliar with Clojure as a language, I suggest you read Clojure for the Brave and True. It’s free, it’s the book I first read to learn Clojure, and I found it pretty good at teaching the basics and then building on those to explore more advanced concepts.

Clojure.org is another great resource for learning Clojure. The Guides section of the site has in-depth content on specific concepts.

The Clojurians Slack is a great place to get answers to those specific questions that might be hard to search. I’ve asked many questions in the beginner channel there, and usually someone answers within minutes.

A good way to get familiar with the language’s vast array of functions is to do problems on 4clojure.com.

The best way to learn, at least for me, is to build something. Start a new project, or use the one we just created, and set a goal of something to build — maybe a simple web server, maybe a small game, maybe something useful that you need for work. You may not know the exact steps to get to the finished product, but the point is to figure them out as you go! And don’t forget, the community is always there to help.