Clojure Template Project

A simple template for Clojure projects

Overview

This Clojure project shows my favorite layout of for both source & test files (sample Java source is included as well). The project is also set-up to use the Tupelo Clojure library and the lein-test-refresh plugin.

How to User This Project

To use this project, we assume you have already installed Java, Clojure, and Leiningen, and git.

Clone the Project Using Git

Verify you have Git installed:

> git --version
git version 2.25.0

Use git to clone the project (via SSH) into a new project names demo:

> git clone  git@github.com:io-tupelo/clj-template.git  demo  # git ssh URL

or, clone via HTTPS (if you don’t have SSH set up on your computer & GitHub):

> git clone  https://github.com/io-tupelo/clj-template.git  demo  # git https URL

Then cd (change directory) into the new project:

> cd demo

Verify you have Java & Clojure set up correctly

Try the following commands, and make sure you get similar output:

> java --version
java 13 2019-09-17
Java(TM) SE Runtime Environment (build 13+33)
Java HotSpot(TM) 64-Bit Server VM (build 13+33, mixed mode, sharing)

> clojure --version
Clojure CLI version 1.11.1.1208
> clj --version
Clojure CLI version 1.11.1.1208

Running Unit Tests - Plain

I use the alias ct for "clojure-test" and ctr fr "clojure-test-refresh". You can copy that or just cut/paste the actual commands echoed below.

Simple way:

> clojure -X:test

Running tests in #{"test"}

Testing tst._bootstrap

------------------------------------------
   Clojure 1.12.0-alpha3    Java 19.0.2
------------------------------------------

Testing tst.demo.core

Ran 2 tests containing 5 assertions.
0 failures, 0 errors.

With the alias:

> ct
time (clojure -X:test)    # <= the alias echos the actual command

Running tests in #{"test"}

Testing tst._bootstrap

------------------------------------------
   Clojure 1.12.0-alpha3    Java 19.0.2
------------------------------------------

Testing tst.demo.core

Ran 2 tests containing 5 assertions.
0 failures, 0 errors.
  27.82s user 0.82s system 326% cpu 8.776 total

Running Unit Tests with `test-refresh`

IMHO, the lein-test-refresh project provides the best way of doing iterative development in Clojure, re-running unit tests every time you save a source file from the editor.

> clojure -M:test-refresh

or make an alias ctr, with result:

> ctr
time (clojure -M:test-refresh)
*********************************************
*************** Running tests ***************
:reloading (demo.core tst._bootstrap tst.demo.core)

Testing tst._bootstrap

------------------------------------------
   Clojure 1.12.0-alpha3    Java 19.0.2
------------------------------------------

Testing tst.demo.core

Ran 2 tests containing 5 assertions.
0 failures, 0 errors.

Passed all tests
Finished at 15:17:49.395 (run time: 5.327s)
...

in this instance, the test output pauses after printing the elapsed time, and waits to re-run upon any file change. For example, make a simple change in the namespace demo.core by adding the word "Again!" to the println expression, and watch as the tests are automatically re-run:

...
Testing tst.demo.core
result => "Hello, World! Again!\n"
...
Finished at 07:59:53.863 (run time: 0.034s)

Note that the tests were all re-run in only 34 milliseconds (nearly instantaneous), since the JVM was already started and Clojure itself (plus library code) has already been compiled.

Using "Focus" Mode

Change one of the dotest forms in tst.demo.core to dotest-focus. If there is at least one dotest-focus present in the project, then only the "focus" tests will be run. This is helpful when you want to temporarily focus on a specific feature, without the distraction of all the other tests runnning.

Note that only lein test-refresh (i.e. lctr) will honor the focus mode; lein test (i.e. lct) will always run all tests.

Keeping Dependency Versions Up-To-Date

This deps.edn includes the old alias, which will tell you if any of your dependency libraries are out of date. I have a BASH alias:

> which cold
cold () {
	evalEcho 'time (clojure -M:old)'
}

which will give you a list of version updates you should make, or just

> cold
time (clojure -M:old)
[##################################################] 6/6
All dependencies are up-to-date.
  28.14s user 0.67s system 370% cpu 7.782 total

if you are already up-to-date on everything.

Plumatic Schema

The function demo.core/add2 shows the usage of Plumatic Schema to document function argument types and return value type. This is a lifesaver!

Documentation

The Tupelo Clojure library on GitHub
The Tupelo Clojure API Docs on cljdoc.org
The Clojure CheatSheet. Always have a browser tab open here, and study frequently!
The ClojureScript CheatSheet. Another great resource!
The above links to examples on ClojureDocs.org
Also see Clojure-Doc.org (similar name, different website!)
API Documentation for most any Clojure library can be found at cljdoc.org
The online book Brave Clojure. Be sure to also buy a copy!
The book Getting Clojure
The book Living Clojure
The Clojure Cookbook
The Clojure Toolbox has a large list of libraries you can use
Clojure.org and ClojureScript.org - the mothership

License

Distributed under the Eclipse Public License, the same as Clojure.

Development Environment

Developed using IntelliJ IDEA with the Cursive Clojure plugin.

YourKit supports open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of YourKit Java Profiler and YourKit .NET Profiler, innovative and intelligent tools for profiling Java and .NET applications.

cloojure/attic