DEV Community: Volodymyr Kozieiev

Full Clojure project in 5 seconds!

Volodymyr Kozieiev — Tue, 18 Oct 2022 14:44:12 +0000

Every time you start a new Clojure project, there is a lot of boilerplate that needs to be added:

deps.edn with aliases to run tests and build actions
build.clj with build actions
.gitignore
README.md
you name it…

Creating all these can be easily automated with deps-new.

Install `deps-new`

deps-new intended to be installed as a "tool" for Clojure CLI.

"Tools" in Clojure CLI

Tools are 3rd party libraries that can be installed and than invoked from Clojure CLI using clj -T option. They use their own classpath and do not interfere with the project's deps.edn if you run tool commands from the project directory.

Few commands you may need:

clj -Ttools list - to view already installed tools

clj -Ttools remove :tool tool-name - to remove the tool

clj -Ttools install tool-path tool-version :as tool-name - to install a new tool

More info about tools you can find in this video.

Installing `deps-new` tool

Here is a command to add deps-new to your system

clojure -Ttools install io.github.seancorfield/deps-new '{:git/tag "v0.4.13"}' :as new

:as new part of the command means that "new" is now a name for deps-new tool on your system. You can use any name you want.

Let's check our list of tools now:

$ clj -Ttools list
TOOL   LIB                              TYPE  VERSION
new    io.github.seancorfield/deps-new  :git  v0.4.13
tools  io.github.clojure/tools.tools    :git  v0.2.8

To check what functions new tool exposes you can run the command:

clojure -A:deps -Tnew help/doc

Create a library

Now, when deps-new is installed, we can use it to create a new library.

The following command will create a library with root namespace vkjr and one source file mycoollib.clj in it

$ clojure -Tnew lib :name vkjr/mycoollib
  Creating project from org.corfield.new/lib in mycoollib

And here is a content of new library:

mycoollib
├── .gitignore
├── CHANGELOG.md
├── LICENSE
├── README.md
├── build.clj
├── deps.edn
├── doc
│   └── intro.md
├── pom.xml
├── resources
│   └── .keep
├── src
│   └── vkjr
│       └── mycoollib.clj
└── test
    └── vkjr
        └── mycoollib_test.clj

Top level directory of the library was also named mycoollib but you can override this behavior by providing additional key/value pair to the library creation command :target-dir some-folder-name.

Content of created library

As you can see, there are plenty of automatically generated files in our new lib.

deps.edn from the start contains aliases for testing and build actions

{:paths ["src" "resources"]
 :deps {org.clojure/clojure {:mvn/version "1.11.1"}}
 :aliases
 {:test
  {:extra-paths ["test"]
   :extra-deps {org.clojure/test.check {:mvn/version "1.1.1"}
                io.github.cognitect-labs/test-runner
                {:git/tag "v0.5.1" :git/sha "dfb30dd"}}}
  :build {:deps {io.github.seancorfield/build-clj
                 {:git/tag "v0.8.2" :git/sha "0ffdb4c"}}
          :ns-default build}}}

src/vkjr/mycoollib.clj contains a dummy function

(ns vkjr.mycoollib)

(defn foo
  "I don't do a whole lot."
  [x]
  (prn x "Hello, World!"))

And in test/vkjr/mycoollib_test.clj already exists one failing test

(ns vkjr.mycoollib-test
  (:require [clojure.test :refer :all]
            [vkjr.mycoollib :refer :all]))

(deftest a-test
  (testing "FIXME, I fail."
    (is (= 0 1))))

build.clj contains build actions test, ci, install and deploy

(ns build
  (:refer-clojure :exclude [test])
  (:require [clojure.tools.build.api :as b] ; for b/git-count-revs
            [org.corfield.build :as bb]))

(def lib 'net.clojars.vkjr/mycoollib)
(def version "0.1.0-SNAPSHOT")
#_ ; alternatively, use MAJOR.MINOR.COMMITS:
(def version (format "1.0.%s" (b/git-count-revs nil)))

(defn test "Run the tests." [opts]
  (bb/run-tests opts))

(defn ci "Run the CI pipeline of tests (and build the JAR)." [opts]
  (-> opts
      (assoc :lib lib :version version)
      (bb/run-tests)
      (bb/clean)
      (bb/jar)))

(defn install "Install the JAR locally." [opts]
  (-> opts
      (assoc :lib lib :version version)
      (bb/install)))

(defn deploy "Deploy the JAR to Clojars." [opts]
  (-> opts
      (assoc :lib lib :version version)
      (bb/deploy)))

Note, that build.clj implements actions using the build-clj library instead of standard Clojure's tools.build. That library hides some unnecessary details and provides the functionality of deploying to Clojars, which is missed in tools.build

There are a bunch of other useful files also: .gitignore, README.md, pom.xml, LICENSE.. real time-saver, ha?

Create an application

Creating an application with deps-new as simple as a library:

$ clojure -Tnew app :name vkjr/mycoolapp
Creating project from org.corfield.new/app in mycoolapp

And here is a folder structure:

mycoolapp
├── .gitignore
├── CHANGELOG.md
├── LICENSE
├── README.md
├── build.clj
├── deps.edn
├── doc
│   └── intro.md
├── pom.xml
├── resources
│   └── .keep
├── src
│   └── vkjr
│       └── mycoolapp.clj
└── test
    └── vkjr
        └── mycoolapp_test.clj

Main differences from the library project:

src/vkjr/mycoolapp.clj contains the (-main) and (greet) functions

(ns vkjr.mycoolapp
  (:gen-class))

(defn greet
  "Callable entry point to the application."
  [data]
  (println (str "Hello, " (or (:name data) "World") "!")))

(defn -main
  "I don't do a whole lot ... yet."
  [& args]
  (greet {:name (first args)}))

deps.edn has additional aliases run-m and run-x to run (main) and (greet) functions respectively

...
{:run-m {:main-opts ["-m" "vkjr.mycoolapp"]}
 :run-x {:ns-default vkjr.mycoolapp
         :exec-fn greet
         :exec-args {:name "Clojure"}}
...
}

build.clj creates an uberjar instead of a jar and doesn't have (install) and (deploy) functions

...
(defn ci "Run the CI pipeline of tests (and build the uberjar)." [opts]
  (-> opts
      (assoc :lib lib :version version :main main)
      (bb/run-tests)
      (bb/clean)
      (bb/uber)))

Create a minimal "scratch" project

For the cases when you don't need a full-blown application, but merely a playground, deps-new supports creating a "scratch" projects:

$ clojure -Tnew scratch :name playground                                            
Creating project from org.corfield.new/scratch in playground

Folder structure for such "scratch":

playground
├── deps.edn
└── src
    └── scratch.clj

With almost empty deps.edn and scratch.clj with (-main) and (greet) functions, like in the application example

Using deps-new you can create your own project template, but this is another story… ;)

originally posted at kozieiev.com

Is Clojure the only language you need?

Volodymyr Kozieiev — Wed, 12 Oct 2022 19:01:17 +0000

Video version

The question

Clojure is a hosted programming language. This means what you wrote in Clojure will run in an environment of another language.

The most popular implementation of Clojure turns Clojure code into Java bytecode that runs on Java Virtual Machine.

Another popular implementation is ClojureScript. And its compiler turns your Clojure code into JavaScript.

And there are a lot of other implementations.

If you can run Clojure where Java or JavaScript runs, can you learn Clojure and conveniently use it in ALL areas of software development?

Well, no. There is no silver bullet.

But can Clojure be the only language YOU need? Yes, if you write software in areas where Clojure proved to be good.

Backend

Here Clojure fits perfectly. Running on JVM, with its immutable data structures and built-in concurrency support, Clojure is very good at dealing with simultaneous connections and processing big amounts of data.

One of the main examples of a production Clojure backend is a Nubank. It is a Latin American digital bank that used Clojure so heavily, that in 2020 they decided to acquire the Cognitect company that develops Clojure.

On job boards, you can find backend Clojure roles in advertising or sports data processing.

FrontEnd

FrontEnd is also an area where Clojure fits, particularly ClojureScript. If you don’t know the difference - watch this video.

The most popular approach for building frontend with ClojureScript is using React. You can use it via a wrapper library called Reagent and describe UI components as pure functions returning Clojure data structures.

One of the biggest Ukrainian internet-shops Kasta uses ClojureScript with React.

Mobile

Mobile development is also possible with Clojure. The stack you can use here is ClojureScript + ReactNative. Though it is not as popular as frontend or backend.

I did a quick search on job boards and didn’t find Clojure mobile positions published now.

But they exist. For example Status company where I met Clojure for the first time and worked for a few years has a mature blockchain-based mobile messenger written in ClojureScript with ReactNative.

Scripting

Another area where you can use Clojure is scripting. Whatever you write in Bash, you can write in Clojure and without switching your brain context to another syntax.

But If you will write the scripts with JVM Clojure there will be an issue - long startup time.

Instead, you can use a tool called Babashka. It is a native Clojure interpreter that implements a sufficient subset of Clojure and goes with a bunch of prepacked libs to work with the filesystem, command line arguments, json. All these packed in a standalone binary, that you can deploy anywhere and run Clojure without JVM.

On my local machine, I use babashka script that generates folder structure for the new blogpost and new video project when I start preparing them.

Desktop

With desktop development, the situation is more complicated than with all mentioned before. There are different approaches to creating interfaces.

If you decide to use JVM Clojure, you can use one of Java UI kits. Either directly, or via more idiomatic wrapper libraries.

You can use Clojure + JavaFX like the guys from Defold. They wrote an editor for their game engine this way.

Or you can use Clojure + Swing, like in this tool (beat-link-trigger). Unfortunately, I have no idea what it is for but will leave a link in the description.

You can create web-UI with ClojureScript + React and wrap it in Electron.

One more approach - to write an app in ClojureScript + Microsoft’s version of react-native for windows or macOS.

Or you can try to write an ipad-compatible app with standard React-Native and run it on Mac using apple’s project Catalyst :)

So you can see, there are really a lot of choices but none of them dominates, which means they all have flaws. You can read a good article from Niki Tonsky where Clojure UI problems are discussed. Also to address the problems Niki Tonsky started the development of a new UI for Clojure, called Humble UI. So now we have one more option :)

Ah, and there is also a new version of Clojure in active development - ClojureDart. It is a port of Clojure language to Dart with the primary goal of using Flutter framework and getting a native mobile and desktop UI.

So one more option, yes :)

Embedded

As for embedded, I haven’t heard about production Clojure in this area, sorry.

But here is the video with an experimental running ClojureScript on ESP32 chip.

Conclusion:

As you can see, there are situations when Clojure is not very convenient. But there are plenty of situations where it is. And if you are, for example, fullstack developer who occasionally writes scripts, you can use different flavors of Clojure in all your tasks ;)

originally posted at kozieiev.com

How to create a library that works with Clojure and ClojureScript

Volodymyr Kozieiev — Sun, 21 Aug 2022 16:14:54 +0000

this article originally posted at https://kozieiev.com

Content:

Creating Clojure version of logger library
Creating Clojure app to use logger library
Introducing reader conditionals
Making the logger library work with ClojureScript
Creating ClojureScript app to use logger library

Clojure and ClojureScript are forms of the same language targeting different hosts - JVM and JavaScript respectively. If you are creating a library, there is a big chance that a significant part of the code will work for both hosts but a part of it will be host-dependent.

Here we will discuss how to isolate the host-dependent parts of code to be used only when appropriate in order to write a single library that works for both Clojure and ClojureScript.

Steps that we are going to do:

Create a simple logger Clojure library. Its (log) function will print the passed object with added timestamp and information from what language it was invoked.
Create a Clojure app that uses the logger library
Modify logger library to work with ClojureScript as well
Create a ClojureScript app that uses the logger library to check that our modifications worked correctly

Creating Clojure version of logger library

Here is a folder structure for our logger library:

logger
├── deps.edn
└── src
    └── vkjr
        └── logger.clj

It’s deps.edn can be an empty map:

{}

And here is a code of the logger.clj:

(ns vkjr.logger
  (:require [clojure.pprint :as pprint]))

(defn- timestamp []
  (.format (java.text.SimpleDateFormat. "d/M/yyyy, HH:mm:ss") (new java.util.Date)))

(defn log [arg]
  (pprint/cl-format true
                    "Time: ~S | Host: ~S | Object: ~S\n"
                    (timestamp)
                    "Clojure"
                    arg))

(timestamp) is a helper function that uses Java host features to get a formatted timestamp.

(log) is the function visible to the library users. It takes the user argument and using (cl-format) prints it prepended with timestamp and language name (”Clojure” in this case).

The first argument of (cl-format) - true, means that printing should be done to the default output. You can read more about this function in the official documentation.

Creating Clojure app to use logger library

Now let’s create a Clojure app to use the library. It will be called cljapp and put on the same lever with the logger:

playground
├── logger      <- logger library
└── cljapp      <- our new app

Here is a folder structure for cljapp:

cljapp
├── deps.edn
└── src
    └── core.clj

In deps.edn we’ll reference logger library by location on the filesystem:

{:deps {vkjr/logger {:local/root "../logger"}}}

And here is the code inside core.clj:

(ns core
  (:require [vkjr.logger :as logger]))

(defn -main [& _]
  (logger/log "Hi there!")
  (logger/log {:a 1 :b 2})
  (logger/log [1 2 3 4]))

We required the namespace of the logger library and used (logger/log) inside the (main) to print different arguments.
Now let’s run the main function using Clojure CLI (from cljapp folder) to make sure it works correctly:

$ clj -M -m core                                          
Time: "18/8/2022, 16:39:30" | Host: "Clojure" | Object: "Hi there!"
Time: "18/8/2022, 16:39:30" | Host: "Clojure" | Object: {:a 1, :b 2}
Time: "18/8/2022, 16:39:30" | Host: "Clojure" | Object: [1 2 3 4]

Nice, as we see, it does)

Introducing reader conditionals

There is a part of Clojure tooling called Reader. It takes a textual code representation and turns it into the Clojure data structures. When you compile Clojure code, Reader will be responsible for processing your sources.

Reader supports two reader conditionals which allow you to specify different pieces of code and choose between them depending on the platform where the reader is invoked.

The standard reader starts with #? and looks like:

#?(:clj     (any Clojure expression)
   :cljs    (any ClojureScript expression)
   :default (default expression))

When Reader encounters such a conditional, it will leave only one expression in the result data structure - the one corresponding to the current host or the default one if the current host is not listed.

So after reading this code:

#?(:clj (+ 1 2) :cljs (+ 3 4))

On ClojureScript host Reader will return this datastructure:

(+ 3 4)

The splicing reader starts with #?@ and looks like this:

#?@(:clj  [vector of elements]
    :cljs [another vector of elements])

When it encountered, Reader will choose the vector depending on the host and will put the content of vector in the surrounding context. Not the vector itself! It’s content.

And after reading this code:

(print #?@(:clj [1 2] :cljs [3 4]))

on Clojure platform Reader will return the datastructure:

(print 1 2)

Note: in the source code reader conditionals work only in files with *.cljc file extension!

To grasp reader conditionals better you can experiment in REPL by feeding different code pieces to the read-string function (with {:read-cond :allow} as a first argument) and inspecting the output.

$ clj                               <- run repl
user=> (read-string {:read-cond :allow} "#?(:clj (+ 1 2) :cljs (+ 3 4))")
(+ 1 2)

Making the logger library work with ClojureScript

Now with all that knowledge about reader conditionals, it is time to revamp logger to make it work for ClojureScript.

First, we need to rename logger.clj → logger.cljc to enable reader conditionals.

Folder structure now:

logger
├── deps.edn
└── src
    └── vkjr
        └── logger.cljc

Next we need to add ClojureScript-related code in (comment) function in logger.cljc. It will be wrapped with standard reader conditional:

(defn- timestamp []
  #?(:clj
     (.format (java.text.SimpleDateFormat. "d/M/yyyy, HH:mm:ss") (new java.util.Date))
     :cljs
     (let [now (new js/Date)]
       (.toLocaleString now "en-US" #js{:hour12 false}))))

And as the last step, we modify (log) function to display the correct language name depending on the host. We use splicing reader conditional on doing this:

(defn log [arg]
  (pprint/cl-format true
                    "Time: ~S | Host: ~S | Object: ~S\n"
                    (timestamp)
                    #?@(:clj ["Clojure"]
                        :cljs ["ClojureScript"])
                    arg))

Full content of logger.cljc now:

(ns vkjr.logger
  (:require [clojure.pprint :as pprint]))

(defn- timestamp []
  #?(:clj
     (.format (java.text.SimpleDateFormat. "d/M/yyyy, HH:mm:ss") (new java.util.Date))
     :cljs
     (let [now (new js/Date)]
       (.toLocaleString now "en-US" #js{:hour12 false}))))

(defn log [arg]
  (pprint/cl-format true
                    "Time: ~S | Host: ~S | Object: ~S\n"
                    (timestamp)
                    #?@(:clj  ["Clojure"]
                        :cljs ["ClojureScript"])
                    arg))

Now we need to check that changes didn’t affect the work of existing cljapp

Calling core namespace again from cljapp folder:

$ clj -M -m core                                          
Time: "18/8/2022, 16:50:39" | Host: "Clojure" | Object: "Hi there!"
Time: "18/8/2022, 16:50:39" | Host: "Clojure" | Object: {:a 1, :b 2}
Time: "18/8/2022, 16:50:39" | Host: "Clojure" | Object: [1 2 3 4]

Creating ClojureScript app to use logger library

And finally, we need to check that the library also works for the ClojureScript project.
Let’s create one, called cljsapp on the same level as logger and cljapp:

playground
├── logger
├── cljsapp   <- ClojureScript app
└── cljapp

Project structure:

cljsapp
├── deps.edn
└── src
    └── core.cljs

deps.edn content:

{:deps {org.clojure/clojurescript {:mvn/version "1.11.60"}
        vkjr/logger {:local/root "../logger"}}}

core.cljs content:

(ns core
  (:require [vkjr.logger :as logger]))

(defn -main [& _]
  (logger/log "Hi there!")
  (logger/log {:a 1 :b 2})
  (logger/log [1 2 3 4])
  (logger/log (new js/Date)))

And the actual check using Clojure CLI:

clj -M -m cljs.main -re node -m core
Time: "8/19/2022, 13:45:03" | Lang: "ClojureScript" | Object: "Hi there!"

Time: "8/19/2022, 13:45:03" | Lang: "ClojureScript" | Object: {:a 1, :b 2}

Time: "8/19/2022, 13:45:03" | Lang: "ClojureScript" | Object: [1 2 3 4]

Time: "8/19/2022, 13:45:03" | Lang: "ClojureScript" | Object: #inst "2022-08-19T12:45:03.775-00:00"

Perfect, now we have a library that works for both Clojure and ClojureScript :)

Links

Complete code for on github

Official documentation on reader conditionals

Packaging Clojure projects into jars and uberjars with tools.build

Volodymyr Kozieiev — Fri, 03 Jun 2022 20:22:00 +0000

This article was originally posted at kozieiev.com.

Video version of this article
Jars and uberjars
- jar/uberjar content
- Resouces
- MANIFEST.mf
- pom.xml
tools.build library
- adding tools.build to a project
- creating a jar for the library
- creating a runnable ubjerjar
- more tools.build functions

Video version of this article

Jars and uberjars

The most common way to prepare your Clojure project for distribution is to pack it into a *.jar file.

JAR format came from the Java world and it stands for "Java ARchive". It is a zip archive with a *.jar extension that contains Java class files, resources, and metadata.

To distribute Clojure library you can create a jar with library's source files or with compiled code (Java *.class files with bytecode). Optionally you can put both - source files and compiled files. Compiled files will be preferred over a source files unless source files are newer.

To distribute a Clojure application you have to create a jar that contains compiled Clojure code of the app along with all its dependencies. Such self-contained archive called uberjar.

jar/uberjar content

In addition to Clojure sources and Java bytecode files, jars can contain resources and metadata files.

Resouces

When preparing the jar you can put there any resource files that your library or app needs (images, text, etc). From the Clojure code, those resources can be accessed via (io/resource) function.

`MANIFEST.mf`

Manifest is a special file that contains information about jar content. Here can be specified the entry point of an application but you won't need to do that manually. tools.build will generate a default manifest for every jar automatically. If you will need to extend manifest with custom fields, you can use :manifest option in (jar) and (uber) functions of tools.build.

More info about manifest can be found in Java documentation.

`pom.xml`

In the Java world, there is a super-popular buiid framework called Maven. it uses pom.xml files to store project information and configuration. This framework also has its own type of repository for built projects called "maven repository".

In Clojure, we don't have to use Maven to build projects but we extensively use maven repositories to store build artifacts (jars). Dependencies of our project could be downloaded from maven repos and the resulting artifact of our project (its jar) can be uploaded to maven repo to be accessible by others.

The most popular maven repo for Clojure artifacts is Clojars.

If you are planning to upload your project's jar to some maven repository, that jar should contain a pom.xml with artifact info.

More info about POM can be found in maven documentation.

`tools.build` library

Not so long ago you had to use 3rd-party tools to create jars for your own Clojure projects. But now the official tools.build library can be used.

The main idea behind tools.build is that project's build is also a program and it can be written in Clojure code. And tools.build is a library that provides functions commonly needed for builds.

adding `tools.build` to a project

Let's imagine that we have a simple project structured like this:

project
├── deps.edn
└── src
    └── ...

To start using tools.build we need to:

create a Clojure namespace to keep build functions
add a new alias to deps.edn to call build functions with its help
invoke build function via Clojure CLI

Let's add a build.clj to the root of the project. This is where we are going to keep all the build tasks. For now, there will be only one function - (clean) . It removes target directory using (b/delete) from tools.build.api. Inside target, we will keep all our build artifacts, so it should be cleaned between builds.

We don't use any arguments inside (clean) but it should be defined as a function with one argument because, when invoked from Clojure CLI, it will be called with one - map of the arguments passed via the command line (nil if you didn't pass any).

build.clj:

(ns build
  (:require [clojure.tools.build.api :as b]))                     ; requiring tools.build

(def build-folder "target")

(defn clean [_]
  (b/delete {:path build-folder})                                 ; removing artifacts folder with (b/delete)
  (println (format "Build folder \"%s\" removed" build-folder)))

To make build functions accessible via Clojure CLI, let's create a new alias in deps.edn. In that alias there should be :deps key with tools.build dependency and :ns-default key which tells CLI in what namespace it should look for the function mentioned in the command line.

deps.edn:

{
; ... other deps.edn content ...
:aliases
  {
    ; ... other aliases ...

    ; build alias:
    :build {:deps {io.github.clojure/tools.build {:git/tag "v0.8.1" :git/sha "7d40500"}}
            :ns-default build}}  ; <-- set build namespace as default
}

And finally, to run (clean) from the command line using the new alias, we need to call Clojure CLI with -T option. That option ignores the rest of deps.edn content and uses the dependencies only from the current alias. In this way, we do not interfere with the other project dependencies and source files.

$ clj -T:build clean
Build folder "target" removed

creating a jar for the library

Now let's review an example of creating a jar for the library with the following folder structure

mymathlibary
├── build.clj
├── deps.edn
├── resources
│   └── lib_resource.txt
└── src
    └── mymath
        └── sum.clj

Inside sum.clj there is a sum function that adds two values and prints text from the resource file (please promise me to not do like this in real-world libs).

sum.clj:

(ns mymath.sum
  (:require [clojure.java.io :as io]))

(defn sum [a b]
  (println "Lib resource content:" (slurp (io/resource "mymath_resource.txt")))
  (+ a b))

Text inside lib_resource.txt:

hello from mymath lib

Let's say we want our jar to contain only source code, without compiled bytecode. To achieve this, in build.clj we need to add a new function named (jar) that does the following:

cleans target directory from leftovers
copies sources and resources to target. They should go into the result jar.
creates pom.xml file. You will need it if you are going to put the library into maven repositories.
creates the jar file

Here is the code of our new build.clj:

(ns build
  (:require [clojure.tools.build.api :as b]))

(def build-folder "target")
(def jar-content (str build-folder "/classes"))     ; folder where we collect files to pack in a jar

(def lib-name 'com.github.YOURNAME/mymath-lib)      ; library name
(def version "0.0.1")                               ; library version
(def basis (b/create-basis {:project "deps.edn"}))  ; basis structure (read details in the article)
(def jar-file-name (format "%s/%s-%s.jar" build-folder (name lib-name) version))  ; path for result jar file

(defn clean [_]
  (b/delete {:path build-folder})
  (println (format "Build folder \"%s\" removed" build-folder)))

(defn jar [_]
  (clean nil)                                     ; clean leftovers

  (b/copy-dir {:src-dirs   ["src" "resources"]    ; prepare jar content
               :target-dir jar-content})

  (b/write-pom {:class-dir jar-content            ; create pom.xml
                :lib       lib-name
                :version   version
                :basis     basis
                :src-dirs  ["src"]})

  (b/jar {:class-dir jar-content                  ; create jar
          :jar-file  jar-file-name})
  (println (format "Jar file created: \"%s\"" jar-file-name)))

In the code of (jar) we use three functions from tools.build to achieve steps mentioned before: (b/copy-dir), (b/write-pom) and (b/jar). Their names and arguments are pretty self-explanatory except one - :basis.

The basis is a big structure that contains a superset of all deps.edn files, project classpath, and description of all dependencies. In the official Clojure documentation, it is mentioned here.

tools.build uses basis in a few functions and gives a function to create it - (b/create-basis). The (b/write-pom) function uses basis to correctly reflect the library dependencies in pom.xml

Now to create the jar we can run (jar) function using Clojure CLI (assuming your deps.edn already contains :build alias):

$ clj -T:build jar
Build folder "target" removed
Jar file created: "target/mymath-lib-0.0.1.jar"

Now it can be uploaded to a maven repo and used as a dependency in other projects.

You can examine jar content using jar -tf command:

$ jar -tf target/mymath-lib-0.0.1.jar 
META-INF/MANIFEST.MF
lib_resource.txt
META-INF/
mymath/
META-INF/maven/
mymath/sum.clj
META-INF/maven/com.github.YOURNAME/
META-INF/maven/com.github.YOURNAME/mymath-lib/
META-INF/maven/com.github.YOURNAME/mymath-lib/pom.xml
META-INF/maven/com.github.YOURNAME/mymath-lib/pom.properties

creating a runnable ubjerjar

Now we can take a look at how to create a runnable uberjar for a Clojure application.

For example, we have a project with the following structure:

simpleapp
├── build.clj
├── deps.edn
├── resources
│   └── app_resource.txt
└── src
    └── dev
        └── core.clj

core.clj contains (-main) function that will work as an entry point when the application invoked. The (-main) calls (sum) function from the library created in a previous section and prints text from the local resource file.

core.clj:

(ns dev.core
  (:require [mymath.sum :as s]
            [clojure.java.io :as io])
  (:gen-class))     ; !!! instruction to generate bytecode for java class from this namespace

(defn -main []
  (println "Sum is:" (s/sum 1 2))
  (println "App resource content:" (slurp (io/resource "app_resource.txt"))))

Most important thing here is a :gen-class directive to (ns) function. It tells Clojure compiler to generate an additional bytecode file with java class corresponding to this namespace. That class will serve an entry point for our uberjar.

Now in build.clj we can create an (uber) function that builds uberjar. Here is what it should do:

clean target directory from leftovers
copy resources to target. They should go into result uber.
compile Clojure code
create the uberjar with (-main) entrypoint

Full code of build.clj:

(ns build
  (:require [clojure.tools.build.api :as b]))

(def build-folder "target")
(def jar-content (str build-folder "/classes"))

(def basis (b/create-basis {:project "deps.edn"}))
(def version "0.0.1")
(def app-name "myapp")
(def uber-file-name (format "%s/%s-%s-standalone.jar" build-folder app-name version)) ; path for result uber file

(defn clean [_]
  (b/delete {:path "target"})
  (println (format "Build folder \"%s\" removed" build-folder)))

(defn uber [_]
  (clean nil)

  (b/copy-dir {:src-dirs   ["resources"]         ; copy resources
               :target-dir jar-content})

  (b/compile-clj {:basis     basis               ; compile clojure code
                  :src-dirs  ["src"]
                  :class-dir jar-content})

  (b/uber {:class-dir jar-content                ; create uber file
           :uber-file uber-file-name
           :basis     basis
           :main      'dev.core})                ; here we specify the entry point for uberjar

  (println (format "Uber file created: \"%s\"" uber-file-name)))

The code is quite similar to the one where we were creating jar and probably doesn't require many explanations. New functions here are (b/compile-clj) and (b/uber).

By the way you could have used (b/compile-clj) in library example to create a library jar with compiled code.

Now let's bulid our uberjar:

$ clj -T:build uber
Build folder "target" removed
Uber file created: "target/myapp-0.0.1-standalone.jar"

And run it using java -jar command:

$ java -jar target/myapp-0.0.1-standalone.jar
Lib resource content: hello from mymath lib
Sum is: 3
App resource content: hello from app

As we can see, resource file content was printed from the app and the lib. That means uberjar was created successfully and contains all the necessary files.

The output of jar -tf target/myapp-0.0.1-standalone.jar will be too long to post it here but I encourage you to investigate the content of created uberjar to see how dependencies are included there.

more `tools.build` functions

Your build.clj is not restricted to creating jars and uberjars. There are more functions in tools.build that give you freedom to build scripts of an arbitrary complexity:

(process) - runs an arbitrary command with arguments

(git-process) - runs git command

(zip) and (unzip) - work with archives

(install) - installs jar to a local maven repository

More details can be found in the tools.build official api.

Build and run Clojure projects. CLI, tools.deps and deps.edn guide

Volodymyr Kozieiev — Sat, 02 Apr 2022 15:42:00 +0000

This article was originally posted at kozieiev.com.

Note for readers
Video version of this article
What is Clojure CLI?
- Difference between clj and clojure executables
Most usable clj options
- -M option to work with clojure.main namespace
- Running (-main) function from namespace
- Running clojure file as a script
- -X option to run specific functions
deps.edn configuration files
- :paths key
- :deps key
- :aliases key
- Aliases for clj -M
- Aliases for clj -X
tools.deps library
- Managing dependencies
- Building classpath
Running REPL with clj -A
Real-world examples
- Cognitect test-runner setup
- clj-new library setup
Other clj capabilities
Conclusion

Note for readers

This article was written for those who want to understand how to work with Clojure CLI (command line interface), and how to configure it with deps.edn files. There are 2 official articles on this topic: Deps and CLI Guide and Deps and CLI Reference. These are both very helpful, but In my opinion, the first one is too brief to gain a good enough understanding of concepts, and the second one is too long for an introduction to the topic. So I tried to write something in between that gives the reader a deep enough explanation of how clj works, but without all the nitty-gritty details.

At the time of writing this, I used Clojure CLI version 1.10.3.855 on Mac.

Video version of this article

What is Clojure CLI?

Clojure CLI provides the tools to execute Clojure programs and manage their dependencies.
To understand Clojure CLI, we should cover 3 main topics:

clj and clojure are executables that you invoke to run Clojure code.
tools.deps is a library that works behind the scenes to manage dependencies and to create classpaths.
deps.edn configuration files that you create to customize work of clj/clojure and tools.deps.

Difference between clj and clojure executables

Both clj and clojure are scripts, and clj is just a wrapper on clojure.

Let's find where clj is located:

$ which clj
/usr/local/bin/clj

And examine its content:

$ cat /usr/local/bin/clj              
#!/usr/bin/env bash
...
  exec rlwrap -r -q '\"' -b "(){}[],^%#@\";:'" "$bin_dir/clojure" "$@"
...

As you can see ,clj, behind the scenes, wraps a call to $bin_dir/clojure with the rlwrap tool. rlwrap provides a better command-line editing experience.

If you run clojure without arguments, REPL will be started. Try to type something in it, and press up/down/left/right keyboard keys.

$ clojure                                                                                                 
Clojure 1.10.3
user=>(+ 1 2) ^[[A^[[B^[[D^[[C

You will notice that those keys don't work properly.

But if you run clj instead, you will be able to use left/right keys to navigate the typed text, and up/down to navigate the calls history. This is exactly the function provided by rlwrap.

I will be using only clj later in the article.

Most usable `clj` options

-M and -X are the most important options, and the ones you need to learn first.

`-M` option to work with `clojure.main` namespace

Invoking clj with the -M option gives you access to functionality from the clojure.main namespace. All arguments after -M will be passed to the clojure.main/main and interpreted by it. To see all available options of clojure.main, you can run:

$ clj -M --help

Or take a look at official documentation.

Running (-main) function from namespace

The most common usage of clj -M is to run the entry point of your clojure code. To do this, you should pass -m namespace-name options to the clojure.main. It will find the specified namespace, and invoke its (-main) function.

For example, if you have the following project directory structure:

project-dir        (project directory)
└─ src             (default sources directory)
   └─ core.clj

With the core.clj file:

(ns core)

(defn -main []
  (println "(-main) invoked"))

Running core/main from the project-dir directory looks like this:

$ clj -M -m core
(-main) invoked

Running clojure file as a script

clojure.main also allows running Clojure file as a script. To do this via CLI, you should use the command, clj -M /path/to/script/file.clj arg1 arg2 arg3. An arbitrary number of arguments passed after script path will be available in a script under *command-line-args* var.
If you have a script.clj file:

(println "Script invoked with args: " *command-line-args*)

Calling it will give you:

$ clj -M script.clj 1 2 3
Script invoked with args:  (1 2 3)

`-X` option to run specific functions

(-main) is not the only function you can run via CLI. You can run any other one using the -X option as long as this function takes a map as an argument. The command should look like this: clj -X namespace/fn [arg-key value]*

With file core.clj

(ns core)

(defn print-args [arg]
  (println "print-args function called with arg: " arg))

If core.clj is located in your project-dir/src, you can call (print-args) using CLI from the project-dir folder:

$ clj -X core/print-args :key1 value1 :key2 value2
print-args function called with arg:  {:key1 value1, :key2 value2}

Key-value pairs specified after the function name will be passed to the function as a map.

`deps.edn` configuration files

There are a few files with the name deps.edn. One in the clj installation itself. You can also have another one in the $HOME/.clojure folder to keep the common settings for all your projects. And, of course, you can create one in your project directory with project-specific settings. All of them store configuration settings in clojure maps. When clj is invoked, it merges them all to create a final configuration map. You can read more about locations of different deps.edn files in official documentation.

Later in this article, I will mostly talk about deps.edn that you create in a project directory.

The most important keys in the configuration map are :deps, :paths, and :aliases:.

`:paths` key

Under the :path key, you specify the vector of directories where source code is located.

If the deps.edn file doesn't exist in your project folder or it doesn't contain the:path key, clj uses the src folder by default.

For example, if you have the following directory structure:

project-dir        
├─ src             
│  └─ core.clj
└─ test  
   └─ test_runner.clj

With core.clj:

(ns core)

(defn -main []
  (println "(-main) invoked"))

And test_runner.clj:

(ns test-runner)

(defn run [_]
  (println "Running tests.."))

You can run something from core.clj because it is in the src folder:

$ clj -M -m core
(-main) invoked

But an attempt to run test-runner/run will fail. The test-runner namespace from thetest folder isn't available:

$ clj -X test-runner/run
Execution error (FileNotFoundException) at clojure.run.exec/requiring-resolve' (exec.clj:31).
...

To fix this, add the deps.edn file at the root of your project-dir, and put a vector of all source folders under the :paths key:

{:paths ["src" "test"]}

Now the content of the test folder is visible to clj:

$ clj -X test-runner/run
Running tests..

Note, that you should specify both the src and test folders under the:paths key.

`:deps` key

Under the :deps key , you can place a map of external libraries that your project relies on. Libraries will be downloaded along with their dependencies, and become available for use.

Dependencies can be taken from the Maven repository, git repository, or local disk.

For Maven dependencies, you should specify their version. By default, two Maven repos are used for the search:

For Git dependencies, you should specify :git/url with the repo address, and the :git/sha or :git/tag keys to specify the library version.

Let's declare deps.edn like this:

{:paths ["src" "test"]
 :deps {com.taoensso/timbre                  {:mvn/version "5.1.2"}
        io.github.cognitect-labs/test-runner {:git/url "https://github.com/cognitect-labs/test-runner.git"
                                              :git/sha     "705ad25bbf0228b1c38d0244a36001c2987d7337"}}}

When clj is invoked, two libraries will be available in our code: timbre logging library which artifacts taken from Maven, and test-runner, taken from GitHub.

From core.clj timbre now can be used after importing its namespace:

(ns core
  (:require [taoensso.timbre :as log]))

(defn -main []
  (log/info "Logged with taoensso.timbre"))

And test-runner main function can be invoked by clj with already known -M switch:

$ clj -M -m cognitect.test-runner
Running tests in #{"test"}

Testing user

Ran 0 tests containing 0 assertions.
0 failures, 0 errors.

More details on how to use local dependencies and meaning of different keys can be found in official documentation.

`:aliases` key

The "alias" is the main concept in deps.edn. It is where concentrates all convenience of clj tool. Let's explore it with examples.

Aliases for `clj -M`

So far, we've been using clj with the -M option to run the (-main) function in a specified namespace. Let's imagine that our project has two different entry namespaces with (-main) functions. One is used for development and one for production. Our project folder looks like this:

project-dir        
└─ src             
   └─ dev
   │  └─ core.clj
   └─ prod
      └─ core.clj

The command line for the dev build is:

$ clj -M -m dev.core

And for prod:

$ clj -M -m prod.core

To minimize typing, we can declare two different aliases in the deps.edn file, and store all options after clj -M under that aliases.

Here is the content of deps.edn with two declared aliases :dev and :prod. You can use any keywords as alias names.

{:aliases {:dev  {:main-opts ["-m" "dev.core"]}
           :prod {:main-opts ["-m" "prod.core"]}}}

To invoke an alias, you add its name right after the -M option. Now, running the dev build using an alias looks like this:

$ clj -M:dev

It's similar for prod:

$ clj -M:prod

So, :aliases is a key in the deps.edn map where you store a map with user-defined aliases.

Every alias is a key-value pair, where the key is a user-defined name of the alias, and value is a map with pre-defined keys. In the example above, we used :main-opts, a pre-defined key that keeps a vector of options to be passed to the clojure.main namespace. When clj -M is invoked with an alias, it runs clojure.main with arguments taken from :main-opts.

Aliases for `clj -X`

We can also create aliases to run specific functions. They look pretty much the same as aliases from the example above, but rely on other pre-defined keys.

Let's imagine you have a function for generating reports. It is located in the db.reports namespace, named generate. The only argument is a map with two possible keys: :settings for a map of settings, and :tables with a vector of tables for which we want to get reports. If the :tables key is absent, we generate reports for all tables.

Let's make a stub for our reports.clj:

(ns db.reports)

(defn generate [{:keys [settings tables]}]
  (println "generated report with settings:" settings "for tables:" (if tables tables "all")))

To run reports for all tables from the command line, we can invoke:

clj -X db.reports/generate '{:settings {:brief true}}'
generated report with settings: {:brief true} for tables: all

For orders and users tables:

$ clj -X db.reports/generate '{:settings {:brief true} :tables ["users" "orders"]}'
generated report with settings: {:brief true} for tables: [users orders]

Since typing all arguments in the command line is quite tedious, let's create aliases in deps.edn:

{:aliases {:generate-all  {:exec-fn   db.reports/generate
                           :exec-args {:settings {:brief true}}}
           :generate-some {:exec-fn   db.reports/generate
                           :exec-args {:settings {:brief true}
                                       :tables   ["users" "orders"]}}}
}

Now you can generate reports more conveniently:

$ clj -X:generate-all
generated report with settings: {:brief true} for tables: all

clj -X:generate-some
generated report with settings: {:brief true} for tables: [users orders]

As you probably noticed, we don't use the :main-opts's pre-defined key anymore, because it works only with clj -M. Instead, we use the :exec-fn key to specify the namespace/function to run, and :exec-args to pass arguments map.

If you will try to run one of these aliases with clj -M, you will see a REPL started instead of the invoked function. This is because clj starts clojure.core when it sees the -M option, and since there is no :main-opts key, it won't pass any arguments to it. And clojure.core invoked without arguments will simply start REPL.

$ clj -M:generate-some
Clojure 1.10.3
user=>

There are pre-defined keys common to the -X and -M options, but we will discuss them later.

`tools.deps` library

When clj runs clojure programs, it runs a JVM process and needs to pass a classpath to it. (To read more about how Clojure works on top of JVM, you can check this article) Classpath is a list of all paths where java should look for classes used in your program, including classes for your dependencies. So to build a classpath, all dependencies should be resolved first. Both these tasks, resolving dependencies and creating a classpath, is done by thetools.deps library that goes with Clojure. clj calls tools.deps internally.

Two main functions in tools.deps that resolve and build classpaths are (resolve-deps) and (make-classpath-map), respectively.

Let's take a look at their work and arguments:

Managing dependencies

(resolve-deps) is the first one that comes into play. As a first argument, it takes a list of dependencies declared in a top-level :deps key of deps.edn. And as a second argument, map of pre-defined keys taken from an alias that you used when launched clj.

:extra-deps allows you to add dependencies only when a particular alias is invoked. For example, you don't need to use the test-runner dependency, unless you are running a test. So you can put it in an alias under :extra-deps:

{:deps    {org.clojure/clojure {:mvn/version "1.10.3"}}
 :aliases {:test {:extra-deps {io.github.cognitect-labs/test-runner
                               {:git/url "https://github.com/cognitect-labs/test-runner.git"
                                :git/sha     "705ad25bbf0228b1c38d0244a36001c2987d7337"}}
                  :main-opts  ["-m" "cognitect.test-runner"]}}}

Other keys that can be used in an alias on this step are:

:override-deps - overrides the library version chosen by the version resolution to force a particular version instead.
:default-deps - provides a set of default versions to use.
:replace-deps - a map from libs to versions of dependencies that will fully replace the project :deps.

When invoked, (resolve-deps) will combine the original list of dependencies with modifications provided in aliases, resolve all transitive dependencies, download required artifacts, and will build a flat libraries map of all dependencies needed for current invokation.

Since managing dependencies step happens at any kind of clj invocation, pre-defined keys :extra-deps, :override-deps and :default-deps can be used with any clj option we described before.

Building classpath

After the libraries map is created, the classpath building function comes into play. (make-classpath-map) takes three arguments:

libraries map that is a result of the (resolve-deps) step.
content of :paths key in deps.edn map.
map of pre-defined keys :extra-paths, :classpath-overrides and :replace-paths taken from executed alias.

:extra-paths allows you to add new paths when a specific alias is invoked. For example, if you have source code for all the tests in a specific test folder, you can include it in a dedicated alias and not include it in other builds. deps.edn will look similar to this:

{:paths ["src"]
 :aliases {:test {:extra-paths ["test"]
                  :main-opts  ["-m" "cognitect.test-runner"]}}}

Other pre-defined keys for this stage are:

:classpath-overrides specifies a location to pull a dependency that overrides the path found during dependency resolution; for example, to replace a dependency with a local debug version.

{:classpath-overrides
 {org.clojure/clojure "/my/clojure/target"}}

:replace-paths: a collection of string paths that will replace the ones in a :paths key.

Running REPL with `clj -A`

There is one more clj option that can work with aliases that we haven't talked about yet.

clj -A runs REPL. If you invoke it with some alias, it will take into account all dependency-related and path-related predefined keys mentioned in the alias. There are no pre-defined keys that are specific only to the -A option.

Let's say we have the following project structure:

project-dir        
├─ src             
│  └─ core.clj
└─ test  
   └─ test_runner.clj

With core.clj:

(ns core)

(defn print-hello []
  (println "Hello from core"))

test_runner.clj:

(ns test-runner
  (:require [taoensso.timbre :as log]))

(defn print-hello []
  (log/info "Hello from test-runner"))

And deps.edn:

{:paths ["src"]
 :aliases {:test  {:extra-deps  {com.taoensso/timbre {:mvn/version "5.1.2"}}
                   :extra-paths ["test"]}}}

If we start a REPL with the clj command, we will be able to run something from core, but won't be able to reach test-runner, because test folder is not in the :paths key of deps.edn:

$ clj
Clojure 1.10.3
user=> (require '[core :as c])
nil
user=> (core/print-hello)
Hello from core
nil
user=> (require '[test-runner :as tr])
Execution error (FileNotFoundException) at user/eval151 (REPL:1).
Could not locate test_runner__init.class, test_runner.clj or test_runner.cljc on classpath. Please check that namespaces with dashes use underscores in the Clojure file name.

But if we run clj -A:test, there won't be an error, because the:extra-paths key in the alias adds a test folder. Also, note that test-runner can use the taoensso.timbre library because that lib is listed in :extra-deps.

clj -A:test
Clojure 1.10.3
user=> (require '[core :as c])
nil
user=> (core/print-hello)
Hello from core
nil
user=> (require '[test-runner :as tr])
nil
user=> (tr/print-hello)
2021-09-05T11:12:00.459Z MacBook-Pro.local INFO [test-runner:5] - Hello from test-runner

Real-world examples

Let's analyze some real-world deps.edn files to understand how they work.

Cognitect `test-runner` setup

We already mentioned cognitect's test-runner above. It is a library for discovering and running tests in your project.

Its documentation suggests adding the following alias to your deps.edn:

:aliases {:test {:extra-paths ["test"]
                 :extra-deps {io.github.cognitect-labs/test-runner 
                              {:git/url "https://github.com/cognitect-labs/test-runner.git"
                               :git/sha "8c3f22363d63715de4087b038d79ae0de36a3263"}}
                 :main-opts ["-m" "cognitect.test-runner"]
                 :exec-fn cognitect.test-runner.api/test}}

Let's break it down:

:extra-paths says that clj should consider the "test" folder to build our classpath when using the:test alias.
:extra-deps specifies that the test-runner library can be downloaded from github.
having :main-opts means that we can run tests using clj -M:test ...args... Args description can be found on the documentation page.
having :exec-fn means that we can also run testing with clj -X:test args-map. Args-map description can be found on the documentation page.

`clj-new` library setup

clj-new library allows you to generate new projects from templates. In contrast to the previous example, this time you suggested adding a new alias globally in ~/.clojure/deps.edn:

{:aliases
 {:new {:extra-deps {com.github.seancorfield/clj-new {:mvn/version "1.1.331"}}
        :exec-fn clj-new/create
        :exec-args {:template "app"}}}}

:extra-deps says we can get clj-new from Maven.
:exec-fn means that we can run the alias via clj -X:new.
and by defining alias in ~/.clojure/deps.edn you make it available in any folder on your system. So you can run something like clojure -X:new :name myname/myapp to create myapp project. Arguments :name myname/myapp will be put in a map, merged with a map under :exec-args, and passed to clj-new/create function.

Other `clj` capabilities

clj has a bunch of other functionality that you can explore by reading the output of clj --help.

clj -Sdescribe will print environment info. In the output you can find the :config-files key with a list of deps.edn files used in the current run.

clj -Spath will print you the result classpath. Try running it with different aliases to figure out the impact on the resulting classpath; for example, by running with :test alias: clj -Spath -A:test

In Deps and CLI Reference you will find a full explanation of clj capabilities.
In Deps and CLI Guide you can find a bunch of useful examples of clj and deps.edn usage, like running a socket server remote REPL.

Conclusion

In this article, we've covered how clj, tools.deps, and deps.edn work together. The key concept of "alias" is explained in different examples. Also, the process of building a classpath was reviewed in detail to provide a better understanding of how pre-defined keys from your aliases impact it.

Creating and publishing Clojure libraries

Volodymyr Kozieiev — Sun, 31 Oct 2021 18:42:00 +0000

Notes for readers
Forms and locations of Clojure libraries
Creating local library
Creating git-based library
Packaging library to a JAR file
Installing JAR to local Maven repo
Installing JAR to remote repo
Modifying library to be suitable for ClojureScript
Adding pom.xml to library root
Creating library project with clj-new

Here we are going to create a Clojure library, pack it to a JAR file, deploy it to a Maven repository and make its code available from Clojure and ClojureScript projects. We will create the simplest project and will grow it step by step. At the end, we will discuss the build-clj tool that can be used to create the library template projects.

Video version of this article

Notes for readers

Projects here are organized using deps.edn configuration files.

All examples in this post use single-segment namespaces, like (ns basic-math). It makes examples simpler but please don't use this approach for production code. Both Clojure and ClojureScript have subtle issues with single-segment namespaces. Also this can lead to name clashes when your library published and imported along with another library with the same name. So please use something like (ns basic-math.core) or (ns your-name/basic-math).

At the time of writing Clojure CLI with version 1.10.3.986 was used on Mac.

Forms and locations of Clojure libraries

Clojure library can exist in a form of a source code or as a JAR file. JAR stands for "java-archive" and it is a zip-archive with all the library files - sources and resources.

tools.deps library that is used behind the scenes when we invoke clj command has a concept of "procurer". Each procurer knows how to download the library and its dependencies. Currently, three procurers exist: local, git and mvn.

local procurer allows you to use a library from a local disk. It can be a folder with a source code or a JAR file.

git procurer allows you to download a library source code from a git repository. Downloaded libraries will be stored in a local folder ~/.gitlibs by default.

mvn procurer gives access to the Maven repositories. These are storages of files widely used in a java-world. Libraries are stored there as JARs. When the library is downloaded from a remote Maven repo it is cached in a local repo on your disk. By default, it lives in ~/.m2/repository. Library JAR should be published to a Maven repo along with the pom.xml file. It is a configuration file for the Maven that contains information about an artifact, for example, its name and version. More information about the POM files can be found in the official documentation.
Later in this article we will use Maven repository called Clojars. It is a community repo for open-source Clojure libraries.

Creating local library

The simplest form of a library is a local folder with a source code. It can be referenced from another project by a relative path.

As an example let's create a test-lib that defines the simple sum function.

The folder structure looks like this:

playground
└── test-lib
    ├── deps.edn
    └── src
        └── basic_math.clj

test-lib/basic_math.clj:

(ns basic-math)

(defn sum [a b]
  (+ a b))

test-lib/deps.edn contains an empty map:

{}

Another project in a playground folder will be the one that uses the test-lib. Let's call it adder. Its main function will take arbitrary number of arguments, sum them and print the result.

Updated folder structure now looks like this:

playground
├── adder
│   ├── deps.edn
│   └── src
│       └── core.clj
└── test-lib
    ├── deps.edn
    └── src
        └── basic_math.clj

adder/core.clj references basic-math namespace from test library, uses the sum function and prints the sum of arguments:

(ns core
  (:require basic-math))

(defn -main [& args]
  (println "Args sum: " (reduce basic-math/sum (map #(Integer/parseInt %) args))))

Here is the content of deps.edn:

{:paths ["src"]
 :deps {test-lib/test-lib  {:local/root "../test-lib"}}}

To make basic-math namespace available, test-lib added under :deps key and pointed to a local folder ../test-lib.

Note that lib name should be qualified, so if you write {test-lib {:local/root "../test-lib"}}, you'll get a warning. At the same time the name itself is not really important because later in the code we won't use it, we use only name of the namespace. So you can write {any-name/any-name {:local/root "../test-lib"}} and that won't be an error.

To check that library successfully used we can switch to adder folder and run main function of core namespace with couple arguments.

$ cd adder
$ clj -M -m core 1 2 3
Args sum:  6

Creating git-based library

Libraries can be stored in a git. Let's push the lib from the previous section to the github and reuse it from there.

First, let's create an empty github repo named clojure-test-lib. After that we need to push there an already existing code of our library.

Here is a series of commands to do this. Note: you have to be inside the test-lib folder when invoking them.

$ cd test-lib
$ git init
$ git add deps.edn
$ git add src/*
$ git commit -m "init"
$ git branch -M main
$ git remote add origin https://github.com/YOUR-GITHUB-NAME/clojure-test-lib.git
$ git push -u origin main

To use the library from the github we need to update an adder/deps.edn file. :git/sha value can be taken from github. It specifies revision of library you want to use:

{:paths ["src"]
 :deps {io.github.YOUR-GITHUB-NAME/clojure-test-lib {:git/sha "4c42a56d9dec002d5a198b61a5d8dcc30b69d3dc"}}}

By contrast with referencing local libraries, here the library name is important. From that name the git url will be deducted for downloading the source code. List of possible library name formats can be found in the official documentation.

Now when we run the updated adder app, we see the notification that our library was downloaded from git:

$ cd adder
$ clj -M -m core 1 2 3
Cloning: https://github.com/YOUR-GITHUB-NAME/clojure-test-lib.git
Checking out: https://github.com/YOUR-GITHUB-NAME/clojure-test-lib.git at 4c42a56d9dec002d5a198b61a5d8dcc30b69d3dc
Args sum:  6

We can use tags to make referencing of particular library version easier. Let's create one by running commands:

$ cd test-lib
$ git tag -a 'v0.0.1' -m 'initial release' 
$ git push --tags

Now adder/deps.edn can be extended with :git/tag key referencing our newly created tag:

{:paths ["src"]
 :deps {io.github.YOUR-GITHUB-NAME/clojure-test-lib {:git/tag "v0.0.1" :git/sha "4c42a5"}}}

Note that :git/sha key still should exist but it can contain a brief version of sha just to make sure that tag wasn't moved to other commit.

Packaging library to a JAR file

Not so long ago you had to use 3rd-party tools to build JAR for own Clojure library. But now official tools.build can be used to create project artificats.

tools.build itself is a Clojure library and it provides API that allows developers to run build actions from Clojure code. It is the core idea of the project that building process should be also written in Clojure and build scripts are just Clojure scripts. Examples can be found in an official documentation.

Let's use tools.build to create JAR for our test-lib project.

First, we need to add build library to test-lib/deps.edn. That file had empty map before and now should look like this:

{:aliases
 {:build {:deps {io.github.clojure/tools.build {:git/tag "v0.6.2" :git/sha "226fb52"}}
          :ns-default build}}}

Here we created build alias that uses dependency on tools.build when invoked. That alias should be used as a tool, with -T option when running clj.

By providing :ns-default build we tell that all commands passed to this alias will be found in the build namespace. So if we run clj -T:build clean, the (clean) function from build.clj file will run.

Now it is time to create the build.clj file itself. It is placed in a root of test-lib project:

playground
├── adder
│   └── ...
└── test-lib
    ├── build.clj      <---
    ├── deps.edn
    └── src
        └── basic_math.clj

Here is the content of build.clj:

(ns build
  (:require [clojure.tools.build.api :as b]))

(def lib 'com.github.YOUR-GITHUB-NAME/clojure-test-lib)
(def version (format "0.0.%s" (b/git-count-revs nil)))
(def class-dir "target/classes")
(def basis (b/create-basis {:project "deps.edn"}))
(def jar-file (format "target/%s-%s.jar" (name lib) version))

(defn clean [_]
  (b/delete {:path "target"}))

(defn jar [_]
  (b/write-pom {:class-dir class-dir
                :lib lib
                :version version
                :basis basis
                :src-dirs ["src"]})
  (b/copy-dir {:src-dirs ["src" "resources"]
               :target-dir class-dir})
  (b/jar {:class-dir class-dir
          :jar-file jar-file}))

At the top of the file we require an API from tools.build library. Than go few declared vars:

lib - fully qualified name of our library. Note: here we used com.github.YOUR-GITHUB-NAME as an organization part of the name. But you are free to use any, without mentioning github.
version - lib's version. In this code versioning depends on amount of git commits made so far. So after every commit your version will bump.
class-dir - folder were we put all files that will go to a JAR file
basis - it is a clojure map with all project settings obtained from project deps.edn and its parents. Probably the most important among them are classpath and dependencies.
jar-file - name of result JAR file

There are two declared functions in a build.clj. (clean) removes our build directory. And (jar) does the main work - fills the build directory with all required files and creates a JAR file with our library.

There are 3 calls to the tools.build inside the (jar):

(b/write-pom) - creates a pom.xml file inside the build directory.
(b/copy-dir) - copies the source files and the resources (if we'd have any) to a build directory
(b/jar) - packs the content of a build directory to a JAR file

Now when everything is ready we can generate JAR file for our library with commands:

$ cd test-lib
$ clj -T:build jar
$ ls target
classes                    clojure-test-lib-0.0.1.jar

Our library now stored in test-lib/target/clojure-test-lib-0.0.1.jar

Lets change adder/deps.edn to use the library from the local jar:

{:paths ["src"]
 :deps {com.github.YOUR-GITHUB-NAME/clojure-test-lib {:local/root "../test-lib/target/clojure-test-lib-0.0.1.jar"}}}

And run the adder again to make sure everything works:

$ cd adder
$ clj -M -m core 1 2 3
Args sum:  6

Installing JAR to local Maven repo

Now we have a JAR file but referencing it by relative path doesn't look nice. Ideally we'd like to have it in some remote Maven repo. But before lets install it in a local repo - ~/.m2/repository.

To do this we'll add a new function to the test-lib/build.clj called (install):

; ... previous content of build.clj ...

(defn install [_]
  (b/install {:basis      basis
              :lib        lib
              :version    version
              :jar-file   jar-file
              :class-dir  class-dir}))

Inside our new function we call a function with the same name from the tools.build library that does actual work.

Now we can create and install JAR of our test library with commands:

$ cd test-lib
$ clj -T:build clean
$ clj -T:build jar
$ clj -T:build install

To check that the library was added to the local repo we can inspect the local folder ~/.m2/repository/com/github/YOUR-GITHUB-NAME/clojure-test-lib/. There should be our JAR inside the folder for version 0.0.1.

Now adder/deps.edn should be changed to use library from maven repo instead of local JAR:

{:paths ["src"]
 :deps {com.github.YOUR-GITHUB-NAME/clojure-test-lib {:mvn/version "0.0.1"}}}

Let's run adder again to confirm that changes work:

$ cd adder
$ clj -M -m core 1 2 3
Args sum:  6

Installing JAR to remote repo

Now it is a time to make our extremely useful library publicly available. We want to push it to the Clojars. As you probably already guessed, we are going to add a new function to deps-edn/build.clj that will be responsible for this action. It will be named (deploy).

Unfortunately the standard tools.build library that we were using before doesn't provide functionality to deploy to Clojars. So we will use a 3rd-party library called deps-deploy.

Let's add it as another dependency of the build alias in the test-lib/deps.edn.

{:aliases
 {:build {:deps {io.github.clojure/tools.build {:git/tag "v0.6.2" :git/sha "226fb52"}
                 slipset/deps-deploy {:mvn/version "RELEASE"}}                            ; <-- new dependency
          :ns-default build}}}

Changes to the test-lib/build.clj add the new (deploy) function:

(ns build
  (:require [clojure.tools.build.api :as b]
            [deps-deploy.deps-deploy :as dd])) ; <--- don't foget to add a new require

; ... previous content of build.clj ...

(defn deploy [_]
  (dd/deploy {:installer :remote
              :artifact jar-file
              :pom-file (b/pom-path {:lib lib :class-dir class-dir})}))

As you can see, our (deploy) function relies on the function with the same name from deps-deploy package. Being invoked it will take the JAR file and pom.xml and publish them to Clojars. (b/pom-path) is a helper function from tools.build that retuns path to the pom.xml.

Before you will be able to publish anything to the Clojars, you need to go to clojars.org, create an account there and add a "deploy token". It is used in a place of a password when deploying from the command line.

When you've created an account and a deploy token, deploying the lib will be as simple as running our newly created build command with couple additionl environment variables set:

$ env CLOJARS_USERNAME=USER-NAME CLOJARS_PASSWORD=CLOJARS_XXXXXXXX clj -T:build deploy

CLOJARS_USERNAME - your Clojars account name

CLOJARS_PASSWORD - your created deploy token. Not a login password.

After executing previous command you should see the shell messages saying that *.jar and *.pom were successfully uploaded to Clojars. Also you will see a new library on the Clojars dashboard.

adder/deps.edn doesn't need to be changed, because the way we reference test-lib dependency is the same for local and remote Maven repos.

Modifying library to be suitable for ClojureScript

Our test-lib contains pure Clojure code and doesn't depend on anything Java-specific, so it would be nice to make it available for ClojureScript as well.

At first, let's create a simple ClojureScript project called adder-cljs and try to use test-lib as is.

Here is a structure of the new project created in the playground folder on the same level as the already existing adder and test-lib projects:

adder-cljs
├── deps.edn
└── src
    └── core.cljs

core.cljs implements the same logic that we had before in the adder/src/core.clj. The only difference is that we use the js/parseInt for turning arguments to integers:

(ns core
  (:require basic-math))

(defn -main [& args]
  (println "Args sum: " (reduce basic-math/sum (map js/parseInt args))))

adder-cljs/deps.edn contains dependencies for ClojureScript itself and our test-lib:

{:deps {org.clojure/clojurescript        {:mvn/version "1.10.879"}
        com.github.YOUR-GITHUB-NAME/clojure-test-lib {:mvn/version "0.0.1"}}}

Command for running the script from a terminal will be:

$ clj -M -m cljs.main -re node -m core 1 2 3

And as a result we will get an exception:

Unexpected error (ExceptionInfo) compiling at (REPL:1).
No such namespace: basic-math, could not locate basic_math.cljs, basic_math.cljc, or JavaScript source providing "basic-math" (Please check that namespaces with dashes use underscores in the ClojureScript file name) in file core.cljs

It says that basic-math can't be found because it is not in a .cljs or *.cljc file. As we remember test_lib keeps this namespace in the basic_math.clj. **Fortunately the only change we need to make clojure code usable from both Clojure and ClojureScript is simply store it in *.cljc file.* More sophisticated libraries can also use "reader conditionals" to add the Clojure- or ClojureScript-specific expressions to the code. More info can be found in the official documentation.

So let's rename test-lib/src/basic_math.clj to test-lib/src/basic_math.cljc and publish a new version of the library:

$ cd test-lib
$ mv src/basic_math.clj src/basic_math.cljc
$ git add .
$ git commit -m "make library usable for ClojureScript"
$ clj -T:build clean
$ clj -T:build jar
$ env CLOJARS_USERNAME=USER-NAME CLOJARS_PASSWORD=CLOJARS_XXXXXXXX clj -T:build deploy

As you remember, build.clj file of our library uses commits count for changing version name. This is why we've made a commit here before deploying the library.

As a result, version 0.0.2 of our library now should be pushed to the Clojars.

To use it let's change adder-cljs/deps.edn and bump library version there:

{:deps {org.clojure/clojurescript        {:mvn/version "1.10.879"}
        com.github.YOUR-GITHUB-NAME/clojure-test-lib {:mvn/version "0.0.2"}}}   ; !!!

And run adder-cljs again:

$ clj -M -m cljs.main -re node -m core 1 2 3
Args sum:  6

Adding pom.xml to library root

Up to now the pom.xml file for our library was generated automatically by a call to the (write-pom) function in the test-lib/build.clj and stored in the temporary target folder. Drawback of this is that we can't add any persistent changes to this file because they will be wiped out when clj -T:bulid clean invoked. But fortunately (write-pom) is clever enough and if you have some pom.xml file in the root of the project, it will be taken as a basis and merged with a generated one.

Let's use this feature to add a description and a homepage url to our library so they can be seen on the Clojars page.

First, let's go to the test-lib directory and copy an already generated pom.xml to the root of a project for future modification:

$ cd test-lib
$ cp target/classes/META-INF/maven/com.github.YOUR-GITHUB-NAME/clojure-test-lib/pom.xml .

Now we are going to modify the new pom.xml. We want to replace the actual version of the library with "VERSION" placeholder just to avoid future confusion. Also the description and url fields need to be added. Here is an updated content of the pom.xml, slightly truncated for readability:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <packaging>jar</packaging>
  <groupId>com.github.YOUR-GITHUB-NAME</groupId>
  <artifactId>clojure-test-lib</artifactId>
  <version>VERSION</version>                                               <!-- changed -->
  <name>clojure-test-lib</name>
  <description>Test library for article on Clojure libraries</description> <!-- added -->
  <url>https://github.com/YOUR-GITHUB-NAME/clojure-test-lib</url>          <!-- added -->
  .....
</project>

And now let's commit these changes and push the updated library to the Clojars:

$ cd test-lib
$ git add .
$ git commit -m "Added root pom.xml with description and homepage url"
$ clj -T:build clean
$ clj -T:build jar
$ env CLOJARS_USERNAME=USER-NAME CLOJARS_PASSWORD=CLOJARS_XXXXXXXX clj -T:build deploy

Now, when we go to Clojars, on the page of our library we can see that the version number was bumped, description added and there is a link to our homepage. That means that the url and description fields of root pom.xml were successfully used and merged with the generated fields like version.

Creating library project with `clj-new`

So far to setup the test-lib project we've made the following:

added dependencies for tools.build and deps-deploy
created the build.clj with own build commands
added the root pom.xml file

These steps aren't unique for the test-lib and you'll need to repeat them again when creating another libraries. Fortunately, there is a project called clj-new that will save you from doing similar work again and again.

With the clj-new you can generate a project template that already equipped with all the features we've discussed and even more.

Here we'll cover the basic steps to create a library with clj-new but please go and read the official docs for the detailed instructions and up to date version of the library.

First, we need to install the clj-new as a tool to make it available for use:

$ clojure -Ttools install com.github.seancorfield/clj-new '{:git/tag "v1.2.362"}' :as clj-new

Now, to create a library we need to run the command:

$ clojure -Tclj-new lib :name com.github.YOUR-GITHUB-NAME/clojure-test-lib

After that we'll get the library template:

clojure-test-lib
├── CHANGELOG.md
├── LICENSE
├── README.md
├── build.clj
├── deps.edn
├── doc
│   └── intro.md
├── pom.xml
├── resources
├── src
│   └── YOUR-GITHUB-NAME
│       └── clojure_test_lib.clj
└── test
    └── YOUR-GITHUB-NAME
        └── clojure_test_lib_test.clj

Please take a look at build.clj file that contains available build commands. Note, that the command for creating a JAR file called here ci (which stands for "continuous integration"), because it doesn't only create a JAR but also runs tests.

Also please read the README.md file. It has the examples of the build commands and an important note that you have to fix the existing test to get a successfull build ;)

DEV Community: Volodymyr Kozieiev

Full Clojure project in 5 seconds!

Install deps-new

"Tools" in Clojure CLI

Installing deps-new tool

Create a library

Content of created library

Create an application

Create a minimal "scratch" project

Is Clojure the only language you need?

Video version

The question

Backend

FrontEnd

Mobile

Scripting

Desktop

Embedded

Conclusion:

How to create a library that works with Clojure and ClojureScript

Content:

Creating Clojure version of logger library

Creating Clojure app to use logger library

Introducing reader conditionals

Making the logger library work with ClojureScript

Creating ClojureScript app to use logger library

Links

Packaging Clojure projects into jars and uberjars with tools.build

Table of contents

Video version of this article

Jars and uberjars

jar/uberjar content

Resouces

MANIFEST.mf

pom.xml

tools.build library

adding tools.build to a project

creating a jar for the library

creating a runnable ubjerjar

more tools.build functions

Build and run Clojure projects. CLI, tools.deps and deps.edn guide

Table of contents

Note for readers

Video version of this article

What is Clojure CLI?

Difference between clj and clojure executables

Most usable clj options

-M option to work with clojure.main namespace

Running (-main) function from namespace

Running clojure file as a script

-X option to run specific functions

deps.edn configuration files

:paths key

:deps key

:aliases key

Aliases for clj -M

Aliases for clj -X

tools.deps library

Managing dependencies

Building classpath

Running REPL with clj -A

Real-world examples

Cognitect test-runner setup

clj-new library setup

Other clj capabilities

Conclusion

Creating and publishing Clojure libraries

Table of contents:

Video version of this article

Notes for readers

Forms and locations of Clojure libraries

Creating local library

Creating git-based library

Packaging library to a JAR file

Installing JAR to local Maven repo

Installing JAR to remote repo

Modifying library to be suitable for ClojureScript

Adding pom.xml to library root

Creating library project with clj-new

Install `deps-new`

Installing `deps-new` tool

`MANIFEST.mf`

`pom.xml`

`tools.build` library

adding `tools.build` to a project

more `tools.build` functions

Most usable `clj` options

`-M` option to work with `clojure.main` namespace

`-X` option to run specific functions

`deps.edn` configuration files

`:paths` key

`:deps` key

`:aliases` key

Aliases for `clj -M`

Aliases for `clj -X`

`tools.deps` library

Running REPL with `clj -A`

Cognitect `test-runner` setup

`clj-new` library setup

Other `clj` capabilities

Creating library project with `clj-new`