puredanger / clj-template

A simple template for Clojure projects

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  [email protected]: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, and Leiningen 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)

> lein --version
Leiningen 2.9.1 on Java 13 Java HotSpot(TM) 64-Bit Server VM

Running Unit Tests - Plain

> lein clean ; lein test

with result:

lein test _bootstrap
-------------------------------
   Clojure 1.10.1    Java 13
-------------------------------

lein test tst.demo.core
result => "Hello, World!\n"

Ran 4 tests containing 6 assertions.
0 failures, 0 errors.

I do the above so often that I have a Bash/Zsh alias set up:

alias lct="time (lein do clean, test)"       # lct => Lein Clean Test

Running Unit Tests with lein 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.

> lein test-refresh

or make an alias:

alias lctr="lein do clean, test-refresh"    # lctr => Lein Clean Test-Refresh

with result:

Testing _bootstrap
-------------------------------
   Clojure 1.10.1    Java 13
-------------------------------

Testing tst.demo.core
result => "Hello, World!\n"

Ran 4 tests containing 6 assertions.
0 failures, 0 errors.

Passed all tests
Finished at 07:56:48.252 (run time: 6.709s)
...

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.

Running Unit Tests with Deps/CLI & Kaocha

These files allow one to test/run the code via Deps/CLI:

• deps.edn

• tests.edn

• bin/kaocha

Just type the following to run the unit tets:

> bin/kaocha

It will also compile any Java source code and include it in the unit tests.

Keeping Dependency Versions Up-To-Date

This project includes the lein-ancient plugin, which will tell you if any of your dependency libraries are out of date. I have an alias:

alias laca="lein ancient check :all"

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

all artifacts are up-to-date.

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!)

• 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

Copyright © 2020 Alan Thompson

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.