Skip to main content
Version: 2.x

ZIO CLI SBT Plugin

Overview

ZIO CLI offers an SBT plugin to provide some tasks to make generation and deployment of applications simple.

Current State

The current functionality of the plugin offers:

Native Images

This SBT plugin depends on and utilizes the sbt-native-image plugin. Tasks and settings related to building a native image map 1:1 to the upstream plugin.

Outstanding Action Items

  • Investigate if any cross versions are needed for different versions of SBT
  • Add remaining corresponding upstream configuration options to pass into the sbt-native-image plugin.
  • Implement zioCliGenerateBashCompletion, when ready.
  • Implement zioCliGenerateZshCompletion, when ready.
  • Implement zioCliInstallCli, when ready.

Plugin Settings

zioCliMainClass: Option[String]

The mainClass of the CLI App in the Compile scope. Defaults to None, and will need to be set.

zioCliNativeImageOptions: Seq[String]

A collection of arguments to pass the native-image builder to customize native image generation. Defaults to

List(
"--allow-incomplete-classpath",
"--report-unsupported-elements-at-runtime",
"--initialize-at-build-time",
"--no-fallback"
)

zioCliNativeImageReady: () => Unit

A side-effecting callback that is called the native image is ready. Defaults to

() => {
println("ZIO CLI App Native Image Ready!")
}

Plugin Tasks

zioCliBuildNative: Unit

Sets mainClass in Compile, and attempts to run nativeImage with any applied nativeImageOptions. Fires zioCliNativeImageReady on success.

zioCliGenerateBashCompletion: Unit

Not currently implemented; prints "TODO: Not Implemented!"

zioCliGenerateZshCompletion: Unit

Not currently implemented; prints "TODO: Not Implemented!"

zioCliInstallCli: Unit

Not currently implemented; prints "TODO: Not Implemented!"

End User Project Setup

There are several steps that are needed to use this in an end user project:

Locally Publishing the Plugin

To compile and locally publish a copy of the SBT plugin, simply call publishLocal on the sbtZioCli project. Example:

sbt> project sbtZioCli
sbt> publishLocal

This will locally publish an artifact: "zio.cli.sbt" % "sbt-zio-cli" % "0.0.0-SNAPSHOT"

End User Project

In your project, configure SBT to use the plugin by adding to project/plugins.sbt:

addSbtPlugin("zio.cli.sbt" % "sbt-zio-cli" % "0.0.0-SNAPSHOT")

Then, enable the plugin for your project in your build.sbt file. Example:

lazy val root = project
.in(file("."))
.enablePlugins(ZIOCLIPlugin)
.settings(
CLIPlugin.zioCliMainClass := Some("zio.cli.YourApp")
)

At this point, you should be able to build a native image of your application with the task:

sbt> zioCliBuildNative