clojure.tools.build.api

*project-root*

dynamic

Project root path, defaults to current directory.
Use `resolve-path` to resolve relative paths in terms of the *project-root*.
Use `set-project-root!` to override the default for all tasks.

compile-clj

(compile-clj params)
Compile Clojure source to classes. Returns nil.

To determine the namespaces to compile:
* If :ns-compile - use coll of explicit namespaces to compile
* Else if :sort = :topo (default) - topologically sort all
  namespaces in :src-dirs and compile from least dependent
* Else if :sort = :bfs - compile all namespaces in :src-dirs
  and compile in breadth-first search order

Options:
  :basis - required, basis to use when compiling
  :class-dir - required, dir to write classes, will be created if needed
  :src-dirs - coll of Clojure source dirs, used to find all Clojure nses to compile
  :ns-compile - coll of specific namespace symbols to compile
  :sort - :topo (default) or :bfs for breadth-first search
  :compile-opts - map of Clojure compiler options:
    {:disable-locals-clearing false
     :elide-meta [:doc :file :line ...]
     :direct-linking false}
  :filter-nses - coll of symbols representing a namespace prefix to include

copy-dir

(copy-dir params)
Copy the contents of the src-dirs to the target-dir, optionally do text replacement.
Returns nil.

Globs are wildcard patterns for specifying sets of files in a directory
tree, as specified in the glob syntax of java.nio.file.FileSystem:
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)

Options:
  :target-dir - required, dir to write files, will be created if it doesn't exist
  :src-dirs   - required, coll of dirs to copy from
  :include    - glob of files to include, default = "**"
  :ignores    - collection of ignore regex patterns (applied only to file names),
                see clojure.tools.build.tasks.copy/default-ignores for defaults
  :replace    - map of source to replacement string in files

copy-file

(copy-file {:keys [src target], :as params})
Copy one file from source to target, creating target dirs if needed.
Returns nil.

Options:
  :src - required, source path
  :target - required, target path

create-basis

(create-basis)(create-basis params)
Create a basis from a set of deps sources and a set of aliases. By default, use
root, user, and project deps and no aliases (essentially the same classpath you
get by default from the Clojure CLI).

Each dep source value can be :standard, a string path, a deps edn map, or nil.
Sources are merged in the order - :root, :user, :project, :extra.

Options (note, paths resolved via *project-root*):
  :root    - dep source, default = :standard
  :user    - dep source, default = nil (for reproducibility, not included)
  :project - dep source, default = :standard ("./deps.edn")
  :extra   - dep source, default = nil
  :aliases - coll of aliases of argmaps to apply to subprocesses

Returns a runtime basis, which is the initial merged deps edn map plus these keys:
 :resolve-args - the resolve args passed in, if any
 :classpath-args - the classpath args passed in, if any
 :libs - lib map, per resolve-deps
 :classpath - classpath map per make-classpath-map
 :classpath-roots - vector of paths in classpath order

delete

(delete {:keys [path], :as params})
Delete file or directory recursively, if it exists. Returns nil.

Options:
  :path - required, path to file or directory

git-count-revs

(git-count-revs {:keys [dir path], :or {dir "."}, :as params})
Shells out to git and returns count of commits on this branch:
  git rev-list HEAD --count

Options:
  :dir - dir to invoke this command from, by default current directory
  :path - path to count commits for relative to dir

install

(install params)
Install pom and jar to local Maven repo.
Returns nil.

Options:
  :basis - required, used for :mvn/local-repo
  :lib - required, lib symbol
  :classifier - classifier string, if needed
  :version - required, string version
  :jar-file - required, path to jar file
  :class-dir - required, used to find the pom file

jar

(jar params)
Create jar file containing contents of class-dir. Use main in the manifest
if provided. Returns nil.

Options:
  :class-dir - required, dir to include in jar
  :jar-file - required, jar to write
  :main - main class symbol
  :manifest - map of manifest attributes, merged last over defaults+:main

java-command

(java-command params)
Create Java command line args from a basis.

Options:
  :java-cmd - Java command, default = "java"
  :basis - required, runtime basis (used to make a classpath)
  :java-opts - coll of string jvm opts
  :main - required, main class symbol
  :main-args - coll of main class args

Returns map suitable for passing to process with keys:
  :command-args - coll of command arg strings

javac

(javac params)
Compile Java source to classes. Returns nil.

Options:
  :src-dirs - required, coll of Java source dirs
  :class-dir - required, dir to write classes, will be created if needed
  :basis - classpath basis to use when compiling
  :javac-opts - coll of string opts, like ["-source" "8" "-target" "8"]

pom-path

(pom-path params)
Calculate path to pom.xml in jar meta (same path used by write-pom).
Relative path in jar is:
  META-INF/maven/<groupId>/<artifactId>/pom.xml

If :class-dir provided, return path will start with resolved class-dir
(which may be either absolute or relative), otherwise just relative
path in jar.

Options:
  :lib - required, used to form the relative path in jar to pom.xml
  :class-dir - optional, if provided will be resolved and form the root of the path

process

(process params)
Exec the command made from command-args, redirect out and err as directed,
and return {:exit exit-code, :out captured-out, :err captured-err}

Options:
  :command-args - required, coll of string args
  :dir - directory to run the command from, default current directory
  :out - one of :inherit :capture :write :append :ignore
  :err - one of :inherit :capture :write :append :ignore
  :out-file - file path to write if :out is :write or :append
  :err-file - file path to write if :err is :write or :append
  :env - map of environment variables to set

The :out and :err input flags take one of the following options:
  :inherit - inherit the stream and write the subprocess io to this process's stream (default)
  :capture - capture the stream to a string and return it
  :write - write to :out-file or :err-file
  :append - append to :out-file or :err-file
  :ignore - ignore the stream

resolve-path

(resolve-path path)
If path is absolute or root-path is nil then return path,
otherwise resolve relative to *project-root*.

set-project-root!

(set-project-root! root)
Set *project-root* dir (default is ".")

uber

(uber params)
Create uberjar file containing contents of deps in basis and class-dir.
Use main class in manifest if provided. Returns nil.

Options:
  :class-dir - required, local class dir to include
  :uber-file - required, uber jar file to create
  :basis - used to pull dep jars
  :main - main class symbol
  :manifest - map of manifest attributes, merged last over defaults + :main
  :exclude - coll of string patterns (regex) to exclude from deps
  :conflict-handlers - map of string pattern (regex) to built-in handlers,
                       symbols to eval, or function instances

When combining jar files into an uber jar, multiple jars may contain a file
at the same path. The conflict handlers are a map of string regex pattern
to:
  a keyword (to use a built-in handler) or
  a symbol (to resolve and invoke) or
  a function instance
The special key `:default` specifies the default behavior if not matched.

Conflict handler signature (fn [params]) => effect-map:
  params:
    :path     - String, path in uber jar, matched by regex
    :in       - InputStream to incoming file (see stream->string if needed)
    :existing - File, existing File at path
    :lib      - symbol, lib source for incoming conflict
    :state    - map, available for retaining state during uberjar process

Handler should return effect-map with optional keys:
  :state      - updated state map
  :write      - map of string path to map of :string (string) or
                :stream (InputStream) to write and optional :append
                flag. Omit if no files to write.

Available built-in conflict handlers:
  :ignore - don't do anything (default)
  :overwrite - overwrite (replaces prior file)
  :append - append the file with a blank line separator
  :append-dedupe - append the file but dedupe appended sections
  :data-readers - merge data_readers.clj
  :warn - print a warning
  :error - throw an error

Default conflict handlers map:
  {"^data_readers.clj[cs]?$" :data-readers
   "^META-INF/services/" :append
   "(?i)^(META-INF/)?(COPYRIGHT|NOTICE|LICENSE)(\\.(txt|md))?$" :append-dedupe
   :default :ignore}

unzip

(unzip params)
Unzip zip file to target-dir. Returns nil.

Options:
  :zip-file - required, zip file to unzip
  :target-dir - required, directory to unzip in

write-file

(write-file {:keys [path content string opts], :as params})
Writes a file at path, will create parent dirs if needed. Returns nil.
File contents may be specified either with :content (for data, that
will be pr-str'ed) or with :string for the string to write. If
neither is specified, an empty file is created (like touch).

Options:
  :path - required, file path
  :content - val to write, will pr-str
  :string - string to write
  :opts - coll of writer opts like :append and :encoding (per clojure.java.io)

write-pom

(write-pom params)
Write pom.xml and pom.properties files to the class dir under
META-INF/maven/group-id/artifact-id/ (where Maven typically writes
these files). The pom deps, dirs, and repos are either synced from
the src-pom or generated from the basis.

If a repos map is provided it supersedes the repos in the basis.

Returns nil.

Options:
  :basis - required, used to pull deps, repos
  :class-dir - required, root dir for writing pom files, created if needed
  :src-pom - source pom.xml to synchronize from, default = "./pom.xml"
  :lib - required, project lib symbol
  :version - required, project version
  :scm - map of scm properties to write in pom
         keys:  :connection, :developerConnection, :tag, :url
         See: https://maven.apache.org/pom.html#SCM for details
  :src-dirs - coll of src dirs
  :resource-dirs - coll of resource dirs
  :repos - map of repo name to repo config, replaces repos from deps.edn

zip

(zip params)
Create zip file containing contents of src dirs. Returns nil.

Options:
  :src-dirs - required, coll of source directories to include in zip
  :zip-file - required, zip file to create