nokeedev / init.nokee.dev

Nokee ❤️ Gradle (deep integration with Gradle)

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.

init.nokee.dev's Issues

Provide a `nokee` task flag to installer/update system-wide init script

It would make the installation easier to source from a Gradle instance already decorated with init script.

Embed a signature of the init script inside the init script

Together with #22 it would allow users to certify the init script wasn't modified.

Ensure the repos are properly configured with caching

Potentially use the subdomain repos repo-release, repo-snapshot to ensure full caching with minimum redirect.

Print lifecycle message when generating the wrapper without -Duse-nokee-version

It will help users to be conscious about the possibility of the Nokee initialization.

Explain the Bintray deprecation in README

There is a dummy section, now we should explain it.

Find a way to detect version conflict

When using the following in a buildSrc project:

dependencies {
    implementation platform("dev.nokee:nokee-gradle-plugins:0.5.0-fcde9b9d")
}

and the Nokee init project on another version, it wrongly mentions the Nokee version loaded at all Nokee plugins are available on the classpath via the platform from buildSrc. We should have a pill in the classpath to find the Nokee version (and versions, if misaligned) to give a better error message or warning.

Gradle wrapper patching on Windows trigger on the wrong segment in 6.5+

We really intend to patch the Gradle wrapper execution line. At the moment we trigger a bit too early in the script. The outcome is the same but the intent is not. We should move the patching logic for 6.5+ before the logic for wrapper prior to 6.5.

Sort Gradle wrapper keys using natural order

It seems to be the default behaviour for the Wrapper task where Nokee init breaks when rewriting it.

Release version 0.8.0

• release into repo.nokeedev.net
• validate everything is working as expected
• then release into bintray

Disable functional test when Gradle doesn't support Java version

Java 14-ea isn't supported on Gradle 6.2.1 and should be disabled. Maybe the toolbox should handle these constrain with a warning on the command line when disabling.

Exclude non-snapshot version from release repository and vice-versa

This avoid unecessary network activity.

Allow users to initialize nokee enabled project through the init plugin

This is a great story that could tie into the build init template sourced from the plugin portal. For Nokee's need, we will source all the init template from within the init.nokee.dev artifact. It is important that whatever we do here, we align with the strategic goal of this effort:

• start.nokee.dev will be a subdomain that users can navigate and initialize a build like https://start.spring.io/ and https://gradle-initializr.cleverapps.io/
• Following the previous point, the Gradle initializer simply exposes the build-init options and templates.
• All of the build-init options should point to a template that is itself a sample available in the documentation.
• Given the previous, all samples "should" be consumable as build-init templates.

What I suggest here is the following, either:

Each sample should be self-standing and published as individual components (just the code and build script). Then from the build-init task, we map the options to the correct sample code. Finally, we add the .git* files drop a wrapper at generation. The templates would be embedded inside the init jar.

Or we create another type of artifact, e.g. 'build-init' that may be sourced from a sample which is defined in this repo. We would still "publish" samples and their templates to allow some composition here.

Init project aren't configured with the Nokee init script with patch to wrapper script

Unfortunately, the build-init projects will not work out of the box. The build-init templates are however experimental and are not recommended for global usage right now.

Remove Bintray checks

Those won't be needed after version 0.8.0.

Write documentation on the init plugin feature

We should focus the documentation as a README for the project and consumable chapter for Nokee documentation.

Introduce flags to explicitly disable Nokee enhancement for wrapper task

This avoids manually unpatch the wrapper script.

Does not warn version override from build classpath

In the following example, the wrapper version is 0.5.0-12c22234 which is overridden by the cache file to 0.4.0 which is overridden by build classpath to 0.5.0-12c22234.

$ gradlew nokee --show-version

> Configure project :static_lib
WARNING: version '0.4.0' (from cache file) overrides version '0.5.0-12c22234' (from Gradle wrapper property).

> Task :nokee
Build ':' using Nokee version '0.5.0-12c22234' (from build classpath).

BUILD SUCCESSFUL in 4s

Open questions

• Should we even warn when versions are overridden back to the original version?
  • We should probably show all overrides to understand where the version comes from.

Add new line at the end of the wrapper script

The way we write the wrapper script, unfortunately, remove the last newline. It should keep the last newline.

Write blog post about deep Nokee integration with Gradle

Wrongly report nightly version

Nightly version drop commit hash. This is a bug in the parsing of the version from the classpath (both buildscript and build class path has this issue).

Print Build ':' using version <blah> at info level instead of lifecycle

It doesn't bring anything useful so let's move it one level down. It's only useful when debugging and wanting more information about the build.

Assume Nokee is wanted inside the wrapper when a version is configured but not passed to the wrapper task

If a user previously configured Nokee in the wrapper then update the wrapper we should assume the user still wants Nokee to be configured with the same version.

Include nokee.init.gradle script hash in the gradle-wrapper.properties

The hash should also be included in the gradle-wrapper.properties beside the nokeeVersion property.

Wrong property used when warning about Gradle wrapper property

Ex: WARNING: Use nokee-version Gradle wrapper property instead. , it should be nokeeVersion instead of nokee-version.

Convert spaces indentation to tabs

Consume less space ;-)

Detect nokee init script having a reference to Bintray

The next version should have a one-time code that checks each script in gradle.initscript and ~/init.d for a script that still references Bintray repository and warn they should upgrade.

Add test coverage for build-init integration

Build-init integration heavily depends on internal Gradle implementation. There should be enough testing coverage to ensure it behaves properly all the time.

Add Nokee version detection using `eachPlugin`

When a plugin is requested, we could capture the plugin request version if no version was specified.

Avoid resolving two different init plugin version

It seems possible to resolve two different versions of the plugin. We should have a way to avoid this as much as possible.

Provide a way to validate the nokee.init.gradle script hash

Add a section in the documentation to that effect.

Create a more lenient wrapper script patching

We already improved the patching by avoiding the System property for the "base" Nokee version. However, we should make the init-script flag event more lenient. When something is wrong, users may simply delete the dropped flag by hand which will cause issues on the next execution as the init script doesn't exist anymore. We should ignore the init-script flag when the init-script doesn't exist.

Print lifecycle message from Wrapper task to mention which Nokee version is being configured

This will help users being more conscious about the patching and extra files. Try to point to the right documentation as well.

Self disable init script on buildSrc auto-included build

The buildSrc are special hence don't receive --init-script side-effect. This causes a difference in behaviour between a --init-script CLI vs ~/.gradle/init.d.

Publish nokee.init.gradle to repository

The script will be archived, signed and hash.

Sign artifacts

All non-build classpath provider overshadow build classpath provider when showing version

Build classpath should be the absolute truth.

Same version should not print overwrite warnings

Ex: WARNING: version '0.5.0-12c22234' (from System property) overrides version '0.5.0-12c22234' (from Gradle wrapper property).

Notify users when the init script is out-of-date

We should warn when an init script is not the latest hash.

Windows wrapper patching seems to be broken

The Windows wrapper script patching fails with '-init-script' is not recognized as an internal or external command, operable program or batch file. and/or Could not find patching hook inside script at 'C:\Dev\haystack\gradlew.bat'.

Notify users when a nokee init script is not a known hash

This fits in the security measure for the init script.

Avoid spamming on each plugin resolution version conflict

We should finalize the version on the NokeeExtension

Improve UX when reporting warnings

The warnings are reported when the version is resolved this can happen at various points in time typically when a plugin is being resolved. Instead, we should most likely resolve the version once with warnings when settings is finish evaluated.

Current UX:

$ gradlew nokee --show-version

> Configure project :static_lib
WARNING: version '0.4.0' (from cache file) overrides version '0.5.0-12c22234' (from Gradle wrapper property).

> Task :nokee
Build ':' using Nokee version '0.5.0-12c22234' (from build classpath).

Expected UX:

$ gradlew nokee --show-version

> Configure project :
WARNING: version '0.4.0' (from cache file) overrides version '0.5.0-12c22234' (from Gradle wrapper property).

> Task :nokee
Build ':' using Nokee version '0.5.0-12c22234' (from build classpath).

Allow decorating the wrapper with just the init-script but no Nokee version

This allows to easily configure the plugin repositories for dev.nokee and dev.gradleplugins which is the case for this project.

Remove all reference to Bintray in repository/test/etc.

Init script is drop as mode 0755 instead of 0644 (previous version)

We shouldn't change the mode of the script more than what the containing directory has. It's also a Gradle script so there is no need to be executable. readable and writable is enough.

If build fails because of dev.nokee. plugins, mention how to manually update the version to use

If Gradle fails because the init plugin can't configure the right Nokee version users should use echo <nokeeVersion> > .gradle/use-nokee-version.txt to update to the right version.

Expand Java test coverage to Java 14+

Re-add detection for `buildscript` configuration of Nokee

We disabled this version provider as it was locking the build classpath too early. We should add the provider after the settings script is evaluated.

The implementation would need to change so we register version providers and the version would query the providers. This has the possibility of giving different version at a different time which we should guard against by printing warnings when we have a version mismatch.

Do not add timestamp to the Gradle wrapper properties when adding Nokee version

Gradle wrapper properties escaping lost

There is a loss of property escaping in generated Gradle wrapper properties:

Expected:
distributionUrl=https\://services.gradle.org/distributions/gradle-6.8.1-bin.zip

Actual
distributionUrl=https://services.gradle.org/distributions/gradle-6.8.1-bin.zip

Notice the missing backslash.