Clojure CLI: Defining aliases
Clojure CLI tools provide a very flexible way to run Clojure, using aliases to include community libraries and tools to enhance clojure projects and provide independent tools. Understand the execution options (exec-opts) on the command line options ensures an effective use of Clojure CLI tools.
Aliases are used to add (or remove) configuration from the
Aliases are used with Clojure tools to provide additional configuration when explicitly added to the clojure
command.
Aliases can be used to modify:
- the classpath and dependencies included, by adding or removing dependencies and paths
- providing a simple way to configure community tools, such as rebel readline, clj-new, depstar, etc.
Aliases can be defined in a project deps.edn
or be available to all projects via the ~/.clojure/deps.edn
configuration file.
practicalli/clojure-deps-edn user level aliases and tools
practicalli/clojure-deps-edn is a configuration designed to work across all Clojure projects, containing unique and meaningful alias names for ease of understanding.
Clojure CLI tool options
Clojure CLI tool has several options that determine how aliases and other configuration is used
- add or remove dependencies
- add or remove directories on the class path
- define a function or main namespace to run, along with arguments
Clojure CLI main flag options
-A to configure paths and dependencies when running the Clojure CLI tools REPL
-M using clojure.main to run the -main function of a Clojure project or tool, using the -m flag to specify the namespace containing -main (clojure.main has other features too)
-X for running any fully qualified function from a Clojure project or tool
-P a dry run, downloading all dependencies (must use flag in first position)
-T running a tool separate from a Clojure project (class path)
Using an alias
An alias is used via the -M
option to the clojure
command:
clojure -M:qualified/alias-name
Multiple aliases can be used together
clojure -M:env/test:test/runner
Only one main namespace
An alias for a community tool
Use the rebel community tool by including its alias.
clojure -M:repl/rebel
This alias adds the library dependency for the rebel readline project and defines the main namespace. The namespace is where the -main
function is located that will start rebel readline.
{:aliases
:rebel
{:extra-deps {com.bhauman/rebel-readline {:mvn/version "0.1.4"}}
:main-opts ["-m" "rebel-readline.main"]}
} ;; End of aliases
Including paths, deps and main-opts
The Cognitect Lab test runner included the test
directory in the class path, so test code will be included when run with this alias.
The test runner dependency is pulled from a specific commit shared on GitHub (defined as a Git SHA).
The main namespace is set to that library and the -main
function is called when using this alias.
{:aliases
:test-runner/cognitect
{:extra-paths ["test"]
:extra-deps {com.cognitect/test-runner
{:git/url "https://github.com/cognitect-labs/test-runner.git"
:sha "f7ef16dc3b8332b0d77bc0274578ad5270fbfedd"}}
:main-opts ["-m" "cognitect.test-runner"]}
}
Stand-alone tools
When a community tool does not require any of the project paths or dependencies to operate, :replace-paths
and :replace-deps
should be used when defining an alias. These configurations only used paths and dependencies defined within the alias itself, minimizing the resources used to run the tool, improving the speed of using these tools.
:project/new
{:replace-deps {seancorfield/clj-new {:mvn/version "1.1.226"}}
:main-opts ["-m" "clj-new.create"]}
Clojure Exec
With Clojure CLI tools version 1.10.1.697 the -X
flag was introduced using aliases with Clojure exec.
The configuration should define a fully qualified function that runs the tool.
The function should take arguments as key/value pairs as with an Edn hash-map, rather than relying on positional arguments as strings.
In this example, :exec-fn
defines the fully qualified function name that will be called. :exec-args
is a hash-map of the default key values pairs that are passed to the function as an argument.
:project/new
{:replace-deps {seancorfield/clj-new {:mvn/version "1.1.23"}}
:main-opts ["-m" "clj-new.create"] ;; deprecated
:exec-fn clj-new/create
:exec-args {:template lib :name practicalli/playground}
}
Default arguments can be over-ridden in the command, e.g. clojure -X:project/new :template app :name practicalli/simple-application
uses a different template
Additional arguments can be sent when running the command, e.g. clojure -X:project/new :template figwheel-main :name practicalli/landing-page :args '["--reagent"]'
uses the figwheel-main
template, specifies a name and :args
arguments sent to
:ns-default
can also be used to qualify the function that will be executed in an alias. :ns-default
is especially useful when there are several functions that could be called from the specific namespace.
The command line can over-ride the :exec-fn
function configuration, allowing for a default configuration that can be easily over-ridden.
: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}
}
Keyword naming
Resources
- clj-exec - insideclojure.org
- clj-exec update - insideclojure.org