Building an Application JAR

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

  ;; build an uberjar (application) with AOT compilation by default:
  :uberjar {:replace-deps {com.github.seancorfield/depstar {:mvn/version "2.1.278"}}
            :exec-fn hf.depstar/uberjar
            :exec-args {:aot true}}

Building an application JAR file can be as simple as:

clojure -X:uberjar :jar MyProject.jar :main-class project.core

where project.core is your main namespace -- with (:gen-class) in the ns form and a -main function. The :exec-args already specify :aot true so the namespace specified by :main-class will be compiled, along with any Clojure code that it depends on (compilation is transitive).

An uberjar created by that command can be run as follows:

java -jar MyProject.jar

When building an application "uber" JAR file, depstar will use the project's deps.edn file (in the current directory) to calculate the "basis" for the project, and then build the JAR file from all of the files and JAR files that would be on the classpath by default for the project. In a simple project, that is likely to be whatever is in :paths, which is typically the src folder, and optionally the resources folder, as well as all the JAR files that represent the full set of dependencies from :deps (including any transitive dependencies).

Sometimes you might want to include additional files or dependencies that are not on the default classpath of a project, but are added through one or more aliases that have their own :extra-paths and/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:uberjar :jar MyProject.jar :aliases '[:assets]'

An application 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.

Note: if a pom.xml file exists (or is created by depstar, using the :sync-pom true option), it will be included in the JAR file, along with a pom.properties file, unless you specify :no-pom true. A pom.xml file is not required for an application JAR, however.

If you choose to build an application JAR file without AOT compilation or without specifying a main namespace, you can still run the JAR file but you need a longer command:

clojure -X:uberjar :aot false :jar MyProject.jar

java -cp MyProject.jar clojure.main -m project.core

This takes advantage of the fact that clojure.main is already AOT compiled and has a -main function (and Clojure will be included in your application JAR file because it is a dependency of your project), and that -main function understands the -m command-line option to specify a namespace to be required and then a -main function within that namespace to be executed.

The simplest AOT compilation for an application JAR just starts at the :main-class namespace but you can tell depstar to compile multiple namespaces, or even all namespaces it finds in your project, using the :compile-ns option. For more details, see AOT Compilation.

Additional options that can affect application 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.