Building a Library JAR

Assuming this alias in your user or project deps.edn file:

  ;; build a jar (library):
  :jar {:replace-deps {com.github.seancorfield/depstar {:mvn/version "2.1.303"}}
        :exec-fn hf.depstar/jar
        :exec-args {}}

Building a library JAR file can be as simple as:

clojure -X:jar :jar MyLib.jar

This will use the project's deps.edn file (in the current directory) to calculate the "basis" for the project, and then build a "thin" library JAR file from all of the directories and non-.jar files that would be on the classpath by default for the project. In a simple project, that is likely to be just whatever is in :paths, which is typically the src folder, and optionally the resources folder.

For a project with :local/root or :git/url dependencies, the classpath will include those directories as well, and depstar will also include those (source) files in the JAR as well. If you plan to publish this library JAR files and those sources are not already available as dependencies for your users, this can be convenient since your library will include them directly. This is not always what you want, so you can specify :paths-only true to use only the directories in the :paths entry in deps.edn instead, or you can use the :exclude option to provide a list of strings to use as regex patterns to exclude certain files from being copied into the JAR file.

Sometimes you might want to include additional files that are not on the default classpath of a project, but are added through one or more aliases that have their own :extra-paths (or :extra-deps). If you want depstar to take those aliases into account, you can specify the :aliases option (which takes a vector of keywords). For example, if your deps.edn file has:

  :assets {:extra-paths ["web/assets"]}

then you can ask depstar to include them like this:

clojure -X:jar :jar MyLib.jar :aliases '[:assets]'

If you specify :paths-only true, any such :extra-paths from aliases will be included in the JAR but local/git dependencies from :extra-deps will not.

A library JAR will also include a manifest, generated by depstar, which includes information about who built the JAR (Built-By: with your username, if available) and how: Created-By: depstar and Build-Jdk: (a trimmed version of the java.version system property). You can specify additional entries for the manifest using the :manifest option, which expects a hash map argument. Keywords are capitalized around -. Values are converted to strings. :the-answer 42 will become The-Answer: 42 in the manifest.

If you plan to publish your library to Clojars or similar, you will need a pom.xml file. If you created your project with clj-new, then you will have a fully-detailed pom.xml file. Otherwise, you can either create one manually (ugh! XML!) or you can ask depstar to generate a minimal one for you:

clojure -X:jar :jar MyLib.jar :sync-pom true :version '"1.2.3"' :group-id io.github.myname :artifact-id my-cool-lib

When creating a new pom.xml file, all three of :version, :group-id, and :artifact-id are required. Once you have a pom.xml file, you can have depstar update any or all of those fields by specifying just the options you want to change. See pom.xml for more detail about creating and synchronizing this file.

Note: if a pom.xml file exists (or is created), it will be included in the JAR file, along with a pom.properties file, unless you specify :no-pom true.

Additional options that can affect library JAR building:

• :exclude -- a vector of strings used as regex patterns to exclude specific files from the JAR,
• :repro false -- consider the user deps.edn file when calculating the "basis" (in case you want to use aliases from that, as well as from the project deps.edn file),
• :verbose true -- print out the names of all the files being added to the JAR as well as the contents of the generated manifest, and the generated pom.properties if a pom.xml file is used.

Finally, although it is generally discouraged, it is possible to AOT compile some or all of your code prior to adding it to the library. See AOT Compilation for more details. There are many caveats to this, including potential compatibility issues with different versions of Clojure, and the fact that AOT compilation is, unfortunately, transitive, so compiling your code ends up compiling everything that your code references so you generally need a liberal set of :exclude regex patterns to ensure that you do not get a lot of unwanted .class files in your supposedly "thin" library JAR!