.CLJ File Format – Tooling

The Clojure CLI and deps.edn

The Clojure CLI is started as clojure or clj (the same, with rlwrap added for editing at the REPL). Each run determines the paths, dependencies and entry point from deps.edn files, then starts the program on the JVM. Any CLI version can run any version of the language.

deps.edn is an edn map. The CLI combines up to four sources into one map, in this order: the root deps (built into the tools.deps library: Clojure as the only dependency, :paths ["src"], the aliases :deps and :test and the repositories Maven Central and Clojars), the user deps.edn in the configuration folder, the project deps.edn in the current folder, and extra deps given with -Sdeps. They are merged as merge-with merge, except that only the last source's :paths is used.

tools.build

tools.build is a library of build tasks. A build is a program: a build.clj namespace with functions that call clojure.tools.build.api, run with clj -T:build jar from an alias that adds the library and sets :ns-default build. The tasks include create-basis (the project basis: its paths and downloaded libraries), copy-dir, write-pom, jar and delete; the guide's second example builds a compiled uberjar (a single jar with the application and its libraries) with an uber task.

(ns build
  (:require [clojure.tools.build.api :as b]))

(def lib 'my/lib1)
(def version "0.1.0")
(def class-dir "target/classes")
(def jar-file (format "target/%s-%s.jar" (name lib) version))
(def basis (delay (b/create-basis {:project "deps.edn"})))

(defn clean [_]
  (b/delete {:path "target"}))

(defn jar [_]
  (b/write-pom {:class-dir class-dir :lib lib :version version
                :basis @basis :src-dirs ["src"]})
  (b/copy-dir {:src-dirs ["src" "resources"] :target-dir class-dir})
  (b/jar {:class-dir class-dir :jar-file jar-file}))

Leiningen: project.clj

Leiningen's project.clj is a Clojure file holding one defproject form: the name (group/artifact), the version string, and then keyword-value pairs. It is code and can be edited with the usual syntax, so the viewer shows it as Clojure.

Boot, Babashka and shadow-cljs

• Boot keeps its build in a build.boot file: Clojure code that calls set-env! for dependencies and source paths and defines tasks with deftask. The viewer shows .boot files as Clojure.
• Babashka (bb) runs scripts with fast start-up. Its bb.edn is an edn map, read from the current folder, that can hold :paths, :deps and a :tasks map of named tasks run as bb task-name. A script file can start with #!/usr/bin/env bb. See Dialects.
• shadow-cljs builds ClojureScript. Its shadow-cljs.edn is an edn map that configures the build and the ClojureScript dependencies; the :builds section names each build with a :target (such as :esm). The package.json next to it manages JavaScript dependencies with npm.
• clj-kondo (a linter) reads .clj-kondo/config.edn; cljfmt and editor tools read their own edn files.

The REPL and editors

Clojure is developed interactively: forms are sent from the editor to a running REPL (clojure.main, with *1 *2 *3 and *e holding the last results and error) over a socket (the runtime can start a socket server from a JVM property) or over nREPL (which Leiningen starts), which editor plugins such as Calva (VS Code) and CIDER (Emacs) do. clojure.repl supplies doc, find-doc, apropos, source, dir and pst; since Clojure 1.12 add-lib can add a library to a running REPL.

Not described

Known, not yet covered

• Reference: only the headings of the deps.edn reference (about 25 KB), the CLI reference's command list and the tools.build guide's first example were read; the following are not described: the full deps.edn merge rules, the -P prepare and other CLI options, tool installation, the function execution protocol, the Maven pom generation, version finding, Git procurer details, :deps/prep-lib, the runtime basis and the other tools.build tasks.
• Reference: Leiningen's full sample.project.clj (33 KB) was downloaded and its keys sampled; the plugin system, profile merging and every key are not covered. The Babashka book pages on bb.edn, tasks and usage, the Boot README, the Leiningen tutorial, the clj-kondo configuration page and the shadow-cljs README were downloaded and read only for the points above; Babashka task options, Boot tasks and shadow-cljs build options are not described.
• Viewer: the keys of project.clj are coloured as keywords of an ordinary Clojure form; dependency vectors in :dependencies, :plugins and :managed-dependencies have their library name coloured as a name.

Unknown

• Reference: checked against downloaded pages: bb.edn with :paths, :deps and :tasks (the Babashka book), a build.boot that calls set-env! (the Boot README), the project config file .clj-kondo/config.edn (the clj-kondo configuration page) and the project.clj keys :dependencies, :main, :profiles, :aot, :jvm-opts and :aliases (the Leiningen tutorial). Not found in any downloaded page: that deftask defines Boot tasks, the other project.clj keys listed above (they come from the sample project file only in part), and that Calva and CIDER speak nREPL or a socket REPL.

See also

• EDN – the format of deps.edn, bb.edn and shadow-cljs.edn
• File structure – source paths and namespaces
• Versions and history – the language releases