anchor.diff:  *** Else use `$HOME/.clojure`
   ** Contents:
   *** `deps.edn` - user deps file, defines default Clojure version and provider defaults
  -* cache directory
  +* Cache directory
   ** Lazily created if `clojure` is invoked without a local `deps.edn` file. Locations checked 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` (follows Freedesktop conventions)
   *** Else use `config_dir/.cpcache`
  +* Project directory
  +** The current directory
   ** Contents:
  -*** See the section below on classpath caching
  -
  -== Classpath caching
  -
  -Classpath files are cached in the current directory under `.cpcache/`. File are of two forms:
  -
  -* `.cpcache/<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`
  -* `.cpcache/<hash>.cp` - a classpath string, the output of `make-classpath`
  -
  -where the `<hash>` is based on the config file paths, the resolve-aliases, and the classpath aliases.
  -
  -The cached classpath file is used when:
  -
  -* It exists
  -* It is newer than all `deps.edn` files
  +*** `deps.edn` - optional project deps
  +*** `.cpcache` - project cache directory, same as the user-level cache directory, created if there is a `deps.edn`
   
   == Examples
   
   === Running a REPL from anywhere
   
  -* Invoke: `clj`
  -* Given: No deps.edn file in the current directory.
  -* Result: Start a repl using the default deps file at <install>/deps.edn.
  -
  -=== Running a REPL using deps.edn in the current directory
  -
  -* Invoke: `clj`
  -* Given: A deps.edn file in the current directory.
  -* Result: Start a repl using the deps.edn file at ./deps.edn.
  -
  -=== Including a test source directory into a classpath
  -
  -* Invoke: `clj -C:test`
  -* Given: A deps.edn file like the one below.
  -* Result: Start a repl including external deps and a test source directory root.
  -
  -[source,clojure]
  -----
  -;; deps.edn
  -{:deps {org.clojure/clojure {:mvn/version "1.9.0-beta2"}}
  +To start a repl, you can invoke the `clj` script from anywhere as long as your installation has put the script in your path. Presuming there is no `deps.edn` in the current directory, the `deps.edn` files in the install directory (which includes a default depenendency on Clojure) and the config directory (which starts empty) are used to build the classpath.
  +
  +The classpath will be cached in the user-level cache directory (location as described in the Installation files and directories above), so after the first invocation this should be pretty fast.
  +
  +=== Running a REPL and specifying libs from Maven
  +
  +When you want to specify libraries, you'll need to create a `deps.edn` file in the current directory, for example:
  +
  +[source,clojure]
  +----
  +;; deps.edn
  +{:deps {
  +   org.clojure/clojure {:mvn/version "1.9.0"}
  +   org.clojure/core.async {:mvn/version "0.3.465"}
  + }
  +}
  +----
  +
  +Invoking `clj` will then use the install, config, and local `deps.edn` files, merge them together, build the classpath, download the dependencies if needed, and start the REPL using a classpath for those dependencies. The classpath will be cached under `./cpcache` so subsequent invocations will be faster.
  +
  +=== Including a test source directory into your classpath
  +
  +The primary project classpath will not include the test source directory, but you can add extra paths as modifications to the make-classpath step of the classpath construction. To do so, add an alias `:test` that includes the extra relative source path `"test"`:
  +
  +[source,clojure]
  +----
  +;; deps.edn
  +{:deps {
  +   org.clojure/clojure {:mvn/version "1.9.0"}
  + }
    :aliases {
      :test {:extra-paths ["test"]}
    }
   }
   ----
   
  -=== Refer to a specific jar on disk
  -
  -* Invoke `clj`
  -* Given: A deps.edn file like the one below.
  -* Result: Includes a specific jar file in your classpath
  -
  -[source,clojure]
  -----
  -;; deps.edn
  -{:deps {org.clojure/clojure {:mvn/version "1.9.0-beta2"}
  -        oracle/driver {:local/root "/path/to/oracle/driver.jar"}}}
  -----
  -
  -=== Refer to another project on disk that has a deps.edn file
  -
  -* Invoke `clj`
  -* Given: A deps.edn file like the one below
  -* Result: Includes another project defined on disk, using /path/to/project/deps.edn will be used as the source of paths and deps for the dependency project. Support for other project types (pom.xml, project.clj) will be possible, but is not yet implemented.
  -
  -[source,clojure]
  -----
  -;; deps.edn
  -{:deps {org.clojure/clojure {:mvn/version "1.9.0-beta2"}
  -        my.company/sibling-project {:local/root "/path/to/project"}}}
  -----
  +Apply that classpath modification and start a REPL by invoking `clj -C:test`.
  +
  +=== Refer to a specific local jar on disk
  +
  +Occasionally you may need to refer directly to a jar on disk that is not present in a Maven repository. One common example is a database driver jar that is not distributed via Maven.
  +
  +Local jar dependencies can be specified by using a local coordinate with the key `:local/root`. The local artifact provider will detect that this refers to a specific file.
  +
  +[source,clojure]
  +----
  +;; deps.edn
  +{:deps {
  +   org.clojure/clojure {:mvn/version "1.9.0-beta2"}
  +   oracle/driver {:local/root "/path/to/oracle/driver.jar"}
  + }
  +}
  +----
  +
  +=== Refer to a local project on disk with a deps.edn file
  +
  +You can also refer to local projects that have not been published to any Maven repository or built into a jar. This can be used to create a network of projects that are still in development. 
  +
  +In this case you refer to the local root directory rather than a particular file. The local artifact provider will automatically detect the manifest file (deps.edn) in that directory and use it to determine the project's dependencies, which may either be local or Maven-based:
  +
  +[source,clojure]
  +----
  +;; deps.edn
  +{:deps {
  +   org.clojure/clojure {:mvn/version "1.9.0-beta2"}
  +   my.company/sibling-project {:local/root "/path/to/project"}
  + }
  +}
  +----
  +
  +Support for other manifest file types (pom.xml, project.clj, etc) are future possible extensions.
   
   === Running a Clojure namespace in the current directory
   
  -* Invoke: `clojure -m my.app 1 2 3`
  -* Result: Load the my.app namespace and invoke my.app/-main with the arguments `1 2 3`. If a deps.edn file exists, use it, otherwise use the default deps file.
  +When you invoke `clojure` or `clj`, the classpath is built and `clojure.main` is invoked. `clojure.main` has support for loading a namespace and invoking it's `-main` function with arguments:
  +
  +`clojure -m my.app 1 2 3`
   
   === Add an optional dependency to your classpath
   
  -* Invoke: `clj -R:bench`
  -* Given: A deps.edn file like the one below.
  -* Result: Start a repl using the deps and add the extra deps defined by the `:bench` alias.
  -
  -[source,clojure]
  -----
  -;; deps.edn
  -{:deps {org.clojure/clojure {:mvn/version "1.8.0"}}
  - :aliases {:bench {:extra-deps {criterium {:mvn/version "0.4.4"}}}}}
  -----
  +Aliases in the `deps.edn` file can also be used to add optional dependencies that affect the classpath:
  +
  +[source,clojure]
  +----
  +;; deps.edn
  +{:deps {
  +   org.clojure/clojure {:mvn/version "1.8.0"}
  + }
  + :aliases {
  +   :bench {:extra-deps {criterium {:mvn/version "0.4.4"}}}
  + }
  +}
  +----
  +
  +Here the `:bench` alias is used to add an extra dependency, namely the criterium benchmarking library.
  +
  +You can add this dependency to your classpath by adding the `:bench` alias to modify the dependency resolution: `clj -R:bench`.
   
   === Add an optional dependency and override a dependency
   
  -* Invoke: `clj -R:bench:1.9`
  -* Given: A deps.edn file like the one below.
  -* Result: Start a repl using the deps and add the extra deps defined by the `:bench` alias and the override deps defined by the `:1.9` alias.
  -
  -[source,clojure]
  -----
  -;; deps.edn
  -{:deps {org.clojure/clojure {:mvn/version "1.8.0"}}
  - :aliases {:1.9 {:override-deps {org.clojure/clojure {:mvn/version "1.9.0-beta2"}}}
  -           :bench {:extra-deps {criterium {:mvn/version "0.4.4"}}}}}
  -----
  +You can use multiple aliases in combination. For example this `deps.edn` file defines two aliases - `:1.9` to force the use of a particular Clojure version and `:bench` to add an extra dependency:
  +
  +[source,clojure]
  +----
  +;; deps.edn
  +{:deps {
  +   org.clojure/clojure {:mvn/version "1.8.0"}
  + }
  + :aliases {
  +   :1.9 {:override-deps {org.clojure/clojure {:mvn/version "1.9.0"}}}
  +   :bench {:extra-deps {criterium {:mvn/version "0.4.4"}}}
  + }
  +}
  +----
  +
  +Activate both aliases as follows: `clj -R:bench:1.9`
   
   === Override a classpath source
   
  -* Invoke: `clj -R1.9 -Cdev`
  -* Given: A deps.edn file like the one below.
  -* Result: Start a repl using the deps, the override deps defined by the `:1.9` alias, and the classpath override for the dev path.
  -
  -[source,clojure]
  -----
  -;; deps.edn
  -{:deps {org.clojure/clojure {:mvn/version "1.8.0"}}
  - :aliases {:1.9 {:override-deps {org.clojure/clojure {:mvn/version "1.9.0-beta2"}}}
  -           :dev {:classpath-overrides {org.clojure/clojure "/Users/me/code/clojure/target/classes"}}}}
  -----
  +After dependency resolution, the classpath is constructed. You can modify this step to choose a different source for an artifact by using `:classpath-overrides`:
  +
  +[source,clojure]
  +----
  +;; deps.edn
  +{:deps {
  +   org.clojure/clojure {:mvn/version "1.8.0"}
  + }
  + :aliases {
  +   :1.9 {:override-deps {org.clojure/clojure {:mvn/version "1.9.0"}}}
  +   :dev {:classpath-overrides {org.clojure/clojure "/Users/me/code/clojure/target/classes"}}
  + }
  +}
  +----
  +
  +The `:1.9` alias is a dependency resolution modification and the `:dev` alias is a classpath modification. Use them both together with: `clj -R:1.9 -C:dev`
   
   === Show classpath
   
  -* Invoke `clj -Spath`
  -* Given: A deps.edn like the one below.
  -* Result: Computes the classpath and prints it to stdout
  -
  -[source,clojure]
  -----
  -;; deps.edn
  -{:deps {:org.clojure/clojure {:mvn/version "1.8.0"}}}
  -----
  -
  -Note that `-S` can be combined with other `clj` options as well.
  +In most of the previous examples we were starting a REPL or running a Clojure program. You can also use `-Spath` to just print the computed classpath and exit:
  +
  +`clj -Spath`
  +
  +Note that `-S` can be used in combination with other `clj` options as well.
   
   == Connecting to S3 Maven repositories
   
  
positive.code: *** `deps.edn` - install level deps.edn file, with some default deps (Clojure, etc)
  *** `example-deps.edn` - commented example that gets copied to `<config_dir>/deps.edn`
  *** `libexec/clojure-scripts-X.Y.Z.jar` - uberjar invoked by `clojure` to construct classpaths
  * config directory
  ** Can be created to hold a deps.edn file that carries across installation upgrades and takes affect across projects
  ** Locations checked in this order:
  *** If `$CLJ_CONFIG` is set, then use `$CLJ_CONFIG` (explicit override)
  
negative.code: 
  toc::[]
  
  Clojure 1.9 introduces a new command-line script (`clojure`) and a wrapper script (`clj`) designed for use at the terminal. These scripts use configuration files to construct (and cache) a classpath and then invoke <<repl_and_main#,clojure.main>> which can be used as a REPL, expression evaluator, or program runner. For more background on how classpaths are built, see the <<xref/../../guides/deps_and_cli#,Deps and CLI guide>>.
  
  == Installation
  
  === Installation on Mac via `brew`
  