{"id":13760455,"url":"https://github.com/taylorwood/lein-native-image","last_synced_at":"2025-05-07T20:55:53.751Z","repository":{"id":32458752,"uuid":"134150744","full_name":"taylorwood/lein-native-image","owner":"taylorwood","description":"A Leiningen plugin to build GraalVM native images","archived":false,"fork":false,"pushed_at":"2022-05-09T22:24:55.000Z","size":38,"stargazers_count":247,"open_issues_count":0,"forks_count":6,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-07T20:55:43.755Z","etag":null,"topics":["clojure","graalvm","lein-plugin","leiningen","native-image"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taylorwood.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-20T12:59:00.000Z","updated_at":"2025-02-18T14:00:22.000Z","dependencies_parsed_at":"2022-08-08T19:00:08.251Z","dependency_job_id":null,"html_url":"https://github.com/taylorwood/lein-native-image","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylorwood%2Flein-native-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylorwood%2Flein-native-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylorwood%2Flein-native-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylorwood%2Flein-native-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taylorwood","download_url":"https://codeload.github.com/taylorwood/lein-native-image/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252954375,"owners_count":21830902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clojure","graalvm","lein-plugin","leiningen","native-image"],"created_at":"2024-08-03T13:01:10.626Z","updated_at":"2025-05-07T20:55:53.731Z","avatar_url":"https://github.com/taylorwood.png","language":"Clojure","funding_links":[],"categories":["Clojure"],"sub_categories":[],"readme":"# lein-native-image\n\nA Leiningen plugin for generating [GraalVM](https://www.graalvm.org) native images from your project.\n\nThe `lein native-image` command compiles your project then uses GraalVM's\n[`native-image`](https://www.graalvm.org/docs/reference-manual/aot-compilation/) to build a native image.\n\n[![Clojars Project](https://img.shields.io/clojars/v/io.taylorwood/lein-native-image.svg)](https://clojars.org/io.taylorwood/lein-native-image)\n\n\u003csup\u003eFor deps.edn projects, try [clj.native-image](https://github.com/taylorwood/clj.native-image).\u003c/sup\u003e\n\n## Prerequisites\n\n* This plugin depends on [GraalVM](https://www.graalvm.org/downloads/) to build native images.\n\n  **NOTE:** As of GraalVM 19.0.0, `native-image` is no longer included by default:\n  \u003e 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.\n\n  ```\n  ➜ $GRAALVM_HOME/bin/gu install native-image\n  Downloading: Component catalog from www.graalvm.org\n  Processing component archive: Native Image\n  Downloading: Component native-image: Native Image  from github.com\n  Installing new component: Native Image licence files (org.graalvm.native-image, version 19.0.0)\n  ```\n  \n* Your project.clj must set a `:main` namespace w/entrypoint and support AOT compilation:\n  ```clojure\n  :main ^:skip-aot my-app.core\n  ```\n\n## Examples\n\nSee the [examples](examples) directory for projects that can be compiled to native images with GraalVM:\n\n* [jdnsmith](examples/jdnsmith) - CLI command to read JSON from stdin and write EDN to stdout.\n* [http-api](examples/http-api) - Basic HTTP server using Ring, Compojure, http-kit.\n* [nlp](examples/nlp) - CLI command to analyze sentiment of text using StanfordNLP. Includes examples of reflection hints and delaying class initialization.\n* [clojurl](https://github.com/taylorwood/clojurl) - cURL-like tool using clojure.spec, HTTPS, hiccup.\n\n## Usage\n\n1. Configure your project with a custom image name, path to GraalVM's home directory or `native-image` path,\n   or `native-image` CLI options:\n    ```clojure\n    (defproject my-app \"0.1.0\"\n      :plugins [[io.taylorwood/lein-native-image \"0.3.1\"]]    ;; or in ~/.lein/profiles.clj\n\n      :native-image {:name \"my-app\"                 ;; name of output image, optional\n                     :graal-bin \"/path/to/graalvm/\" ;; path to GraalVM home, optional\n                     :opts [\"--verbose\"]}           ;; pass-thru args to GraalVM native-image, optional\n\n      ;; optionally set profile-specific :native-image overrides\n      :profiles {:test    ;; e.g. lein with-profile +test native-image\n                 {:native-image {:opts [\"--report-unsupported-elements-at-runtime\"\n                                        \"--initialize-at-build-time\"\n                                        \"--verbose\"]}}\n    \n                 :native-image ;; used by default\n                 {:jvm-opts [\"-Dclojure.compiler.direct-linking=true\"]}})\n    ```\n\n    `:native-image` config keys:\n    - `:name` is an optional name for the generated native image. \n    - The `:graal-bin` path can be specified as a string or resolved from an environment variable\n      using a keyword e.g. `:env/GRAALVM_HOME`.\n      If `:graal-bin` is unspecified, the `GRAALVM_HOME` environment variable will be used by default.\n    - `:opts` is an optional vector of arguments to `native-image`; see its\n      [documentation](https://www.graalvm.org/docs/reference-manual/aot-compilation/#image-generation-options) for more.\n\n    Note: task-specific `:native-image` profile will be merged in by default, or the `:uberjar` profile\n    if that doesn't exist.\n\n    You can also specify these in your Leiningen user profile `~/.lein/profiles.clj`:\n    ```clojure\n    {:user {:plugins [[io.taylorwood/lein-native-image \"0.3.1\"]]\n            :native-image {:graal-bin \"/path/to/graalvm-ce-19.0.0/Contents/Home/bin\"}}}\n    ```\n\n1. Build a native image from your project:\n    ```\n    ➜ lein native-image\n    Compiling my-app.core\n    Build on Server(pid: 36212, port: 26681)\n       classlist:     332.89 ms\n           (cap):   1,289.90 ms\n       8\u003c----------------------\n           write:     932.61 ms\n         [total]:  11,789.08 ms\n    Created native image /path/to/my-app/target/my-app\n    ```\n\n1. Execute the native image:\n    ```\n    ➜ ./target/my-app with optional args\n    Hello, World!\n    ```\n\n## Caveats\n\nThe primary benefits to using a GraalVM native image are faster startup, lower memory requirements,\nand smaller distribution footprint (no JDK/JRE required). This doesn't necessarily mean the same code\nwill _run_ faster than it would on the JVM.\nGraalVM Community Edition and Enterprise Edition also have different performance characteristics.\n\nGraalVM's native image capabilities have evolved across many release candidates. Several AOT issues have been fixed since 1.0.0-RC1.\nGraalVM and Substrate VM's support for AOT compilation and native images has [limitations](https://github.com/oracle/graal/blob/master/substratevm/LIMITATIONS.md),\nand there are [unsupported features](https://github.com/oracle/graal/blob/master/substratevm/REFLECTION.md).\nThis release and its example projects were tested with GraalVM 19.0.0 Community Edition.\n\nGraalVM 19.0.0 (first non-RC release) changes the default class-initialization behavior of `native-image`.\nNow you must specify `--initialize-at-build-time` explicitly in your `native-image` options.\n\nThere is a [known issue](https://dev.clojure.org/jira/browse/CLJ-1472) where usages of `clojure.core/locking` macro will fail compilation.\nClojure 1.10 depends on a version of clojure.spec that uses `locking`.\nSee [this commit](https://github.com/taylorwood/clojurl/commit/12b96b5e9a722b372f153436b1f6827709d0f2ab) for an example workaround.\n\nWhen the `--report-unsupported-elements-at-runtime` flag is set,\nsome `native-image` AOT compilation issues will be deferred as runtime exceptions.\nYou can try specifying this flag if `native-image` compilation fails.\nTo avoid unexpected errors at runtime, don't use this flag for \"production\" builds.\n\nSet `--enable-url-protocols=http` to use HTTP libraries.\nHTTPS is available as of 1.0.0-RC7 (e.g. `--enable-url-protocols=http,https`)\nbut [requires additional configuration](https://github.com/oracle/graal/blob/master/substratevm/URL-PROTOCOLS.md#https-support).\n\nSpecifying `:jvm-opts [\"-Dclojure.compiler.direct-linking=true\"]` might allow for better\ncompile-time optimizations.\n\nThis plugin doesn't shutdown GraalVM `native-image` build servers after builds, so that subsequent\nbuilds are slightly faster. You can set `:opts [\"--no-server\"]` to not spawn a build server at\nall, or use GraalVM's `native-image` command directly to manage build server(s).\n\n### References\n\n[GraalVM Native Image AOT Compilation](https://www.graalvm.org/docs/reference-manual/aot-compilation/)\n\n[Native Clojure with GraalVM](https://www.innoq.com/en/blog/native-clojure-and-graalvm/)\n\n[Instant Netty Startup using GraalVM](https://medium.com/graalvm/instant-netty-startup-using-graalvm-native-image-generation-ed6f14ff7692) (and [source](https://github.com/cstancu/netty-native-demo))\n\n## Contributing\n\nYou'll need Leiningen and GraalVM installed to build and test the plugin.\n\nIssues and PRs are welcome!\n\n## License\n\nCopyright © 2019 Taylor Wood.\n\nDistributed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaylorwood%2Flein-native-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaylorwood%2Flein-native-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaylorwood%2Flein-native-image/lists"}