anchor.diff:  user=>
   ----
   
  -=== Executing a function that takes a map
  +== Executing a function that takes a map
   
   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:
   
  
positive.code: * 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
  * 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.
  
  
negative.code:  }}
  ----
  
  == Aliases
  
  Aliases give a name to a data structure that can be used either by the Clojure tool itself or other consumers of deps.edn. They are defined in the `:aliases` section of the config file. These Clojure tool subprocesses use data which can be read from aliases:
  
  = Basis and classpath
  
  The core of the tools.deps library is a process to take a merged deps.edn file, arg maps for the resolve-deps and make-classpath steps, and produce the "runtime basis", or "basis" for short. The basis is a superset of the deps.edn file also containing those args, the lib map, and the classpath map.
  
  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`.
  
  == 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 libraries to be included on the classpath.
  
  The deps from the merged deps.edn is 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 or git).
  
  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"}}
  ----
  
  = Clojure tools usage
  
  == deps.edn sources
  
  The Clojure tools will use the following deps.edn map sources, in this order:
  
  * Root - found in the installation of clj (or as a resource in tools.deps)
  * User - cross-project configuration (typically tools)
  ** 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)
  * Project - the `deps.edn` in the current directory
  * Config data - a `deps.edn` map passed on the command line
  
  The deps.edn sources can be modified or inspected by the following options:
  
  * `-Sverbose` - print all source locations
  * `-Sdeps` - pass the config data on the command line
  * `-Srepro` - omit the user deps source (other sources will be used if found)
  
  == Classpath caching
  
  The cached classpath file is used for execution when:
  
  * It exists and
  * It is newer than all `deps.edn` sources
  
  Classpath and basis files are cached in a directory computed as follows:
  
  * If there is a project deps.edn
  ** Use `./.cpcache`
  * Else (no project deps.edn)
  ** 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` (see deps.edn sources for config_dir logic, usually `~/.clojure`)
  
  A hash is computed based on the config file paths, the resolve-aliases, and the classpath aliases.
  
  Files cached (if needed):
  
  * `<hash>.libs` - a `::lib-map` in the https://github.com/clojure/tools.deps.alpha/blob/master/src/main/clojure/clojure/tools/deps/alpha/specs.clj[specs], the output of running `resolve-deps`
  * `<hash>.cp` - a classpath string, the output of `make-classpath`
  * `<hash>.jvm` - jvm options for main execution
  * `<hash>.main` - main options for main execution
  * `<hash>.basis` - the runtime basis, for injection
  
  Caching can be modified by the following options:
  
  * `-Sforce` - ignore cache and force recomputation
  * `-Scp CP` - don't use cache or compute, use the provided classpath instead
  
  == Replace project environment (tool)
  
  The `tool` process is used when executing a tool that should not use the project classpath environment. This process takes the project deps.edn and the following modifier args and replaces them (if provided) before the project deps is merged:
  
  * `:deps` - a deps map from lib to coordinate of deps to REPLACE the project `:deps`
  * `:paths` a collection of string paths to REPLACE project `:paths`
  
  This tool map should be provided as an alias in one of the deps sources and provided to the Clojure tools using either `-T:an-alias` or `-A:an-alias`. Multiple aliases can be provided by concatentating the alias names.
  
  == Merging deps.edn
  
  The `deps.edn` files found from the source locations (with Clojure tool modifications by any options) are merged to form one master deps map. The merge is done in the order above root/user/project/config, 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).
  
  == Resolve deps modifiers
  
  The resolve-deps modifiers are provided in a map that was described in a prior section:
  
  * `resolve-deps` args
  ** `:extra-deps` - a deps map from lib to coordinate of deps to add to the deps
  ** `:override-deps` - a deps map from lib to coordinate of override versions to use
  ** `:default-deps` - a deps map from lib to coordinate of versions to use if none is found
  ** If multiple alias maps with these keys are activated, all of them are merge-with merged
  
  The resolve-deps args should be provided as an alias in one of deps sources and provided to the Clojure tools using either `-R:an-alias` or `-A:an-alias`. Multiple aliases can be provided by concatentating the alias names.
  
  == Make classpath modifiers
  
  The make-classpath modifiers are provided in a map that was described in a prior section:
  
  * `make-classpath` args
  ** `:extra-paths` - a collection of string paths to add to `:paths`
  ** `:classpath-overrides` - a map of lib to string path to replace the location of the lib
  ** If multiple maps with these keys are activated, `:extra-paths` concatenate and `:classpath-overrides` merge-with merge
  
  The resolve-deps args should be provided as an alias in one of deps sources and provided to the Clojure tools using either `-C:an-alias` or `-A:an-alias`. Multiple aliases can be provided by concatentating the alias names.
  
  == Prepare JVM environment
  
  The JVM has many options and some programs also take configuration via Java system properties. JVM options can be passed on the command line for any execution specfier by prefixing with `-J`. If multiple options are specified, each must be prefixed.
  
  Additionally, main execution can take a map with key `:jvm-opts`:
  
  * JVM options
  ** `:jvm-opts` - a collection of string JVM options
  ** If multiple maps with these keys are activated, `:jvm-opts` concatenate
  ** If -J JVM options are also specified on the command line, they are concatenated after the alias options
  
  This map is stored in alias data and provided to the Clojure tools using either `-O:an-alias` or `-A:an-alias`.  Multiple aliases can be provided by concatentating the alias names.
  
  == Execution
  
  Execution options were mostly covered in the earlier Overview section.
  
  === Main execution
  
  One additional option for main execution is a map with key `:main-opts`:
  
  * Main arguments
  ** `:main-opts` - a collection of clojure.main options
  ** If multiple maps with these keys are activated, only the last one will be used
  ** If command line clojure.main arguments are supplied on the command line, they are concatenated after the last main alias map
  
  This map is stored in alias data and provided to the Clojure tools using either `-M:an-alias` or `-A:an-alias`. Multiple aliases can be provided by concatentating the alias names.
  
  == Other options
  
  Other options that can be provided to `clj` (all of these effectively short circuit normal execution):
  
  * `-Sdescribe` - print environment and command parsing info as data
  * `-Stree` - print dependency tree
  * `-Spath` - compute classpath and echo to stdout only
  * `-Spom` - generate (or update an existing) pom.xml with deps and paths
  * `-Sresolve-tags` - resolve git coordinate tags to shas and update deps.edn
  
  = Procurers
  
  Coordinates are interpreted by procurers, which know how to determine dependencies for a library and download artifacts. tools.deps.alpha is designed to support an extensible set of procurers that can expand over time. Currently the available procurers are: `mvn`,  `local`, and `git`.
  
  The procurer to use is determined by examining the attributes of the coordinate and using the first attribute qualifier that's found (ignoring the reserved qualifier "deps"). For example, a Maven coordinate contains a `:mvn/version` attribute and a local coordinate contains a `:local/root` attribute.
  
  Procurers may also have configuration attributes stored at the root of the configuration map under the same qualifier. 
  
  == Maven
  
  The `mvn` procurer will look for `:mvn/repos`. The installation deps.edn configures the default Maven repos:
  
  [source,clojure]
  ----
  