Native Image

Creates a Native Image binary using GraalVM Native Image.

You need a local installation of GraalVM. JReleaser will not install GraalVM for you, however it can install the native-image command if needed. You may configure the JDKs Maven Plugin or the JDKs Gradle Plugin to downloads a GraalVM distribution.

Legend:

  • required

  • optional

  • may use environment variable

  • accepts Name Templates

  • YAML

  • TOML

  • JSON

  • Maven

  • Gradle

# 
assemble:
  # 
  nativeImage:
    # Assemblers require a name.
    # 
    app:

      # Enables or disables the assembler.
      # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      # Defaults to `NEVER`.
      # 
      active: ALWAYS

      # Export the assembled artifacts as a matching named distribution.
      # Defaults to `true`.
      # 
      exported: true

      # Additional properties used when evaluating templates.
      #  
      extraProperties:
        # Key will be capitalized and prefixed with `nativeImage`, i.e, `nativeImageFoo`.
        foo: bar

      # Name of the executable launcher.
      # If left undefined, will use ${assembler.name}.
      # 
      executable: app

      # Directory with file templates used to prepare the NativeImage assembler.
      # Defaults to `src/jreleaser/assemblers/${distribution.name}/nativeImage`.
      # If specified, path must exist.
      # 
      templateDirectory: path/to/nativeImage/templates

      # Name of the generated image.
      # If left undefined, will use
      # ${assembler.executable}-${project.version}.
      # Generated artifacts always have the platform as suffix.
      #  
      imageName: 'app-{{projectVersion}}'

      # Name transformation of the generated image.
      # Transformed artifacts always have the platform as suffix.
      #  
      imageNameTransform: 'app-{{projectEffectiveVersion}}'

      # The GraalVM JDK to use.
      #  
      graal:
        path: path/to/graalvm

      # A list of build arguments.
      # The `-H:Name` argument will always be replaced with the
      # value of $executable.
      # 
      args:
        - "--install-exit-handlers"

      # The executable JAR that contains the application.
      #  
      mainJar:
        path: path/to/app.jar

      # Defines a list of additional JARs as globs.
      # 
      jars:
          # The pattern to use.
          # May use glob or regex pattern syntax.
          #  
        - pattern: path/to/**/*.jar

      # 
      java:
        # Maven coordinates: groupId.
        # If left undefined, will use ${project.java.groupId}.
        # 
        groupId: com.acme

        # Maven coordinates: artifactId.
        # If left undefined, will use ${project.java.artifactId}.
        # 
        artifactId: app

        # The minimum Java version required by consumers to run the application.
        # If left undefined, will use ${project.java.version}.
        # 
        version: 8

        # The application's entry point.
        # If left undefined, will use ${project.java.mainClass}.
        # 
        mainClass: com.acme.Main

        # Identifies the project as being member of a multi-project build.
        # If left undefined, will use ${project.java.multiProject}.
        # 
        multiProject: false

        # Additional properties used when evaluating templates.
        # 
        extraProperties:
          # Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
          foo: bar

      # Defines a list of additional files as globs.
      # These files will be added to the assembled Zip file.
      # 
      files:
          # The pattern to use.
          # May use glob or regex pattern syntax.
          #  
        - pattern: path/to/**/*.txt

      # Defines a list of additional files as filesets.
      # These files will be added to the assembled Zip file.
      # 
      fileSets:
          # The input directory to copy files from.
          #  
        - input: path/to/input/directory

          # The target path inside the archive.
          # If left undefined, defaults to the root of the archive.
          #  
          output: path/to/archive/entry

          # A set of files and directory to include.
          #  
          includes:
            - 'name_or_regex'

          # A set of files and directory to exclude.
          #  
          excludes:
            - 'name_or_regex'

          # Additional properties used when evaluating templates.
          #  
          extraProperties:
            # Key will be capitalized and prefixed with `artifact`, i.e, `artifactFoo`.
            foo: bar
# Assemblers require a name.
# 
[assemble.nativeImage.app]

  # Enables or disables the assembler.
  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `NEVER`.
  # 
  active = "ALWAYS"

  # Export the assembled artifacts as a matching named distribution.
  # Defaults to `true`.
  # 
  exported = true

  # Additional properties used when evaluating templates.
  #  
  extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `nativeImage`, i.e, `nativeImageFoo`.

  # Name of the executable launcher.
  # If left undefined, will use ${assembler.name}.
  # 
  executable = "app"

  # Directory with file templates used to prepare the NativeImage assembler.
  # Defaults to `src/jreleaser/assemblers/${distribution.name}/nativeImage`.
  # If specified, path must exist.
  # 
  templateDirectory = "path/to/nativeImage/templates"

  # Name of the generated image.
  # If left undefined, will use
  # ${assembler.executable}-${project.version}.
  # Generated artifacts always have the platform as suffix.
  #  
  imageName = "app-{{projectVersion}}"

  # Name transformation of the generated image.
  # Transformed artifacts always have the platform as suffix.
  #  
  imageNameTransform = "app-{{projectEffectiveVersion}}"

  # The GraalVM JDK to use.
  #  
  graal = { path = "path/to/graalvm" }

  # A list of build arguments.
  # The `-H:Name` argument will always be replaced with the
  # value of $executable.
  # 
  args = ["--install-exit-handlers"]

  # The executable JAR that contains the application.
  #  
  mainJar = { path = "path/to/app.jar" }

  # Defines a list of additional JARs as globs.
  # 
  [[assemble.nativeImage.app.jars]]
    # The pattern to use.
    # May use glob or regex pattern syntax.
    #  
    pattern = "path/to/**/*.jar"

  # Maven coordinates: groupId.
  # If left undefined, will use ${project.java.groupId}.
  # 
  java.groupId = "com.acme"

  # Maven coordinates: artifactId.
  # If left undefined, will use ${project.java.artifactId}.
  # 
  java.artifactId = "app"

  # The minimum Java version required by consumers to run the application.
  # If left undefined, will use ${project.java.version}.
  # 
  java.version = "8"

  # The application's entry point.
  # If left undefined, will use ${project.java.mainClass}.
  # 
  java.mainClass = "com.acme.Main"

  # Identifies the project as being member of a multi-project build.
  # If left undefined, will use ${project.java.multiProject}.
  # 
  java.multiProject = false

  # Additional properties used when evaluating templates.
  # 
  java.extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.

  # Defines a list of additional files as globs.
  # These files will be added to the assembled Zip file.
  # 
  [[assemble.nativeImage.app.files]]
    # The pattern to use.
    # May use glob or regex pattern syntax.
    #  
    pattern = "path/to/**/*.txt"

  # Defines a list of additional files as filesets.
  # These files will be added to the assembled Zip file.
  # 
  [[assemble.nativeImage.app.fileSets]]
    # The input directory to copy files from.
    #  
    input = "path/to/input/directory"

    # The target path inside the archive.
    # If left undefined, defaults to the root of the archive.
    #  
    output = "path/to/archive/entry"

    # A set of files and directory to include.
    #  
    includes = ["name_or_regex"]

    # A set of files and directory to exclude.
    #  
    excludes = ["name_or_regex"]

    # Additional properties used when evaluating templates.
    #  
    [[assemble.nativeImage.app.fileSets.extraProperties]]
      # Key will be capitalized and prefixed with `artifact`, i.e, `artifactFoo`.
      foo: bar
{
  // 
  "assemble": {
    // 
    "nativeImage": {
      // Assemblers require a name.
      // 
      "app": {

        // Enables or disables the assembler.
        // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `NEVER`.
        // 
        "active": "ALWAYS",

        // Export the assembled artifacts as a matching named distribution.
        // Defaults to `true`.
        // 
        "exported": true,

        // Additional properties used when evaluating templates.
        //  
        "extraProperties": {
          // Key will be capitalized and prefixed with `nativeImage`, i.e, `nativeImageFoo`.
          "foo": "bar"
        },

        // Name of the executable launcher.
        // If left undefined, will use ${assembler.name}.
        // 
        "executable": "app",

        // Directory with file templates used to prepare the NativeImage assembler.
        // Defaults to `src/jreleaser/assemblers/${distribution.name}/nativeImage`.
        // If specified, path must exist.
        // 
        "templateDirectory": "path/to/nativeImage/templates",

        // Name of the generated image.
        // If left undefined, will use
        // ${assembler.executable}-${project.version}.
        // Generated artifacts always have the platform as suffix.
        //  
        "imageName": "app-{{projectVersion}}",

        // Name transformation of the generated image.
        // Transformed artifacts always have the platform as suffix.
        //  
        "imageNameTransform": "app-{{projectEffectiveVersion}}",

        // The GraalVM JDK to use.
        //  
        "graal": {
          "path": "path/to/graalvm"
        },

        // A list of build arguments.
        // The `-H:Name` argument will always be replaced with the
        // value of $executable.
        // 
        "args": [
          "--install-exit-handlers"
        ],

        // The executable JAR that contains the application.
        //  
        "mainJar": {
          "path": "path/to/app.jar"
        },

        // Defines a list of additional JARs as globs.
        // 
        "jars": [
          {
            // The pattern to use.
            // May use glob or regex pattern syntax.
            //  
            "pattern": "path/to/**/*.jar"
          }
        ],

        // 
        "java": {
          // Maven coordinates: groupId.
          // If left undefined, will use ${project.java.groupId}.
          // 
          "groupId": "com.acme",

          // Maven coordinates: artifactId.
          // If left undefined, will use ${project.java.artifactId}.
          // 
          "artifactId": "app",

          // The minimum Java version required by consumers to run the application.
          // If left undefined, will use ${project.java.version}.
          // 
          "version": "8",

          // The application's entry point.
          // If left undefined, will use ${project.java.mainClass}.
          // 
          "mainClass": "com.acme.Main",

          // Identifies the project as being member of a multi-project build.
          // If left undefined, will use ${project.java.multiProject}.
          // 
          "multiProject": false,

          // Additional properties used when evaluating templates.
          // 
          "extraProperties": {
            // Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
            "foo": "bar"
          }
        },

        // Defines a list of additional files as globs.
        // These files will be added to the assembled Zip file.
        // 
        "files": [
          {
            // The pattern to use.
            // May use glob or regex pattern syntax.
            //  
            "pattern": "path/to/**/*.txt"
          }
        ],

        // Defines a list of additional files as filesets.
        // These files will be added to the assembled Zip file.
        // 
        "fileSets": [
          {
            // The input directory to copy files from.
            //  
            "input": "path/to/input/directory",

            // The target path inside the archive.
            // If left undefined, defaults to the root of the archive.
            //  
            "output": "path/to/archive/entry",

            // A set of files and directory to include.
            //  
            "includes": ["name_or_regex"],

            // A set of files and directory to exclude.
            //  
            "excludes": ["name_or_regex"],

            // Additional properties used when evaluating templates.
            //  
            "extraProperties": {
              // Key will be capitalized and prefixed with `artifact`, i.e, `artifactFoo`.
              "foo": "bar"
            }
          }
        ]
      }
    }
  }
}
<jreleaser>
  <!--
    
  -->
  <assemble>
    <!--
      
    -->
    <nativeImage>
      <!--
        Assemblers require a name.
        
      -->
      <app>
        <!--
          Enables or disables the distribution.
          Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
          Defaults to `ALWAYS`.
          
        -->
        <active>ALWAYS</active>

        <!--
          Export the assembled artifacts as a matching named distribution.
          Defaults to `true`.
          
        -->
        <exported>true</exported>

        <!--
          Additional properties used when evaluating templates.
           
        -->
        <extraProperties>
          <!--
            Key will be capitalized and prefixed with `nativeImage`, i.e, `nativeImageFoo`.
          -->
          <foo>bar</foo>
        </extraProperties>

        <!--
          Name of the executable launcher.
          If left undefined, will use ${distribution.name}.
          
        -->
        <executable>app</executable>

        <!--
          Directory with file templates used to prepare the NativeImage assembler.
          Defaults to `src/jreleaser/assemblers/${distribution.name}/nativeImage`.
          If specified, path must exist.
          
        -->
        <templateDirectory>path/to/brew/templates</templateDirectory>

        <!--
          Name of the generated image.
          If left undefined, will use
          ${assembler.executable}-${project.version}.
          Generated artifacts always have the platform as suffix.
           
        -->
        <imageName>app-{{projectVersion}}</imageName>

        <!--
          Name transformation of the generated image.
          Transformed artifacts always have the platform as suffix.
           
        -->
        <imageNameTransform>app</imageNameTransform>

        <!--
          The GraalVM JDK to use.
           
        -->
        <graal>
          <path>path/to/graalvm</path>
        </graal>

        <!--
          The executable JAR that contains the application.
           
        -->
        <mainJar>
          <path>path/to/app.jar</path>
        </mainJar>

        <!--
          A list of build arguments.
          The `-H =Name` argument will always be replaced with the
          value of $executable.
          
        -->
        <args>
          <arg>--install-exit-handlers</arg>
        </args>

        <!--
          Defines a list of additional JARs as globs.
          
        -->
        <jars>
          <jar>
            <!--
              The pattern to use.
              May use glob or regex pattern syntax.
               
            -->
            <pattern>path/to/**/*.jar</pattern>
          </jar>
        </jars>

        <!--
          
        -->
        <java>
          <!--
            Maven coordinates>groupId.
            If left undefined, will use ${project.java.groupId}.
            
          -->
          <groupId>com.acme</groupId>

          <!--
            Maven coordinates>artifactId.
            If left undefined, will use ${project.java.artifactId}.
            
          -->
          <artifactId>app</artifactId>

          <!--
            The minimum Java version required by consumers to run the application.
            If left undefined, will use ${project.java.version}.
            
          -->
          <version>8</version>

          <!--
            The application's entry point.
            If left undefined, will use ${project.java.mainClass}.
            
          -->
          <mainClass>com.acme.Main</mainClass>

          <!--
            Identifies the project as being member of a multi-project build.
            If left undefined, will use ${project.java.multiProject}.
            
          -->
          <multiProject>false</multiProject>

          <!--
            Additional properties used when evaluating templates.
            
          -->
          <extraProperties>
            <!--
              Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
            -->
            <foo>bar</foo>
          </extraProperties>
        </java>

        <!--
          Defines a list of additional files as globs.
          These files will be added to the assembled Zip file.
          
        -->
        <files>
          <file>
            <!--
              The pattern to use.
              May use glob or regex pattern syntax.
               
            -->
            <pattern>path/to/**/*.txt</pattern>
          </file>
        </files>

        <!--
          Defines a list of additional files as filesets.
          These files will be added to the assembled Zip file.
          
        -->
        <fileSets>
          <fileSet>
            <!--
              The input directory to copy files from.
               
            -->
            <input>path/to/input/directory</input>

            <!--
              The target path inside the archive.
              If left undefined, defaults to the root of the archive.
               
            -->
            <output>path/to/archive/entry</output>

            <!--
              A set of files and directory to include.
               
            -->
            <includes>
              <include>name_or_regex</include>
            </includes>

            <!--
              A set of files and directory to exclude.
               
            -->
            <excludes>
              <exclude>name_or_regex</exclude>
            </excludes>

            <!--
              Additional properties used when evaluating templates.
              
            -->
            <extraProperties>
              <!--
                Key will be capitalized and prefixed with `artifact`, i.e, `artifactFoo`.
              -->
              <foo>bar</foo>
            </extraProperties>
          </fileSet>
        </fileSets>
      </app>
    </nativeImage>
  </assemble>
</jreleaser>
jreleaser {
  // 
  assemble {
    // 
    nativeImage {
      // Assemblers require a name.
      // 
      app {

        // Enables or disables the assembler.
        // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `NEVER`.
        // 
        active = 'ALWAYS'

        // Export the assembled artifacts as a matching named distribution.
        // Defaults to `true`.
        // 
        exported = true

        // Additional properties used when evaluating templates.
        // Key will be capitalized and prefixed with `nativeImage`, i.e, `nativeImageFoo`.
        //  
        extraProperties.put('foo', 'bar')

        // Name of the executable launcher.
        // If left undefined, will use ${assembler.name}.
        // 
        executable = 'app'

        // Directory with file templates used to prepare the NativeImage assembler.
        // Defaults to `src/jreleaser/assemblers/${distribution.name}/nativeImage`.
        // If specified, path must exist.
        // 
        templateDirectory = 'path/to/nativeImage/templates'

        // Name of the generated image.
        // If left undefined, will use
        // ${assembler.executable}-${project.version}.
        // Generated artifacts always have the platform as suffix.
        //  
        imageName = 'app-{{projectVersion}}'

        // Name transformation of the generated image.
        // Transformed artifacts always have the platform as suffix.
        //  
        imageNameTransform = 'app-{{projectEffectiveVersion}}'

        // The GraalVM JDK to use.
        //  
        graal {
          path = 'path/to/graalvm'
        }

        // A list of build arguments.
        // The `-H =Name` argument will always be replaced with the
        // value of $executable.
        // 
        addArg('--install-exit-handlers')

        // The executable JAR that contains the application.
        //  
        mainJar {
          path = 'path/to/app.jar'
        }

        // Defines a list of additional JARs as globs.
        // 
        jars {
          // The pattern to use.
          // May use glob or regex pattern syntax.
          //  
          pattern = 'path/to/**/*.jar'
        }

        // 
        java {
          // Maven coordinates = groupId.
          // If left undefined, will use ${project.java.groupId}.
          // 
          groupI = 'com.acme'

          // Maven coordinates = artifactId.
          // If left undefined, will use ${project.java.artifactId}.
          // 
          artifactId = 'app'

          // The minimum Java version required by consumers to run the application.
          // If left undefined, will use ${project.java.version}.
          // 
          version = '8'

          // The application's entry point.
          // If left undefined, will use ${project.java.mainClass}.
          // 
          mainClass = 'com.acme.Main'

          // Identifies the project as being member of a multi-project build.
          // If left undefined, will use ${project.java.multiProject}.
          // 
          multiProject = false

          // Additional properties used when evaluating templates.
          // Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
          // 
          extraProperties.put('foo', 'bar')
        }

        // Defines a list of additional files as globs.
        // These files will be added to the assembled Zip file.
        // 
        files {
          // The pattern to use.
          // May use glob or regex pattern syntax.
          //  
          pattern = 'path/to/**/*.txt'
        }

        // Defines a list of additional files as filesets.
        // These files will be added to the assembled Zip file.
        // 
        fileSet {
          // The input directory to copy files from.
          //  
          input = 'path/to/input/directory'

          // The target path inside the archive.
          // If left undefined, defaults to the root of the archive.
          //  
          output = 'path/to/archive/entry'

          // A set of files and directory to include.
          //  
          includes = ['name_or_regex']

          // A set of files and directory to exclude.
          //  
          excludes = ['name_or_regex']

          // Additional properties used when evaluating templates.
          // Key will be capitalized and prefixed with `artifact`, i.e, `artifactFoo`.
          //  
          extraProperties.put('foo', 'bar')
        }
      }
    }
  }
}

Graal

The path for graal must exist in the file system. You may use the maven jdks-maven-plugin or gradle jdks-gradle-plugin to download a Graal distribution.

Templates

The default location for templates is:

src/jreleaser/assemblers/<distribution-name>/nativeImage