anchor.diff:  
   Clojure build tools have traditionally taken the approach of wrapping the Maven ecosystem to gain access to Java libraries. However, they have also forced this approach on Clojure code as well, requiring a focus on artifacts that must be built and deployed (which Clojure does not require). This approach has created friction for Clojure developers, making it hard to e.g. work with libs not yet publishing artifacts, work on speculative changes w/o artifacts or across multiple libs, or give control to a 3rd party to manage shared dependencies.
   
  -To this end Clojure provides:
  -
  -* https://github.com/clojure/tools.deps.alpha[tools.deps.alpha] - a library providing an API for resolving dependency graphs and building classpaths that can utilize both Maven and other providers of code or artifacts
  -* Command line tools (`clojure` and `clj`) that enable users to make use of this capability at the terminal to declare dependencies, assemble classpaths, and launch Clojure programs with data
  +Clojure provides:
  +
  +* https://github.com/clojure/tools.deps.alpha[tools.deps.alpha] - a library providing a functional API for resolving dependency graphs and building classpaths that can utilize both Maven and other providers of code or artifacts
  +* Command line tools (`clojure` and `clj`) that enable users to make use of this capability at the terminal to declare dependencies, assemble classpaths, and launch Clojure programs
   * System-specific installers for downloading the tools, improving the "Getting Started" experience
   
  -= Overview
  -
  -You use the Clojure tools (`clj` or `clojure`) to run Clojure programs on the JVM, e.g. to start a REPL or invoke a specific function with data. The Clojure tools will configure the JVM process by defining a classpath (of desired libraries), an execution environment (JVM options) and specifying a main class and args.
  -
  -Using a deps.edn file (or files), you tell Clojure where your source code resides and what libraries you need. Clojure will then calculate the full set of required libraries and a classpath, caching expensive parts of this process for better performance.
  -
  -The internal steps of the Clojure tools, as well as the Clojure functions you intend to run, are parameterized by data structures, often maps. Shell command lines are not optimized for passing nested data, so instead you will put the data structures in your deps.edn file and refer to them on the command line via _aliases_ - keywords that name data structures.
  -
  -`clj` and `clojure` differ in that `clj` has extra support for use as a REPL in a terminal, and should be preferred unless you don't want that support, then use `clojure`. The invocation structure is the same for both:
  -
  -[source]
  -----
  -clj [clj-opt*] [execution-specifier]
  -----
  -
  -== Starting a REPL
  -
  -To run a REPL, just do not supply any execution-specifier:
  -
  -[source]
  -----
  -$ clj
  -Clojure 1.10.1
  -user=>
  -----
  -
  -== Executing a function that takes a map
  -
  -_Available in clj 1.10.1.619 or higher, currently a release candidate_
  -
  -If you have a function invocation you will frequently repeat, you can put a descriptor for it under a `deps.edn` alias and execute it with `-X`:
  -
  -[source]
  -----
  -clojure [clj-opt*] -X:an-alias [kpath v]*
  -----
  -
  -`-X` is configured with a descriptor map with `:fn` and `:args` keys, and stored under an alias in `deps.edn`:
  -
  -[source,clojure]
  -----
  -{:aliases
  - {:my-fn
  -  {:fn my.qualified/fn
  -   :args {:my {:data 123}
  -          :config 456}}}}
  -----
  -
  -To invoke, pass the name of the alias:
  -
  -[source]
  -----
  -clj -X:my-fn
  -----
  -
  -You can supply additional keys, or override values stored in the deps.edn file by passing pairs of key-path and value. The key-path should either be a single key or a vector of keys to refer to a nested key (as with `assoc-in`). Each key-path will be used to `assoc-in` to the original `:args` map, overriding the value there.
  -
  -[source]
  -----
  -# Top key override
  -clj -X:my-fn :config 789
  -
  -# Nested key override
  -clj -X:my-fn '[:my :data]' 789
  -----
  -
  -If you want to execute an arbitrary function, you can do that with `-F`:
  -
  -[source]
  -----
  -clojure [clj-opt*] -Fmy/fn [kpath v]*
  -----
  -
  -Pass the fully qualified function name with `-F` and then any number of key/value pairs for the invocation map:
  -
  -[source]
  -----
  -clj -Fclojure.core/pr :a 1 :b 2
  -----
  -
  -=== Quoting keys and values
  -
  -Key/value pairs are read as edn strings. A general rule is that you can surround edn data with single quotes `'data'` to get a literal string (which exec will read as edn data). In some cases (particularly numbers and keywords), you can omit the single quotes as bash does not have any conflicting interpretation.
  -
  -Note that strings must be passed in double quotes, also surrounded by single quotes to escape correctly with bash: `clj -X:my-fn :config '"foo"'`.
  -
  -
  -== Running a main or script
  -
  -In other cases, the Clojure tools will invoke clojure.main to run either a namespace with a `-main` function or load a Clojure script.
  -
  -See the <<repl_and_main#,clojure.main>> documentation for more details.
  -
  -= Operation
  -
  -When you execute the Clojure tool, there are a series of steps performed to prepare and execute your command. This section is an overview of those steps, see later sections for how to modify those steps in a variety of ways.
  -
  -== Locate deps.edn sources
  -
  -Configuration is stored in one or more "deps.edn" maps. These are edn maps with the following top-level keys:
  -
  -* `:deps` - map of lib (symbol) to coordinate
  -* `:paths` - vector of paths
  -* `:aliases` - map of alias name to alias data
  -* provider-specific keys for configuring dependency sources
  -
  -The Clojure tools look for 4 potential deps.edn sources:
  -
  -* Root - found in the installation of clj (or as a resource in tools.deps)
  -* User - cross-project configuration (typically tools), usually found at `~/.clojure/deps.edn`
  -* Project - the `deps.edn` in the current directory
  -* Config data - a `deps.edn` map passed on the command line
  -
  -== Check cache
  -
  -The next several steps of this execution can be skipped if we have already computed the classpath and cached it. Classpath and the runtime basis files are cached in the current directory under `.cpcache/`. The key is based on the contents of the deps.edn files and some of the command arguments passed and several files will be cached, most importantly the classpath and runtime basis.
  -
  -If the key is found, and the cached files are newer than all deps.edn sources, they will be used and execution begins immediately.
  -
  -== Replace project environment ("tool")
  -
  -When you execute a tool in the context of your project, the tool uses its own paths and/or deps in place of the project's paths and/or deps.
  -
  -== Merge sources
  -
  -All deps.edn sources are merged into a single master edn file in the order listed above - root, user, project (possibly with tool replacements), config. This merged deps will be included in the runtime basis and used after this point.
  -
  -deps.edn sources is essentially `merge-with merge`, except for the `:paths` key, where only the last `:paths` found is used (they replace, not combine).
  -
  -== Resolve dependencies
  -
  -Starting from the master edn's merged :deps, the full transitive expansion of the dependency tree is computed. Dependency sources (procurers) are used to obtain metadata and other dependency information. At the completion of this step, all libraries to use in the execution have been found and downloaded to local files if needed.
  -
  -== Make classpath
  -
  -JVM execution relies on computing the classpath for the execution. The classpath will consist of the `:paths` in the merged `deps.edn` and the locations of all resolved dependencies.
  -
  -== Prepare JVM environment
  -
  -JVM arguments may either be passed on the command line (with `-J`) or by using data stored in an alias under `:jvm-opts` and passed with `-O` or `-A`
  -
  -== Execute command
  -
  -Finally the command is executed - see the Overview above for the execution options. The already computed (or loaded from cache) classpath, JVM environment, and main arguments if relevant are used in the execution. 
  -
  -= deps.edn
  -
  -The configuration file format (in `deps.edn` files) is an edn map with top-level keys `:deps`, `:paths`, and `:aliases`, plus provider-specific keys for configuring dependency sources.
  -
  -== Paths
  -
  -Paths are declared in a top level key `:paths` and are a vector of string paths or alias names. Relative paths are resolved in relation to the directory containing the deps.edn (the project root). These source paths will be added to the classpath.
  -
  -Example:
  -
  -[source,clojure]
  -----
  -{:paths ["src"]}
  -----
  -
  -If used, alias names should refer to a path vector in the alias data:
  -
  -[source,clojure]
  -----
  -{:paths [:clj-paths :resource-paths]
  - :aliases
  - {:clj-paths ["src/clj" "src/cljc"]
  -  :resource-paths ["resources"]}}
  -----
  -
  -== Dependencies
  -
  -Dependencies are declared in deps.edn with a top level key `:deps` - a map from library to coordinate. Libraries are symbols of the form `<groupID>/<artifactId>`. To indicate a Maven classifier, use `<groupId>/<artifactId>$<classifier>`.
  +== Building classpaths with tools.deps.alpha
  +
  +The JVM classpath consists of a series of roots, either directory paths or the path to a jar file. Classes (and Clojure files) map via package or namespace to a path relative to a classpath root. For example, the `java.lang.String` class can be found at path `java/lang/String.class` and the `clojure.set` Clojure namespace may be found at paths `clojure/set.class` (for AOT), `clojure/set.clj`, or `clojure/set.cljc`. When the JVM needs to load one of these files it searches each root for the relative path and loads it when found.
  +
  +We divide the process of building a classpath into two primary operations: `resolve-deps` and `make-classpath`. Below is a high-level view of this process:
  +
  +
  +image::/images/content/guides/deps/deps.png["Dep Tools", link="/images/content/guides/deps/deps.png"]
  +
  +=== resolve-deps
  +
  +**`(resolve-deps deps args-map)`**
  +
  +`resolve-deps` takes an initial map of required dependencies and a map of args that modify the resolution process. It builds a full graph of transitive dependencies, resolves any version differences, and flattens that graph to a full list of dependencies required in the classpath.
  +
  +The deps are a map of library to coordinate. The library is (in Maven terms) the groupId and artifactId, which are sufficient to locate the desired project. The coordinate is used to describe a particular version that is being requested from a particular provider (like Maven).
  +
  +For example, this deps map specifies a (Maven-based) dependency:
  +
  +[source,clojure]
  +----
  +{org.clojure/core.cache {:mvn/version "0.6.5"}}
  +----
  +
  +`resolve-deps` expands these dependencies to include all transitive dependencies, cut cycles, resolve version differences, download required artifacts from the provider, and produce a *lib map* of the flattened set of all needed dependencies and where to find their artifacts:
  +
  +[source,clojure]
  +----
  +{org.clojure/core.cache        {:mvn/version "0.6.5",
  +                                :deps/manifest :mvn,
  +                                :paths [".../core.cache-0.6.5.jar"]}
  + org.clojure/data.priority-map {:mvn/version "0.0.7",
  +                                :deps/manifest :mvn,
  +                                :dependents [org.clojure/core.cache],
  +                                :paths [".../data.priority-map-0.0.7.jar"]} 
  + ... }
  +----
  +
  +The lib map lists all libraries, their selected coordinates, the `:paths` on disk, and a list of dependents that caused it to be included. Here you can see that `data.priority-map` was included as a dependency of core.cache.
  +
  +The second `args-map` is a map of optional modifications to the standard expansion to account for common use cases: adding extra dependencies, overriding deps, and default deps. These can be used separately or together, or not at all:
  +
  +[source,clojure]
  +----
  +{:extra-deps { ... }
  + :override-deps { ... }
  + :default-deps { ... }}
  +----
  +
  +`:extra-deps` is the most common modification - it allows you to optionally add extra dependencies to the base dependency set. The value is a map of library to coordinate:
  +
  +[source,clojure]
  +----
  +{:extra-deps {criterium/criterium {:mvn/version "0.4.4"}}}
  +----
  +
  +`:override-deps` overrides the coordinate version chosen by the version resolution to force a particular version instead. This also takes a map of library to coordinate:
  +
  +[source,clojure]
  +----
  +{:override-deps {org.clojure/clojure {:mvn/version "1.9.0"}}}
  +----
  +
  +`:default-deps` provides a set of default coordinate versions to use if no coordinate is specified. The default deps can be used across a set of shared projects to act as a dependency management system:
  +
  +[source,clojure]
  +----
  +{:default-deps {org.clojure/core.cache {:mvn/version "0.6.4"}}}
  +----
  +
  +=== make-classpath
  +
  +**`(make-classpath lib-map paths args-map)`**
  +
  +The `make-classpath` step takes the lib map (the result of `resolve-deps`), the internal source paths of the project `["src"]`, an args-map of optional modifications, and produces a classpath string for use in the JVM.
  +
  +The args-map includes support for modifications to be applied while making the classpath: adding extra paths, and overriding the location of libraries specified in the lib map. These modifications can be used separately or together or not at all in a map like this:
  +
  +[source,clojure]
  +----
  +{:extra-paths [ ... ]
  + :classpath-overrides { ... }}
  +----
  +
  +`:extra-paths` is used to include source paths in addition to your standard source paths, for example to include directories of test source:
  +
  +[source,clojure]
  +----
  +{:extra-paths ["test" "resources"]}
  +----
  +
  +`:classpath-overrides` specify a location to pull a dependency that overrides the path found during dependency resolution, for example to replace a dependency with a local debug version. Many of these use cases are ones where you would be tempted to prepend the classpath to "override" something else.
  +
  +[source,clojure]
  +----
  +{:classpath-overrides 
  + {org.clojure/clojure "/my/clojure/target"}}
  +----
  +
  +== Command line tools
  +
  +=== Directories
  +
  +The tools rely on several directories and optionally on several environment variables.
  +
  +* Installation directory
  +** Created during installation
  +** Contents:
  +*** `bin/clojure` - main tool
  +*** `bin/clj` - wrapper for interactive repl use (uses `rlwrap`)
  +*** `deps.edn` - install level deps.edn file, with some default deps (Clojure, etc) and provider config
  +*** `example-deps.edn` - commented example that gets copied to `<config_dir>/deps.edn`
  +*** `libexec/clojure-tools-X.Y.Z.jar` - uberjar invoked by `clojure` to construct classpaths
  +* Config directory
  +** Holds a deps.edn file that persists across tool upgrades and affects all projects
  +** Locations used in this order:
  +*** If `$CLJ_CONFIG` is set, then use `$CLJ_CONFIG` (explicit override)
  +*** If `$XDG_CONFIG_HOME` is set, then use `$XDG_CONFIG_HOME/clojure` (Freedesktop conventions)
  +*** Else use `$HOME/.clojure` (most common)
  +** Contents:
  +*** `deps.edn` - user deps file, defines default Clojure version and provider defaults
  +* Cache directory
  +** Lazily created when `clojure` is invoked without a local `deps.edn` file. Locations used in this order:
  +*** If `$CLJ_CACHE` is set, then use `$CLJ_CACHE` (explicit override)
  +*** If `$XDG_CACHE_HOME` is set, then use `$XDG_CACHE_HOME/clojure` (Freedesktop conventions)
  +*** Else use `config_dir/.cpcache` (most common)
  +* Project directory
  +** The current directory
  +** Contents:
  +*** `deps.edn` - optional project deps
  +*** `.cpcache` - project cache directory, same as the user-level cache directory, created if there is a `deps.edn`
  +
  +=== deps.edn
  +
  +The configuration file format (in "deps.edn" files) is an edn map with top-level keys for `:deps`, `:paths`, and `:aliases`, plus provider-specific keys for configuring dependency sources.
  +
  +After installation, deps.edn configuration files can be found in (up to) three locations:
  +
  +- installation directory - created only at install time
  +- config directory (often ~/.clojure) - modified to change cross-project (or no-project) defaults
  +- the local directory - per-project settings
  +
  +The `deps.edn` files in each of these locations (if they exist) are merged to form one combined dependency configuration. The merge is done in the order above install/config/local, last one wins. The operation is essentially `merge-with merge`, except for the `:paths` key, where only the last one found is used (they are not combined).
  +
  +You can use the  `-Sverbose` option to see all of the actual directory locations.
  +
  +=== Dependencies
  +
  +Dependencies are declared in deps.edn with a top level key `:deps` - a map from library to coordinate. Libraries are symbols of the form <groupID>/<artifactId>. To indicate a classifier, use <groupId>/<artifactId>$<classifier>.
   
   Coordinates can take several forms depending on the coordinate type:
   
   * Maven coordinate: `{:mvn/version "1.2.3"}`
  -** Other optional keys: `:exclusions`
  +** Other optional keys: `:extension`, `:exclusions`
   ** Note: `:classifier` is not supported - add to lib name as specified above
   * Local project coordinate: `{:local/root "/path/to/project"}`
   ** Optional key `:deps/manifest`
   *** Specifies the project manifest type
   *** Default is to auto-detect the project type (currently either `:deps` or `:pom`)
  -* Local jar coordinate: `{:local/root "/path/to/file.jar"}`
  -** If the jar includes a pom.xml file, it will be used to find transitive deps
  +* Local jar: `{:local/root "/path/to/file.jar"}`
  +** If the jar has been packaged with a pom.xml file, the pom will be read and used to find transitive deps
   * Git coordinate: `{:git/url "https://github.com/user/project.git", :sha "sha", :tag "tag"}`
   ** Required key `:git/url` can be one of the following:
   *** https - secure anonymous access to public repos
  
positive.code:   "clojars" {:url "https://clojars.org/repo"}}}
  ----
  
  === Modifying the default repositories
  
  The `:mvn/repos` map is `merge-with` `merge` across the deps.edn sources, so you can modify the default repositories by specifying a new definition or remove it by specifying `nil`.
  
  tools.deps guarantees that the `"central"` and `"clojars"` repositories will be checked first for Maven libraries.
  
  === Maven authenticated repos
  
  For Maven deps in authenticated repositories, existing Maven infrastructure is used to convey credentials.
  
  
negative.code: 
  Refer to the Maven https://maven.apache.org/guides/mini/guide-proxies.html[Guide to using proxies] for further details.
  
  ==== Maven HTTP headers
  
  For adding custom headers to outgoing HTTP requests, existing Maven configuration in `~/.m2/settings.xml` is used.
  
  