feat: improve control and reporting of the configuration plugin overall

* add `FLUXO_VERBOSE` flag to enable verbose output without enabling the `MAX_DEBUG` mode;
* `DISABLE_R8` now disables all shrinking altogether;
* report a version of the bundled/classpath ProGuard version;
* report `includedBuilds` number during the composite build;
* add some documentation and to-do notes;

Signed-off-by: Artyom Shendrik <artyom.shendrik@gmail.com>

CHANGELOG.md

@@ -7,6 +7,13 @@
 
 ### Added
 - allow switching on/off the R8 full mode, also called "non-compat mode." Disabled by default.
+- add `FLUXO_VERBOSE` flag to enable verbose output without enabling the `MAX_DEBUG` mode.
+- report a version of the bundled/classpath ProGuard version.
+- report `includedBuilds` number during the composite build.
+- add some documentation and to-do notes.
+
+### Changed
+- `DISABLE_R8` now disables all shrinking altogether.
 
 
 ## [0.6.0] - 2024-01-05

README.md

@@ -172,6 +172,27 @@ pluginManagement {
   * https://github.com/avito-tech/avito-android
     * https://github.com/avito-tech/avito-android/blob/a1949b4/subprojects/assemble/proguard-guard/src/main/kotlin/com/avito/android/proguard_guard/shadowr8/ShadowR8TaskCreator.kt
     * GIT hooks: https://github.com/avito-tech/avito-android/tree/develop/.git_hooks
+  * Gradle Core plugins
+    * https://github.com/gradle/gradle/tree/a300b86/platforms/documentation/docs/src/docs/userguide/core-plugins
+  * Gradle configuration
+    * https://github.com/Kotlin/kotlinx.coroutines/blob/d12eb45/kotlinx-coroutines-core/build.gradle#L238
+    * SgtSilvio gradle plugins
+      * Example: https://github.com/SgtSilvio/gradle-proguard/blob/61e7230/build.gradle.kts
+      * Gradle plugin to ease using and producing (multi-arch) OCI (Open Container Initiative, prev. Docker) images.
+        without requiring external tools.
+        * https://github.com/SgtSilvio/gradle-oci
+        * https://github.com/SgtSilvio/oci-registry (OCI registry Java library that allows serving OCI artifacts to pull operations).
+        * https://github.com/SgtSilvio/gradle-oci-junit-jupiter.
+      * Gradle plugin to ease defining project metadata (urls, license, scm).
+        * module name, readable name, url, docUrl, organization, license, developers, issue management, github.
+        * https://github.com/SgtSilvio/gradle-metadata
+      * Gradle plugin to ease defining Javadoc links.
+        * https://github.com/SgtSilvio/gradle-javadoc-links
+      * Gradle plugin that configures sensible defaults.
+        * https://github.com/SgtSilvio/gradle-defaults
+        * UTF 8 for Java compilation and Javadoc
+        * Reproducible artifacts
+        * Granular test reports per test case (method instead of class)
 * https://github.com/BenWoodworth/Parameterize
 * https://github.com/kotlin-hands-on/kotlin-swift-interopedia
 * https://github.com/drewhamilton/poko/

fluxo-kmp-conf/api/plugin.api

@@ -607,6 +607,7 @@ public abstract interface class fluxo/minification/FluxoShrinkerConfig {
 	public abstract fun getMaxHeapSize ()Lorg/gradle/api/provider/Property;
 	public abstract fun getObfuscate ()Lorg/gradle/api/provider/Property;
 	public abstract fun getOptimize ()Lorg/gradle/api/provider/Property;
+	public abstract fun getR8FullMode ()Lorg/gradle/api/provider/Property;
 	public abstract fun getReplaceOutgoingJar ()Lorg/gradle/api/provider/Property;
 	public abstract fun getUseBothShrinkers ()Lorg/gradle/api/provider/Property;
 	public abstract fun getUseR8 ()Lorg/gradle/api/provider/Property;

fluxo-kmp-conf/build.gradle.kts

@@ -128,10 +128,14 @@ buildConfig {
     fun buildConfigField(
         fieldName: String,
         p: Provider<MinimalExternalModuleDependency>,
+        compileOnly: Boolean = true,
     ) {
         p.get().apply {
             buildConfigField("String", fieldName, "\"$group:$name:$version\"")
         }
+        if (compileOnly) {
+            dependencies.compileOnly(p)
+        }
     }
     buildConfigField("PROGUARD_PLUGIN", libs.proguard.plugin)
     buildConfigField("PROGUARD_CORE", libs.proguard.core)

fluxo-kmp-conf/dependencies/compileClasspath.txt

@@ -5,6 +5,7 @@ com.android.tools.build:builder:8.4.0-alpha02
 com.android.tools.build:gradle-api:8.4.0-alpha02
 com.android.tools.build:gradle:8.4.0-alpha02
 com.android.tools.build:manifest-merger:31.4.0-alpha02
+com.android.tools:r8:8.2.33
 com.android:zipflinger:8.4.0-alpha02
 com.autonomousapps.dependency-analysis:com.autonomousapps.dependency-analysis.gradle.plugin:1.28.0
 com.autonomousapps:dependency-analysis-gradle-plugin:1.28.0
@@ -30,6 +31,9 @@ com.gradle.enterprise:com.gradle.enterprise.gradle.plugin:3.16.1
 com.gradle.plugin-publish:com.gradle.plugin-publish.gradle.plugin:1.2.1
 com.gradle.publish:plugin-publish-plugin:1.2.1
 com.gradle:gradle-enterprise-gradle-plugin:3.16.1
+com.guardsquare:proguard-base:7.4.1
+com.guardsquare:proguard-core:9.1.1
+com.guardsquare:proguard-gradle:7.4.1
 com.louiscad.complete-kotlin:com.louiscad.complete-kotlin.gradle.plugin:1.1.0
 com.louiscad.complete-kotlin:plugin:1.1.0
 com.mikepenz.aboutlibraries.plugin:aboutlibraries-plugin:10.10.0
@@ -81,4 +85,5 @@ org.jetbrains.kotlin:kotlin-util-io:1.9.22
 org.jetbrains.kotlin:kotlin-util-klib:1.9.22
 org.jetbrains.kotlinx.binary-compatibility-validator:org.jetbrains.kotlinx.binary-compatibility-validator.gradle.plugin:0.13.2
 org.jetbrains.kotlinx:binary-compatibility-validator:0.13.2
+org.jetbrains.kotlinx:kotlinx-metadata-jvm:0.6.0
 org.ow2.asm:asm:9.6

fluxo-kmp-conf/detekt-baseline.xml

@@ -6,6 +6,7 @@
     <ID>ComplexCondition:SetupTestsReport.kt$!enabled || mergedReportTask == null || mergedReportService == null || !isTestTaskAllowed()</ID>
     <ID>CyclomaticComplexMethod:LoadAndApplyPluginIfNotApplied.kt$private fun FluxoKmpConfContext.loadPluginArtifactAndGetClass( pluginId: String, pluginVersion: String?, className: String?, catalogPluginAlias: String?, lookupClassName: Boolean, canLoadDynamically: Boolean, project: Project, ): Class&lt;*>?</ID>
     <ID>CyclomaticComplexMethod:SetupAndroidLint.kt$internal fun Project.setupAndroidLint( conf: FluxoConfigurationExtensionImpl, ignoredBuildTypes: List&lt;String>, ignoredFlavors: List&lt;String>, )</ID>
+    <ID>ForbiddenComment:AbstractShrinkerTask.kt$// FIXME: Before Java 9, the runtime classes were packaged in a single jar file.</ID>
     <ID>ForbiddenComment:AbstractShrinkerTask.kt$// TODO: Move into a separate file, loaded from resources</ID>
     <ID>ForbiddenComment:AbstractShrinkerTask.kt$AbstractShrinkerTask$// FIXME: Move mapping to the output dir?</ID>
     <ID>ForbiddenComment:AbstractShrinkerTask.kt$AbstractShrinkerTask$// FIXME: When java toolchain used or JDK target is specified, read the specified JDK.</ID>

fluxo-kmp-conf/pg/keep-api-autogenerated.pro

@@ -603,6 +603,7 @@
     public abstract org.gradle.api.provider.Property getMaxHeapSize();
     public abstract org.gradle.api.provider.Property getObfuscate();
     public abstract org.gradle.api.provider.Property getOptimize();
+    public abstract org.gradle.api.provider.Property getR8FullMode();
     public abstract org.gradle.api.provider.Property getReplaceOutgoingJar();
     public abstract org.gradle.api.provider.Property getUseBothShrinkers();
     public abstract org.gradle.api.provider.Property getUseR8();

fluxo-kmp-conf/src/main/kotlin/PropsAndEnv.kt

@@ -44,6 +44,8 @@ public fun Project.isDesugaringEnabled(): Provider<Boolean> = envOrPropFlag("DES
 
 public fun Project.isMaxDebugEnabled(): Provider<Boolean> = envOrPropFlag("MAX_DEBUG")
 
+internal fun Project.isFluxoVerbose(): Provider<Boolean> = envOrPropFlag("FLUXO_VERBOSE")
+
 public fun Project.isR8Disabled(): Provider<Boolean> = envOrPropFlag("DISABLE_R8")
 
 public fun Project?.buildNumber(): String? = envOrPropValueLenient("BUILD_NUMBER")

fluxo-kmp-conf/src/main/kotlin/fluxo/conf/FluxoKmpConfContext.kt

@@ -24,6 +24,7 @@ import fluxo.conf.impl.w
 import getValue
 import isCI
 import isDesugaringEnabled
+import isFluxoVerbose
 import isMaxDebugEnabled
 import isR8Disabled
 import isRelease
@@ -103,7 +104,8 @@ internal abstract class FluxoKmpConfContext
         val gradle = project.gradle
         val logger = project.logger
 
-        if (isMaxDebug) SHOW_DEBUG_LOGS = true
+        val isVerbose = isMaxDebug || logger.isInfoEnabled || project.isFluxoVerbose().get()
+        if (isVerbose) SHOW_DEBUG_LOGS = true
 
         // Log environment
         run {
@@ -112,13 +114,20 @@ internal abstract class FluxoKmpConfContext
                 "Kotlin $kotlinPluginVersion, " +
                 "$CPUs CPUs"
 
-            // R8 version
+            // Bundled/Classpath R8 version
             try {
                 // https://r8.googlesource.com/r8/+refs
                 // https://issuetracker.google.com/issues/193543616#comment4
                 // https://mvnrepository.com/artifact/com.android.tools/r8
                 val r8 = com.android.tools.r8.Version.getVersionString().substringBefore(" (")
-                m += ", R8 $r8"
+                m += ", Bundled R8 $r8"
+            } catch (_: Throwable) {
+            }
+
+            // Bundled/Classpath ProGuard version
+            try {
+                val pg = proguard.ProGuard.getVersion()
+                m += ", Bundled ProGuard $pg"
             } catch (_: Throwable) {
             }
 
@@ -150,14 +159,23 @@ internal abstract class FluxoKmpConfContext
             taskGraphBasedProjectSyncDetection()
         }
 
+        if (isInCompositeBuild) {
+            val includedBuilds = gradle.includedBuilds.size
+            logger.l("COMPOSITE build is enabled! ($includedBuilds includedBuilds)")
+        }
         if (isCI) logger.l("CI mode is enabled!")
         if (isRelease) logger.l("RELEASE mode is enabled!")
         if (composeMetricsEnabled) logger.l("COMPOSE_METRICS are enabled!")
 
         if (useKotlinDebug) logger.w("USE_KOTLIN_DEBUG is enabled!")
-        if (isMaxDebug) logger.w("MAX_DEBUG is enabled!")
+        when {
+            isMaxDebug -> logger.w("MAX_DEBUG is enabled!")
+            isVerbose -> logger.w("FLUXO_VERBOSE is enabled!")
+        }
         if (isDesugaringEnabled) logger.w("DESUGARING is enabled!")
-        if (project.isR8Disabled().get()) logger.w("R8 is disabled! (DISABLE_R8)")
+        if (project.isR8Disabled().get()) {
+            logger.w("SHRINKING (R8/ProGuard) is disabled! (DISABLE_R8)")
+        }
 
         // Disable all tests if:
         //  - `DISABLE_TESTS` is enabled;
@@ -180,7 +198,7 @@ internal abstract class FluxoKmpConfContext
         }
 
         logger.v("Cleaned start task names: $startTaskNames")
-        logger.v("kotlinPluginVersion: $kotlinPluginVersion")
+        logger.v("Kotlin Plugin version: $kotlinPluginVersion")
         logger.v("isInIde: $isInIde")
     }
 

fluxo-kmp-conf/src/main/kotlin/fluxo/conf/FluxoKmpConfPlugin.kt

@@ -33,6 +33,7 @@ import fluxo.conf.impl.kotlin.KOTLIN_EXT
 import fluxo.conf.impl.kotlin.configureKotlinJvm
 import fluxo.conf.impl.kotlin.configureKotlinMultiplatform
 import fluxo.conf.impl.kotlin.setupKmpYarnPlugin
+import isR8Disabled
 import org.gradle.api.GradleException
 import org.gradle.api.Plugin
 import org.gradle.api.Project
@@ -121,14 +122,17 @@ public class FluxoKmpConfPlugin : Plugin<Project> {
         }
 
         // Artifacts minification
-        setupArtifactsShrinking(conf)
+        val project = conf.project
+        if (!project.isR8Disabled().get()) {
+            setupArtifactsShrinking(conf)
+        }
 
         // Gradle project atifacts publication
         setupGradleProjectPublication(conf)
 
         // Generic custom lazy configuration
         conf.onConfiguration?.let { action ->
-            conf.project.configureExtension(KOTLIN_EXT, action = action)
+            project.configureExtension(KOTLIN_EXT, action = action)
         }
     }
 
@@ -137,9 +141,28 @@ public class FluxoKmpConfPlugin : Plugin<Project> {
      *
      * @see org.gradle.api.plugins.BasePlugin ('base')
      * @see org.gradle.language.base.plugins.LifecycleBasePlugin
+     * @see org.gradle.api.plugins.JavaPlugin
+     * @see org.gradle.api.plugins.JavaBasePlugin
+     * @see org.gradle.api.plugins.JavaPlatformPlugin
+     * @see org.gradle.api.plugins.JavaLibraryPlugin
+     * @see org.gradle.api.plugins.JavaTestFixturesPlugin
+     * @see org.gradle.api.plugins.JvmEcosystemPlugin
+     * @see org.gradle.api.plugins.JvmTestSuitePlugin
+     * @see org.gradle.api.plugins.JvmToolchainManagementPlugin
+     * @see org.gradle.api.plugins.JvmToolchainsPlugin
+     * @see org.gradle.api.plugins.catalog.VersionCatalogPlugin
+     * @see org.gradle.api.plugins.ReportingBasePlugin
+     * @see org.gradle.api.plugins.ProjectReportsPlugin
+     * @see org.gradle.api.plugins.TestReportAggregationPlugin
+     * @see org.gradle.api.plugins.HelpTasksPlugin
      */
-    private fun checkGradleLifecycleBase(target: Project) =
+    @Suppress("UnstableApiUsage")
+    private fun checkGradleLifecycleBase(target: Project) {
+        // https://docs.gradle.org/current/userguide/base_plugin.html
+        // https://github.com/gradle/gradle/tree/a300b86/platforms/documentation/docs/src/docs/userguide/core-plugins
+
         target.pluginManager.apply(LifecycleBasePlugin::class.java)
+    }
 
     /**
      * Make sure there's a Kotlin plugin in the classpath.

fluxo-kmp-conf/src/main/kotlin/fluxo/conf/feat/SetupArtifactsShrinking.kt

@@ -25,8 +25,17 @@ import org.gradle.language.base.plugins.LifecycleBasePlugin.CHECK_TASK_NAME
 // https://github.com/JetBrains/compose-multiplatform/blob/50d45f3/gradle-plugins/compose/src/main/kotlin/org/jetbrains/compose/desktop/application/internal/configureJvmApplication.kt#L241
 // https://github.com/JetBrains/compose-multiplatform/blob/b67dde7/gradle-plugins/compose/src/main/kotlin/org/jetbrains/compose/desktop/application/tasks/AbstractProguardTask.kt#L22
 // https://github.com/TWiStErRob/net.twisterrob.inventory/blob/cc4eb02/gradle/plugins-inventory/src/main/kotlin/net/twisterrob/inventory/build/unfuscation/UnfuscateTask.kt#L33
+// https://github.com/SgtSilvio/gradle-proguard/blob/36e9437/src/main/kotlin/io/github/sgtsilvio/gradle/proguard/ProguardTask.kt#L39
+// https://github.com/ArcticLampyrid/gradle-git-version/blob/23ccfc8/build.gradle.kts#L72
 // endregion
 
+/**
+ *
+ * @see com.android.tools.r8.R8
+ * @see com.android.tools.r8.Version
+ * @see proguard.ProGuard
+ * @see proguard.ProGuard.getVersion
+ */
 internal fun setupArtifactsShrinking(
     conf: FluxoConfigurationExtensionImpl,
 ) {
@@ -92,6 +101,7 @@ internal fun setupArtifactsShrinking(
     }
 
     // FIXME: Run tests with minified artifacts
+    //  https://github.com/ArcticLampyrid/gradle-git-version/blob/23ccfc8/build.gradle.kts#L72
 }
 
 private fun modeIsNotSupported(conf: FluxoConfigurationExtensionImpl) = when (conf.mode) {

fluxo-kmp-conf/src/main/kotlin/fluxo/minification/AbstractShrinkerTask.kt

@@ -483,10 +483,14 @@ internal abstract class AbstractShrinkerTask : AbstractExternalFluxoTask() {
     private fun Writer.ln(s: String) = appendLine(s)
 }
 
-private fun getJmods(javaHome: File) =
-    javaHome.resolve("jmods").walk().filter {
+private fun getJmods(javaHome: File): Sequence<File> {
+    // FIXME: Before Java 9, the runtime classes were packaged in a single jar file.
+    //  https://github.com/ArcticLampyrid/gradle-git-version/blob/23ccfc8/build.gradle.kts#L72
+
+    return javaHome.resolve("jmods").walk().filter {
         it.isFile && it.path.endsWith("jmod", ignoreCase = true)
     }
+}
 
 internal const val SHRINKER_TASK_PREFIX = "shrinkWith"
 

fluxo-kmp-conf/src/main/kotlin/fluxo/minification/RegisterShrinkerTask.kt

@@ -6,6 +6,7 @@ import fluxo.conf.data.BuildConstants.PROGUARD_CORE
 import fluxo.conf.data.BuildConstants.PROGUARD_PLUGIN
 import fluxo.conf.deps.detachedDependency
 import fluxo.conf.dsl.impl.FluxoConfigurationExtensionImpl
+import fluxo.conf.impl.SHOW_DEBUG_LOGS
 import fluxo.conf.impl.capitalizeAsciiOnly
 import fluxo.conf.impl.get
 import fluxo.conf.impl.kotlin.KOTLIN_JVM_PLUGIN_ID
@@ -36,7 +37,7 @@ internal fun Project.registerShrinkerTask(
 ) = tasks.register<AbstractShrinkerTask>(
     name = getShrinkerTaskName(conf, forceShrinker),
 ) {
-    val isVerbose = logger.isInfoEnabled
+    val isVerbose = SHOW_DEBUG_LOGS || logger.isInfoEnabled
     if (isVerbose) {
         verbose.set(true)
     }