Native Image

Elide bundles Native Image and can compile your JVM program to a standalone native executable or native shared library. You can invoke the compiler directly with the elide native-image drop-in, or declare a Native Image artifact in your elide.pkl manifest and build it with elide build.

The Native Image artifact

Declare a Native Image in the artifacts block using the NativeImage type from elide:NativeImage.pkl. An image is built from one or more upstream artifacts (typically a JAR):

pkl

amends "elide:project.pkl"
import "elide:Jvm.pkl" as Jvm
import "elide:NativeImage.pkl" as Native

artifacts {
  ["app-jar"] = new Jvm.Jar {
    sources { "main" }
  }
  ["app"] = new Native.NativeImage {
    from { "app-jar" }
    entrypoint = "com.example.Main"
    type = "binary"
  }
}

Artifact fields

Field	Type	Default	Description
`from`	`Listing<String>`	`{}`	Artifact names to build the image from
`name`	`String?`	computed	Output name (binary or library); computed if omitted
`entrypoint`	`String?`	none	Entry (main) class; use `moduleName` if it lives in a JPMS module
`type`	`ImageType`	`"binary"`	`binary` (executable) or `library` (shared library)
`moduleName`	`String?`	none	JPMS module holding the entrypoint, if applicable
`options`	`NativeImageOptions`	`{}`	Compiler options for this artifact (see below)

A Native Image builds from other artifacts; there is no sources field on it (sources belongs to the JAR artifacts).

Compiler options

Set compiler options per artifact, inside that artifact's options block. The available options are:

Option	Type	Default	Description
`verbose`	`Boolean`	`false`	Verbose compiler output
`driverMode`	`"embedded" \`	"external"	`"embedded"`	Run Native Image in-process or as a sub-process
`optimization`	`OptimizationLevel`	`"auto"`	Optimization level (see below)
`linkAtBuildTime`	block	enabled	Link-at-build-time default plus specific packages
`classInit`	block	build-time	Class-initialization policy plus per-class/package overrides
`pgo`	block	enabled with profiles	Profile-Guided Optimization settings
`exclusions`	block	compiler internals	Maven coordinates excluded from classpath/modulepath
`features`	`Listing<JvmClass>`	`{}`	Native Image `Feature` classes to enable
`flags`	`Listing<String>`	`{}`	Extra flags for the Native Image compiler
`cflags`	`Listing<String>`	`{}`	Extra flags for the C compiler
`ldflags`	`Listing<String>`	`{}`	Extra flags for the native linker
`defs`	`Mapping<String, String>`	`{}`	System properties defined at build time

Project-wide settings

> The top-level nativeImage { } block is parsed but not currently applied — > its settings are not consumed by the build. Set all Native Image options **per > artifact**, inside that artifact's options { } block (above).

Optimization levels

The optimization value is one of auto (default), b (optimize for build speed), s (optimize for size), or 0–4 (increasing runtime performance). All values are strings.

Class initialization

Classes initialize at build time by default. Override the policy per class or package with the buildtime and runtime listings inside classInit.

Profile-Guided Optimization

PGO activates only when profiles are present. Build an instrumented image (pgo { instrument = true }) to produce a profile, then supply the collected profile file(s) via pgo { profiles { ... } } for the optimized build.