Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nokeedev/init.nokee.dev

Nokee ❤️ Gradle (deep integration with Gradle)
https://github.com/nokeedev/init.nokee.dev

gradle gradle-plugins gradle-wrapper

Last synced: about 2 months ago
JSON representation

Nokee ❤️ Gradle (deep integration with Gradle)

Awesome Lists containing this project

README 

        
= 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 link:nokee.init.gradle[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 link:nokee.init.gradle[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]]

== Bintray deprecation



link:https://jfrog.com/blog/into-the-sunset-bintray-jcenter-gocenter-and-chartcenter/[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 link:nokee.init.gradle[latest version].



[[runtime-conflict]]

== 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 link:nokee.init.gradle[latest version].



[[troubleshooting]]

== 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 link:nokee.init.gradle[latest version].

If the upgrade doesn't solve your issue, please link:https://github.com/nokeedev/init.nokee.dev/issues[open a new issue], and we will fix it for everyone.