Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API docs #97

Merged
merged 16 commits into from
May 12, 2023
Prev Previous commit
Next Next commit
slight rename
borkdude committed May 11, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
commit 2c761dccd0c34b70df1dbecf58891e026d33993f
71 changes: 39 additions & 32 deletions API.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Table of contents
- [`borkdude.deps`](#borkdude.deps) - Port of https://github.com/clojure/brew-install/blob/1.11.1/src/main/resources/clojure/install/clojure in Clojure.
- [`-main`](#borkdude.deps/-main) - See <code>help-text</code>.
- [`cache-version`](#borkdude.deps/cache-version)
- [`clojure-tools-download!`](#borkdude.deps/clojure-tools-download!) - Downloads clojure tools archive in <code>:out-dir</code>, if not already there, and extracts in-place the clojure tools jar file and other important files.
- [`clojure-tools-download-direct!`](#borkdude.deps/clojure-tools-download-direct!) - Downloads from <code>:url</code> to <code>:dest</code> file returning true on success.
- [`clojure-tools-download-jar!`](#borkdude.deps/clojure-tools-download-jar!) - Downloads clojure tools archive in <code>:out-dir</code>, if not already there, and extracts in-place the clojure tools jar file and other important files.
- [`deps-clj-version`](#borkdude.deps/deps-clj-version)
- [`clojure-tools-download-java!`](#borkdude.deps/clojure-tools-download-java!) - Downloads <code>:url</code> zip file to <code>:dest</code> by invoking <code>java</code> with <code>:jvm-opts</code> on a <code>.java</code> program file, and returns true on success.
- [`deps-clj-version`](#borkdude.deps/deps-clj-version) - The current version of deps.clj.
- [`get-cache-dir`](#borkdude.deps/get-cache-dir) - Returns cache dir (<code>.cpcache</code>) from either local dir, if <code>deps-edn</code> exists, or the user cache dir.
- [`get-config-dir`](#borkdude.deps/get-config-dir) - Retrieves configuration directory.
- [`get-config-paths`](#borkdude.deps/get-config-paths) - Returns vec of configuration paths, i.e.
@@ -47,13 +47,26 @@ See [`help-text`](#borkdude.deps/help-text).
env variable is set and a succesful attempt is made to download the
archive by invoking a java subprocess passing the env variable value
as command line options.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L706-L953">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L707-L954">Source</a></sub></p>

## <a name="borkdude.deps/cache-version">`cache-version`</a><a name="borkdude.deps/cache-version"></a>
## <a name="borkdude.deps/clojure-tools-download!">`clojure-tools-download!`</a><a name="borkdude.deps/clojure-tools-download!"></a>
``` clojure

(clojure-tools-download! {:keys [out-dir jvm-opts debug]})
```

Downloads clojure tools archive in `:out-dir`, if not already there,
and extracts in-place the clojure tools jar file and other important
files.

The download is attempted directly from this process, unless
`:jvm-opts` is set, in which case a java subprocess
is created to download the archive passing in its value as command
line options.

<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L21-L21">Source</a></sub></p>
It calls [`*exit-fn*`](#borkdude.deps/*exit-fn*) if it cannot download the archive, with
instructions how to manually download it.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L451-L485">Source</a></sub></p>

## <a name="borkdude.deps/clojure-tools-download-direct!">`clojure-tools-download-direct!`</a><a name="borkdude.deps/clojure-tools-download-direct!"></a>
``` clojure
@@ -62,32 +75,26 @@ See [`help-text`](#borkdude.deps/help-text).
```

Downloads from `:url` to `:dest` file returning true on success.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L313-L329">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L314-L330">Source</a></sub></p>

## <a name="borkdude.deps/clojure-tools-download-jar!">`clojure-tools-download-jar!`</a><a name="borkdude.deps/clojure-tools-download-jar!"></a>
## <a name="borkdude.deps/clojure-tools-download-java!">`clojure-tools-download-java!`</a><a name="borkdude.deps/clojure-tools-download-java!"></a>
``` clojure

(clojure-tools-download-jar! {:keys [out-dir jvm-opts debug]})
(clojure-tools-download-java! {:keys [url dest jvm-opts]})
```

Downloads clojure tools archive in `:out-dir`, if not already there,
and extracts in-place the clojure tools jar file and other important
files.

The download is attempted directly from this process, unless
`:jvm-opts` is set, in which case a java subprocess
is created to download the archive passing in its value as command
line options.

It calls [`*exit-fn*`](#borkdude.deps/*exit-fn*) if it cannot download the archive, with
instructions how to manually download it.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L450-L484">Source</a></sub></p>
Downloads `:url` zip file to `:dest` by invoking `java` with
`:jvm-opts` on a `.java` program file, and returns true on
success. Requires Java 11+ (JEP 330).
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L421-L439">Source</a></sub></p>

## <a name="borkdude.deps/deps-clj-version">`deps-clj-version`</a><a name="borkdude.deps/deps-clj-version"></a>



<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L23-L26">Source</a></sub></p>

The current version of deps.clj
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L23-L27">Source</a></sub></p>

## <a name="borkdude.deps/get-cache-dir">`get-cache-dir`</a><a name="borkdude.deps/get-cache-dir"></a>
``` clojure
@@ -97,7 +104,7 @@ Downloads clojure tools archive in `:out-dir`, if not already there,

Returns cache dir (`.cpcache`) from either local dir, if `deps-edn`
exists, or the user cache dir.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L659-L670">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L660-L671">Source</a></sub></p>

## <a name="borkdude.deps/get-config-dir">`get-config-dir`</a><a name="borkdude.deps/get-config-dir"></a>
``` clojure
@@ -107,7 +114,7 @@ Returns cache dir (`.cpcache`) from either local dir, if `deps-edn`

Retrieves configuration directory.
First tries `CLJ_CONFIG` env var, then `$XDG_CONFIG_HOME/clojure`, then ~/.clojure.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L642-L649">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L643-L650">Source</a></sub></p>

## <a name="borkdude.deps/get-config-paths">`get-config-paths`</a><a name="borkdude.deps/get-config-paths"></a>
``` clojure
@@ -119,7 +126,7 @@ Returns vec of configuration paths, i.e. deps.edn from:
- `:install-dir` as obtained thrhough [`get-install-dir`](#borkdude.deps/get-install-dir)
- `:config-dir` as obtained through [`get-config-dir`](#borkdude.deps/get-config-dir)
- `:deps-edn` as obtained through [`get-local-deps-edn`](#borkdude.deps/get-local-deps-edn)
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L672-L687">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L673-L688">Source</a></sub></p>

## <a name="borkdude.deps/get-install-dir">`get-install-dir`</a><a name="borkdude.deps/get-install-dir"></a>
``` clojure
@@ -129,7 +136,7 @@ Returns vec of configuration paths, i.e. deps.edn from:

Retrieves the install directory where tools jar is located (after download).
Defaults to ~/.deps.clj/<version>/ClojureTools.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L631-L640">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L632-L641">Source</a></sub></p>

## <a name="borkdude.deps/get-local-deps-edn">`get-local-deps-edn`</a><a name="borkdude.deps/get-local-deps-edn"></a>
``` clojure
@@ -140,7 +147,7 @@ Retrieves the install directory where tools jar is located (after download).
Returns the path of the `deps.edn` file (as string) in the current directory or as set by `-Sdeps-file`.
Required options:
* `:cli-opts`: command line options as parsed by `parse-opts`
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L651-L657">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L652-L658">Source</a></sub></p>

## <a name="borkdude.deps/get-proxy-info">`get-proxy-info`</a><a name="borkdude.deps/get-proxy-info"></a>
``` clojure
@@ -152,13 +159,13 @@ Returns a map with proxy information parsed from env vars. The map
will contain :http-proxy and :https-proxy entries if the relevant
env vars are set and parsed correctly. The value for each is a map
with :host and :port entries.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L288-L300">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L289-L301">Source</a></sub></p>

## <a name="borkdude.deps/help-text">`help-text`</a><a name="borkdude.deps/help-text"></a>



<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L117-L197">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L118-L198">Source</a></sub></p>

## <a name="borkdude.deps/jvm-proxy-opts">`jvm-proxy-opts`</a><a name="borkdude.deps/jvm-proxy-opts"></a>
``` clojure
@@ -169,7 +176,7 @@ Returns a map with proxy information parsed from env vars. The map
Returns a vector containing the JVM args to be passed to a new process
to set its proxy system properties.
proxy-info parameter is as returned from env-proxy-info.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L486-L495">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L487-L496">Source</a></sub></p>

## <a name="borkdude.deps/parse-cli-opts">`parse-cli-opts`</a><a name="borkdude.deps/parse-cli-opts"></a>
``` clojure
@@ -178,7 +185,7 @@ Returns a vector containing the JVM args to be passed to a new process
```

Parses the command line options.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L528-L599">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L529-L600">Source</a></sub></p>

## <a name="borkdude.deps/set-proxy-system-props!">`set-proxy-system-props!`</a><a name="borkdude.deps/set-proxy-system-props!"></a>
``` clojure
@@ -188,4 +195,4 @@ Parses the command line options.

Sets the proxy system properties in the current JVM.
proxy-info parameter is as returned from env-proxy-info.
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L302-L311">Source</a></sub></p>
<p><sub><a href="https://github.com/borkdude/deps.clj/blob/master/src/borkdude/deps.clj#L303-L312">Source</a></sub></p>
9 changes: 5 additions & 4 deletions src/borkdude/deps.clj
Original file line number Diff line number Diff line change
@@ -18,9 +18,10 @@
(delay (or (System/getenv "DEPS_CLJ_TOOLS_VERSION")
"1.11.1.1273")))

(def cache-version "4")
(def ^:private cache-version "4")

(def deps-clj-version
"The current version of deps.clj"
(-> (io/resource "DEPS_CLJ_VERSION")
(slurp)
(str/trim)))
@@ -417,7 +418,7 @@ public class ClojureToolsDownloader {
System.exit(1); }}}"))
dest-file))

(defn- clojure-tools-download-java!
(defn clojure-tools-download-java!
"Downloads `:url` zip file to `:dest` by invoking `java` with
`:jvm-opts` on a `.java` program file, and returns true on
success. Requires Java 11+ (JEP 330)."
@@ -447,7 +448,7 @@ public class ClojureToolsDownloader {
Should return true if the download was successful, or false if not."
nil)

(defn clojure-tools-download-jar!
(defn clojure-tools-download!
"Downloads clojure tools archive in `:out-dir`, if not already there,
and extracts in-place the clojure tools jar file and other important
files.
@@ -744,7 +745,7 @@ public class ClojureToolsDownloader {
(warn "Clojure tools not yet in expected location:" (str tools-jar))
(let [jvm-opts (when clj-jvm-opts (vec (concat clj-jvm-opts
proxy-settings)))]
(clojure-tools-download-jar! {:out-dir libexec-dir :debug debug :jvm-opts jvm-opts}))
(clojure-tools-download! {:out-dir libexec-dir :debug debug :jvm-opts jvm-opts}))
tools-jar))
mode (:mode cli-opts)
exec? (= :exec mode)