Nokee Deep Integration with Gradle

To ensure an exceptional integration of the Nokee plugins with Gradle, we use advance ticks. First, we use an init script to bootstrap Nokee into every build (project-local or system-wide). The init script apply what is known as an init plugin where all the magic happen. We configure the plugin management repositories for artifact group dev.nokee and dev.gradleplugins. We also detect and align the version for all Nokee plugins. Soon, we will also provide build templates to quickly initialize new Nokee-enabled projects.

Usage

We support two different usage scenario:

1- (preferred) System-wide installation by copying the init script into your Gradle user home init.d directory, e.g. ~/.gradle/init.d:

curl -o ~/.gradle/init.d/nokee.init.gradle https://raw.githubusercontent.com/nokeedev/init.nokee.dev/main/nokee.init.gradle

2- Build-local installation by supplying the init script using --init-script command line flag.

Tasks

Nokee Task

Entrypoint task to query information regarding Nokee’s integration with Gradle. We provide the following command line flag to the nokee task:

--show-help

Print helpful information on what the nokee task can do for you.

--show-version (-Dshow-version)

Show the Nokee version detected for the build. Due to a limitation in Gradle, use the System property flag alternative -Dshow-version to query the Nokee version of included builds.

--use-version

Write a temporary version file to use instead of the version provided inside the gradle-wrapper.properties. See version detection priority for more information.

Wrapper Task

The init plugin will patch the Wrapper task to allow for additional wrapper task configuration. It does three additional things after the wrapper task finish executing if it detects Nokee usage:

1. Writes the nokee.init.script to the project (by default in gradle/nokee.init.gradle

2. Patches the wrapper scripts to implicitly pass the init script writen at one on every invocation using --init-script flag

3. Adds configured Nokee version to the gradle-wrapper.properties file.

We add an extension named nokee that control the wrapper enhancement:

version

Configure to the version to use. This version will be writen to the wrapper properties. By default the version is set to what we detected according to version detection (see section) The Nokee version to use can be overridden using the nokee-version system property or Gradle property.

For example: $ ./gradlew wrapper -Dnokee-version=0.4.0 will generate a wrapper using Nokee version 0.4.0 by writing the version into the gradle-wrapper.properties file. Upon the next execution, the version will be considered according to the version detection order (see section).

initScriptFile

Location where to write the nokee.init.gradle file, defaults to gradle/nokee.init.gradle.

Note

On Windows, invoking the wrapper task may yield the following expected output: '<…​>' is not recognized as an internal or external command, operable program or batch file. The patching process adds code in the Gradle wrapper batch script causing the CMD runtime to misinterpret the end of the script. It is normal Gradle wrapper behaviour.

Nokee version detection

The init plugin will source the Nokee version from these various location, the first one wins:

1. Included plugin build runtime classpath (e.g. buildSrc or any plugin’s includeBuild). Typically, in used when building convention plugins against the Nokee API. For example:

   plugins {
       id 'dev.gradleplugins.java-gradle-plugin'
   }
   
   dependencies {
       implementation platform('dev.nokee:nokee-gradle-plugins:0.4.0')
   }

2. System property nokee-version, i.e. ./gradlew -Dnokee-version=0.4.0 nokee --show-version.

   Warning

   Avoid setting this value in your global gradle.properties.

3. Gradle property nokee-version, i.e. ./gradlew -Pnokee-version=0.4.0 nokee --show-version.

   Warning

   Avoid setting this value in your global gradle.properties.

   Note	Prefer NOKEE_VERSION environment variable to Gradle’s long form property setting through environment variable, e.g. ORG_GRADLE_PROJECT_nokee-version. It’s shorter.

4. Environment variable NOKEE_VERSION, i.e.

   • *nix:

     $ export NOKEE_VERSION=0.4.0
     $ ./gradlew nokee --show-version

   • Windows:

     > set NOKEE_VERSION=0.4.0
     > gradlew nokee --show-version

5. Temporary version file, i.e. ./gradlew nokee --use-version=0.4.0 (or manually via echo "0.4.0" > .gradle/nokee-version.txt)

6. Gradle wrapper properties, e.g. nokeeVersion property in gradle/wrapper/gradle-wrapper.properties.

Deprecation notice

Previous Nokee init plugins were using slightly different System/Gradle property, environment variable, and file names. Please use the official names mentioned in the version detection section. Previous values are deprecated and should no longer be used:

• Instead of use-nokee-version System/Gradle property use nokee-version,

• Instead of USE_NOKEE_VERSION environment variable use NOKEE_VERSION, and

• Instead of .gradle/use-nokee-version.txt cache file use .gradle/nokee-version.txt.

Previous Nokee init plugins were injecting the Nokee version as a System property (e.g. useNokeeVersionFromWrapper) directly inside the generated wrapper. To migrate, simply regenerate the Gradle wrapper: ./gradlew wrapper

Bintray deprecation

JFrog is sunsetting their Bintray service by May 1st. Sadly for Nokee, we were hosting all our artifacts using their service. We are committed to offering our plugins without interruption. We already migrated all of our artifacts to our repositories. Unfortunately, the Nokee init plugin does not yet provide auto-updating functionally for the init bootstrapping script. You will need to use the latest version.

Runtime Plugin Conflict

Under unfortunate circumstance, Gradle can end up appling multiple distinct Nokee init plugins. We try our best to recover from such scenario by soft-disabling the extra plugins. However, in some scenarios, it may not be possible to disalbe the extra plugins which will most likely result in a runtime failure. It is important to solve this issue by updating all Nokee init script to its latest version.

Troubleshooting

We try our best to workaround possible failure cases. However, usage in the wild my differ from the use cases we test in our labs. Before opening an issue, please try upgrading all Nokee init script to its latest version. If the upgrade doesn’t solve your issue, please open a new issue, and we will fix it for everyone.