Introduction

Clojurephant (GitHub Repo) is a Gradle plugin providing support for Clojure and ClojureScript projects.

clojurephant should not be considered stable before v1.0. Until then, minor versions will often contain breaking changes.

Rationale

Gradle is a popular build tool in the JVM ecosysytem with a rich plugin ecosystem and support for polyglot projects.

In particular, if you have a need to interop with Java code (maybe even other JVM languages), Gradle provides a good base of support.

Features

Gradle

Features provided by Gradle (or its ecosystem) that are useful for Clojure programmers.

  • Packaging into ZIPs, JARs, or Uberjars (via the third-party Shadow plugin)

  • Multi-project builds

  • Publishing to Maven repositories (such as Clojars or Maven Central)

Clojure/ClojureScript

Unique features provided by Clojurephant.

  • Running clojure.test tests with Gradle’s out-of-box Test task (via the jovial Junit Platform Engine)

  • Clojure AOT compilation

  • ClojureScript compilation (supporting multiple builds)

  • Running an nREPL server (supporting custom middleware or handlers)

    • Supporting "jack-in" dependencies

    • Enriching classpath with dependencies' sources/javadoc by default

ClojureScript features, in particular, are not fully settled and may change before 1.0.

Release Notes

See the GitHub releases for the changelog of each version.

Quick Start

Look at our sample projects:

If the samples or our documentation doesn’t answer your questions, please ask in Clojurephant Discussions.

Project Layout

This the default layout, which can be configured via Gradle’s sourceSets extension.

<project>/
  settings.gradle
  build.gradle
  gradlew
  gradlew.bat
  gradle/
    wrapper/
      gradle-wrapper.jar
      gradle-wrapper.properties
  src/
    main/
      clojure/
        sample_clojure/
          core.clj
      clojurescript/
        sample_clojure/
          main.cljs
    test/
      clojure/
        sample_clojure/
          core_test.clj
      clojurescript/
        sample_clojure/
          main_test.cljs // right now we don't support cljs.test
    dev/
      clojure/
        user.clj
      clojurescript/
        user.cljs

Build Script

A sample, relatively complete build file for a full-stack project looks like this:

build.gradle
plugins {
  id 'dev.clojurephant.clojure' version '0.7.0'
  id 'dev.clojurephant.clojurescript' version '0.7.0'
}

repositories {
  mavenCentral()
  maven {
    name = 'clojars'
    url = 'https://repo.clojars.org'
  }
}

dependencies {
  // clojure
  implementation 'org.clojure:clojure:1.11.1'
  implementation 'org.clojure:clojurescript:1.11.60'

  // testing
  testRuntimeOnly 'dev.clojurephant:jovial:0.4.2'

  // backend
  implementation 'io.pedestal:pedestal.service:0.5.10'
  implementation 'io.pedestal:pedestal.jetty:0.5.10'

  // frontend
  implementation 're-frame:re-frame:1.2.0'

  // component
  implementation 'com.stuartsierra:component:1.1.0'
  devImplementation 'com.stuartsierra:component.repl:0.2.0'

  // figwheel
  devImplementation 'com.bhauman:figwheel-repl:0.2.18'
  devImplementation 'ring:ring-jetty-adapter:1.9.5'
}

tasks.withType(Test) {
  useJUnitPlatform()
}

clojure {
  builds {
    main {
      aotNamespaces.add('sample.core')
      reflection = 'warn'
    }
  }
}

clojurescript {
  builds {
    all {
      compiler {
        outputTo = 'public/js/main.js'
        outputDir = 'public/js/out'
        assetPath = '/js/out'
        main = 'sample.main'
      }
    }
    main {
      compiler {
        optimizations = 'advanced'
        sourceMap = 'public/js/main.js.map'
      }
    }
    dev {
      compiler {
        optimizations = 'none'
        sourceMap = true
        preloads = ['sample.dev']
      }
    }
  }
}

Documentation

Documentation is divided into sections based on your need:

Many of these sections are still under-construction so please give feedback on what would be most useful to you.