Getting started with clojure / calva

README.md

Rationale

My colleague wanted a quick start for clojure, and I didn't find anything that used clojure / deps.edn. This guide is created to get started with Clojure in general and clj/deps.edn in particular.

Install

1. Java (v11 LTS is recommended) -- https://adoptopenjdk.net/
2. Clojure / clj -- https://clojure.org/guides/getting_started
3. Visual Studio Code -- https://code.visualstudio.com/

Preparations

1. Create a folder for your project
2. Open it in Visual Studio Code (VSCode from here on)

Creating a project

After installing Clojure, you get a program called clj. clj performs tasks such as downloading dependencies and compiling / running Clojure code.

clj is run from the command line, and looks for a deps.edn file, which is where you configure dependencies / source paths. If you've used npm, it's very similar to package.json.

A common project structure is a deps.edn at the root, then a src-folder which contains the source code. We don't have a reason not to go along with this, so let's create the following folders / files:

1. deps.edn -- .edn is the extension for EDN files
2. src/try_clojure/core.clj -- `.clj´ is the extension for Clojure source files

Now your structure should look like this:

+
|
+-+ src
| |
| +-+ try_clojure
|   |
|   +-> core.clj
|
+-> deps.edn

EDN is a file format that has the same appearance as Clojure data structure. In the same way that JSON code is also valid JavaScript, EDN is valid Clojure.

Creating deps.edn

Open deps.edn, either by clicking it, or using Search files by name (Ctrl-P on Windows, Cmd-P on MacOS). Then write the following:

{:paths ["src"]}

Then save.

Since clj looks at deps.edn whenever it is run, clj will know to look for source code inside "src".

Your first Clojure program

Now open src/try_clojure/core.clj side by side with this file. You can do this by right clicking the file in VSCode and clicking "Open to the side".

Now we will start writing some Clojure into a file, so we can save our code. Start by writing:

"Hello, World!"

Running the project

We can run Clojure code in two ways, either "one shot" which is similar to how you compile / run other languages. One of the main benefits of Clojure though, is the second way to run programs: using a REPL. With a REPL you are able to live code your app, which mean you can change the code while the app is running.

In order to use a REPL in a pleasant way, we want integration between the editor and our app and its REPL server. The easiest way to get that integration in VSCode is to install the extension Calva.

1. Click the Extensions-icon in the left sidebar, or View > Extensions in the menu bar.
2. Search for calva
3. Click Install

Whet Calva is installed, open core.clj again (Ctrl-P/Cmd-P).

Then to run >Calva: Start a Project REPL and Connect (aka Jack-in) and press Enter. The way to run >-commands is to press Ctrl-Shift-P/Cmd-Shift-P/View > Command Palette to open the Command Palette. Here you can search for essentially all VSCode commands. Try finding the Calva: Start a Project REPL and Connect (aka Jack-in) entry in the list by searching for e.g. jack-in or calva start. The searching is fuzzy, so you can write any parts of the command. When you have selected Calva: Start a Project REPL and Connect (aka Jack-in), hit Enter.

In the terminal you will see Calva downloading multiple dependencies. When you see the line nREPL server started on port ... on host localhost - nrepl://localhost:.... This means that the REPL server has started, and Calva has connected to it. What has happened is that Calva has run clj with some extra flags, then Calva connects to clj and can send it code using the REPL.

Now, inside core.clj, move your cursor to the end of the line of (println "Hello, World!"), then run the >Calva: Evaluate Current Form (Ctrl-Shift-P/Cmd-Shift-P/View > Command Palette). core.clj should now look like this:

"Hello, World!" => "Hello, World!"

What's after the => is the result of running the code on that line. Since a string evaluates to itself, you get the "Hello, World!" back. We can do something a bit more interesting by calling functions:

Write

(+ 1 1)

With the cursor behind ), run >Calva: Evaluate Current Form (Ctrl-Shift-P/Cmd-Shift-P/View > Command Palette).

You should get the following result:

(+ 1 1) => 2

To make it easier to evaluate parts of your code, it is helpful to look at the hotkey for >Calva: Evaluate Current Form. You can see the hotkey to the right, when you look in the Command Palette (Ctrl-Shift-P/Cmd-Shift-P/View > Command Palette).

Some other things you can try running:

(str "concatenate" "multiple" "parts")
(def your-name "<Insert Your Name Here>")
(str "Hello, " your-name "!")

NOTE: Install rainbow parens as well.

Good job! Now you are ready to start reading Clojure for the Brave and True. This book will teach you how to start writing interesting and fun Clojure programs. I wish you the best of luck. :)

https://www.braveclojure.com/do-things/

The link above goes to Chapter 3. You can skip Chapter 1-2, which describes how to install a different build tool. The author also introduces Emacs, an editor which I personally love. But I don't recommend learning Emacs at the same time as you learn Clojure.