diff --git a/README.md b/README.md index 1cbf989..ff22998 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,15 @@ and ensure compatibility with performance features such as the The convention plugins pull in a [curated set of third-party Gradle plugins](build.gradle.kts#L18-L34) that also support these features and are compatible with the latest Gradle version. +## ToC + +- [Using the Convention Plugins](#using-the-convention-plugins) (for project maintainers) +- [List of Convention Plugins](#list-of-convention-plugins) (for project maintainers) +- [Building a project that uses these plugins](#building-a-project-that-uses-these-plugins) (for developers) + - [From the command line](#from-the-command-line) + - [In IntelliJ](#in-intellij) + - [In GitHub Actions](#in-github-actions) + ## Using the Convention Plugins Apply the entry point plugin `org.hiero.gradle.build` in the `settings.gradle.kts` file. Additionally, define where @@ -90,6 +99,142 @@ Each plugin configures a certain build aspect, following this naming pattern: - `org.hiero.gradle.module.*` _Module_ plugins combine plugins from all categories above to define _Module Types_ that are then used in the `build.gradle.kts` files of the individual Modules of our software. +## Building a project that uses these plugins + +## From the command line + +Run `./gradlw` to get the list of tasks that are useful to check and test local changes: + +``` +Build tasks +----------- +assemble - Assembles the outputs of this project. +build - Assembles and tests this project. +qualityGate - Apply spotless rules and run all quality checks. +test - Runs the test suite. +``` + +In addition, the following build parameters may be useful: + +| Task | Parameter | Description | Remarks | +|--------|----------------------------------------|----------------------------------------------------------------|----------------------------------------| +| `test` | `-PactiveProcessorCount=` | not run tests in parallel and reduce number of processors used | | +| `jmh` | `-PjmhTests=` | select benchmarks to run - e.g. `com.example.jmh.Benchmark1` | only projects with `feature.benchmark` | + +## In IntelliJ + +Open the root folder of the project in IntelliJ. It is automatically recognized as Gradle project and imported. + +### Configure the JDK used by Gradle + +Before you can use all features reliably, make sure that Gradle is started with the JDK used in the project. +The JDK version of the project is defined in `gradle/toolchain-versions.properties`. + +You can use IntelliJ to download the JDK if you do not have it installed. + +![Configuring the JDK in IntelliJ](src/docs/assets/gradle-jdk.png) + +## Reload Project with Gradle + +After you changed something in the project setup you should press the **Reload All Gradle project** in IntelliJ. +Changes to the project setup include: + +- Changing build setup/plugins in `build.gradle.kts` files +- Changing dependencies in `src/main/java/module-info.java` files +- Changing dependency versions in `hiero-dependency-versions/build.gradle.kts` + +![Configuring the JDK in IntelliJ](src/docs/assets/gradle-reload.png) + +## Build, test, run through Gradle tasks + +You can run all tasks (see [command line](#from-the-command-line)) from the Gradle tool window. +Usually, you only require the tasks listed in the **build** group. + +![Configuring the JDK in IntelliJ](src/docs/assets/gradle-tasks.png) + +To run only a single test, you can use the _run test_ options offered by IntelliJ when you open a test file. +IntelliJ then automatically constructs the required Gradle call to run the test through Gradle. + +## In GitHub Actions + +GitHub action pipelines should use the official [setup-gradle action](https://github.com/gradle/actions/) with the following tasks and parameters. + +### Building and testing + +In a CI pipeline for PR validation with multiple steps use the following. +(The available _test sets_ are determined by the additional `feature.test-*` plugins used in the project.) + +| Task and Parameters | Description | +|---------------------------------|------------------------------------------------------------------------| +| `./gradlew assemble --scan` | Build all artifacts (populates remote build cache) | +| `./gradlew qualityCheck --scan` | Run all checks except tests | +| `./gradlew test --scan` | Run all unit tests | +| `./gradlew --scan` | Run all tests in _test-set_ (possibly on different agents in parallel) | + +Alternatively, if you are fine to do more in one pipeline step, you can use: + +| Task and Parameters | Description | +|-------------------------------|-------------------------------------| +| `./gradlew build --scan` | `assemble` + `qualiyCheck` + `test` | +| `./gradlew --scan` | Run all tests in _test-set_ | + +#### Environment + +The following environment variables should be populated from _secrets_ to ensure a performant build. + +| Env Variable | Description | +|-------------------------|--------------------------------------| +| `GRADLE_CACHE_USERNAME` | Gradle remote build cache _username_ | +| `GRADLE_CACHE_PASSWORD` | Gradle remote build cache _password_ | + +### Publishing + +Before doing the publishing, you may need to update the version (version.txt file) in a preceding step. + +| Task and Parameters | Description | +|-------------------------------------------------------------|------------------------------------------| +| `./gradlew versionAsSpecified -PnewVersion=` | Define version to store in version.txt | +| `./gradlew versionAsSnapshot` | Add _-SNAPSHOT_ suffix to version.txt | +| `./gradlew versionAsPrefixedCommit -PcommitPrefix=` | Set version based on current commit hash | + +To perform the actual publishing use one of the following. +(If multiple _products_ with different _groups_ should be published, the `releaseMavenCentral` task needs to run +multiple times with different values for the `publishingPackageGroup` parameter.) + +| Task and Parameters | Description | +|--------------------------------------------------------------------------------------------------|----------------------------------------| +| `./gradlew releaseMavenCentral -PpublishingPackageGroup= --no-configuration-cache --scan` | Publish artifacts to Maven central | +| `./gradlew publishPlugins --no-configuration-cache --scan` | Publish plugin to Gradle plugin portal | + +The following parameters may be used to tune or test the publishing (default is `false` for all parameters). + +| Task and Parameters | Description | +|-----------------------------------------|-----------------------------------------------------| +| `-PpublishSigningEnabled=` | Set to `true` for actual publishing | +| `-Ps01SonatypeHost=` | Use the `s01.oss.sonatype.org` host if required | +| `-PpublishTestRelease=` | `false` - auto-release from staging when successful | + +The following environment variables should be populated from _secrets_ to ensure a fully functional build. + +#### Environment + +| Env Variable | Description | +|-------------------------|-----------------------------------------| +| `NEXUS_USERNAME` | Maven Central publish _username_ | +| `NEXUS_PASSWORD` | Maven Central publish _password_ | +| `GRADLE_PUBLISH_KEY` | Gradle plugin portal publish _username_ | +| `GRADLE_PUBLISH_SECRET` | Gradle plugin portal publish _password_ | + +### Testing Rust code on multiple operating systems + +If `feature.rust` and `feature.test-multios` is used, you can configure a matrix pipeline to run `test` on multiple +agents with different operating systems. In this case, you can use the following parameter to skip the rust installation +on the test-only agents where compiled code is retrieved from the remote build cache. + +| Env Variable | Description | +|---------------------------------------------|-----------------------------------------------------------------------------| +| `-PskipInstallRustToolchains=` | Skip `installRustToolchains` task if all `cargoBuild*` tasks are FROM-CACHE | + ## Contributing Whether you’re fixing bugs, enhancing features, or improving documentation, your contributions are important — let’s build something great together! @@ -119,7 +264,7 @@ Your changes are automatically used when running a build. #### Add or adjust a test Each change done to the plugins should be covered by a test. The tests are located in -[src/test/kotlin](src/main/kotlin). They are written in Kotlin using [JUnit5](https://junit.org/junit5/), +[src/test/kotlin](src/main/kotlin). They are written in Kotlin using [JUnit5](https://junit.org/junit5/), [AssertJ](https://assertj.github.io/doc/) and [Gradle Test Kit](https://docs.gradle.org/current/userguide/test_kit.html). Each test creates an artificial project that applies the plugin(s) under test, runs a build and asserts build results – such as: state of tasks executed, console logging, created files. Take a look at the existing tests for more details. diff --git a/src/docs/assets/gradle-jdk.png b/src/docs/assets/gradle-jdk.png new file mode 100644 index 0000000..d15b49f Binary files /dev/null and b/src/docs/assets/gradle-jdk.png differ diff --git a/src/docs/assets/gradle-reload.png b/src/docs/assets/gradle-reload.png new file mode 100644 index 0000000..5424312 Binary files /dev/null and b/src/docs/assets/gradle-reload.png differ diff --git a/src/docs/assets/gradle-tasks.png b/src/docs/assets/gradle-tasks.png new file mode 100644 index 0000000..1a605f9 Binary files /dev/null and b/src/docs/assets/gradle-tasks.png differ diff --git a/src/main/kotlin/org.hiero.gradle.feature.benchmark.gradle.kts b/src/main/kotlin/org.hiero.gradle.feature.benchmark.gradle.kts index 4361107..b04f6ad 100644 --- a/src/main/kotlin/org.hiero.gradle.feature.benchmark.gradle.kts +++ b/src/main/kotlin/org.hiero.gradle.feature.benchmark.gradle.kts @@ -19,7 +19,10 @@ dependencies { jmhAnnotationProcessor("org.openjdk.jmh:jmh-generator-annprocess:${jmh.jmhVersion.get()}") } -tasks.jmh { outputs.upToDateWhen { false } } +tasks.jmh { + group = "build" + outputs.upToDateWhen { false } +} tasks.withType().configureEach { group = "jmh"