JBang

Unleash the power of Java with jbang. You can publish distributions as JBang catalogs.

Each separate executable will have its own JBang script. All executables will be collected in the same catalog. Existing catalogs located at the target repository will be merged into a single catalog.

Snapshots are supported, in which case executables will bear the -snapshot suffix in their alias.

Legend:

required
optional
may use environment variable
accepts Name Templates

YAML
TOML
JSON
Maven
Gradle

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

    # Let the release continue if the packager fails.
    # Defaults to `false`.
    # 
    continueOnError: true

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

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

    # Git author used to commit to the repository.
    # 
    commitAuthor:
      # Name used when authoring commits.
      # Defaults to `jreleaserbot`.
      # 
      name: jreleaserbot

      # E-mail used when authoring commits.
      # Defaults to `jreleaser@kordamp.org`.
      # 
      email: jreleaser@kordamp.org

    # Git repository to push the catalog to.
    # Defaults are shown.
    # 
    catalog:

      # The owner of the catalog repository.
      # Defaults to the same owner as the release repository.
      # 
      owner: duke

      # The name of the catalog repository.
      # Defaults to `jbang-catalog`.
      # 
      name: jbang-catalog

      # The target branch to use.
      # May define a `JRELEASER_JBANG_${GIT}_BRANCH` environment variable instead.
      # Defaults to the branch pointed by HEAD.
      #  
      branch: HEAD

      # Username used for authoring commits. Must have write access to the catalog repository.
      # If left unspecified, the `JRELEASER_JBANG_${GIT}_USERNAME`
      # environment variable must be defined.
      # Defaults to the same username as the release repository.
      #  
      username: duke

      # Password or OAuth token with write access to the catalog repository.
      # If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
      # environment variable must be defined.
      #  
      token: __DO_NOT_SET_HERE__

    # The jbang executable alias.
    # If left undefined, will use `${distribution.executable}`
    # 
    alias: cli

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

  # Let the release continue if the packager fails.
  # Defaults to `false`.
  # 
  continueOnError = true

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

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

  # Git author used to commit to the repository.

  # Name used when authoring commits.
  # Defaults to `jreleaserbot`.
  # 
  commitAuthor.name = "jreleaserbot"

  # E-mail used when authoring commits.
  # Defaults to `jreleaser@kordamp.org`.
  # 
  commitAuthor.email = "jreleaser@kordamp.org"

  # Git repository to push the catalog to.
  # Defaults are shown.

  # The owner of the catalog repository.
  # Defaults to the same owner as the release repository.
  # 
  catalog.owner = "duke"

  # The name of the catalog repository.
  # Defaults to `jbang-catalog`.
  # 
  catalog.name = "jbang-catalog"

  # The target branch to use.
  # May define a `JRELEASER_JBANG_${GIT}_BRANCH` environment variable instead.
  # Defaults to the branch pointed by HEAD.
  #  
  catalog.branch = "HEAD"

  # Username used for authoring commits. Must have write access to the catalog repository.
  # If left unspecified, the `JRELEASER_JBANG_${GIT}_USERNAME`
  # environment variable must be defined.
  # Defaults to the same username as the release repository.
  #  
  catalog.username = "duke"

  # Password or OAuth token with write access to the catalog repository.
  # If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
  # environment variable must be defined.
  #  
  catalog.token = "__DO_NOT_SET_HERE__"

  # The jbang executable alias.
  # If left undefined, will use `${distribution.executable}`
  # 
  alias = "cli"

{
  // 
  "packagers": {
    // 
    "jbang": {
      // Enables or disables JBang.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // 
      "active": "ALWAYS",

      // Let the release continue if the packager fails.
      // Defaults to `false`.
      // 
      "continueOnError": true,

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

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

      // Git author used to commit to the repository.
      // 
      "commitAuthor": {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // 
        "name": "jreleaserbot",

        // E-mail used when authoring commits.
        // Defaults to `jreleaser@kordamp.org`.
        // 
        "email": "jreleaser@kordamp.org"
      },

      // Git repository to push the catalog to.
      // Defaults are shown.
      // 
      "catalog": {

        // The owner of the catalog repository.
        // Defaults to the same owner as the release repository.
        // 
        "owner": "duke",

        // The name of the catalog repository.
        // Defaults to `jbang-catalog`.
        // 
        "name": "jbang-catalog",

        // The target branch to use.
        // May define a `JRELEASER_JBANG_${GIT}_BRANCH` environment variable instead.
        // Defaults to the branch pointed by HEAD.
        //  
        "branch": "HEAD",

        // Username used for authoring commits. Must have write access to the catalog repository.
        // If left unspecified, the `JRELEASER_JBANG_${GIT}_USERNAME`
        // environment variable must be defined.
        // Defaults to the same username as the release repository.
        //  
        "username": "duke",

        // Password or OAuth token with write access to the catalog repository.
        // If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
        // environment variable must be defined.
        //  
        "token": "__DO_NOT_SET_HERE__"
      },

      // The jbang executable alias.
      // If left undefined, will use `${distribution.executable}`
      // 
      "alias": "cli"
    }
  }
}

<jreleaser>
  <!--
    
  -->
  <packagers>
    <!--
      
    -->
    <jbang>
      <!--
        Enables or disables JBang.
        Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        Defaults to `NEVER`.
        
      -->
      <active>ALWAYS</active>

      <!--
        Let the release continue if the packager fails.
        Defaults to `false`.
        
      -->
      <continueOnError>true</continueOnError>

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

      <!--
        Directory with file templates used to prepare the JBang distribution.
        Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
        If specified, path must exist.
        
      -->
      <templateDirectory>>path/to/jbang/templates</templateDirectory>

      <!--
        Git author used to commit to the repository.
        
      -->
      <commitAuthor>

        <!--
           Name used when authoring commits.
          Defaults to `jreleaserbot`.
          
        -->
        <name>jreleaserbot</name>

        <!--
          E-mail used when authoring commits.
          Defaults to `jreleaser@kordamp.org`.
          
        -->
        <email>jreleaser@kordamp.org</email>
      </commitAuthor>

      <!--
        Git repository to push the catalog to.
        Defaults are shown.
        
      -->
      <catalog>

        <!--
          The owner of the catalog repository.
          Defaults to the same owner as the release repository.
          
        -->
        <owner>duke</owner>

        <!--
          The name of the catalog repository.
          Defaults to `jbang-catalog`.
          
        -->
        <name>jbang-catalog</name>

        <!--
          The target branch to use.
          May define a `JRELEASER_JBANG_${GIT}_BRANCH`` environment variable instead.
          Defaults to the branch pointed by HEAD.
           
        -->
        <branch>HEAD</branch>

        <!--
          Username used for authoring commits. Must have write access to the catalog repository.
          If left unspecified, the `JRELEASER_JBANG_${GIT}_USERNAME`
          environment variable must be defined.
          Defaults to the same username as the release repository.
           
        -->
        <username>duke</username>

        <!--
          Password or OAuth token with write access to the catalog repository.
          If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
          environment variable must be defined.
           
        -->
        <token>__DO_NOT_SET_HERE__</token>
      </catalog>

      <!--
        The jbang executable alias.
        If left undefined, will use `${distribution.executable}`
        
      -->
      <alias>cli</alias>
    </jbang>
  </packagers>
</jreleaser>

jreleaser {
  // 
  packagers {
    // 
    jbang {
      // Enables or disables JBang.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // 
      active = 'ALWAYS'

      // Let the release continue if the packager fails.
      // Defaults to `false`.
      // 
      continueOnError = true

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

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

      // Git author used to commit to the repository.
      // 
      commitAuthor {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // 
        name = 'jreleaserbot'

        // E-mail used when authoring commits.
        // Defaults to `jreleaser@kordamp.org`.
        // 
        email = 'jreleaser@kordamp.org'
      }

      // Git repository to push the catalog to.
      // Defaults are shown.
      // 
      catalog {

        // The owner of the catalog repository.
        // Defaults to the same owner as the release repository.
        // 
        owner = 'duke'

        // The name of the catalog repository.
        // Defaults to `jbang-catalog`.
        // 
        name = 'jbang-catalog'

        // The target branch to use.
        // May define a `JRELEASER_BRANCH` environment variable instead.
        // Defaults to the branch pointed by HEAD.
        //  
        branch = 'HEAD'

        // Username used for authoring commits. Must have write access to the catalog repository.
        // If left unspecified, the `JRELEASER_JBANG_${GIT}_USERNAME`
        // environment variable must be defined.
        // Defaults to the same username as the release repository.
        //  
        username = 'duke'

        // Password or OAuth token with write access to the catalog repository.
        // If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
        // environment variable must be defined.
        //  
        token = '__DO_NOT_SET_HERE__'
      }

      // The jbang executable alias.
      // If left undefined, will use `${distribution.executable}`
      // 
      alias = 'cli'
    }
  }
}

Template files may be initialized using the template command.

The catalog token environment variable must match with the chosen Release service, that is, it must be one of [JRELEASER_JBANG_GITHUB_TOKEN, JRELEASER_JBANG_GITLAB_TOKEN, JRELEASER_JBANG_GITEA_TOKEN].

You must define a value for java.mainClass in the owning distribution.

When the project’s version is snapshot, unless manually updated, the default prepared template assumes JARs may be resolved from https://jitpack.io.

Aliases must be unique!

The following property names have additional meaning

Key	Description
reverseRepoHost	reversed Git host, i.e. "com.github"
reverseDomain	reversed custom domain name

Key

Description

reverseRepoHost

reversed Git host, i.e. "com.github"

reverseDomain

reversed custom domain name

Assuming that the current version is 1.2.3, and a distribution named app, the above configuration will generate a app.java file in the duke/jbang-catalog repository:

jbang-catalog.json

{
  "aliases": {
    "app": {
      "script-ref": "app.java",
      "description": "Sample app"
    }
  }
}

app.java

//usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 8
//DEPS com.acme:app:1.2.3

public class app {
    public static void main(String... args) throws Exception {
        com.acme.Main.main(args);
    }
}

When the version is snapshot then the catalog and the script template change to:

jbang-catalog.json

{
  "aliases": {
    "app-snapshot": {
      "script-ref": "app_snapshot.java",
      "description": "Sample app"
    }
  }
}

app_snapshot.java

//usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 8
//REPOS jitpack
//DEPS com.github.duke:app:main-SNAPSHOT

public class app_snapshot {
    public static void main(String... args) throws Exception {
        com.acme.Main.main(args);
    }
}