<commit_before># SLS Distribution Gradle Plugins

[![Build Status](https://circleci.com/gh/palantir/sls-packaging.svg?style=shield)](https://circleci.com/gh/palantir/sls-packaging)
[![Download](https://api.bintray.com/packages/palantir/releases/sls-packaging/images/download.svg) ](https://bintray.com/palantir/releases/sls-packaging/_latestVersion)

A set of Gradle plugins that facilitate packaging projects for distributions conforming to Palantir's Service Layout
Specification. This project was formerly known as gradle-java-distribution.

The Java Service and Asset plugins cannot both be applied to the same gradle project, and
distributions from both are produced as a gzipped tar named `[service-name]-[project-version].sls.tgz`.

## Java Service Distribution Gradle Plugin

Similar to the standard application plugin, this plugin helps package Java
Gradle projects for easy distribution and execution. This distribution conforms with Palantir's 
SLS service layout conventions that attempt to split immutable files from mutable state and configuration.

In particular, this plugin packages a project into a common deployment structure
with a simple start script, daemonizing script, and, a manifest describing the
content of the package. The package will follow this structure:

    [service-name]-[service-version]/
        deployment/
            manifest.yml                      # simple package manifest
        service/
            bin/
                [service-name]                # Bash start script
                [service-name].bat            # Windows start script
                init.sh                       # daemonizing script
                darwin-amd64/go-java-launcher # Native Java launcher binary (MacOS)
                linux-amd64/go-java-launcher  # Native Java launcher binary (Linux)
                launcher-static.yml           # generated configuration for go-java-launcher
                launcher-check.yml            # generated configuration for check.sh go-java-launcher
            lib/
                [jars]
            monitoring/
                bin/
                    check.sh                  # monitoring script
        var/                                  # application configuration and data

The `service/bin/` directory contains both Gradle-generated launcher scripts (`[service-name]` and `[service-name].bat`)
and [go-java-launcher](https://github.com/palantir/go-java-launcher) launcher binaries.

## Asset Distribution Gradle Plugin

This plugin helps package static files and directories into a distribution that conforms with Palantir's SLS asset
layout conventions.  Asset distributions differ from service distributions in that they do not have a top-level
`service` or `var` directory, and instead utilize a top-level `asset` directory that can contain arbitrary files.

## Pod Distribution Gradle Plugin

This plugin helps generate configuration to describe a collection of services and produces a distribution that conforms
with Palantir's SLS pod specification. Pod distributions contain a deployment directory with the `pod.yml` and
`manifest.yml` files in it. A `pod.yml` contains a set of services that are intended to run together and may have
requirements about shared resources, such as shared disk.

## Usage

### Java Service Distribution plugin

Apply the plugin using standard Gradle convention:

    plugins {
        id 'com.palantir.sls-java-service-distribution'
    }

A sample configuration for the Service plugin:

    distribution {
        serviceName 'my-service'
        serviceGroup 'my.service.group'
        mainClass 'com.palantir.foo.bar.MyServiceMainClass'
        args 'server', 'var/conf/my-service.yml'
        env 'KEY1': 'value1', 'KEY2': 'value1'
        manifestExtensions 'KEY3': 'value2'
        productDependency {
            productGroup = "other-group"
            productName = "other-service"
            minimumVersion = "1.1.0"
            maximumVersion = "1.5.x"
            recommendedVersion = "1.3.0"
        }
        productDependency {
            productGroup = "other-group2"
            productName = "other-service2"
            // Automatically detect the constraints based on the runtime configuration
            // API jars that publish recommended product dependencies.
            // See the recommended product dependencies plugin section below.
            detectConstraints = true
        }
    }

And the complete list of configurable properties:

 * (optional) `serviceName` the name of this service, used to construct the final artifact's file name.
   Defaults to the configured "name" of the Gradle project, `project.name`.
 * (optional) `serviceGroup` the group of the service, used in the final artifact's manifest.
   Defaults to the configured "group" of the Gradle project, `project.group`.
 * (optional) `manifestExtensions` a map of extended manifest attributes, as specified in SLS 1.0
 * (optional) `productDependency` adds an entry to the `extensions.product-dependencies` block of the SLS manifest,
   declaring that this service has a dependency on the given other service with specific version bounds. The `productDependency` object must specify the following properties:
   * `productGroup` the `serviceGroup` of the dependency.
   * `productName` the `serviceName` of the dependency.
   * `minVersion` the minimal compatible version of the dependency.
   * `maxVersion` the maximal compatible version of the dependency.
   * `recommended` the version developers think you should use; most commonly the version of the implementation that was tested during CI (`minVersion` typically matches the version of the api you use to negotiate).
 * `mainClass` class containing the entry point to start the program.
 * (optional) `args` a list of arguments to supply when running `start`.
 * (optional) `checkArgs` a list of arguments to supply to the monitoring script, if omitted,
   no monitoring script will be generated.
 * (optional) `env` a map of environment variables that will be placed into the `env` block
   of the static launcher config. See [go-java-launcher](https://github.com/palantir/go-java-launcher)
   for details on the custom environment block.
 * (optional) `defaultJvmOpts` a list of default JVM options to set on the program.
 * (optional) `enableManifestClasspath` a boolean flag; if set to true, then the explicit Java
   classpath is omitted from the generated Windows start script and instead inferred
   from a JAR file whose MANIFEST contains the classpath entries.
 * (optional) `excludeFromVar` a list of directories (relative to `${projectDir}/var`) to exclude from the distribution,
   defaulting to `['log', 'run']`.
 * (optional) `javaHome` a fixed override for the `JAVA_HOME` environment variable that will
   be applied when `init.sh` is run.
 * (optional) `gc` override the default GC settings. Available GC settings: `throughput` (default), `hybrid` and `response-time`.

#### JVM Options

The list of JVM options passed to the Java processes launched through a package's start-up scripts is obtained by
concatenating the following list of hard-coded *required options* and the list of options specified in
`distribution.defaultJvmOpts`:

Hard-coded required JVM options:<commit_msg>update readme to include brief mention of ignoredProductDependency (#323)<commit_after># SLS Distribution Gradle Plugins

[![Build Status](https://circleci.com/gh/palantir/sls-packaging.svg?style=shield)](https://circleci.com/gh/palantir/sls-packaging)
[![Download](https://api.bintray.com/packages/palantir/releases/sls-packaging/images/download.svg) ](https://bintray.com/palantir/releases/sls-packaging/_latestVersion)

A set of Gradle plugins that facilitate packaging projects for distributions conforming to Palantir's Service Layout
Specification. This project was formerly known as gradle-java-distribution.

The Java Service and Asset plugins cannot both be applied to the same gradle project, and
distributions from both are produced as a gzipped tar named `[service-name]-[project-version].sls.tgz`.

## Java Service Distribution Gradle Plugin

Similar to the standard application plugin, this plugin helps package Java
Gradle projects for easy distribution and execution. This distribution conforms with Palantir's 
SLS service layout conventions that attempt to split immutable files from mutable state and configuration.

In particular, this plugin packages a project into a common deployment structure
with a simple start script, daemonizing script, and, a manifest describing the
content of the package. The package will follow this structure:

    [service-name]-[service-version]/
        deployment/
            manifest.yml                      # simple package manifest
        service/
            bin/
                [service-name]                # Bash start script
                [service-name].bat            # Windows start script
                init.sh                       # daemonizing script
                darwin-amd64/go-java-launcher # Native Java launcher binary (MacOS)
                linux-amd64/go-java-launcher  # Native Java launcher binary (Linux)
                launcher-static.yml           # generated configuration for go-java-launcher
                launcher-check.yml            # generated configuration for check.sh go-java-launcher
            lib/
                [jars]
            monitoring/
                bin/
                    check.sh                  # monitoring script
        var/                                  # application configuration and data

The `service/bin/` directory contains both Gradle-generated launcher scripts (`[service-name]` and `[service-name].bat`)
and [go-java-launcher](https://github.com/palantir/go-java-launcher) launcher binaries.

## Asset Distribution Gradle Plugin

This plugin helps package static files and directories into a distribution that conforms with Palantir's SLS asset
layout conventions.  Asset distributions differ from service distributions in that they do not have a top-level
`service` or `var` directory, and instead utilize a top-level `asset` directory that can contain arbitrary files.

## Pod Distribution Gradle Plugin

This plugin helps generate configuration to describe a collection of services and produces a distribution that conforms
with Palantir's SLS pod specification. Pod distributions contain a deployment directory with the `pod.yml` and
`manifest.yml` files in it. A `pod.yml` contains a set of services that are intended to run together and may have
requirements about shared resources, such as shared disk.

## Usage

### Java Service Distribution plugin

Apply the plugin using standard Gradle convention:

    plugins {
        id 'com.palantir.sls-java-service-distribution'
    }

A sample configuration for the Service plugin:

    distribution {
        serviceName 'my-service'
        serviceGroup 'my.service.group'
        mainClass 'com.palantir.foo.bar.MyServiceMainClass'
        args 'server', 'var/conf/my-service.yml'
        env 'KEY1': 'value1', 'KEY2': 'value1'
        manifestExtensions 'KEY3': 'value2'
        productDependency {
            productGroup = "other-group"
            productName = "other-service"
            minimumVersion = "1.1.0"
            maximumVersion = "1.5.x"
            recommendedVersion = "1.3.0"
        }
        productDependency {
            productGroup = "other-group2"
            productName = "other-service2"
            // Automatically detect the constraints based on the runtime configuration
            // API jars that publish recommended product dependencies.
            // See the recommended product dependencies plugin section below.
            detectConstraints = true
        }
    }

And the complete list of configurable properties:

 * (optional) `serviceName` the name of this service, used to construct the final artifact's file name.
   Defaults to the configured "name" of the Gradle project, `project.name`.
 * (optional) `serviceGroup` the group of the service, used in the final artifact's manifest.
   Defaults to the configured "group" of the Gradle project, `project.group`.
 * (optional) `manifestExtensions` a map of extended manifest attributes, as specified in SLS 1.0
 * (optional) `productDependency` adds an entry to the `extensions.product-dependencies` block of the SLS manifest,
   declaring that this service has a dependency on the given other service with specific version bounds. The `productDependency` object must specify the following properties:
   * `productGroup` the `serviceGroup` of the dependency.
   * `productName` the `serviceName` of the dependency.
   * `minVersion` the minimal compatible version of the dependency.
   * `maxVersion` the maximal compatible version of the dependency.
   * `recommended` the version developers think you should use; most commonly the version of the implementation that was tested during CI (`minVersion` typically matches the version of the api you use to negotiate).
 * `mainClass` class containing the entry point to start the program.
 * (optional) `args` a list of arguments to supply when running `start`.
 * (optional) `checkArgs` a list of arguments to supply to the monitoring script, if omitted,
   no monitoring script will be generated.
 * (optional) `env` a map of environment variables that will be placed into the `env` block
   of the static launcher config. See [go-java-launcher](https://github.com/palantir/go-java-launcher)
   for details on the custom environment block.
 * (optional) `defaultJvmOpts` a list of default JVM options to set on the program.
 * (optional) `enableManifestClasspath` a boolean flag; if set to true, then the explicit Java
   classpath is omitted from the generated Windows start script and instead inferred
   from a JAR file whose MANIFEST contains the classpath entries.
 * (optional) `excludeFromVar` a list of directories (relative to `${projectDir}/var`) to exclude from the distribution,
   defaulting to `['log', 'run']`.
 * (optional) `javaHome` a fixed override for the `JAVA_HOME` environment variable that will
   be applied when `init.sh` is run.
 * (optional) `gc` override the default GC settings. Available GC settings: `throughput` (default), `hybrid` and `response-time`.
 

If there is a jar recommending a version of a dependency but that product is not listed in a `productDependency` block an error will be produced: `The following products are recommended as dependencies but do not appear in the product dependencies or product dependencies ignored list: ...`.

The solution is to either add the product as a dependency via a `productDependency` block, or to explicitly ignore it:

    ignoredProductDependency('other-group3', 'other-service3')

#### JVM Options

The list of JVM options passed to the Java processes launched through a package's start-up scripts is obtained by
concatenating the following list of hard-coded *required options* and the list of options specified in
`distribution.defaultJvmOpts`:

Hard-coded required JVM options:
{'fraction_non_alphanumeric': 0.07063812868597177, 'fraction_numerical': 0.003246968391756676, 'mean_word_length': 3.281418439716312, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1907248', 'n_tokens_mistral': 3793, 'n_tokens_neox': 3603, 'n_words': 1637}