From c5c9107d51ca3984add30e95e1b7bae435996134 Mon Sep 17 00:00:00 2001 From: Osip Fatkullin Date: Tue, 9 Jul 2024 21:03:30 +0200 Subject: [PATCH] docs: Update plugins features in README --- README.md | 129 ++++++++++++++---- build.gradle.kts | 5 +- .../src/main/kotlin/StaticAnalyzerSpec.kt | 4 +- .../src/main/kotlin/kotlin/TestOptions.kt | 9 +- 4 files changed, 115 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 2f505bb..d6f9066 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,8 @@ Small plugins to reduce boilerplate in Gradle build scripts. -> :warning: It is designed to use with Gradle Kotlin DSL and can't be used from Groovy DSL. +> [!IMPORTANT] +> These plugins are designed to be used with Gradle Kotlin DSL only. --- @@ -24,7 +25,7 @@ Small plugins to reduce boilerplate in Gradle build scripts. - [Configuration](#configuration) - [Align version of all Kotlin libraries](#align-version-of-all-kotlin-libraries) - [Warnings as errors](#warnings-as-errors) - - [Share sources between build types](#share-sources-between-build-types) + - [Share sources between build variants](#share-sources-between-build-variants) - [Enable Detekt checks only on changed files](#enable-detekt-checks-only-on-changed-files) - [Configure JUnit test execution options](#configure-junit-test-execution-options) - [Automatically added repositories](#automatically-added-repositories) @@ -109,7 +110,30 @@ android { ## Plugins -[![](https://mermaid.ink/img/eyJjb2RlIjoiZ3JhcGggQlRcbnN1YmdyYXBoIGluZnJhc3RydWN0dXJlLWFuZHJvaWRcbiAgICBhbmRyb2lkLWNvbmZpZ1tjb20ucmVkbWFkcm9ib3QuYW5kcm9pZC1jb25maWddXG4gICAgY29tLnJlZG1hZHJvYm90LmFwcGxpY2F0aW9uIC0tPiBhbmRyb2lkLWNvbmZpZ1xuICAgIGNvbS5yZWRtYWRyb2JvdC5hbmRyb2lkLWxpYnJhcnkgLS0-IGFuZHJvaWQtY29uZmlnXG5lbmRcblxuc3ViZ3JhcGggaW5mcmFzdHJ1Y3R1cmUtZGV0ZWt0XG4gICAgY29tLnJlZG1hZHJvYm90LmRldGVrdFxuZW5kXG5cbnN1YmdyYXBoIGluZnJhc3RydWN0dXJlLWtvdGxpblxuICAgIGtvdGxpbi1jb25maWdbY29tLnJlZG1hZHJvYm90LmtvdGxpbi1jb25maWddXG4gICAgY29tLnJlZG1hZHJvYm90LmtvdGxpbi1saWJyYXJ5IC0tPiBrb3RsaW4tY29uZmlnXG5lbmRcblxuc3ViZ3JhcGggaW5mcmFzdHJ1Y3R1cmUtcHVibGlzaFxuICAgIHB1Ymxpc2gtY29uZmlnW2NvbS5yZWRtYWRyb2JvdC5wdWJsaXNoLWNvbmZpZ11cbiAgICBjb20ucmVkbWFkcm9ib3QucHVibGlzaCAtLT4gcHVibGlzaC1jb25maWdcbmVuZFxuXG5hbmRyb2lkLWNvbmZpZyAtLT4ga290bGluLWNvbmZpZyIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6dHJ1ZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOnRydWV9)](https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggQlRcbnN1YmdyYXBoIGluZnJhc3RydWN0dXJlLWFuZHJvaWRcbiAgICBhbmRyb2lkLWNvbmZpZ1tjb20ucmVkbWFkcm9ib3QuYW5kcm9pZC1jb25maWddXG4gICAgY29tLnJlZG1hZHJvYm90LmFwcGxpY2F0aW9uIC0tPiBhbmRyb2lkLWNvbmZpZ1xuICAgIGNvbS5yZWRtYWRyb2JvdC5hbmRyb2lkLWxpYnJhcnkgLS0-IGFuZHJvaWQtY29uZmlnXG5lbmRcblxuc3ViZ3JhcGggaW5mcmFzdHJ1Y3R1cmUtZGV0ZWt0XG4gICAgY29tLnJlZG1hZHJvYm90LmRldGVrdFxuZW5kXG5cbnN1YmdyYXBoIGluZnJhc3RydWN0dXJlLWtvdGxpblxuICAgIGtvdGxpbi1jb25maWdbY29tLnJlZG1hZHJvYm90LmtvdGxpbi1jb25maWddXG4gICAgY29tLnJlZG1hZHJvYm90LmtvdGxpbi1saWJyYXJ5IC0tPiBrb3RsaW4tY29uZmlnXG5lbmRcblxuc3ViZ3JhcGggaW5mcmFzdHJ1Y3R1cmUtcHVibGlzaFxuICAgIHB1Ymxpc2gtY29uZmlnW2NvbS5yZWRtYWRyb2JvdC5wdWJsaXNoLWNvbmZpZ11cbiAgICBjb20ucmVkbWFkcm9ib3QucHVibGlzaCAtLT4gcHVibGlzaC1jb25maWdcbmVuZFxuXG5hbmRyb2lkLWNvbmZpZyAtLT4ga290bGluLWNvbmZpZyIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOnRydWUsImF1dG9TeW5jIjp0cnVlLCJ1cGRhdGVEaWFncmFtIjp0cnVlfQ) +```mermaid +graph BT +subgraph infrastructure-android + android-config[com.redmadrobot.android-config] + com.redmadrobot.application --> android-config + com.redmadrobot.android-library --> android-config +end + +subgraph infrastructure-detekt + com.redmadrobot.detekt +end + +subgraph infrastructure-kotlin + kotlin-config[com.redmadrobot.kotlin-config] + com.redmadrobot.kotlin-library --> kotlin-config +end + +subgraph infrastructure-publish + publish-config[com.redmadrobot.publish-config] + com.redmadrobot.publish --> publish-config +end + +android-config --> kotlin-config +``` ### kotlin-library @@ -221,22 +245,24 @@ publishing.publications.getByName(PUBLICATION_NAME) { Common configurations for Android libraries and application. -Both: +[Both][BaseAndroidPlugin]: - Specifies default compile, min and target SDK - Disables `shaders` [build-features] by default - Applies [android-cache-fix-gradle-plugin](https://github.com/gradle/android-cache-fix-gradle-plugin) +- Configures Android Lint with [defaults][lint-options] +- [Filters tests][testTaskFilter] to be run on `test` task according to the config. + By default, keeps only tests for build type `release`. -Library: +[Library][AndroidLibraryPlugin]: - Applies plugin `com.android.library` - Adds all proguard files from `proguard` folder as `consumerProguardFiles` - Disables `androidResources` and `resValues` [build-features] by default - Enables [explicit API mode][explicit-api] -Application: +[Application][AndroidApplicationPlugin]: - Applies plugin `com.android.application` - Adds all proguard files from `proguard` folder - Configures `debug`, `qa` and `release` build types -- Configures Android Lint [default options][lint-options] #### QA build type name configuration @@ -288,15 +314,68 @@ See [compatibility table](#compatibility) to check what versions are compatible ### Configuration -You can configure the plugins with an extension named `redmadrobot`. -Look for available properties with description in [RedmadrobotExtension]. +You can configure the plugins via the `redmadrobot` extension. +Here are listed all available options, with their default values: -The extension should be configured in root project. ```kotlin -// root project build.gradle.kts - redmadrobot { - configsDir = file("path/to/configs/") + /* Common options */ + // Directory with configs for static analyzers and other tools. + configsDir = file("config/") + + // Directory with reports of static analyzers and other tools. + reportsDir = file("build/reports/") + + /* `kotlin-config` options */ + test { + // Specifies that JUnit Platform (JUnit 5) should be used to execute tests. + useJunitPlatform() + + // Specifies that JUnit 4 should be used to execute tests. + useJunit() + } + + /* `android-config` options */ + android { + // minSdk to be used in all android modules. + minSdk = 23 + + // targetSdk to be used in all android modules. + targetSdk = 34 + + // compileSdk to be used in all android modules + compileSdk = "34" + + // Build Tools version to be used in all android modules. + buildToolsVersion = System.getenv("ANDROID_BUILD_TOOLS_VERSION") + + // Filter for test tasks that should be run on ':test'. + testTasksFilter = { taskProvider -> taskProvider.name.endsWith("ReleaseUnitTest") } + + // Overrides of test configuration for android projects + test { /* ... */ } + } + + /* `detekt` options */ + detekt { + // Enable Detekt checks only for modified files + // (Disabled by default) + checkOnlyDiffWithBranch(branch = "main") { + fileExtensions = setOf(".kt", ".kts") + } + } + + /* `publish-config` options */ + publishing { + // Enables artifacts signing before publication. + signArtifacts = false + + // Use gpg-agent to sign artifacts. Has effect only if signArtifacts is `true`. + useGpgAgent = true + + // Configures POM file for this project and its subprojects. + pom { /* ... */ } + } } ``` @@ -337,18 +416,19 @@ You can change it by defining the `warningsAsErrors` project property. [Read more about Gradle project properties][project-properties] -### Share sources between build types +### Share sources between build variants + +You can share sources between two build variants. +For example, you need to use debug panel in both "debug" and "QA" builds, and don't want to duplicate code for each of these build types. +You can do it in one line with [addSharedSourceSetRoot] extension-function: -You can share sources between two build types. -For example, you need to use debug panel in both debug and QA builds, and don't want to write similar duplicating code for each of these build types. -You can do it with one line with [addSharedSourceSetRoot] extension-function: ```kotlin android { // We need to share sources between debug and QA builds - addSharedSourceSetRoot(BUILD_TYPE_DEBUG, BUILD_TYPE_QA) + sourceSet.addSharedSourceSetRoot(BUILD_TYPE_DEBUG, BUILD_TYPE_QA) - // We can specify name for the source set root if need - addSharedSourceSetRoot(BUILD_TYPE_DEBUG, BUILD_TYPE_QA, name = "debugPanel") + // We can specify a name for the source set root if needed + sourceSet.addSharedSourceSetRoot(BUILD_TYPE_DEBUG, BUILD_TYPE_QA, name = "debugPanel") } ``` @@ -495,7 +575,7 @@ Execution failed for task ':app:stripDebugDebugSymbols'. It is because NDK version on CI differs from a requested version. You can change requested version by setting `android.ndkVersion`. -Plugins `com.redmadrobot.android-library` and `com.redmadrobot.application` by default apply NDK version from env variable `ANDROID_NDK_VERSION` if it set. +Plugins `com.redmadrobot.android-library` and `com.redmadrobot.application` by default apply NDK version from env variable `ANDROID_NDK_VERSION` if it is set. ### `Could not resolve` or `Could not find` dependencies @@ -535,11 +615,14 @@ For major changes, please open an issue first to discuss what you would like to [MIT][license] [samples]: samples/ -[RedmadrobotExtension]: infrastructure/src/main/kotlin/extension/RedmadrobotExtension.kt [MavenPom]: infrastructure/src/main/kotlin/dsl/MavenPom.kt [predicates]: infrastructure/src/main/kotlin/dsl/PublishingPredicates.kt [addSharedSourceSetRoot]: infrastructure-android/src/main/kotlin/dsl/SourceSets.kt -[lint-options]: https://github.com/RedMadRobot/gradle-infrastructure/blob/2e96c04cbb9d15ca508d1d4b4a8b1e2da4bab6af/infrastructure/src/main/kotlin/AndroidApplicationPlugin.kt#L63-L72 +[lint-options]: infrastructure-android/src/main/kotlin/android/BaseAndroidPlugin.kt#L76-L80 +[testTaskFilter]: infrastructure-android/src/main/kotlin/android/AndroidOptions.kt#L28-L35 +[BaseAndroidPlugin]: infrastructure-android/src/main/kotlin/android/BaseAndroidPlugin.kt +[AndroidLibraryPlugin]: infrastructure-android/src/main/kotlin/android/AndroidLibraryPlugin.kt +[AndroidApplicationPlugin]: infrastructure-android/src/main/kotlin/android/AndroidApplicationPlugin.kt [infrastructure]: # [itemsadapter]: https://github.com/RedMadRobot/itemsadapter diff --git a/build.gradle.kts b/build.gradle.kts index 23a62af..84e9439 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -1,7 +1,4 @@ -import com.redmadrobot.build.dsl.developer -import com.redmadrobot.build.dsl.isRunningOnCi -import com.redmadrobot.build.dsl.mit -import com.redmadrobot.build.dsl.setGitHubProject +import com.redmadrobot.build.dsl.* plugins { id("com.redmadrobot.detekt") diff --git a/infrastructure-common/src/main/kotlin/StaticAnalyzerSpec.kt b/infrastructure-common/src/main/kotlin/StaticAnalyzerSpec.kt index ce9766d..cdc9fb7 100644 --- a/infrastructure-common/src/main/kotlin/StaticAnalyzerSpec.kt +++ b/infrastructure-common/src/main/kotlin/StaticAnalyzerSpec.kt @@ -5,10 +5,10 @@ import org.gradle.api.file.DirectoryProperty /** Options used for static analyzers' configurations. */ public interface StaticAnalyzerSpec { - /** Directory where stored configs for static analyzers. */ + /** Directory with configs for static analyzers and other tools. */ public val configsDir: DirectoryProperty - /** Directory where will be stored static analyzers reports. */ + /** Directory with reports of static analyzers and other tools. */ public val reportsDir: DirectoryProperty public companion object { diff --git a/infrastructure-kotlin/src/main/kotlin/kotlin/TestOptions.kt b/infrastructure-kotlin/src/main/kotlin/kotlin/TestOptions.kt index d20ae5a..733d090 100644 --- a/infrastructure-kotlin/src/main/kotlin/kotlin/TestOptions.kt +++ b/infrastructure-kotlin/src/main/kotlin/kotlin/TestOptions.kt @@ -7,12 +7,15 @@ import org.gradle.api.tasks.testing.junitplatform.JUnitPlatformOptions /** Options used to configure tests. */ public interface TestOptions { - /** Flag for using Junit Jupiter Platform. Use functions [useJunit] or [useJunitPlatform]. */ + /** + * Flag for using Junit Jupiter Platform. + * Use functions [useJunitPlatform] and [useJunit] to change it. + */ public val useJunitPlatform: Provider - /** Specifies that JUnit Platform (JUnit 5) should be used to execute the tests. */ + /** Specifies that JUnit Platform (JUnit 5) should be used to execute tests. */ public fun useJunitPlatform(configure: JUnitPlatformOptions.() -> Unit = {}) - /** Specifies that JUnit should be used to execute the tests. */ + /** Specifies that JUnit 4 should be used to execute tests. */ public fun useJunit(configure: JUnitOptions.() -> Unit = {}) }