Practicalli Clojure CLI Configuration

Practicalli Clojure CLI Config is a user configuration for Clojure CLI tools providing a range of community tools via meaningful aliases, supporting Clojure and ClojureScript development.

Alias names are designed with qualified keywords that provide context for the use of an alias (env, inspect, project, repl, search test). These keywords help with discovery and reduce cognitive load required to remember their purpose.

Commonly used arguments are included in many alias via :main-opts or :exec-args which can be overridden on the command line.

Minimum Clojure CLI Version - 1.10.3.1040

Clojure CLI version 1.10.3.1040 is the minimum version, although the latest available version is recommended.

Check the version of Clojure CLI currently installed via clojure --version or clojure -Sdescribe

Remote Environments or Continuous Integration

For remote environments or Continuous Integration services, include Practicalli Clojure CLI Config) in the environment build or copy specific aliases to the Clojure project deps.edn configuration.

Practicalli Clojure CLI Config

Install

Fork or clone Practicalli Clojure CLI Config GitHub repository, first removing the $XDG_CONFIG_HOME/clojure or $HOME/.clojure directory if they exist.

Check Clojure CLI configuration location

Check the location of your Clojure configuration directory by running clojure -Sdescribe and checking the :user-config value.

Free Desktop XDG CONFIGClassic Config

If XDG_CONFIG_HOME environment variable is set, clone the repository to $XDG_CONFIG_HOME/clojure

git clone https://github.com/practicalli/clojure-cli-config.git $XDG_CONFIG_HOME/clojure

Clojure CLI will look for its configuration in $HOME/.clojure directory if $XDG_CONFIG_HOME and CLJ_CONFIG environment variables not set.

git clone https://github.com/practicalli/clojure-cli-config.git $HOME/.clojure

Community Tools

The Clojure configuration directory contains a deps.edn file containing a substantial :aliases section with a long list of aliases. These aliases are described in the README of the project.

All tools are provided via libraries and are only installed on first use. Unused aliases will therefore not install their libraries.

Aliases to start with

Start with the following aliases to keep things simple

clojure -T:project/create :name domain/project-name to create a new clojure project

clojure -M:repl/reloaded to run a fully loaded REPL and rich terminal UI (which can be connected to from Clojure editors)

clojure -X:test/watch to run tests on file save (or :test/run to manually run tests once)

Use Clojure tools.build to create jar and uberjar packages of the project.

REPL experience

Rebel REPL terminal UI provides a feature rich REPL prompt experience, far beyond the basic clj command.

Command	Description
clojure -M:repl/rebel	Rebel terminal UI
clojure -M:env/dev:repl/rebel	Rebel including deps & path from :env/dev alias to configure REPL start
clojure -M:repl/reloaded	Rebel with dev & test paths, library hotload, namespace reload, portal data inspector
clojure -M:repl/rebel-cljs	Run a ClojureScript REPL using Rebel Readline

:repl/help in the REPL for help and available commands. :repl/quit to close the REPL.

Clojure Projects

• Create Clojure CLI specific projects using deps-new
• Create projects from deps, leiningen and boot templates with clj-new

Command	Description
clojure -T:project/create	library project called playground
clojure -T:project/create :template app :name practialli/service	Clojure CLI project from app template
clojure -T:project/new :template luminus :name practicalli/full-stack-app +http-kit +h2	Luminus project with given name and template options

Run projects

Run project with or without an alias:

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

The -M flag 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

Command	Description
clojure -M:project/errors	detailed report of compilation errors for a project
clojure -M:search/libraries library-name	fuzzy search Maven & Clojars
clojure -M:search/libraries -F:merge library-name	fuzzy search Maven & Clojars and save to project deps.edn
clojure -M:search/outdated	report newer versions for maven and git dependencies
clojure -M:search/unused-vars	search and remove unused vars

Project Deployment

Deploy a project archive file locally or to Clojars.org

Package projects into jars using tools.build

Clojure tools.build is the recommended way to create library jar files and application Uberjar files.

Command	Description
clojure -X:deps mvn-install project.jar	[NEW] 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 project.jar for local deployment of jars is part of the 1.10.1.697 release of the Clojure CLI tools in September 2020.

Java Sources

Include Java source on the classpath to look up Java Class and method definitions, e.g. cider-find-var in Emacs Requires: Java sources installed locally (e.g. "/usr/lib/jvm/openjdk-11/lib/src.zip")

• :lib/java17-source

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

Format tools

Use formatting tools to support a consistent code style across all Clojure projects

Command	Description
clojure -M:format/cljstyle check / fix	Check or fix code style (cljstyle)
clojure -M:format/cljfmt check / fix	Check or fix code style (cljfmt)
clojure -M:format/zprint filename	Format file using zprint

Include :lib/pprint-sorted when starting a REPL to pretty print data with sorted keys and set values

Databases and drivers

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

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

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

https://cljdoc.org/d/seancorfield/next.jdbc/CURRENT/doc/getting-started#create--populate-a-database

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

Data Science

• lib/clerk - Clerk Notebooks

Visualizing projects

Create Graphviz graphs of project and library dependencies

Morpheus creates grahps of project vars and their relationships

• :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

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.

Vizns creates graphs of relationships between library dependencies and project namespaces

• :graph/deps
• :graph/deps-png - generate a single deps-graph png image

Other options: - clojure -M:graph/deps navigate # navigable folder of SVGs - clojure -M:graph/deps single # deps-graph.dot file - clojure -M:graph/deps single -o deps-graph.png -f png - clojure -M:graph/deps single -o deps-graph.svg -f svg - clojure -M:graph/deps single --show # View graph without saving

Data Inspector

Portal Navigate data in the form of edn, json and transit

Practicalli Clojure - data browsers section - portal

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 "jen@jen.com"} {:name "sara" :email "sara@sara.com"}]}) 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.

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.

• :test/env - add test directory to classpath
• :lib/expectations - clojure.test with expectations
• :lib/expectations-classic - expectations framework

Use expectations in a project clojure -M:test:expectations or from the command line with a test runner, e.g. clojure -M:lib/expectations:test/runner

Test runners and Test Coverage

Tools to run unit tests in a project which are defined under test path.

Run clojure with the specific test runner alias: clojure -M:test-runner-alias

Command	Description
clojure -M:test/run	Kaocha test runner for Clojure
clojure -M:test/watch	Kaocha: watch for changes
clojure -M:test/cljs	Kaocha test runner for ClojureScript

Lint tools

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

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

Performance testing

:performance/benchmark alias includes the Criterium library for performance testing of Clojure expressions.

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

:dev/reloaded and :repl/reloaded both include criterium library

Start a REPL using the :repl/reloaded alias, or by including the :performance/benchmark in a Clojure command to start a REPL.

Repl Reloaded

```shell clojure -M:repl/reloaded

```

Clojure command

```shell clojure -M:performance/benchmark:repl/basic

```

REPL

Require the Criterium quick-bench function

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

(quick-bench (adhoc-expression))

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))

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))