Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/taylorwood/clj.native-image

Build GraalVM native images with Clojure Deps and CLI tools
https://github.com/taylorwood/clj.native-image

cli clojure graalvm native-image

Last synced: 12 days ago
JSON representation

Build GraalVM native images with Clojure Deps and CLI tools

Host: GitHub
URL: https://github.com/taylorwood/clj.native-image
Owner: taylorwood
License: mit
Created: 2018-05-25T17:55:03.000Z (about 6 years ago)
Default Branch: master
Last Pushed: 2021-08-07T12:27:34.000Z (almost 3 years ago)
Last Synced: 2024-03-07T01:35:18.080Z (4 months ago)
Topics: cli, clojure, graalvm, native-image
Language: Clojure
Homepage:
Size: 29.3 KB
Stars: 267
Watchers: 9
Forks: 18
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE

Lists

awesome-stars - clj.native-image

README

# clj.native-image

Build [GraalVM](https://www.graalvm.org) native images using [Clojure Deps and CLI tools](https://clojure.org/guides/deps_and_cli).

This should be useful for creating lightweight, native CLI executables using Clojure and `deps.edn`.
See [clj.native-cli](https://github.com/taylorwood/clj.native-cli) for a starter project template.

_This project depends on tools.deps.alpha and should be considered alpha itself._

## Prerequisites

- [Clojure CLI tools](https://clojure.org/guides/getting_started#_clojure_installer_and_cli_tools)
- [GraalVM](https://www.graalvm.org/downloads/)

**NOTE:** As of GraalVM 19.0.0, `native-image` is no longer included by default:
> 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)
```

## Usage

Assuming a project structure like this:
```
.
├── deps.edn
└── src
└── core.clj
```

In your `deps.edn` specify an alias with a dependency on `clj.native-image`:
```clojure
{:aliases {:native-image
{:main-opts ["-m" "clj.native-image" "core"
"--initialize-at-build-time"
;; optional native image name override
"-H:Name=core"]
:jvm-opts ["-Dclojure.compiler.direct-linking=true"]
:extra-deps
{clj.native-image/clj.native-image
{:git/url "https://github.com/taylorwood/clj.native-image.git"
:sha "7708e7fd4572459c81f6a6b8e44c96f41cdd92d4"}}}}}
```

Where `core.clj` is a class with `-main` entrypoint, for example:
```clojure
(ns core
(:gen-class))
(defn -main [& args]
(println "Hello, World!"))
```

From your project directory, invoke `clojure` with the `native-image` alias, specifying the main namespace
(`core` in example above):
```
➜ clojure -A:native-image
Loading core
Compiling core
Building native image 'core' with classpath 'classes:src:etc.'

classlist: 1,944.26 ms
8<----------------------
[total]: 38,970.37 ms
```
Note: Either `GRAALVM_HOME` environment variable must be set, or GraalVM's `native-image` path must be passed as an argument,
and any [additional arguments](https://www.graalvm.org/docs/reference-manual/aot-compilation/#image-generation-options)
will be passed to `native-image` e.g.:
```
➜ clojure -A:native-image --verbose
```

You can now execute the native image:
```
➜ ./core
Hello, World!
```

See [this Gist](https://gist.github.com/taylorwood/23d370f70b8b09dbf6d31cd4f27d31ff) for another example.

### Example Projects

There are example deps.edn projects in the [lein-native-image](https://github.com/taylorwood/lein-native-image) repo:
- [jdnsmith](https://github.com/taylorwood/lein-native-image/blob/master/examples/http-api) - CLI JSON-to-EDN transformer
- [http-api](https://github.com/taylorwood/lein-native-image/blob/master/examples/http-api) - simple HTTP API server
- [clojurl](https://github.com/taylorwood/clojurl) - cURL-like tool using clojure.spec, HTTPS, hiccup

## Caveats

The `--no-server` flag is passed to `native-image` by default, to avoid creating orphaned build servers.

Also see [caveats](https://github.com/taylorwood/lein-native-image#caveats) section of lein-native-image.

## References

[GraalVM Native Image AOT Compilation](https://www.graalvm.org/docs/reference-manual/aot-compilation/)

This project was inspired by [depstar](https://github.com/healthfinch/depstar).

## Contributing

You'll need Clojure CLI tooling and GraalVM installed to test locally.
Just change the source of the `clj.native-image` dependency to a `:local/root` instead of `:git/url`.

Issues, PRs, and suggestions are welcome!

## License

Distributed under the MIT License.