1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<!DOCTYPE html PUBLIC ""
"">
<html><head><meta charset="UTF-8" /><title>clojure.tools.build.api documentation</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name"></span> <span class="project-version"></span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1 current"><a href="clojure.tools.build.api.html"><div class="inner"><span>clojure.tools.build.api</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="clojure.tools.build.api.html#var-*project-root*"><div class="inner"><span>*project-root*</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-compile-clj"><div class="inner"><span>compile-clj</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-copy-dir"><div class="inner"><span>copy-dir</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-copy-file"><div class="inner"><span>copy-file</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-create-basis"><div class="inner"><span>create-basis</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-delete"><div class="inner"><span>delete</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-git-count-revs"><div class="inner"><span>git-count-revs</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-git-process"><div class="inner"><span>git-process</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-install"><div class="inner"><span>install</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-jar"><div class="inner"><span>jar</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-java-command"><div class="inner"><span>java-command</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-javac"><div class="inner"><span>javac</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-pom-path"><div class="inner"><span>pom-path</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-process"><div class="inner"><span>process</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-resolve-path"><div class="inner"><span>resolve-path</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-set-project-root.21"><div class="inner"><span>set-project-root!</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-uber"><div class="inner"><span>uber</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-unzip"><div class="inner"><span>unzip</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-with-project-root"><div class="inner"><span>with-project-root</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-write-file"><div class="inner"><span>write-file</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-write-pom"><div class="inner"><span>write-pom</span></div></a></li><li class="depth-1"><a href="clojure.tools.build.api.html#var-zip"><div class="inner"><span>zip</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">clojure.tools.build.api</h1><div class="doc"><pre class="plaintext"></pre></div><div class="public anchor" id="var-*project-root*"><h3>*project-root*</h3><h4 class="dynamic">dynamic</h4><div class="usage"></div><div class="doc"><pre class="plaintext">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.</pre></div></div><div class="public anchor" id="var-compile-clj"><h3>compile-clj</h3><div class="usage"><code>(compile-clj params)</code></div><div class="doc"><pre class="plaintext">Compile Clojure source to classes in :class-dir.
Clojure source files are found in :basis :paths by default, or override with :src-dirs.
Namespaces and order of compilation are one of:
* :ns-compile - compile these namespaces, in this order
* :sort - find all namespaces in source files and use either :topo (default)
or :bfs to order them for compilation
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}
:bindings - map of Var to value to be set during compilation, for example:
{#'clojure.core/*assert* false
#'clojure.core/*warn-on-reflection* true}
:filter-nses - coll of symbols representing a namespace prefix to include
Additional options flow to the forked process doing the compile:
:java-cmd - Java command, default = $JAVA_CMD or 'java' on $PATH, or $JAVA_HOME/bin/java
:java-opts - coll of string jvm opts
:use-cp-file - one of:
:auto (default) - use only if os=windows && Java >= 9 && command length >= 8k
:always - always write classpath to temp file and include
:never - never write classpath to temp file (pass on command line)
Returns nil.</pre></div></div><div class="public anchor" id="var-copy-dir"><h3>copy-dir</h3><div class="usage"><code>(copy-dir params)</code></div><div class="doc"><pre class="plaintext">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:
<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)">https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)</a>
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
:non-replaced-exts - coll of extensions to skip when replacing (still copied)
default = ["jpg" "jpeg" "png" "gif" "bmp"]</pre></div></div><div class="public anchor" id="var-copy-file"><h3>copy-file</h3><div class="usage"><code>(copy-file {:keys [src target], :as params})</code></div><div class="doc"><pre class="plaintext">Copy one file from source to target, creating target dirs if needed.
Returns nil.
Options:
:src - required, source path
:target - required, target path</pre></div></div><div class="public anchor" id="var-create-basis"><h3>create-basis</h3><div class="usage"><code>(create-basis)</code><code>(create-basis params)</code></div><div class="doc"><pre class="plaintext">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*):
:dir - directory root path, defaults to current directory
: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</pre></div></div><div class="public anchor" id="var-delete"><h3>delete</h3><div class="usage"><code>(delete {:keys [path], :as params})</code></div><div class="doc"><pre class="plaintext">Delete file or directory recursively, if it exists. Returns nil.
Options:
:path - required, path to file or directory</pre></div></div><div class="public anchor" id="var-git-count-revs"><h3>git-count-revs</h3><div class="usage"><code>(git-count-revs {:keys [dir git-command path], :or {git-command "git"}, :as params})</code></div><div class="doc"><pre class="plaintext">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, default = current directory
:git-command - git command to use, default = "git"
:path - path to count commits for relative to dir</pre></div></div><div class="public anchor" id="var-git-process"><h3>git-process</h3><div class="usage"><code>(git-process params)</code></div><div class="doc"><pre class="plaintext">Run git process in the specified dir using git-command with git-args (which should not
start with "git"). git-args may either be a string (split on whitespace) or a vector
of strings. By default, stdout is captured, trimmed, and returned.
Options:
:dir - dir to invoke this command from, default = current directory
:git-command - git command to use, default = "git"
:git-args - required, coll of git-arg strings forming a command line OR
a string (do not use if args may have embedded spaces)
:capture - :out (default) or :err, else nothing
Examples:
(api/git-process {:git-args "rev-list HEAD --count"})
(api/git-process {:git-args "branch --show-current"})
(api/git-process {:git-args "rev-parse --short HEAD"})
(api/git-process {:git-args "push", :capture nil})</pre></div></div><div class="public anchor" id="var-install"><h3>install</h3><div class="usage"><code>(install params)</code></div><div class="doc"><pre class="plaintext">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</pre></div></div><div class="public anchor" id="var-jar"><h3>jar</h3><div class="usage"><code>(jar params)</code></div><div class="doc"><pre class="plaintext">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</pre></div></div><div class="public anchor" id="var-java-command"><h3>java-command</h3><div class="usage"><code>(java-command params)</code></div><div class="doc"><pre class="plaintext">Create Java command line args. The classpath will be the combination of
:cp followed by the classpath from the basis, both are optional.
Note that 'java-command' will NOT resolve any relative paths from basis
or cp in terms of *project-root*, you will get a classpath with the same
relative paths. 'process' (if run with this output), will run in the
context of the *project-root* directory.
Options:
:java-cmd - Java command, default = $JAVA_CMD or 'java' on $PATH, or $JAVA_HOME/bin/java
:cp - coll of string classpath entries, used first (if provided)
:basis - runtime basis used for classpath and jvm opts from aliases, used last (if provided)
:java-opts - coll of string jvm opts
:main - required, main class symbol
:main-args - coll of main class args
:use-cp-file - one of:
:auto (default) - use only if os=windows && Java >= 9 && command length >= 8k
:always - always write classpath to temp file and include
:never - never write classpath to temp file (pass on command line)
Returns map suitable for passing to 'process' with keys:
:command-args - coll of command arg strings</pre></div></div><div class="public anchor" id="var-javac"><h3>javac</h3><div class="usage"><code>(javac params)</code></div><div class="doc"><pre class="plaintext">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"]</pre></div></div><div class="public anchor" id="var-pom-path"><h3>pom-path</h3><div class="usage"><code>(pom-path params)</code></div><div class="doc"><pre class="plaintext">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</pre></div></div><div class="public anchor" id="var-process"><h3>process</h3><div class="usage"><code>(process params)</code></div><div class="doc"><pre class="plaintext">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 *project-root*
: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</pre></div></div><div class="public anchor" id="var-resolve-path"><h3>resolve-path</h3><div class="usage"><code>(resolve-path path)</code></div><div class="doc"><pre class="plaintext">If path is absolute or root-path is nil then return path,
otherwise resolve relative to *project-root*.</pre></div></div><div class="public anchor" id="var-set-project-root.21"><h3>set-project-root!</h3><div class="usage"><code>(set-project-root! root)</code></div><div class="doc"><pre class="plaintext">Set *project-root* dir (default is ".")
</pre></div></div><div class="public anchor" id="var-uber"><h3>uber</h3><div class="usage"><code>(uber params)</code></div><div class="doc"><pre class="plaintext">Create uberjar file. An uberjar is a self-contained jar file containing
both the project contents AND the contents of all dependencies.
The project contents are represented by the class-dir. Use other tasks to
put Clojure source, class files, a pom file, or other resources in the
class-dir. In particular, see the copy-dir, write-pom, compile-clj, and
javac tasks.
The dependencies are pulled from the basis. All transitive deps will be
included. Dependency jars are expanded for inclusion in the uberjar.
Use :exclude to exclude specific paths from the expanded deps. Use
conflict-handlers to handle conflicts that may occur if two dependency
jar files include a file at the same path. See below for more detail.
If a main class or manifest are provided, those are put in the uberjar
META-INF/MANIFEST.MF file. Providing a main allows the jar to be
invoked with java -jar.
Returns nil.
Options:
:uber-file - required, uber jar file to create
:class-dir - required, local class dir to include
: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[c]?$" :data-readers
"^META-INF/services/.*" :append
"(?i)^(META-INF/)?(COPYRIGHT|NOTICE|LICENSE)(\\.(txt|md))?$" :append-dedupe
:default :ignore}</pre></div></div><div class="public anchor" id="var-unzip"><h3>unzip</h3><div class="usage"><code>(unzip params)</code></div><div class="doc"><pre class="plaintext">Unzip zip file to target-dir. Returns nil.
Options:
:zip-file - required, zip file to unzip
:target-dir - required, directory to unzip in</pre></div></div><div class="public anchor" id="var-with-project-root"><h3>with-project-root</h3><h4 class="type">macro</h4><div class="usage"><code>(with-project-root path & forms)</code></div><div class="doc"><pre class="plaintext">Execute forms in a bound project path (string) other than the default (".")
</pre></div></div><div class="public anchor" id="var-write-file"><h3>write-file</h3><div class="usage"><code>(write-file {:keys [path content string opts], :as params})</code></div><div class="doc"><pre class="plaintext">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)</pre></div></div><div class="public anchor" id="var-write-pom"><h3>write-pom</h3><div class="usage"><code>(write-pom params)</code></div><div class="doc"><pre class="plaintext">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), or to target (exactly one of :class-dir and :target must
be provided).
Optionally use :src-pom to provide a pom template (or a default will
be generated from the provided attributes). The pom deps, dirs, and
repos from the basis will replace those sections of the template. Note
that the :src-pom template is not validated and should contain required
elements such as modelVersion.
If a repos map is provided it supersedes the repos in the basis.
Returns nil.
Options:
:basis - required, used to pull deps, repos
:src-pom - source pom.xml to synchronize from, default = "./pom.xml"
:class-dir - root dir for writing pom files, created if needed
:target - file path to write pom if no :class-dir specified
:lib - required, project lib symbol
:version - required, project version
:scm - map of scm properties to write in pom
keys: :connection, :developerConnection, :tag, :url
See: <a href="https://maven.apache.org/pom.html#SCM">https://maven.apache.org/pom.html#SCM</a> 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
:pom-data - vector of hiccup-style extra pom top elements to include when
no :src-pom is provided:
[[:licenses
[:license
[:name "Eclipse Public License 1.0"]
[:url "<a href="https://opensource.org/license/epl-1-0/"">https://opensource.org/license/epl-1-0/"</a>;]
[:distribution "repo"]]]
[:organization "Super Corp"]]
The pom-data MUST NOT include:
:modelVersion, :packaging, :groupId, :artifactId, :version, :name,
:deps, :repositories, :build, or :scm</pre></div></div><div class="public anchor" id="var-zip"><h3>zip</h3><div class="usage"><code>(zip params)</code></div><div class="doc"><pre class="plaintext">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</pre></div></div></div></body></html>
|
