lein-native-image

A Leiningen plugin for generating GraalVM native images from your project.

The

lein native-image

native-image

^{For deps.edn projects, try clj.native-image.}

Prerequisites

• This plugin depends on GraalVM to build native images.

NOTE: As of GraalVM 19.0.0,

native-image

Native Image was extracted from the base GraalVM distribution. Currently it is available as an early adopter plugin. To install it, run:

gu install native-image

. After this additional step, the

native-image

executable will be in the

bin

directory, as for the previous releases.

  ➜ $GRAALVM_HOME/bin/gu install native-image
  Downloading: Component catalog from www.graalvm.org
  Processing component archive: Native Image
  Downloading: Component native-image: Native Image  from github.com
  Installing new component: Native Image licence files (org.graalvm.native-image, version 19.0.0)

• Your project.clj must set a

  :main

  namespace w/entrypoint and support AOT compilation:

  clojure
  :main ^:skip-aot my-app.core
  

Examples

See the examples directory for projects that can be compiled to native images with GraalVM:

• jdnsmith - CLI command to read JSON from stdin and write EDN to stdout.
• http-api - Basic HTTP server using Ring, Compojure, http-kit.
• nlp - CLI command to analyze sentiment of text using StanfordNLP. Includes examples of reflection hints and delaying class initialization.
• clojurl - cURL-like tool using clojure.spec, HTTPS, hiccup.

Usage

1. Configure your project with a custom image name, path to GraalVM's home directory or

   native-image

   path, or

   native-image

   CLI options: ```clojure (defproject my-app "0.1.0" :plugins [[io.taylorwood/lein-native-image "0.3.1"]] ;; or in ~/.lein/profiles.clj

   :native-image {:name "my-app" ;; name of output image, optional :graal-bin "/path/to/graalvm/" ;; path to GraalVM home, optional :opts ["--verbose"]} ;; pass-thru args to GraalVM native-image, optional

   ;; optionally set profile-specific :native-image overrides :profiles {:test ;; e.g. lein with-profile +test native-image {:native-image {:opts ["--report-unsupported-elements-at-runtime" "--initialize-at-build-time" "--verbose"]}}

            :uberjar ;; used by default
            {:aot :all
             :native-image {:jvm-opts ["-Dclojure.compiler.direct-linking=true"]}}})
   

   `:native-image` config keys:
   

   • :name

     is an optional name for the generated native image.
   • The

     :graal-bin

     path can be specified as a string or resolved from an environment variable using a keyword e.g.

     :env/GRAALVM_HOME

     . If

     :graal-bin

     is unspecified, the

     GRAALVM_HOME

     environment variable will be used by default.

   • :opts

     is an optional vector of arguments to

     native-image

     ; see its documentation for more.

   Note: task-specific

   :native-image

   profile will be merged in by default, or the

   :uberjar

   profile if that doesn't exist.

   You can also specify these in your Leiningen user profile

   ~/.lein/profiles.clj

   :

   clojure
   {:user {:plugins [[io.taylorwood/lein-native-image "0.3.1"]]
           :native-image {:graal-bin "/path/to/graalvm-ce-19.0.0/Contents/Home/bin"}}}
   

2. Build a native image from your project:

   ➜ lein native-image
   Compiling my-app.core
   Build on Server(pid: 36212, port: 26681)
      classlist:     332.89 ms
          (cap):   1,289.90 ms
      8

3. Execute the native image:

   ➜ ./target/my-app with optional args
   Hello, World!
   

Caveats

The primary benefits to using a GraalVM native image are faster startup, lower memory requirements, and smaller distribution footprint (no JDK/JRE required). This doesn't necessarily mean the same code will run faster than it would on the JVM. GraalVM Community Edition and Enterprise Edition also have different performance characteristics.

GraalVM's native image capabilities have evolved across many release candidates. Several AOT issues have been fixed since 1.0.0-RC1. GraalVM and Substrate VM's support for AOT compilation and native images has limitations, and there are unsupported features. This release and its example projects were tested with GraalVM 19.0.0 Community Edition.

GraalVM 19.0.0 (first non-RC release) changes the default class-initialization behavior of

native-image

--initialize-at-build-time

native-image

There is a known issue where usages of

clojure.core/locking

locking

When the

--report-unsupported-elements-at-runtime

native-image

native-image

Set

--enable-url-protocols=http

--enable-url-protocols=http,https

Specifying

:jvm-opts ["-Dclojure.compiler.direct-linking=true"]

This plugin doesn't shutdown GraalVM

native-image

:opts ["--no-server"]

native-image

References

GraalVM Native Image AOT Compilation

Native Clojure with GraalVM

Instant Netty Startup using GraalVM (and source)

Contributing

You'll need Leiningen and GraalVM installed to build and test the plugin.

Issues and PRs are welcome!

License

Copyright © 2019 Taylor Wood.

Distributed under the MIT License.