= Scoop

JReleaser can generate and publish a _Scoop App Manifest_ into a repository that you have access to.

The `scoop` section specifies how the manifest should be created.

NOTE: Only artifacts with `.zip`, `.jar` extension may be packaged with Homebrew.

WARNING: Snapshots are *not* supported.

include::partial$legend.adoc[]

[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
# icon:dot-circle[]
packagers:
  # icon:dot-circle[]
  scoop:
    # Enables or disables Scoop.
    # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    # Defaults to `NEVER`.
    # icon:dot-circle[]
    active: ALWAYS

    # Directory with file templates used to prepare the Scoop distribution.
    # Defaults to `src/jreleaser/distributions/${distribution.name}/scoop`.
    # If specified, path must exist.
    # icon:dot-circle[]
    templateDirectory: path/to/scoop/templates

    # Additional properties used when evaluating templates.
    # icon:dot-circle[] icon:file-alt[]
    extraProperties:
      # Key will be capitalized and prefixed with `scoop`, i.e, `scoopFoo`.
      foo: bar

    # URL used to check the latest version.
    # Defaults to the releaser's `latestReleaseUrl`.
    # icon:dot-circle[] icon:file-alt[]
    checkverUrl: pass:[https://host/path]

    # URL used to download a new version.
    # Defaults to the releaser's `downloadUrl`.
    # icon:dot-circle[] icon:file-alt[]
    autoupdateUrl: pass:[https://host/path]

    # Git author used to commit to the bucket repository.
    # icon:dot-circle[]
    commitAuthor:
      # Name used when authoring commits.
      # If left undefined, will use the releaser's commit name.
      # icon:dot-circle[]
      name: jreleaserbot

      # E-mail used when authoring commits.
      # If left undefined, will use the releaser's commit email.
      # icon:dot-circle[]
      email: pass:[jreleaser@kordamp.org]

    # Git repository to push the formula to.
    # Defaults are shown.
    # icon:dot-circle[]
    bucket:

      # The owner of the bucket repository.
      # Defaults to the same owner as the release repository.
      # icon:dot-circle[]
      owner: duke

      # The name of the bucket repository.
      # Defaults to `scoop-${repoOwner}`.
      # icon:dot-circle[]
      name: scoop-duke

      # Username used for authoring commits. Must have write access to the bucket repository.
      # Defaults to the same username as the release repository.
      # icon:dot-circle[]
      username: duke

      # Password or OAuth token with write access to the bucket repository.
      # If left unspecified, the `JRELEASER_SCOOP_${GIT}_TOKEN`
      # environment variable must be defined.
      # icon:dot-circle[] icon:eye-slash[]
      token: __DO_NOT_SET_HERE__
----
TOML::
+
[source,toml]
[subs="+macros"]
----
# icon:dot-circle[]
[packagers.scoop]
  # Enables or disables Scoop.
  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `NEVER`.
  # icon:dot-circle[]
  active = "ALWAYS"

  # Directory with file templates used to prepare the Scoop distribution.
  # Defaults to `src/jreleaser/distributions/${distribution.name}/scoop`.
  # If specified, path must exist.
  # icon:dot-circle[]
  templateDirectory = "path/to/scoop/templates"

  # Additional properties used when evaluating templates.
  # icon:dot-circle[] icon:file-alt[]
  extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `scoop`, i.e, `scoopFoo`.

  # URL used to check the latest version.
  # Defaults to the releaser's `latestReleaseUrl`.
  # icon:dot-circle[] icon:file-alt[]
  checkverUrl = "pass:[https://host/path]"

  # URL used to download a new version.
  # Defaults to the releaser's `downloadUrl`.
  # icon:dot-circle[] icon:file-alt[]
  autoupdateUrl = "pass:[https://host/path]"

  # Git author used to commit to the bucket repository.

  # Name used when authoring commits.
  # If left undefined, will use the releaser's commit name.
  # icon:dot-circle[]
  commitAuthor.name = "jreleaserbot"

  # E-mail used when authoring commits.
  # If left undefined, will use the releaser's commit email.
  # icon:dot-circle[]
  commitAuthor.email = "pass:[jreleaser@kordamp.org]"

  # Git repository to push the formula to.

  # The owner of the bucket repository.
  # Defaults to the same owner as the release repository.
  # icon:dot-circle[]
  bucket.owner = "duke"

  # The name of the bucket repository.
  # Defaults to `scoop-${repoOwner}`.
  # icon:dot-circle[]
  bucket.nam = "scoop-duke"

  # Username used for authoring commits. Must have write access to the bucket repository.
  # Defaults to the same username as the release repository.
  # icon:dot-circle[]
  bucket.username = "duke"

  # Password or OAuth token with write access to the bucket repository.
  # If left unspecified, the `JRELEASER_SCOOP_${GIT}_TOKEN`
  # environment variable must be defined.
  # icon:dot-circle[] icon:eye-slash[]
  bucket.token = "__DO_NOT_SET_HERE__"
----
JSON::
+
[source,json]
[subs="+macros"]
----
{
  // icon:dot-circle[]
  "packagers": {
    // icon:dot-circle[]
    "scoop": {
      // Enables or disables Scoop.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // icon:dot-circle[]
      "active": "ALWAYS",

      // Directory with file templates used to prepare the Scoop distribution.
      // Defaults to `src/jreleaser/distributions/${distribution.name}/scoop`.
      // If specified, path must exist.
      // icon:dot-circle[]
      "templateDirectory": "path/to/scoop/templates",

      // Additional properties used when evaluating templates.
      // icon:dot-circle[] icon:file-alt[]
      "extraProperties": {
        // Key will be capitalized and prefixed with `scoop`, i.e, `scoopFoo`.
        "foo": "bar"
      },

      // URL used to check the latest version.
      // Defaults to the releaser's `latestReleaseUrl`.
      // icon:dot-circle[] icon:file-alt[]
      "checkverUrl": "pass:[https://host/path]",

      // URL used to download a new version.
      // Defaults to the releaser's `downloadUrl`.
      // icon:dot-circle[] icon:file-alt[]
      "autoupdateUrl": "pass:[https://host/path]",

      // Git author used to commit to the bucket repository.
      // icon:dot-circle[]
      "commitAuthor": {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // icon:dot-circle[]
        "name": "jreleaserbot",

        // E-mail used when authoring commits.
        // Defaults to `pass:[jreleaser@kordamp.org]`.
        // icon:dot-circle[]
        "email": "pass:[jreleaser@kordamp.org]"
      },

      // Git repository to push the formula to.
      // Defaults are shown.
      // icon:dot-circle[]
      "bucket": {

        // The owner of the bucket repository.
        // Defaults to the same owner as the release repository.
        // icon:dot-circle[]
        "owner": "duke",

        // The name of the bucket repository.
        // Defaults to `scoop-${repoOwner}`.
        // icon:dot-circle[]
        "name": "scoop-duke",

        // Username used for authoring commits. Must have write access to the bucket repository.
        // Defaults to the same username as the release repository.
        // icon:dot-circle[]
        "username": "duke",

        // Password or OAuth token with write access to the bucket repository.
        // If left unspecified, the `JRELEASER_SCOOP_${GIT}_TOKEN`
        // environment variable must be defined.
        // icon:dot-circle[] icon:eye-slash[]
        "token": "__DO_NOT_SET_HERE__"
      }
    }
  }
}
----
Maven::
+
[source,xml]
[subs="+macros,verbatim"]
----
<jreleaser>
  <!--
    icon:dot-circle[]
  -->
  <packagers>
    <!--
      icon:dot-circle[]
    -->
    <scoop>
      <!--
        Enables or disables Scoop.
        Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        Defaults to `NEVER`.
        icon:dot-circle[]
      -->
      <active>ALWAYS</active>

      <!--
        Directory with file templates used to prepare the Scoop distribution.
        Defaults to `src/jreleaser/distributions/${distribution.name}/scoop`.
        If specified, path must exist.
        icon:dot-circle[]
      -->
      <templateDirectory>>path/to/scoop/templates</templateDirectory>

      <!--
        Additional properties used when evaluating templates.
        icon:dot-circle[] icon:file-alt[]
      -->
      <extraProperties>
        <!--
          Key will be capitalized and prefixed with `scoop`, i.e, `scoopFoo`.
        -->
        <foo>bar</foo>
      </extraProperties>

      <!--
        URL used to check the latest version.
        Defaults to the releaser's `latestReleaseUrl`.
        icon:dot-circle[] icon:file-alt[]
      -->
      <checkverUrl>pass:[https://host/path]</checkverUrl>

      <!--
        URL used to download a new version.
        Defaults to the releaser's `downloadUrl`.
        icon:dot-circle[] icon:file-alt[]
      -->
      <autoupdateUrl>pass:[https://host/path]</autoupdateUrl>

      <!--
        Git author used to commit to the repository.
        icon:dot-circle[]
      -->
      <commitAuthor>

        <!--
           Name used when authoring commits.
          Defaults to `jreleaserbot`.
          icon:dot-circle[]
        -->
        <name>jreleaserbot</name>

        <!--
          E-mail used when authoring commits.
          Defaults to `pass:[jreleaser@kordamp.org]`.
          icon:dot-circle[]
        -->
        <email>pass:[jreleaser@kordamp.org]</email>
      </commitAuthor>

      <!--
        Git repository to push the formula to.
        Defaults are shown.
        icon:dot-circle[]
      -->
      <bucket>

        <!--
          The owner of the bucket repository.
          Defaults to the same owner as the release repository.
          icon:dot-circle[]
        -->
        <owner>duke</owner>

        <!--
          The name of the bucket repository.
          Defaults to `scoop-${repoOwner}`.
          icon:dot-circle[]
        -->
        <name>scoop-duke</name>

        <!--
          Username used for authoring commits. Must have write access to the bucket repository.
          Defaults to the same username as the release repository.
          icon:dot-circle[]
        -->
        <username>duke</username>

        <!--
          Password or OAuth token with write access to the bucket repository.
          If left unspecified, the `JRELEASER_SCOOP_${GIT}_TOKEN`
          environment variable must be defined.
          icon:dot-circle[] icon:eye-slash[]
        -->
        <token>__DO_NOT_SET_HERE__</token>
      </bucket>
    </scoop>
  </packagers>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
jreleaser {
  // icon:dot-circle[]
  packagers {
    // icon:dot-circle[]
    scoop {
      // Enables or disables Scoop.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // icon:dot-circle[]
      active = 'ALWAYS'

      // Directory with file templates used to prepare the Scoop distribution.
      // Defaults to `src/jreleaser/distributions/${distribution.name}/scoop`.
      // If specified, path must exist.
      // icon:dot-circle[]
      templateDirectory = 'path/to/scoop/templates'

      // Additional properties used when evaluating templates.
      // Key will be capitalized and prefixed with `scoop`, i.e, `scoopFoo`.
      // icon:dot-circle[] icon:file-alt[]
      extraProperties.put('foo', 'bar')

      // URL used to check the latest version.
      // Defaults to the releaser's `latestReleaseUrl`.
      // icon:dot-circle[] icon:file-alt[]
      checkverUrl = 'pass:[https://host/path]'

      // URL used to download a new version.
      // Defaults to the releaser's `downloadUrl`.
      // icon:dot-circle[] icon:file-alt[]
      autoupdateUrl = 'pass:[https://host/path]'

      // Git author used to commit to the bucket repository.
      // icon:dot-circle[]
      commitAuthor {
        // Name used when authoring commits.
        // If left undefined, will use the releaser's commit name.
        // icon:dot-circle[]
        name = 'jreleaserbot'

        // E-mail used when authoring commits.
        // If left undefined, will use the releaser's commit email.
        // icon:dot-circle[]
        email = 'pass:[jreleaser@kordamp.org]'
      }

      // Git repository to push the formula to.
      // Defaults are shown.
      // icon:dot-circle[]
      bucket {

        // The owner of the bucket repository.
        // Defaults to the same owner as the release repository.
        // icon:dot-circle[]
        owner = 'duke'

        // The name of the bucket repository.
        // Defaults to `scoop-${repoOwner}`.
        // icon:dot-circle[]
        name = 'scoop-duke'

        // Username used for authoring commits. Must have write access to the bucket repository.
        // Defaults to the same username as the release repository.
        // icon:dot-circle[]
        username = 'duke'

        // Password or OAuth token with write access to the bucket repository.
        // If left unspecified, the `JRELEASER_SCOOP_${GIT}_TOKEN`
        // environment variable must be defined.
        // icon:dot-circle[] icon:eye-slash[]
        token = '__DO_NOT_SET_HERE__'
      }
    }
  }
}
----
====

Template files may be initialized using the `template` command.

NOTE: The bucket token environment variable must match with the chosen xref:release/index.adoc[] service, that is, it must
be one of [`JRELEASER_SCOOP_GITHUB_TOKEN`, `JRELEASER_SCOOP_GITLAB_TOKEN`, `JRELEASER_SCOOP_GITEA_TOKEN`].

Assuming that the current version is `1.2.3`, and a distribution named `app`, the above configuration will generate
a `manifest.json` formula in the `duke/scoop-duke` repository:

[source,json]
----
{
  "homepage": "https://acme.com/app",
  "description": "Sample app",
  "version": "1.2.3",
  "license": "Apache-2.0",
  "url": "https://github.com/duke/app/releases/download/v1.2.3/app-1.2.3.zip",
  "hash": "sha256:812121a64bbd3f49286f7b0be3c9209068f71fcf9541f313708979602e8de466",
  "extract_dir": "app-1.2.3",
  "env_add_path": "bin",
  "suggest": {
    "JDK": [
      "java/oraclejdk",
      "java/openjdk"
    ]
  },
  "checkver": {
    "url": "https://github.com/duke/app/releases/latest",
    "re": "v([\\d.]+).zip"
  },
  "autoupdate": {
    "url": "https://github.com/duke/app/releases/download/v1.2.3/app-$version.zip",
    "extract_dir": "app-$version",
    "hash": {
      "url": "$url.sha256"
    }
  }
}
----

Your users can then install your app by doing:

[source]
----
scoop bucket add duke https://github.com/duke/scoop-duke.git
scoop install app
----

IMPORTANT: GitLab does not yet offer an URL that resolves to a latest release. You may need to adapt the value of
`checkverUrl` or update the tool template by removing that section.
Keep an eye on link:https://gitlab.com/gitlab-org/gitlab/-/issues/16821[].

