clojure-cli: content enhancements

practicalli-johnny · practicalli-johnny · commit 53b5a396e87f · 2024-03-03T12:08:27.000Z
diff --git a/docs/clojure-cli/built-in-commands.md b/docs/clojure-cli/built-in-commands.md
@@ -1,8 +1,13 @@
 # Clojure CLI Built-in commands
 
-`clojure` without any other arguments will run a REPL with a basic terminal prompt.  `clj` is a wrapper script for the `clojure` command (`rlwrap` required) to add command history to the basic REPL prompt.
+`clojure` without any other arguments will run a REPL with a basic terminal prompt.  
+
+`clj` is a wrapper script for the `clojure` command (`rlwrap` required) to add command history to the basic REPL prompt.
+
+`clojure -T:deps` to run one of several built-in commands to help work with Clojure CLI projects and libraries.
+
+`clojure --help` list the available commands.
 
-`clojure -T:deps` to run one of several built-in commands to help work with Clojure CLI projects and libraries.  `clojure --help` list the available commands.
 
 `-X` execution option is used for the  `:deps` aliases, running them via `clojure.exec` and limiting the class path to the current directory.
 
@@ -40,9 +45,10 @@ The list includes transitive dependencies, library dependencies of the project l
 
 The `:aliases '[:alias/name(s)]'` argument will also list library dependencies from a given alias, either project alias or user alias. 
 
-```shell
-clojure -X:deps list
-```
+!!! NOTE ""
+    ```shell
+    clojure -X:deps list
+    ```
 
 ??? EXAMPLE "Dependency list from Practicalli Service project template"
     ```shell
@@ -56,7 +62,7 @@ clojure -X:deps list
     com.brunobonacci/mulog 0.9.0  (Apache-2.0)
     com.brunobonacci/mulog-adv-console 0.9.0  (Apache-2.0)
     com.brunobonacci/mulog-json 0.9.0  (Apache-2.0)
-    com.cnuernber/charred 1.010 
+    com.cnuernber/charred 1.010
     com.cognitect/transit-clj 1.0.324  (Apache-2.0)
     com.cognitect/transit-java 1.0.343  (Apache-2.0)
     com.fasterxml.jackson.core/jackson-annotations 2.12.1  (Apache-2.0)
@@ -125,9 +131,10 @@ clojure -X:deps list
 
 Use the `:aliases '[:alias/name(s)]'` option to also include the dependencies from a project or user alias.  Showing the dependencies from an aliase can useful to identify conflicting dependencies when using an alias (unlikely but it could happen).
 
-```shell
-clojure -X:deps list :aliases '[:dev/reloaded]'
-```
+!!! NOTE ""
+    ```shell
+    clojure -X:deps list :aliases '[:dev/reloaded]'
+    ```
 
 ??? EXAMPLE "Dependency list from project and Practicalli :dev/reloaded alias"
     ```shell
@@ -222,9 +229,10 @@ The tree includes transitive dependencies, library dependencies of the project l
 
 The `:aliases '[:alias/name(s)]'` argument will also list library dependencies from a given alias, either project alias or user alias. 
 
-```shell
-clojure -X:deps tree
-```
+!!! NOTE ""
+    ```shell
+    clojure -X:deps tree
+    ```
 
 ??? EXAMPLE "Dependency list from Practicalli Service project template"
     ```shell
@@ -348,9 +356,10 @@ clojure -X:deps tree
 
 Use the `:aliases` option with the Clojure CLI in the root of a project to show library dependencies for the project and the `:dev/reloaded` alias which could be useful if there are library conflicts when using an alias (unlikely but it could happen).
 
-```shell
-clojure -X:deps tree :aliases '[:dev/reloaded]'
-```
+!!! NOTE ""
+    ```shell
+    clojure -X:deps tree :aliases '[:dev/reloaded]'
+    ```
 
 The `:aliases` option can be used to inspect the dependencies of a user alias, listing only dependencies from the specified aliases when run outside of a Clojure project.
 
@@ -393,18 +402,20 @@ The `:aliases` option can be used to inspect the dependencies of a user alias, l
 
 Add a jar file for a library to the local Maven repository, e.g. `~/.m2/repository`, making that library accessible to all other local projects.
 
-```shell
-clojure -X:deps mvn-install :jar '"/path/to.jar"'`
-```
+!!! NOTE ""
+    ```shell
+    clojure -X:deps mvn-install :jar '"/path/to.jar"'`
+    ```
 
 
 ## Find Library Versions
 
 Find the available versions of a given library in the form domain/library-name (domain is typically the company name or Git Service user or organisation name).
 
-```clojure
-clojure -X:deps find-versions :lib clojure.java-time/clojure.java-time
-```
+!!! NOTE ""
+    ```clojure
+    clojure -X:deps find-versions :lib clojure.java-time/clojure.java-time
+    ```
 
 
 ## Prepare Source dependencies
@@ -413,36 +424,40 @@ Some dependencies will require a preparation step before they can be used on the
 
 Projects that require preparation would have a configuration of the form:
 
-```clojure
-{:paths ["src" "target/classes"]
- :deps/prep-lib {:alias :build
-                 :fn compile
-                 :ensure "target/classes"}}
-```
+!!! EXAMPLE
+    ```clojure
+    {:paths ["src" "target/classes"]
+     :deps/prep-lib {:alias :build
+                     :fn compile
+                     :ensure "target/classes"}}
+    ```
 
 Including the top-level key `:deps/prep-lib` tells the tools.deps classpath construction that something extra is needed to prepare this lib and that can be performed by invoking the compile function in the :build alias. Once the prepare step has been done, it should create the path "target/classes" and that can be checked for completion.
 
 Add a library dependency as with any other library (git or local/root):
 
-```clojure
-{:deps {practicalli/library-name {:local/root "../needs-prep"}
-        practicalli/library-name {:git/sha "../needs-prep"}}}
-```
+!!! EXAMPLE
+    ```clojure
+    {:deps {practicalli/library-name {:local/root "../needs-prep"}
+            practicalli/library-name {:git/sha "../needs-prep"}}}
+    ```
 
 
 `:deps prep` will built the library of any dependency that requires it
 
-```shell
-clojure -X:deps prep
-```
+!!! NOTE ""
+    ```shell
+    clojure -X:deps prep
+    ```
 
 ## POM file
 
 Generate or update pom.xml with deps and paths
 
-```shell
-clojure -X:deps mvn-pom
-```
+!!! NOTE ""
+    ```shell
+    clojure -X:deps mvn-pom
+    ```
 
 
 ## Resolve Git tags
@@ -451,9 +466,10 @@ clojure -X:deps mvn-pom
 
 `-X:deps git-resolve-tags` updates git based dependencies in the project `deps.edn` file which use :git/tags key to the equivalent SHA commit values in the `:git/sha` key
 
-```shell
-clojure -X:deps git-resolve-tags
-```
+!!! NOTE ""
+    ```shell
+    clojure -X:deps git-resolve-tags
+    ```
 
 
 ## References
diff --git a/docs/clojure-cli/defining-aliases.md b/docs/clojure-cli/defining-aliases.md
@@ -26,19 +26,22 @@ Aliases can be used to :
 * `:mvn/local-repo` to [specify an alternative location for the Maven cache](https://github.com/practicalli/clojure-deps-edn#maven-local-repository)
 * `:aliases` - a map of optional libraries and tools, the key being the alias name and its value the configuration
 
-
 The installation of Clojure CLI contains a configuration
 
 * adds `src` and `org.clojure/clojure` library
 * Maven Central & Clojars.org repository sources.
 
-Configuration can be defined in a `deps.edn` file in the root of a Clojure project, applying only to that specific project.
-
-A user `deps.edn` configuration can be used in any Clojure project and the `deps.edn` configuration file resides in either `$XDG_CONFIG_HOME/clojure` or `$HOME/.clojure`.
+Configuration available to all projects (or stand-alone tools) is defined in a user `deps.edn` configuration in either `$XDG_CONFIG_HOME/clojure` or `$HOME/.clojure`.
 
+Project specific configuration is defined in a `deps.edn` file in the root of the Clojure project.
 
 ??? INFO "User configuration locations"
-    User configuration is either `$XDG_CONFIG_HOME/clojure/deps.edn` or `$HOME/.clojure/deps.edn` locations and its aliases can be used for any Clojure project.
+    If `XDG_CONFIG_HOME` environment variable is set, then the user configuration is `$XDG_CONFIG_HOME/clojure/deps.edn`
+
+    Otherwide the user configuration is `$HOME/.clojure/deps.edn`.
+
+    The `CLJ_CONFIG` environment variable will be used if set.
+
 
 
 ## Alias keys
@@ -118,7 +121,7 @@ Arguments can be nested within the `:exec-args` map, especially useful on projec
 
 To run with the default arguments:
 
-```
+```shell
 clojure -X:project/run
 ```
 
@@ -211,19 +214,27 @@ Additional arguments can be sent when running the command, e.g. `clojure -X:proj
 
 The command line can over-ride the `:exec-fn` function configuration, allowing for a default configuration that can be easily over-ridden.
 
-```clojure
-  :project/new
-  {:replace-deps {seancorfield/clj-new {:mvn/version "1.1.226"}}
-   :main-opts    ["-m" "clj-new.create"]    ;; deprecated
-   :ns-default   clj-new
-   :exec-fn      create
-   :exec-args    {:template lib :name practicalli/playground}
-   }
-```
+!!! EXAMPLE
+    ```clojure
+      :project/new
+      {:replace-deps {seancorfield/clj-new {:mvn/version "1.1.226"}}
+       :main-opts    ["-m" "clj-new.create"]    ;; deprecated
+       :ns-default   clj-new
+       :exec-fn      create
+       :exec-args    {:template lib :name practicalli/playground}
+       }
+    ```
 
 !!! HINT "Keyword naming"
-    Legal Clojure keyword names can be used for an alias.  Multiple aliases can be chained together with the `clojure` command.  For example in this command we are combining three aliases:
-    `clojure -M:task/path:task/deps:build/options`
+    Alias names are a Clojure keyword, which can be qualified to provide context, e.g. `:project/create`.  
+
+    Aliases are composable (chained together) and their path and deps configurations merged:
+
+    ```shell
+    clojure -M:task/path:task/deps:build/options
+    ```
+    
+    When multiple aliases contain a `:main-opts` configurations they are not merged, the configuration in the last alias is used
 
 
 ## Resources
diff --git a/docs/clojure-cli/execution-options.md b/docs/clojure-cli/execution-options.md
@@ -2,63 +2,48 @@
 
 Execution options (`-A` `-M` `-P` `-T` `-X`) define how aliases are used with the Clojure CLI. Aliases are included via one of these execution options and each option can affect how the alias is used.
 
-Since the [first documented released](https://clojure.org/releases/tools#v1.10.1.510) which exclusively used the `-A` execution option to include aliases, the design has evolved to provide specific execution options to run code via clojure.main (`-M`) and clojure.exec (`-X`). In July 2021, the ability to run tools (`-T`) independent from the Clojure project classpath was also introduced.
+??? INFO "Clojure CLI design evolution"
+    The [first documented released](https://clojure.org/releases/tools#v1.10.1.510) used the `-A` execution option to include aliases. 
 
-The exec-opts command line flags have evolved to enable these features, so lets explore those flags and show how each flag is typically used.
+    The design has evolved to provide specific execution options to run code via clojure.main (`-M`) and clojure.exec (`-X`). 
 
-??? INFO "Understanding Aliases"
-    [Understand aliases in more detail](https://practical.li/blog/posts/clojure-cli-tools-understanding-aliases/)
+    In July 2021 the ability to run tools (`-T`) independent from the Clojure project classpath was introduced.
 
 
 ## Quick summary
 
-Use `-M` for code that should be called via the `-main` function in a specified namespace, passing string-based arguments.
+`-M` uses `clojure.main` to call the `-main` function of the specified namespace, passing string-based arguments.
 
-Use `-X` to run a specified function, passing arguments as key and value pairs (not hash-maps yet)
+`-X` uses `clojure.exec` to call a fully qualified function, passing arguments as key and value pairs
 
-Use `-T` to run a tool independently from any libraries defined in a project.  Only the libraries in the alias are included in the ClassPath.  The path is defined as `"."` by default.
+`-T` runs a tool independent from project dependencies.  Only the libraries in the alias are included in the Class Path.  The path is defined as `"."` by default.
 
-Use `-P` to download libraries on the class path, including those from specified aliases
+`-P` downloads library dependencies, including those from specified aliases
 
-Use `-A` in the specific case of running a basic terminal UI REPL with the `clojure` command (or `clj` wrapper).
+`-A` in the specific case of running a basic terminal UI REPL with the `clojure` command or `clj` wrapper.
 
-Common aliases will be used to explain the use of these execution options in more detail.
 
+## clojure.main
 
-## Form of clojure.exec command line arguments
+`-M` flag instructs Clojure CLI tools to use `clojure.main` to run Clojure code.
 
-Clojure.exec command takes Key/value pairs read as EDN values (extensible data notation that is the base syntax of Clojure).
-
-Number values and keywords can be parsed from the command line
-
-Arguments that are vectors and hash maps should be wrapped in single quotes to avoid the command line shell splitting arguments at spaces, e.g. `'[:a :b]'`, `'{:c 1}'`.
-
-The double quotes in an EDN string must be wrapped by single quotes, along with vectors and hash-maps
-
-- `'"strings in double quotes surround by single quotes"'`
-- `'[:vectors :with-single-quotes]'`
-- `'{:hash-maps :with-single-quotes}'`
+The `--main` or `-m` flag is an argument to `clojure.main` which specifies the namespace to search for a `-main` function.
 
+`clojure.main/main` function searches for a `-main` function in the given namespace, e.g. `--main pracicalli.gameboard.service`
 
-## Run clojure.main project
-
-`-M` execution option uses `clojure.main` to run Clojure code.
+> If the -main function is not found or the namespace is not specified, then the `clojure` command will run a REPL session.
 
 Run a project with the main namespace `practicalli.sudoku-solver`, without any additional aliases on the command line
 
-```shell
-clojure -M -m practicalli.sudoku-solver
-```
-
-`-M` flag instructs Clojure CLI tools to use `clojure.main` to run the Clojure code.
-
-`-m` flag is an argument to `clojure.main` which specifies the namespace to search for a `-main` function.
-
+!!! NOTE ""
+    ```shell
+    clojure -M -m practicalli.sudoku-solver
+    ```
 
-Adding a `:project/run` alias to the project `deps.edn` file provides a simpler way to run the project on the command line
+Add `:project/run` alias to the project `deps.edn` file to provide a simpler way to run the project on the command line
 
 ```clojure
-:project/run {:main-opts ["-m" "practicalli.sudoku-solver"]}
+:project/run {:main-opts ["--main" "practicalli.sudoku-solver"]}
 ```
 
 Now the project code can be run using the simple command line form
@@ -68,13 +53,10 @@ clojure -M:project/run
 ```
 
 
-### How clojure.main works
+### Using clojure.main
 
-`clojure.main/main` function searches for a `-main` function in the given namespace (`-m fully-qualified.namespace`)
 
-If no -main function is found or the namespace is not specified, then a REPL session is run.  This is the approach Leiningen has always used and still uses today.
-
-> [`clojure.main` namespace](https://clojure.org/reference/repl_and_main) has been the way Clojure code was run (including a REPL) for most of its history.  This is now evolving with the addition of [clojure.exec](#clojure-exec--X).
+> [`clojure.main` namespace](https://clojure.org/reference/repl_and_main) has been the way Clojure code was run (including a REPL) for most of its history.  This is now evolving with the addition of [clojure.exec](#clojureexec).
 > [clojure.main has other features, as covered in the REPL and main entrypoints article](https://clojure.org/reference/repl_and_main)) on clojure.org.
 
 
@@ -137,6 +119,23 @@ If the command line includes the `-m` flag with a namespace, then that namespace
 
 Any function on the class path can be called and is passed a hash-map as an argument.  The argument hash-map is either specified in an alias using `:exec-args` or assembled into a hash-map from key/value pairs on the command line.  Key/values from the command line are merged into the `:exec-args` map if it exists, with the command line key/values taking precedence.
 
+### clojure.exec arguments
+
+Clojure.exec command takes key value pairs read as EDN values (extensible data notation that is the base syntax of Clojure).
+
+Number values and keywords can be parsed from the command line
+
+Arguments that are vectors and hash maps should be wrapped in single quotes to avoid the command line shell splitting arguments at spaces, e.g. `'[:a :b]'`, `'{:c 1}'`.
+
+The double quotes in an EDN string must be wrapped by single quotes, along with vectors and hash-maps
+
+- `'"strings in double quotes surround by single quotes"'`
+- `'[:vectors :with-single-quotes]'`
+- `'{:hash-maps :with-single-quotes}'`
+
+
+### clojure.exec examples
+
 Call the `status` function from the namespace `practicalli.service`, which is on the classpath in the practicalli.service project
 
 ```shell
