practicalli / clojure-cli-config

User aliases and Clojure CLI configuration for deps.edn based projects

Practicalli Clojure CLI Config

██████╗ ██████╗  █████╗  ██████╗████████╗██╗ ██████╗ █████╗ ██╗     ██╗     ██╗
██╔══██╗██╔══██╗██╔══██╗██╔════╝╚══██╔══╝██║██╔════╝██╔══██╗██║     ██║     ██║
██████╔╝██████╔╝███████║██║        ██║   ██║██║     ███████║██║     ██║     ██║
██╔═══╝ ██╔══██╗██╔══██║██║        ██║   ██║██║     ██╔══██║██║     ██║     ██║
██║     ██║  ██║██║  ██║╚██████╗   ██║   ██║╚██████╗██║  ██║███████╗███████╗██║
╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝   ╚═╝   ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚══════╝╚═╝

Practicalli Clojure CLI Config contains a deps.edn alias definitions for a wide range of community libraries and tools to that extend the features of Clojure CLI.

Aliases are qualified keywords using descriptive names to clearly convey purpose and provide a level of consistency to minimise cognitive load.

Common arguments are included in alias definitions via main-opts and :exec-args to provide a default behaviour and simplify the use aliases.

Alias used with the -A, -M, -T or -X execution options

Aliases are defined to be used with all execution options -A, -M, -P, -T or -X where possible, otherwise use the following execution options:

• -M for :main-opts configuration
• -X for :exec-opts configuration
• -T for :exec-opts, ignoring project dependencies

Clojure CLI - Which execution options to use

The project also contains

• GitHub workflow that runs MegaLinter and Code Quality checks (clj-kondo and cljstyle via the setup-clojure action)
• cljstyle configuration that follows the Clojure Style Guide
• Rebel Readline example configuration (supports the Rich Terminal UI used by Practicalli)
• cspell configuration for linting markdown and other text
• deps-deprecated.edn containing alias examples of tools not currently used by Practialli which may still be of interest to the wider community

Practicalli books uses the Clojure CLI Config extensively to support a REPL Reloaded workflow for Clojure projects.

Practicalli Clojure book discusses Clojure CLI and its use, along with video walk-through of the key features.

Creative Commons Attribution 4.0 ShareAlike License

Format Clojure

cljstyle is a format tool for Clojure files that supports the Clojure Style Guide, using the .cljstyle configuration file

Contents

• Install Practicalli Clojure CLI Config
• Updating practicalli/clojure-cli-config
• Common development tasks
• REPL Terminal UI I
  • Hotload dependencies I Remote REPL Connection I Socket REPL
• Development Environment
• Clojure Projects
  • Dependencies I Analysis I Packaging I Deployment
  • Searching
  • Format I Lint
  • Java sources
• Testing
  • Test runners I Clojure Spec I Performance I Security
• Databases
• Data Inspectors
  • Visualise vars and deps
• Debug
• Services
• Library Hosting Services - maven mirrors, local repositories

Install Practicalli Clojure CLI Config

Clojure CLI version 1.11.1.xxxx or later is recommended. Check the version of Clojure CLI currently installed via:

clojure -Sdescribe

Practicalli guide to installing Clojure has detailed instructions to install Clojure CLI for a specific operating system, or follow the Clojure.org Getting Started page.

When Clojure CLI runs for the first time a configuration directory is created in $XDG_CONFIG_HOME/clojure or $HOME/.clojure if XDG_CONFIG_HOME not set

Practicalli recommends setting $XDG_CONFIG_HOME to $HOME/.config

Backup or delete the Clojure CLI configuration directory if it exists

Clone practicalli/clojure-cli-config repository (or create a fork and clone that instead)

git clone [email protected]:practicalli/clojure-cli-config.git $XDG_CONFIG_HOME/clojure

If $XDG_CONFIG_HOME not set, then use git clone [email protected]:practicalli/clojure-cli-config.git $HOME/.clojure

The deps.edn file in the Clojure CLI configuration directory contains all the Practicalli aliases, which are available from any Clojure CLI project for the current user account.

Windows support: Windows Sub-system for Linux (WSL) is strongly encouraged. Aliases should also work on Powershell or cmd.exe, although escape quoting of additional arguments may be required.

Location of local Maven repository

$HOME/.m2/repository is the default location of the local maven repository, the directory where library dependency jar files are cached.

:mvn/local-repo is a top-level key to set the local maven repository location, such as /home/practicalli/.cache/maven/repository to follow the XDG specification. If setting :mvn/local-repository, consider moving the contents of $HOME/.m2/repository to the new location to avoid downloading currently cached jar files (or use this as an opportunity to clear out the cache).

Update Practicalli Clojure CLI Config

The collection of aliases is regularly reviewed and additional alias suggestions and PRs are most welcome.

The versions of libraries are updated at least once per month using the :project/outdated alias, updating the deps.edn file. The antq tool is used to report new library versions, sent to an org file which is then used to update the changelog.

cd $XDG_CONFIG_HOME/clojure
clojure -T:search/outdated > outdated.org

Pull Requests from :search/outdated cannot be accepted unless full testing of every change can be demonstrated

Using Practicalli Clojure CLI Config

Any directory containing a deps.edn file is considered a Clojure project. A deps.edn file can contain an empty hash-map, {} or hash-map with configuration, usually :paths and :dependencies and perhaps some :aliases.

The project deps.edn file is merged with the user wide configuration, e.g $HOME/.clojure/deps.edn, with the project deps.edn keys taking precedence if there is duplication, otherwise they are merged.

Configuration passed via the command line when running clojure or the clj wrapper will take precedence over the project and user level configuration if there is duplication, otherwise they are merged.

See the rest of this readme for examples of how to use each alias this configuration contains.

Common development tasks

How to run common tasks for Clojure development.

• Built-in: tasks provided by Clojure CLI
• Practicalli: aliases provided by Practicalli Clojure CLI Config

Task	Command	Configuration
Create minimal playground project	clojure -T:project/create	Practicalli
Clojure REPL - rebel readline & nrepl server	clojure -M:repl/rebel	Practicalli
ClojureScript REPL with nREPL server	clojure -M:repl/cljs	Practicalli
Run tests / watch for changes	clojure -X:test/run / clojure -X:test/watch	Practicalli
Run the project (clojure.main)	clojure -M -m domain.main-namespace	Built-in
Check library dependencies for newer versions	clojure -T:search/outdated	Practicalli
Download dependencies	clojure -P (followed by optional aliases)	Built-in
Generate image of project dependency graph	clojure -T:project/graph-deps	Practicalli
Deploy library locally (~/.m2/repository)	clojure -X:deps mvn-install :jar '"project.jar"'	Built-in
Find library names (Clojars & Maven Central)	clojure -M:search/libraries qualified-library-names	Practicalli
Find available versions of a library	clojure -X:deps find-versions :lib domain/library-name	Built-in
Resolve git coord tags to shas and update deps.edn	clojure -X:deps git-resolve-tags git-coord-tag	Built-in

REPL terminal UI

Run an interactive REPL on the command line with the basic built-in REPL UI or Rebel for a feature rich REPL experience.

nREPL server is started for all Clojure repl aliases along with the cider-nrepl middleware, so Clojure editors can connect to the REPL process started on the command line.

Command	Description
clojure -M:repl/rebel	Rebel Rich terminal UI Clojure REPL with nREPL for connecting editors
clojure -M:repl/basic	Basic terminal UI Clojure REPL with nREPL for connecting editors
clojure -M:repl/reloaded	As above with dev path, library hotload, namespace reload, Portal data inspector
clojure -M:repl/cljs	Basic terminal UI ClojureScript REPL using Rebel Readline
clojure -M:repl/rebel-cljs	Rich terminal UI ClojureScript REPL using Rebel Readline
clojure -M:repl/figwheel	Rich terminal UI ClojureScript REPL using Rebel Readline with Figwheel built tool
clojure -M:repl/headless	REPL without prompt, include nREPL for connecting editors
clojure -M:repl/rebel-remote	Connect to a remote REPL via nREPL with Rebel Rich terminal UI
clojure -M:repl/remote	As above with basic prompt

Use :env/dev with the :repl/rebel aliases to include dev/ in classpath and configure REPL startup actions using dev/user.clj

Hotload Libraries

clojure -M:repl/reloaded provides common tools to enhance the REPL workflow (hotload libraries, refresh code changes, inspect data, advanced test runner, log & trace)

Use :dev/reloaded with Editor jack-in commands or other aliases to start a REPL process, e.g. clj -M:dev/reloaded:repl/basic for a reloaded REPL workflow with a basic terminal REPL prompt.

Remote REPL connection

Connect to the nREPL server of a remote REPL using nREPL connect, using a simple terminal UI

clojure -M:repl/remote --host hostname --port 12345

As above but using the enhanced Rebel Readline UI

clojure -M:repl/rebel-remote --host hostname --port 12345

Socket REPL

Clojure 1.10.x onward can run a Socket Server for serving a socket-based REPL (Clojure and ClojureScript).

tubular is a Socket Server client for Clojure and Clojurescript REPL processes.

Command	Description
clojure -M:repl/socket	Clojure REPL using Socket Server on port 50505
clojure -M:repl/socket-zero	As above but on first available port (container, cloud environment)
clojure -M:repl/socket-zero -r	As above but and run a REPL
clojure -M:repl/socket-node	ClojureScript REPL using Socket Server on port 55555
clojure -M:repl/socket-browser	ClojureScript REPL using Socket Server on port 58585
clojure -M:repl/socket-client	Socket REPL client on port 50505 (tubular)

Development Environment

Environment settings and libraries to support REPL driven development

• :env/dev - add dev directory to class path - e.g. include dev/user.clj to configure REPL startup
• :dev/reloaded - reloaded workflow, dev and test paths, testing libraries
• :lib/hotload - include org.clojure/tools.deps.alpha add-libs commit to hotload libraries into a running REPL
• :lib/tools-ns - include org.clojure/tools.namespace to refresh the current namespace in a running REPL
• :lib/reloaded - combination of hotload and tools-ns aliases
• :lib/pretty-errors - highlight important aspects of error stack trace using ANSI formatting

Clojure Projects

Create Clojure CLI configured projects, either built-in or practicalli/project-templates to provide REPL Reloaded tools and production-level CI workflows.

Default values (can be over-ridden on the command line)

• :template project/application template, includes REPL Reloaded workflow, GitHub workflows, Dockerfile & compose.yaml, Makefile tasks
• :name practicalli/playground creates a practicalli domain containing playground namespace and example Clojure code

Command	Description
clojure -T:project/create :template app :name domain/app-name	A simple application
clojure -T:project/create	Practicalli application called playground
clojure -T:project/create :template practicalli/service	Practicalli Service called playground

:project/new - uses clj-new which is an archived project, although can still be used to create projects using Leiningen style templates. A Clojure CLI configuration must be manually added if these templates do not provide one.

| clojure -T:project/new :template app :name practicalli/my-application | App project with given name | | clojure -T:project/new :template luminus :name practicalli/full-stack-app :args '["+http-kit" "+h2"]' | Luminus project with given name and template options | | clojure -T:project/new :template figwheel-main :name practicalli/landing-page :args '["--reagent"]' | ClojureScript Figwheel-main project with reagent |

Running projects

Run project using clojure.main with or without an alias:

clojure -M:alias-name -m domain.app-name
clojure -M -m domain.app-name

The -M flag specified running the Clojure code with clojure.main library, so -M' is required even if an alias is not included in the running of the application. A warning will be displayed if the -M option is missing.

In the project deps.edn file it could be useful to define an alias to run the project, specifying the main namespace, the function to run and optionally any default arguments that are passed to that function.

:project/run
{:ns-default domain.main-namespace
 :exec-fn -main
 :exec-args {:port 8888}}

Then the project can be run using clojure -X:project/run and arguments can optionally be included in this command line, to complement or replace any default arguments in exec-args.

Project dependencies

• :project/check - detailed report of compilation errors for a project
• :project/graph-deps - graph of project dependencies (png image)
• :search/libraries - fuzzy search for libraries to add as dependencies
• :search/outdated - report newer versions for maven and git dependencies
• :search/outdated-mvn - check for newer dependencies (maven only)

Command	Description
clojure -M:project/check	detailed report of compilation errors for a project
clojure -M:search/libraries library-name	fuzzy search Maven & Clojars
clojure -M:search/libraries -F:save library-name	fuzzy search Maven & Clojars and save to project deps.edn
clojure -T:search/outdated	report newer versions for maven and git dependencies
clojure -M:search/outdated-mvn	check for newer dependencies (maven only)

:search/libraries will show warnings about unqualified libraries the first time it is used, which can safely be ignored

Project analysis

Carve - static analysis of code (clj-kondo) and remove or report unused vars

• :project/carve - remove / report unused vars
• :project/unused - alternative alias name for :project/carve
• :project/unused-vars - alternative alias name for :project/carve

Command	Description
clojure -M:project/unused --opts '{:paths ["src" "test"]}'	remove unused vars from the src and test paths
clojure -M:project/unused --opts '{:paths ["src" "test"] :report {:format :text}} '	report unused vars from the src and test paths

Generate report in a file:

clojure -M:project/unused --opts '{:paths ["src" "test"] :report {:format :ignore}}' > .carve/ignore

Project packaging

tools.build is a library for creating scripts to manage packaging the projects to a fine level of control. Projects start with common tasks for builind a jar or uberjar from the project.

Project Deployment

Deploy a library jar locally using the built-in :deps alias of Clojure CLI or to Clojars.org using slipset/deps-deploy project.

• -X:deps mvn-install built-in Clojure CLI alias to deploy a Jar locally in the ~/.m2/repository directory
• :deploy/clojars - deploy jar to clojars.org
• :deploy/clojars-signed - sign and deploy jar to clojars.org

Command	Description
clojure -X:deps mvn-install :jar '"project.jar"'	deploy jar file to local maven repository, i.e. ~/.m2/repository
clojure -M:project/clojars project.jar	deploy jar file to Clojars
clojure -M:project/clojars-signed project.jar	deploy signed jar file to Clojars

Set Clojars username/token in CLOJARS_USERNAME and CLOJARS_PASSWORD environment variables.

Set fully qualified artifact-name and version in project pom.xml file

Path to project.jar can also be set in alias to simplify the Clojure command.

clojure -X:deps mvn-install :jar '"project.jar"' for local deployment of jars is part of the 1.10.1.697 release of the Clojure CLI in September 2020.

Searching

Tools to search through code and libraries

• -M:search/errors clj-check - search each namespace and report compilation warnings and errors
• -M::search/unused-vars Carve - search code for unused vars and remove them - optionally specifying paths --opts '{:paths ["src" "test"]}'
• -M:search/libraries - find-deps - fuzzy search Maven & Clojars and add deps to deps.edn
• -T:search/outdated - liquidz/antq - check for newer versions of libraries, updating deps.edn if :update true passed as argument

Searching library options

A fuzzy search for a library by name, passing multiple names to search for

clojure -M:search/libraries http-kit ring compojure

Add the matching library as a dependency into the project deps.edn file

clojure -M:search/libraries --format:merge http-kit

Format code

• :lib/pprint-sorted - pretty printing with sorted keys and set values
• :format/cljstyle - check format of all Clojure, Edn and ClojureScript files in the project or a given file and show a diff of format changes
• :format/cljstyle! - automatically correct format of all Clojure, Edn and ClojureScript files in the project or a given file
• :format/zprint - check format of Clojure code and Edn data structures in the given file, or use file pattern **/*.clj **/*.edn
• :format/zprint! - format Clojure code and Edn data structures in the given file, or use file pattern **/*.clj **/*.edn
• :format/cljfmt - check clojure code and Edn data structures in the given file(s) using cljfmt
• :format/cljfmt! - format clojure code and Edn data structures in the given file(s) using cljfmt

Java Sources

Include Java source on the classpath to look up Java Class and method definitions, eg. cider-find-var in Emacs

Requires: Java sources installed locally (e.g. "/usr/lib/jvm/openjdk-17/lib/src.zip")

• :src/java17
• :src/clojure

Use the aliases with either -A, -M or -X execution options on the Clojure command line.

Clone clojure/clojure repository. Clojure core Java source code in src/jvm/clojure/lang/

Databases and drivers

Databases and drivers, typically for development time inclusion such as embedded databases

• :database/h2 - H2 embedded database library and next.jdbc

clojure -M:database/h2 - run a REPL with an embedded H2 database and next.jdbc libraries

Use the aliases with either -M or -X flags on the Clojure command line.

Data Inspectors

REPL driven data inspectors and tap> sources for visualising data.

Portal

Navigate data in the form of edn, json and transit Practicalli Clojure -data browsers section - portal

• inspect/portal-cli - Clojure CLI (simplest approach)
• inspect/portal-web - Web ClojureScript REPL
• inspect/portal-node - node ClojureScript REPL

Command	Description
clojure -M:inspect/portal-cli	Clojure REPL with Portal dependency
clojure -M:inspect/portal-web	ClojureScript web browser REPL with Portal dependency
clojure -M:inspect/portal-node	ClojureScript node.js REPL with Portal dependency

Using Portal once running (require '[portal.api :as portal]) once the REPL starts. For inspect/portal-web use (require '[portal.web :as portal]) instead

(portal/open) to open the web based inspector window in a browser.

(portal/tap) to add portal as a tap target (add-tap)

(tap> {:accounts [{:name "jen" :email "[email protected]"} {:name "sara" :email "[email protected]"}]}) to send data to the portal inspector window (or any other data you wish to send)

(portal/clear) to clear all values from the portal inspector window.

(portal/close) to close the inspector window.

Debug Tools

Emacs CIDER has a built in debug tool that requires no dependencies (other than Cider itself).

Sayid is a comprehensive debug and profile tool (which requires your code to compile) and generated a full and detailed history of an evaluation.

• :repl/debug run basic REPL prompt with sayid, and cider-nrepl middleware
• :repl/debug-refactor run basic REPL prompt with sayid, clj-refactor and cider-nrepl middleware
• :repl/rebel-debug run Rebel rich UI REPL prompt with sayid, and cider-nrepl middleware
• :repl/rebel-debug-refactor run Rebel rich UI REPL prompt with sayid, clj-refactor and cider-nrepl middleware

Practicalli Spacemacs - Sayid debug and profile tool covers the use of these aliases in more detail

Clojure Specification

Clojure spec, generators and test.check

• :lib/spec-test - generative testing with Clojure test.check
• :lib/spec2 - experiment with the next version of Clojure spec - alpha: design may change

Unit Testing frameworks

Unit test libraries and configuration. The Clojure standard library includes the clojure.test namespace, so no alias is required.

• :env/test - add test directory to classpath

Test runners and Test Coverage tools

Practicalli Clojure: Unit testing covers many aspects of testing for projects. Kaocha is the main test runner used by Practicalli as it is simple to use and easily configurable to create an effective test workflow.

Run unit tests in a project which are defined under the test path. See

Command	Description
clojure -X:test/run	run tests with the Kaocha comprehensive test runner for Clojure (same as :test/kaocha)
clojure -X:test/watch	run tests in watch mode using Kaocha test runner for Clojure (same as :test/kaocha-watch)
clojure -X:test/cognitect	Cognitect Clojure test runner
clojure -X:test/coverage	Cloverage clojure.test coverage report
clojure -M:test/cljs	ClojureScript test runner (Kaocha)

:lib/kaocha alias adds kaocha as a library to the class path, enabling scripts such as kaocha-runner.el to run Kaocha test runner from Emacs Cider

A test.edn configuration file can be used with the :test/run alias instead of using various aliases defined above

Lint tools

Static analysis tools to help maintain code quality and suggest Clojure idioms.

• :lint/clj-kondo - comprehensive and fast static analysis lint tool
• :lint/eastwood - classic lint tool for Clojure
• :lint/idiom-check - checking for idiomatic Clojure code with Kibit

Command	Description
clojure -M:lint/clj-kondo	comprehensive and fast static analysis lint tool
clojure -M:lint/eastwood	classic lint tool for Clojure
clojure -M:lint/idiom	Suggest idiomatic Clojure code

Visualising project vars and library dependencies

Create Graphviz graphs of project and library dependencies

Install Graphviz to generate PNG and SVG images. Or use the Edotor website to convert .dot files to PNG or SVG images and select different graph layout engines.

Var dependencies

Generate dependency graphs for Vars in Clojure & ClojureScript namespaces

• :graph/vars - generate graph of vars in a project as a .dot file
• :graph/vars-png - generate graph of vars in a project as a .png file using src and test paths
• :graph/vars-svg - generate graph of vars in a project as a .svg file using src and test paths

Use -f command line argument to over-ride file type created, i.e -f png

Namespace dependencies

Vizns creates graphs of relationships between namespaces and their dependencies

• clojure -M:graph/ns-deps - generate a single deps-graph SVG image
• clojure -M:graph/ns-deps-png as above with PNG image

Other options described in the visns project readme:

Project Dependency Relationships

Visualise the relationships between dependencies in the project (or given deps.edn configuration). Shows the fully qualified name of a dependency, its version and size.

Generate a PNG image from the project deps.edn configuration and save to project-dependencies-graph.png file

clojure -T:graph/deps

Options available

• :deps - Path to deps file (default = "deps.edn")
• :trace - images showing individual trace images of dependency relations (default = false)
• :trace-file - Path to trace.edn file to read
• :output - file name string to save the generated image, :output '"deps.png"'
• :trace-omit - Collection of lib symbols to omit in trace output
• :size - Boolean flag to include sizes in images (default = false)

Performance testing

Performance testing tools for the REPL

• :performance/benchmark

Use the aliases with either -M or -X flags on the Clojure command line.

clojure -M:performance/benchmark:repl/rebel

(require '[criterium.core :refer [bench quick-bench]])
(bench (expression-to-test))

Performance test a project in the REPL

clojure -M:performance/benchmark:repl/rebel

(require '[practicalli/namespace-name]) ; require project code
(in-ns 'practicalli/namespace-name)
(quick-bench (project-function args))

• :performance/memory-meter - memory usage

Use the aliases with either -M or -X flags on the Clojure command line.

In the REPL:

  (require '[clj-memory-meter.core :as memory-meter])
   (memory-meter/measure (your-expression))

Services

Web servers and other standalone services run with Clojure CLI

• :service/http - serve files from current directory or specified directory and port. More options at kachayev/nasus project.

Command	Description
clojure -M:service/http	HTTP file server for current directory on port 8000
clojure -M:service/http 8888	as above with PORT specified to 8888
clojure -M:service/http 8888 --dir docs	as above with PORT 8888 and doc directory

Use Ctrl-c to stop the server when running in the foreground

Security

DEPRECATED: :security/nvd Using clojure-nvd via an alias checks for security issues in clojure-nvd and its dependencies as they merged into the classpath.

The maintainer of clojure-nvd suggested several ways to avoid classpath interference

• :service/nvd - check library dependencies of a project against the National Vulnerability Database using nvd-clojure

Command	Description
clojure -T:security/nvd "" "$(clojure -Spath)"	check all jar files on the class path for security vulnerabilities

The first "" is required argument and can contain a filename to a json file of additional configuration. The second argument, "$(clojure -Spath)", passes the project classpath to be analysed as a string.

Community activities

The Clojurians Zulip CLI provides a simple way to register community events.

• :community/zulip-event create an event on the Clojurians Zulip community

Set an environment variable called ZULIP_AUTH to your account email, followed by the account token (see Account & privacy), e.g.

[email protected]:493u984u3249834uo4u

Create an event using the following command

Show help and options

clojure -M:community/zulip-event create -h

Announce an meetup.com event (you'll be asked for confirmation before posting)

clojure -M:community/zulip-event create --zulip-auth "${ZULIP_AUTH}" --url https://www.meetup.com/some-group/events/123/

Full example

clojure -M:community/zulip-event create --zulip-auth "${ZULIP_AUTH}" \
--title 'Practicalli Live - Exercism.io challenges' \
--start '2020-11-14T09:00+00:00' \
--duration 1 \
--url https://youtu.be/Z5C7X1UN8yo \
--description 'Walking through solutions to the Exercism.io challenges'

Take care to get the timezone notation correct.

Library Hosting Services

Clojure libraries are packaged as Java Archive (JAR) files and distributed by Maven style repositories. A Clojure project configuration defines library dependencies that are satisfied by downloading jar files from the collective repository sources.

central and clojars are defined in the Clojure CLI installation configuration and are the main repositories for Clojure development.

• central - Maven Central, the canonical repository for JVM libraries, including Clojure releases
• clojars - clojars.org, the canonical repositories for Clojure community libraries fronted by a contend delivery network service

 :mvn/repos
 {"central" {:url "https://repo1.maven.org/maven2/"}
  "clojars" {:url "https://repo.clojars.org/"}}

central and clojars repos can be removed by setting their configuration to nil in the user or project deps.edn configuration.

`:mvn/repos 
 {"central" nil
  "clojars" nil}

Maven supports explicit mirror definition in ~/.m2/settings.xml and Clojure CLI supports this configuration. Adding Maven Central or a mirror to ~/.m2/settings.xml negates the need for its entry in deps.edn configuration.

Optional repositories

The order of additional repositories consulted is not guaranteed, so may cause unpredictable side effects in the project build especially if RELEASE or LATEST tags are used rather than a specifice numerical version.

• sonatype - snapshots of Clojure development releases, useful for testing against before new stable releases.
• business-area - example of adding a local Artifactory server for your team or business area.
• google-maven-central - Maven Central mirror hosted on Google Cloud Storage - Americas, Asia, Europe

Use only one entry for a specific repository to ensure a repeatable build. For example, avoid having Maven Central and a Maven Central mirror both included.

Business area

Example of local Artifactory repository configuration

 :mvn/repos
 {"business-area" {:url "https://artifacts.internal-server.com:443/artifactory/business-area-maven-local"}

Americas mirrors

 :mvn/repos
 {"google-maven-central" {:url "https://maven-central.storage-download.googleapis.com/maven2/"}}

Europe mirrors

 :mvn/repos
 {"google-maven-central" {:url "https://maven-central-eu.storage-download.googleapis.com/maven2/"}

 ;; CDN access to clojars
 "clojars" {:url "https://repo.clojars.org/"}}

Asia Region Mirrors

 :mvn/repos
 {"google-maven-central" {:url "https://maven-central-asia.storage-download.googleapis.com/maven2/"}

 ;; Community mirror
 "clojars-china-mirror" {:url "https://mirrors.tuna.tsinghua.edu.cn/clojars/"}

 ;; CDN access to clojars
 "clojars" {:url "https://repo.clojars.org/"}}

Maven local repository

Specify a local repository for maven, as an alternative to the default location: $HOME/.m2/repository

FreeDesktop.org XDG_CACHE_HOME is the recommended location for an alternative Maven local repository.

:mvn/local-repo "/home/practicalli/.cache/maven/repository"

NOTE: The full path should be specified, otherwise a relative directory path will be created

clojure -Spath will show the current class path which will include the path to the local maven repository for the library dependencies.

NOTE: using clojure -Sforce forces a classpath recompute, deleting the contents of .cpcache

clojure-cli-config's Issues

:test/eftest runner hangs when finished

After running a test suite and reporting the failures it just hangs until you kill the process. eftest.runner/run-tests is intended for REPL usage and returns a map with a summary and doesn't initiate shutdown. If you look at the source for lein-eftest it checks the number of failures/errors returned by run-tests and exits with nonzero if they are nonzero -- see https://github.com/weavejester/eftest/blob/master/lein-eftest/src/leiningen/eftest.clj#L83-L116

:project/outdated not reporting on :replace-deps aliases

:replace-deps aliases are not being updated by antq using the :project/outdated alias.

Example
https://clojars.org/uberdeps
clj-new

Update: issue reported on the antq project liquidz/antq#44

clj-kondo improvements

Hey there!

Thanks for your project. I'm experimenting with using it as my source of truth for all sorts of CI checks i.e. not just for personal productivity.

I noticed a couple possible issues with the clj-kondo setup:

• :main-opts ["-m" "clj-kondo.main" "--lint" "src"]} does not specify "test". This seems a dangerous absence to have by default. It would seem sensible to either drop src or to also include test.
• For best results, clj-kondo shouldn't be run as a one-liner, see e.g. https://github.com/clj-kondo/clj-kondo#project-setup. So it seems to me that there should be an additional alias?
  • The usage I would foresee is clojure -M:lint/clj-kondo.analyse && clojure -M:lint/clj-kondo src test

wdyt?

Cheers - V

User level deps.edn - november update dependencies to latest versions

Windows and Clojure CLI - escape character issues

Currently the readme.md says to execute: clojure -X:deps mvn-install project.jar

The result I get is:
Key is missing value: project.jar

When I execute clojure -X:deps mvn-install :jar project.jar I get

my-library $ clojure -X:deps mvn-install :jar "project.jar"
Installing project.jar
Execution error (IllegalArgumentException) at clojure.tools.cli.api/read-pom-in-jar (api.clj:310).
No implementation of method: :as-file of protocol: #'clojure.java.io/Coercions found for class: clojure.lang.Symbol

Change of user-config to config-user

'user-config' is now 'config-user'

`samusz@CESP-176-39 polylithExample % clojure -Sdescribe

{:version "1.10.3.833"
:config-files ["/usr/local/Cellar/clojure/1.10.3.833/deps.edn" "/Users/samusz/.clojure/deps.edn" "deps.edn" ]
:config-user "/Users/samusz/.clojure/deps.edn"
:config-project "deps.edn"
:install-dir "/usr/local/Cellar/clojure/1.10.3.833"
:config-dir "/Users/samusz/.clojure"
:cache-dir ".cpcache"
:force false
:repro false
:main-aliases ""
:repl-aliases ""}`

[clojure-deps-edn] Create Pull Request template to guide contributions

Please raise an issue before raising a pull request in order to avoid working on something that would not be accepted.

Sweeping changes to this repository (or any open source project) are less likely to be accepted and take longer to review and test by the maintainers.

For example, updating a number of different libraries all at once will require a lot of manual testing to ensure each alias still works, especially with some of the recent changes in the ClojureScript library.

Pull requests that change deprecated aliases will be rejected. Those aliases are to be removed, so no further testing will be done. Updating deprecated aliases does not demonstrate an understanding of the project concerns.

`:project/outdated` is mentioned in comments but it looks like it was renamed to `:search/outdated`

It would probably be good to update the comments

Broken link (updating)

Currently, Updating practicalli/clojure-deps-edn links to https://github.com/practicalli/clojure-deps-edn/blob/live/updating-practicalli/clojure-deps-edn which does not exist.

It looks like it should link to updating-practicalliclojure-deps-edn (without the /).

Accidentally removed "clone" from git installation command in README

In the recent change below, clone was removed, so this isn't a valid git command any more. Also, I don't know if it's just me or all Mac users, but $XDG_CONFIG_HOME isn't set at all, FWIW.

- git clone your-fork-url ~/.clojure/
+ git [email protected]:practicalli/clojure-deps-edn.git $XDG_CONFIG_HOME/clojure

Error when using :search/outdated

Latest clojure, latest clojure-deps-edn.

$ clojure -T:search/outdated
No function found on command line or in :exec-fn

$ clojure -version
Clojure CLI version 1.11.1.1149

$ cd ~/.clojure
[collider@grabber .clojure]$ git status 
On branch live
Your branch is up to date with 'origin/live'.

nothing to commit, working tree clean

support Clerk as inspector ?

An alias like below starts CIDER-nREPL and opens Clerk and starts its "tap inspector", which is conceptually the same as portal and reveal, just powered by Clerk.
After this any "tapped" value is rendered in Browser.

I noticed an "issue", by "tap>" not giving the control back to the repl...
This does not happen, if you connect Emacs or an other nRepl client.

Not sure, what the root cause of this is

:inspect/clerk
  {:extra-deps {io.github.nextjournal/clerk {:mvn/version "0.15.957"}
                nrepl/nrepl                   {:mvn/version "1.0.0"}
                cider/cider-nrepl             {:mvn/version "0.28.7"}
                refactor-nrepl/refactor-nrepl {:mvn/version "3.6.0"}}
   :main-opts ["-e" "(require '[nextjournal.clerk])(nextjournal.clerk/show! 'nextjournal.clerk.tap)(nextjournal.clerk/serve! {:browse? true})"
               "-m" "nrepl.cmdline"
               "--interactive"
               "--middleware" "[refactor-nrepl.middleware/wrap-refactor,cider.nrepl/cider-middleware]"]}

:mvn/local-repo appears to be broken as it is relative

The :mvn/local-repo was changed to ".cache/maven/repository" which is relative ( this probably should be absolute path in $HOME/ )
It appears to break the existing usage.
I commented it out for now - to default back to ~/.m2

sayid alias requires middleware

The :lib/sayid library seems to be of little use without the associated middleware, so that alias should be deprecated

clojure-emacs/sayid#35

Related: Update Practicalli Spacemacs book - https://practical.li/spacemacs/debug-clojure/sayid-debug/

Rewrite hot-load documentation to match changes

Per the changes referenced in this issue, with your approval, I'd like to work on a pull request to change the documentation and language in your deps.edn to reflect changes to the hot-load alias.

User-level deps.edn is in a different place on XDG systems

I've just updated some of my repos to note that the user-level deps.edn file is in ~/.config/clojure/ on some systems (the deps/CLI reference notes them as "Freedesktop conventions"). This seems to be where the XDG_CONFIG environment variable points on such systems (and that takes precedence over the HOME variable in clojure shell script, if CLJ_CONFIG is not set).

Just in case you want to add a note in your repo.

deps-new Invalid Tag

When creating a new service from the template I get an error for io.github.seancorfield/deps-new stating that the tag (0.6.0) is invalid.

Changing the tag for io.github.seancorfield/deps-new in deps.edn to 'v0.6.0' fixes the issue.

I will submit a pull request.

Installation instructions don't mention CLJ_CONFIG or XDG_CONFIG_HOME

After following the installation instructions, calling any of the provided aliases failed with the error message "No function found on command line or in :exec-fn". Due to the help of Alex Miller and Sean Corfield on the Clojurians Slack channel, it became clear that the issue is that after installing the Clojure CLI tools, my config-user is not pointing to $HOME/.clojure but to $HOME/.config/clojure. I.e., see the output of clojure -Sdescribe:

[host->~]clojure -Sdescribe
{:version "1.10.1.727"
 :config-files ["/usr/local/lib/clojure/deps.edn" "/home/schauer/.config/clojure/deps.edn" ]
 :config-user "/home/schaueho/.config/clojure/deps.edn"
 :config-project "deps.edn"
 :install-dir "/usr/local/lib/clojure"
 :config-dir "/home/schaueho/.config/clojure"
 :cache-dir "/home/schaueho/.config/clojure/.cpcache"
 :force false
 :repro false
 :main-aliases ""
 :repl-aliases ""}

According to Alex, the reason is in my case that the environment variable $XDG_CONFIG_HOME points to /home/schaueho/. Apparently, setting $CLJ_CONFIG could lead to similar effects, as described in deps and cli documentation.

My proposal would be to change the documentation so that instead of just assuming ~/.clojure/ to specifically mention the value of :config-user from the output above.

Configure Super Linter for Clojure

Practicalli has used SuperLinter to lint markdown content for books. Add this to practicalli/clojure-deps-edn project to verify the markdown in the readme.md file, describing the project in detail.

Update repo name and branch

The repository has evolved to be more than just a deps.edn file and is specifically referred to as a Clojure CLI configuration.

use the consistent branch name main as the default branch

• rename the repository to clojure-cli-config (github will redirect the old name)
• rename the live branch to main
• update description in readme.md file

Project License?

Hi, @practicalli-john -

Thanks for making all these useful aliases available to the Clojure community. I think it might be helpful for myself and others if you clarified what license you're making this project available under, as there currently doesn't seem to be a license as far as I can tell.

Command line arguments to repl/rebel-remote don't work

The same command line args as applied to repl/remote do not work with repl/rebel-remote.
--host and --port do not have any effect.

Monthly version update

Run antq and update library versions within aliases

GitHub action report:
https://github.com/practicalli/clojure-cli-config/actions/runs/6045350640/job/16405274396#step:8:1

Migrate :project/jar and :project/uberjar aliases to tools.build

Add a workable approach to using tools.build from Practicalli Clojure deps.edn, ideally without having to add any other files to a project (external dependency to using the alias)

Putting this on hold as tools.build seems more applicable to a project deps.edn than user config

References

• tools.build guide
• https://github.com/liquidz/build.edn -

Background

:project/jar and :project/uberjar aliases depend on depstar which was deprecated (and archived) for six months.

tools.build should be the preferred approach

Reveal has disappeared?

I had a setup for debugging some hairy recursive code using Reveal (no reveal specific code required in my app).

Now I return a month or so later and it's gone? diff here.

How do you evaluate that something is 'unused'? Can you keep metrics on clojure-deps-edn alias downloads?

With Portal I seem to have to launch an inspector from within the app. Extra steps for me given it's HumbleUI and can crash if I am doing crazy things.

Also it feels very un-Clojure like that these aliases are mutable and removed (thinking of Rich Hickey's talk and the blessings of Maven immutability).

My code tap>s out reams of info, which was very smooth scrolling through in Reveal (order is important for analysis). Perhaps I can get Portal to the same place.. but will require investigative work and so is jarring.

Thanks for the project and looking forward to your thoughts on this issue.

Add clj-depend tool

Design an alias for the https://github.com/fabiodomingues/clj-depend tool for analysing dependencies

Add mega-linter to support markdown, yaml and deps.edn linting on prs and commits

Add a GitHub action for mega-linter that checks markdown, yaml and deps.edn files.

No function found on command line or in :exec-fn on new project

I run the new project template and it flunks.

user$ clojure -X:project/new :template app :name practicalli/testapp
No function found on command line or in :exec-fn

Here's the output of clojure -Sdescribe

{:version "1.10.1.763"
 :config-files ["/usr/share/clojure/deps.edn" "/home/billy/.clojure/deps.edn" ]
 :config-user "/home/billy/.clojure/deps.edn"
 :config-project "deps.edn"
 :install-dir "/usr/share/clojure"
 :config-dir "/home/billy/.clojure"
 :cache-dir "/home/billy/.clojure/.cpcache"
 :force false
 :repro false
 :main-aliases ""
 :repl-aliases ""}

refactor: deprecate unused aliases for simpler config

Move all alias definitions that are never used to a different file, keeping the deps.edn file much simpler to work with.

Keep the deprecated alias definitions should they be of interest to the community

Would you consider adding scope-capture to the inspect section?

https://github.com/vvvvalvalval/scope-capture