dev.clojurephant.clojure-base

Java Support

Applies the Gradle built-in java-base plugin to get basic support for the JVM ecosystem.

The high-level features provided by java-base for each SourceSet.

Each source set will have a Java compilation task compile<Name>Java task (compileJava for the main source set).

Dependencies

Multiple dependency "buckets" are created for each source set, to allow scoping them to the places their needed.

Names below are for a source set named main. Other source sets' configurations will be prefixed by the source set name (e.g. testRuntimeOnly).

compileOnly for dependencies only needed at compile time, but shouldn’t be pulled in transitively by consumers
implementation for dependencies your code needs to compile and needed by your consumers
runtimeOnly for dependencies your code needs to run, but aren’t necessary at compile time

Project Layout

This is the default project layout for a source set.

settings.gradle
build.gradle
src/
  <source set name>/
    java/
    resources/

Creating a SourceSet

build.gradle

sourceSets {
  myStuff {
    java.srcDirs = ['src/myjava']
    resources.srcDirs = ['src/myresources']
  }
}

dependencies {
  implementation 'org.slf4j:slf4j-api:1.7.0'
  runtimeOnly 'ch.qos.logback:logback-classic:1.2.11'
}

JVM Toolchain

Gradle’s JVM toolchain feature allows you to declare a specific JVM version to use for its tasks. This means that Gradle can run on one JVM version and your tasks can run on another. Or you can have different tasks run on different JVMs.

By default, Gradle will try to detect installed JVM versions from your device and if the requested version is not found it will download it for you.

In the simplest case, you declare a JVM version to use for all tasks that fork a JVM. This is supported by the tasks created by the Java plugins and all tasks created by the Clojurephant plugins.

build.gradle

java {
  toolchain {
    languageVersion = JavaLanguageVersion.of(17)
  }
}

Clojure Extension

Adds the ClojureExtension to the project allowing the user to configure builds.

Clojure Builds

For each ClojureBuild it sets default values and creates the following tasks.

Check Task

Creates a ClojureCheck task named checkClojure (for main build) or check<Name>Clojure (e.g. checkTestClojure), with the following defaults:

task.source is build.sourceRoots
task.classpath is build.sourceRoots plus build.classpath
task.reflection is build.reflection
task.namespaces is build.checkNamespaces

Compile Task

Creates a ClojureCompile task named compileClojure (for main build) or compile<Name>Clojure (e.g. compileTestClojure), with the following defaults:

task.destinationDir is build.outputDir
task.source is build.sourceRoots
task.classpath is build.sourceRoots plus build.classpath
task.options is build.compiler
task.namespaces is build.aotNamespaces

Build per Source Set

For each SourceSet, the clojure-base plugin will create a ClojureBuild. In addition to the defaults above, the following will be configured:

Source Roots

settings.gradle
build.gradle
src/
  <source set name>/
    clojure/ # Adds this to what java-base provides
    java/
    resources/

The build will use this src/<name>/clojure directory as its source root.

The Clojure source directories will also be registed with the source set’s allSource and allJava, making them discoverable to other Gradle plugins.

For maximum compatibility, if you want to modify your source layout, configure on the source set, rather than the build.

build.gradle

sourceSets {
  main {
    clojure.srcDirs = ['src']
    resources.srcDirs = ['resources']
  }
}

Classpath

The Clojure classpath will include:

the source set’s compileClasspath configuration dependencies
the source set’s compiled Java classes
the source set’s processed resources

SourceSet Output

Each source set has a concept of its output directories and the tasks needed to populate them. Depending on your use case, you may want the Clojure source to be considered the output, or you may want AOT classes to be considered the output.

The clojure-base plugin will include only the AOT classes in the source set output, if you enable any build.aotNamespaces. Otherwise, it will only include the Clojure sources.

nREPL Configuration

Creates a Configuration named nrepl with a default nrepl:nrepl:0.9.0 dependency.

The *-base plugins do not create any ClojureNRepl tasks. You’ll either need to apply a convention plugin, or create and configure the REPL task yourself.

nREPL Jack-In Dependencies

Introduced in Clojurephant v0.7.0-alpha.6.

By default, Clojurephant will only provide an nREPL dependency. If you’d like to inject additional dependencies from the commandline, set the Gradle property dev.clojurephant.jack-in.nrepl. The value should be comma-separated group:artifact:version dependencies. These dependencies will be included in the nrepl Configuration conventionally used by the ClojureNRepl task.

Example

$ ./gradlew -Pdev.clojurephant.jack-in.nrepl=nrepl:nrepl:0.9.0,cider:cider-nrepl:0.28.5 clojureRepl --middleware=cider.nrepl/cider-middleware

Usage by Editors

CIDER: Supported by CIDER’s M-x cider-jack-in as of v20220731.522 on MELPA (also anticipated in next release after v1.4.1).