tools.build Guide

The philosophy behind tools.build is that your project build is inherently a program - a series of instructions to create one or more project artifacts from your project source files. We want to write this program with our favorite programming language, Clojure, and tools.build is a library of functions commonly needed for builds that can be connected together in flexible ways. Writing a build program does take a bit more code than other declarative approaches, but can be easily extended or customized far into the future, creating a build that grows with your project.

There is no installation step - tools.build is simply a library that your build program uses. You will create an alias in your deps.edn that includes tools.build as a dependency and a source path to the build program. Builds are designed to be easily executed as a project "tool" in the Clojure CLI (with -T). In the Clojure CLI, "tools" are programs that provide functionality and do not use your project deps or classpath. Tools executed with -T:an-alias remove all project deps and paths, add "." as a path, and include any other deps or paths as defined in :an-alias.

As such, you will need an alias in your deps.edn that defines the build classpath and includes the path to your build source, for example:

Find the most recent TAG and SHA to use at https://github.com/clojure/tools.build#release-information.

As mentioned above, running a tool with -T will create a classpath that does not include the project :paths and :deps. Using -T:build will use only the :paths and :deps from the :build alias. The root deps.edn is still included, which will pull in Clojure as well (but it would also come in as a dependency of tools.build). The :paths are not specified here, so no additional paths are added, however, -T includes the project root "." as a path by default.

So executing clj -T:build jar will use an effective classpath here of:

The :ns-default specifies the default Clojure namespace to find the function specified on the classpath. Because the only local path is the default ".", we should expect to find the build program at build.clj in the root of our project. Note that the path roots (via the :build alias :paths) and the namespace of the build program itself relative to those paths roots are fully under your control. You may wish to put them in a subdirectory of your project too.

And then finally, on the command line we specify the function to run in the build, here jar. That function will be executed in the build namespace, and passed a map built using the same arg passing style as -X - args are provided as alternating keys and values.

The remainder of this guide demonstrates individual common use cases and how to satisfy them with tools.build programs.

The most common Clojure build creates a jar file containing Clojure source code. To do this with tools.build we’ll use the following tasks:

The build.clj will look like this:

Some things to notice:

The deps.edn file will look like this:

And then you can run this build with:

We expect to be able to do these both together on the command line but that is a work in progress.

When preparing an application, it is common to compile the full app + libs and assemble the entire thing as a single uberjar.

It is important that your main Clojure namespace should have (:gen-class), for example:

And that namespace should have a function like:

An example build for a compiled uberjar will look like this:

This example directs compile-clj to compile the main namespace (by default source will be loaded from the basis :paths). Compilation is transitive and all namespaces loaded by the compiled namespace will also be compiled. You may need to add additional namespaces if code is dynamically or optionally loaded.

The deps.edn and build execution will look the same as the prior example.

You can create the uber jar build with:

The output of this build will be an uberjar at target/lib1-1.2.100-standalone.jar. That jar contains both a compiled version of this project and all of its dependencies. The uberjar will have a manifest referring to the my.lib.main namespace (which should have a -main method) and can be invoked like this:

In the builds above we did not parameterize any aspect of the build, just chose which functions to call. You may find that it’s useful to parameterize your builds to differentiate dev/qa/prod, or version, or some other factor. To account for function chaining at the command line, it is advisable to establish the common set of parameters to use across your build functions and have each function pass the parameters along.

For example, consider a parameterization that includes an extra set of dev resources to set a local developer environment. We’ll use a simple :env :dev kv pair to indicate this:

The other aspects of deps.edn and invocation remain the same.

Invocation that activates :dev environment will look like this:

The kv params are passed to the jar function.

A common case that occurs is needing to introduce a Java implementation class or two into a mostly Clojure project. In this case, you need to compile the Java classes and include them with your Clojure source. In this setup, we’ll assume that your Clojure source is in src/ and Java source is in java/ (where you actually put these is of course up to you).

This build creates a jar with classes compiled from Java sources and your Clojure sources.

The compile task here can also be used as the prep task for this lib.

See the API docs for detailed task documentation.