{"id":20727917,"url":"https://github.com/scalameta/sbt-native-image","last_synced_at":"2025-04-06T18:17:02.881Z","repository":{"id":40575450,"uuid":"291246221","full_name":"scalameta/sbt-native-image","owner":"scalameta","description":"Plugin to generate native-image binaries with sbt","archived":false,"fork":false,"pushed_at":"2024-04-20T20:47:43.000Z","size":112,"stargazers_count":254,"open_issues_count":28,"forks_count":23,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-30T16:12:29.509Z","etag":null,"topics":["github-actions","graalvm","graalvm-native-image","native-image","sbt","scala"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scalameta.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-29T10:04:58.000Z","updated_at":"2025-03-27T01:40:57.000Z","dependencies_parsed_at":"2024-04-20T10:43:11.014Z","dependency_job_id":"a7636563-c908-4f52-bf70-297841669af4","html_url":"https://github.com/scalameta/sbt-native-image","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalameta%2Fsbt-native-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalameta%2Fsbt-native-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalameta%2Fsbt-native-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scalameta%2Fsbt-native-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scalameta","download_url":"https://codeload.github.com/scalameta/sbt-native-image/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247526768,"owners_count":20953143,"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":["github-actions","graalvm","graalvm-native-image","native-image","sbt","scala"],"created_at":"2024-11-17T04:34:47.375Z","updated_at":"2025-04-06T18:17:02.862Z","avatar_url":"https://github.com/scalameta.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Generate native-image binaries with sbt\n\nThis plugin makes it easy to generate native-image binaries with sbt. Key\nfeatures:\n\n- automatic GraalVM native-image installation powered by\n  [Coursier](https://get-coursier.io/), no need to start sbt with a custom\n  `$JAVA_HOME` or spin up Docker. See\n  [One-click install for Scala](https://scala-lang.org/2020/06/29/one-click-install.html)\n  for more details.\n- automatic support for Scala 2.12.12+ and 2.13.3+, no need to deal with issues\n  like [scala/bug#11634](https://github.com/scala/bug/issues/11634).\n- works with Scala 3 (Dotty)\n- get a notification when the binary is ready to use.\n- works on macOS, Windows and Linux.\n- works with Java 8 and Java 11.\n\n**Overview:**\n\n- [Getting started](#getting-started)\n- [Configuration](#configuration)\n- [Generate native-image from GitHub Actions](#generate-native-image-from-github-actions)\n- [Comparison with sbt-native-packager](#comparison-with-sbt-native-packager)\n\n## Getting started\n\nFirst, add the sbt plugin to your build in `project/plugins.sbt`.\n\n[![](https://index.scala-lang.org/scalameta/sbt-native-image/latest.svg?color=blue)](https://github.com/scalameta/sbt-native-image/releases)\n\n```scala\n// project/plugins.sbt\naddSbtPlugin(\"org.scalameta\" % \"sbt-native-image\" % \"0.3.2\")\n```\n\nNext, enable the plugin to your native-image application in `build.sbt` and\nconfigure the main class.\n\n```diff\n  // build.sbt\n  lazy val myNativeImageProject = project\n+   .enablePlugins(NativeImagePlugin)\n    .settings(\n      // ...\n+     Compile / mainClass := Some(\"com.my.MainClass\")\n    )\n```\n\nAdditionally, if your app uses reflection or JNI, you may need to run `nativeImageRunAgent` command to capture runtime information. For more details, see [`nativeImageRunAgent`](#nativeimagerunagent) section.\n\n\nFinally, run the `nativeImage` task to generate the binary.\n\n```sh\n$ sbt\n\u003e myNativeImageProject/nativeImage\n...\n[info] Native image ready!\n[info] /path/to/your/binary\n```\n\nOptionally, use `nativeImageRun` to execute the generated binary and manually\ntest that it works as expected.\n\n```sh\n\u003e myNativeImageProject/nativeImageRun argument1 argument 2\n# output from your native-image binary\n```\n\n## Configuration\n\nsbt-native-image provides several settings, tasks and input tasks to customize\nnative-image generation and to automate your native-image workflows.\n\n- [`nativeImage`](#nativeimage): generate a native image\n- [`nativeImageOptions`](#nativeimageoptions): customize native image generation\n- [`nativeImageRun`](#nativeimagerun): execute the generated native image\n- [`nativeImageCopy`](#nativeimagecopy): generate a native image and copy the\n  binary\n- [`nativeImageVersion`](#nativeimageversion): the GraalVM version to use for\n  native-image\n- [`nativeImageJvm`](#nativeimagejvm): the GraalVM JVM version to use for\n  native-image\n- [`nativeImageJvmIndex`](#nativeimagejvmindex): the index to use for resolving\n  the JVM version\n- [`nativeImageCommand`](#nativeimagecommand): the command to launch\n  `native-image`\n- [`nativeImageReady`](#nativeimageready): callback hook when native-image is\n  ready\n- [`nativeImageCoursier`](#nativeimagecoursier): the path to a `coursier` binary\n- [`nativeImageOutput`](#nativeimageoutput): the path to the generated\n  native-image binary\n- [`nativeImageInstalled`](#nativeimageinstalled): whether GraalVM is manually\n  installed or should be downloaded with coursier\n- [`nativeImageGraalHome`](#nativeimagegraalhome): path to GraalVM home\n  directory\n- [`nativeImageRunAgent`](#nativeimagerunagent): run application, tracking all\n  usages of dynamic features of an execution with\n  [`native-image-agent`][assisted-configuration-of-native-image-builds]\n- [`nativeImageAgentOutputDir`](#nativeimageagentoutputdir): directory where\n  `native-image-agent` should put generated configurations\n- [`nativeImageAgentMerge`](#nativeimageagentmerge): whether\n  `native-image-agent` should merge generated configurations\n\n### `nativeImage`\n\n**Type**: `TaskKey[File]`\n\n**Description**: runs native-image and returns the resulting binary file.\n\n**Example usage**: `sbt myProject/nativeImage`\n\n### `nativeImageOptions`\n\n**Type**: `TaskKey[Seq[String]]`\n\n**Description**: custom native-image linking options. See `native-image --help`\nfor available options. Empty by default.\n\n**Example usage**: `nativeImageOptions ++= List(\"--initialize-at-build-time\")`\n\n### `nativeImageRun`\n\n**Type**: `InputKey[File]`\n\n**Description**: executes the native-image binary with given arguments. This\ntask can only be used after `nativeImage` has completed.\n\n**Example usage**:\n\n- `sbt myProject/nativeImage 'myProject/nativeImageRun hello'`\n- Error: `sbt clean myProject/nativeImageRun`. Crashes because native-image does\n  not exist.\n\n### `nativeImageCopy`\n\n**Type**: `InputKey[File]`\n\n**Description**: identical to `nativeImage` except the resulting binary is\nadditionally copied to the provided file. This task is helpful when configuring\nCI to generate the binary in a specific place.\n\n**Example usage**:\n\n- `sbt 'myProject/nativeImageCopy mybinary-x86_64-apple-darwin'`.\n- `sbt 'myProject/nativeImageCopy mybinary-x86_64-pc-linux'`.\n\n### `nativeImageVersion`\n\n**Type**: `SettingKey[String]`\n\n**Description**: the GraalVM version to use.\n\n**Default**: 20.2.0\n\n**Example usage**: `nativeImageVersion := \"19.3.3\"`\n\n### `nativeImageJvm`\n\n**Type**: `SettingKey[String]`\n\n**Description**: the GraalVM JVM version to use.\n\n**Default**: `\"graalvm-java11\"`. Must be one of the combinations below.\n\n**Example usage**: `nativeImageJvm := \"graalvm\"`\n\n|nativeImageJvm|nativeImageVersion|nativeImageJvmIndex|source|\n|---|---|---|---|\n|graalvm, graalvm-java11, graalvm-java17|1.0.0-x,19.0.0~21.1.0|cs|https://github.com/coursier/jvm-index|\n|graalvm-ce-java8, graalvm-ce-java11, graalvm-ce-java16|19.3~21.1.0|jabba|https://raw.githubusercontent.com/shyiko/jabba/master/index.json|\n\n### `nativeImageJvmIndex`\n\n**Type**: `SettingKey[String]`\n\n**Description**: the index to use for resolving the JVM version. By default,\nuses the [Cousier JVM index](https://github.com/coursier/jvm-index).\n\n**Default**: `\"cs\"`. Must be one of: `\"cs\"`, `\"jabba\"`.\n\n**Example usage**: `nativeImageJvmIndex := \"jabba\"`.\n\n### `nativeImageCommand`\n\n**Type**: `TaskKey[Seq[String]]`\n\n**Description**: the base command that is used to launch native-image.\n\n**Default**: resolves the command using `nativeImageGraalHome` task.\n\n**Example usage**: `nativeImageCommand := List(\"/path/to/native-image\")`\n\n### `nativeImageReady`\n\n**Type**: `SettingKey[() =\u003e Unit]`\n\n**Description**: a side-effecting callback that is called the native image is\nready.\n\n**Default**: alerts the message \"Native image ready!\" via the `say` command-line\ntool on macOS. Does nothing by default on Linux and Windows.\n\n### `nativeImageCoursier`\n\n**Type**: `TaskKey[File]`\n\n**Description**: the path to a `coursier` binary.\n\n**Default**: copies a slim bootstrap binary from sbt-native-image resources.\nThis setting is ignored if you customize `nativeImageCommand` to use something\nelse than Coursier.\n\n### `nativeImageOutput`\n\n**Type**: `SettingKey[File]`\n\n**Description**: the path to the native-image binary that is generated.\n\n**Default**: `target/native-image/NAME` where `NAME` is the name of the sbt\nproject. for available options.\n\n**Example usage**: `nativeImageOutput := file(\"target\") / \"my-binary\"`\n\n### `nativeImageInstalled`\n\n**Type**: `SettingKey[Boolean]`\n\n**Description**: whether GraalVM is manually installed or should be downloaded\nwith coursier.\n\n**Default**: checks if `NATIVE_IMAGE_INSTALLED` / `GRAALVM_INSTALLED`\nenvironment variables or `native-image-installed` / `graalvm-installed`\nproperties are set to `true`.\n\n### `nativeImageGraalHome`\n\n**Type**: `TaskKey[Path]`\n\n**Description**: path to GraalVM home directory.\n\n**Default**: if `nativeImageInstalled` is `true`, then tries to read the path\nfrom environment variables 1) `GRAAL_HOME`, 2) `GRAALVM_HOME` or 3) `JAVA_HOME`\n(in given order). Otherwise, automatically installs GraalVM via\n[Coursier](https://get-coursier.io/). Customize this setting if you prefer to\nnot to use environment variables.\n\n**Example usage**:\n`nativeImageGraalHome := file(\"/path/to/graalvm/base/directory\").toPath`\n\n### `nativeImageRunAgent`\n\n**Type**: `InputKey[Unit]`\n\n**Description**: run application, tracking all usages of dynamic features of an\nexecution with\n[`native-image-agent`][assisted-configuration-of-native-image-builds].\n\nYou may need to run this command if your app or any dependency uses reflection or JNI.\n\n**Example usage**:\n\nFirst, add the reflection configuration to the native image options\n\n```diff\n  // build.sbt\n\nlazy val myNativeProject = project\n  .settings(\n+     nativeImageOptions += s\"-H:ReflectionConfigurationFiles=${target.value / \"native-image-configs\" / \"reflect-config.json\"}\",\n+     nativeImageOptions += s\"-H:ConfigurationFileDirectories=${target.value / \"native-image-configs\" }\",\n+     nativeImageOptions +=\"-H:+JNI\"\n  )\n  .enablePlugins(NativeImagePlugin)\n```\n\nThen, make sure to generate the reflection configuration with\n`nativeImageRunAgent` before running `nativeImage`.\n\n```sh\n# Step 0: Start sbt shell.\n$ sbt\n# Step 1: Run application on the JVM with native-image agent.\n\u003e myProject/nativeImageRunAgent \" arg1 arg2\"\n# Step 2: Create native-image binary with assisted configuration.\n\u003e myProject/nativeImage\n# Step 3: Run native-image that was generated with assisted configuration.\n\u003e myProject/nativeImageRun arg1 arg2\n```\n\n### `nativeImageAgentOutputDir`\n\n**Type**: `SettingKey[File]`\n\n**Description**: directory where `native-image-agent` should put generated\nconfigurations.\n\n**Default**: `baseDirectory.value / \"native-image-configs\"`\n\n**Example usage**:\n`nativeImageAgentOutputDir := baseDirectory.value / \"native-image-agent\" / \"out\"`\n\n### `nativeImageAgentMerge`\n\n**Type**: `SettingKey[Boolean]`\n\n**Description**: whether `native-image-agent` should merge generated\nconfigurations.\n\n**Default**: `false`\n\n**Example usage**: `nativeImageAgentMerge := true`\n\n## Generate native-image from GitHub Actions\n\nThe easiest way to distribute native-image binaries for Linux and macOS is to\nbuild the binaries in CI with GitHub Actions.\n\n1.  Copy the `native.yml` file from this repo into the `.github/workflows/`\n    directory in your project.\n\n        mkdir -p .github/workflows \u0026\u0026 \\\n          curl -L https://raw.githubusercontent.com/scalameta/sbt-native-image/master/.github/workflows/native.yml \u003e .github/workflows/native.yml\n\n2.  Edit the file to replace \"example\" with the name of your binary.\n3.  Commit your changes.\n4.  Push your commit to GitHub and see the binary get uploaded as an artifact to\n    the CI job.\n5.  Create a GitHub release and see the binary get uploaded as assets to the\n    release page.\n\n## Comparison with sbt-native-packager\n\nThe sbt-native-packager plugin provides similar support to generate native-image\nbinaries. Check out their documentation at\nhttps://sbt-native-packager.readthedocs.io/en/stable/formats/graalvm-native-image.html\n\nThe key differences between sbt-native-packager and sbt-native-image are:\n\n- sbt-native-image automatically installs GraalVM native-image by default. You\n  don't need to configure a docker image or manually install a correct GraalVM\n  JDK before starting sbt.\n- sbt-native-image automatically works out-of-the-box with Scala 2.12.12+ and\n  2.13.3+. You don't need custom settings to work around issues like like\n  [scala/bug#11634](https://github.com/scala/bug/issues/11634).\n- sbt-native-image displays live progress output from the `native-image` while\n  it's generating the binary. For some reason, sbt-native-packager only displays\n  output from native-image after the process completes (see issue\n  [#1345](https://github.com/sbt/sbt-native-packager/issues/1345)).\n- sbt-native-packager has Docker support, which is helpful if you need more\n  fine-grained control over the linking environment. There are no plans to add\n  Docker support in sbt-native-image.\n\n[assisted-configuration-of-native-image-builds]:\n  https://www.graalvm.org/reference-manual/native-image/BuildConfiguration/#assisted-configuration-of-native-image-builds\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscalameta%2Fsbt-native-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscalameta%2Fsbt-native-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscalameta%2Fsbt-native-image/lists"}