Add recipe for MultipleArtifactTypeOutOperationRequest.toListenTo()

Bug: n/a
Test: n/a
Change-Id: I309661b1d3b11a128cfec592342ac99734c0f135

BUILD

@@ -161,3 +161,7 @@ recipe_test(
 recipe_test(
     name = "registerPreBuild",
 )
+
+recipe_test(
+    name = "listenToMultipleArtifact",
+)

recipes/listenToArtifacts/README.md

@@ -5,18 +5,15 @@ called when the task creating the artifact runs. This allows tasks that must pro
 to run without changing what task should be called by the user. In this particular example, the
 task makes a copy of the APKs while renaming them.
 
-
 Custom plugin is defined in [CustomPlugin.kt](build-logic/plugins/src/main/kotlin/CustomPlugin.kt).
 It registers task [CopyApk.kt](build-logic/plugins/src/main/kotlin/CopyApk.kt) that simply copies
 the file somewhere else using each APK's own metadata information.
 
 `SingleArtifact.APK` is an artifact of type `Artifact.ContainsMany`. This is a type of directory-based
-artifact that can actually contain many artifacts. Each artifact is associated with specificy meta-data.
+artifact that can actually contain many artifacts. Each artifact is associated with specific meta-data.
 
 Reading these artifacts from the directory require usage of `BuiltArtifactsLoader`.
 
-
 ## To Run
 Just type `./gradlew app:assembleDebug`
-You will be able to find the renamed APKs at `app/build/outputs/renamedintermediates/apk/debug/packageDebug/app-debug.apk`
-and `app/build/outputs/apk/debug/app-debug.apk` after copying.
+You will be able to find the renamed APK at `app/build/outputs/renamed_apks/debug/debug-Feb2024-12.apk` after copying.

recipes/listenToArtifacts/build-logic/plugins/src/main/kotlin/CustomPlugin.kt

@@ -75,7 +75,7 @@ class CustomPlugin : Plugin<Project> {
                     // automatically when the normal APK packaging task run.
                     // So we set the input manually, and the validation task will have to be called
                     // separately (in a separate Gradle execution or Gradle will detect the
-                    // lack of dependency between the 2 tasks and complain.
+                    // lack of dependency between the 2 tasks and complain).
                     input.set(project.layout.buildDirectory.dir("outputs/renamed_apks/${variant.name}"))
                     variantName.set(variant.name)
                 }

recipes/listenToMultipleArtifact/README.md

@@ -0,0 +1,25 @@
+# toListenTo recipe for Artifact.Multiple
+
+This sample shows how to react to a change to an artifact of type [`Artifact.Multiple`](https://developer.android.com/reference/tools/gradle-api/current/com/android/build/api/artifact/Artifact.Multiple) that causes the artifact
+to be regenerated. The API will make sure that the task is called when the task regenerating the artifact runs. This
+allows tasks that must process an artifact to run without changing what task should be called by the user. In this
+particular example, the task makes a copy of the multi-dex proguard files while renaming them.
+
+Custom plugin is defined in [CustomPlugin.kt](build-logic/plugins/src/main/kotlin/CustomPlugin.kt).
+It registers task [CopyProguardTask.kt](build-logic/plugins/src/main/kotlin/CopyProguardTask.kt) that simply copies
+a proguard file somewhere else and renames it.
+
+The API used in this recipe is [`MultipleArtifactTypeOutOperationRequest.toListenTo()`](https://developer.android.com/reference/tools/gradle-api/current/com/android/build/api/artifact/MultipleArtifactTypeOutOperationRequest#toListenTo(com.android.build.api.artifact.Artifact.Multiple)),
+and this is wired up to the task with [`TaskBasedOperation.wiredWithMultiple()`](https://developer.android.com/reference/tools/gradle-api/current/com/android/build/api/artifact/TaskBasedOperation#wiredWithMultiple(kotlin.Function1)).
+Below is an example usage of the APIs:
+
+```
+variant.artifacts.use(copyTask).wiredWithMultiple {
+    it.proguardFiles
+}.toListenTo(MultipleArtifact.MULTIDEX_KEEP_PROGUARD)
+```
+
+## To Run
+Just type `./gradlew app:assembleDebug`
+You will be able to find the renamed metadata file at
+`app/build/renamed_intermediates/native_debug_metadata/debug/renamed_test_file.dbg` after copying.

recipes/listenToMultipleArtifact/app/build.gradle.kts

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    id("android.recipes.custom_plugin")
+}
+
+android {
+    namespace = "com.example.android.recipes.listentomultipleartifact"
+    compileSdk = $COMPILE_SDK
+    defaultConfig {
+       minSdk = $MINIMUM_SDK
+       targetSdk = $COMPILE_SDK
+    }
+
+    // This is necessary to enable the tasks that use NATIVE_DEBUG_METADATA
+    buildTypes {
+        debug {
+            ndk {
+                debugSymbolLevel = "FULL"
+            }
+        }
+    }
+}
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(17))
+    }
+}

recipes/listenToMultipleArtifact/app/nativeDebugMetadataDir/test_file.dbg

@@ -0,0 +1 @@
+test data

recipes/listenToMultipleArtifact/app/src/main/AndroidManifest.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!--
+         Copyright 2024 The Android Open Source Project
+         Licensed under the Apache License, Version 2.0 (the "License");
+         you may not use this file except in compliance with the License.
+         You may obtain a copy of the License at
+              http://www.apache.org/licenses/LICENSE-2.0
+         Unless required by applicable law or agreed to in writing, software
+         distributed under the License is distributed on an "AS IS" BASIS,
+         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+         See the License for the specific language governing permissions and
+         limitations under the License.
+    -->
+    <application android:label="Minimal">
+    </application>
+</manifest>

recipes/listenToMultipleArtifact/build-logic/gradle.properties

@@ -0,0 +1,2 @@
+# Gradle properties are not passed to included builds https://github.com/gradle/gradle/issues/2534
+org.gradle.parallel=true

recipes/listenToMultipleArtifact/build-logic/gradle/libs.versions.toml

@@ -0,0 +1,9 @@
+[versions]
+androidGradlePlugin = $AGP_VERSION
+kotlin = $KOTLIN_VERSION
+
+[libraries]
+android-gradlePlugin-api = { group = "com.android.tools.build", name = "gradle-api", version.ref = "androidGradlePlugin" }
+
+[plugins]
+kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }

recipes/listenToMultipleArtifact/build-logic/plugins/build.gradle.kts

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+plugins {
+    `java-gradle-plugin`
+    alias(libs.plugins.kotlin.jvm)
+}
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(17))
+    }
+}
+
+dependencies {
+    compileOnly(libs.android.gradlePlugin.api)
+    implementation(gradleKotlinDsl())
+}
+
+gradlePlugin {
+    plugins {
+        create("customPlugin") {
+            id = "android.recipes.custom_plugin"
+            implementationClass = "CustomPlugin"
+        }
+    }
+}

recipes/listenToMultipleArtifact/build-logic/plugins/src/main/kotlin/CopyNativeDebugMetadataTask.kt

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.Directory
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.provider.ListProperty
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.TaskAction
+import java.io.File
+
+/**
+ * This task will receive the native debug metadata folder and copy the contents to the output
+ */
+abstract class CopyNativeDebugMetadataTask : DefaultTask() {
+
+    @get:InputFiles
+    @get:PathSensitive(PathSensitivity.RELATIVE)
+    abstract val debugMetadataDirectories: ListProperty<Directory>
+
+    @get:OutputDirectory
+    abstract val output: DirectoryProperty
+
+    @TaskAction
+    fun taskAction() {
+        // delete the previous content. This task does not support incremental mode but could be modified to do so
+        val outputDirectory = output.get()
+        val outputFile = outputDirectory.asFile
+
+        outputFile.deleteRecursively()
+        outputFile.mkdirs()
+
+        val debugMetadataFile = File(debugMetadataDirectories.get().first().asFile, "test_file.dbg")
+        debugMetadataFile.copyTo(File(outputFile, "renamed_test_file.dbg"))
+    }
+}

recipes/listenToMultipleArtifact/build-logic/plugins/src/main/kotlin/CustomPlugin.kt

@@ -0,0 +1,105 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+import com.android.build.api.artifact.MultipleArtifact
+import com.android.build.api.variant.ApplicationAndroidComponentsExtension
+import com.android.build.gradle.AppPlugin
+import org.gradle.api.DefaultTask
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.provider.Property
+import org.gradle.api.tasks.InputDirectory
+import org.gradle.api.tasks.TaskAction
+import org.gradle.configurationcache.extensions.capitalized
+import org.gradle.kotlin.dsl.register
+
+/**
+ * This custom plugin will register a callback that is applied to all variants.
+ */
+class CustomPlugin : Plugin<Project> {
+    override fun apply(project: Project) {
+
+        // Registers a callback on the application of the Android Application plugin.
+        // This allows the CustomPlugin to work whether it's applied before or after
+        // the Android Application plugin.
+        project.plugins.withType(AppPlugin::class.java) {
+
+            // Queries for the extension set by the Android Application plugin.
+            // This is the second of two entry points into the Android Gradle plugin
+            val androidComponents =
+                project.extensions.getByType(ApplicationAndroidComponentsExtension::class.java)
+            // Registers a callback to be called, when a new variant is configured
+            androidComponents.onVariants { variant ->
+
+                // -- Setup --
+                // the following is done for the sake of the recipe only, in order to add directories to
+                // MultipleArtifact.NATIVE_DEBUG_METADATA so that there is something to copy
+                variant.artifacts.addStaticDirectory(
+                    MultipleArtifact.NATIVE_DEBUG_METADATA,
+                    project.layout.projectDirectory.dir("nativeDebugMetadataDir")
+                )
+
+                // create a task that will be responsible for copying and renaming a native debug metadata file
+                val copyTaskName = "copyNativeDebugMetadataFor${variant.name.capitalized()}"
+                val copyTask = project.tasks.register<CopyNativeDebugMetadataTask>(copyTaskName) {
+                    // set the output only. the input will be automatically provided via the wiring mechanism
+                    output.set(project.layout.buildDirectory.dir(
+                        "renamed_intermediates/native_debug_metadata/${variant.name}")
+                    )
+                }
+
+                // Wire the task to respond to artifact creation
+                variant.artifacts.use(copyTask).wiredWithMultiple {
+                    it.debugMetadataDirectories
+                }.toListenTo(MultipleArtifact.NATIVE_DEBUG_METADATA)
+
+                // -- Verification --
+                // the following is just to validate the recipe and is not actually part of the recipe itself
+                project.tasks.register<ValidateTask>("validate${variant.name.capitalized()}") {
+                    // The input of the validation task should be the output of the copy task.
+                    // The normal way to do this would be:
+                    //     input.set(copyTask.flatMap { it.output }
+                    // However, doing this will force running the copy task when we want it to run
+                    // automatically when the normal AGP tasks run.
+                    // So we set the input manually, and the validation task will have to be called
+                    // separately (in a separate Gradle execution or Gradle will detect the
+                    // lack of dependency between the 2 tasks and complain).
+                    input.set(project.layout.buildDirectory.dir(
+                        "renamed_intermediates/native_debug_metadata/${variant.name}")
+                    )
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Validation task to verify the behavior of the recipe
+ */
+abstract class ValidateTask : DefaultTask() {
+
+    @get:InputDirectory
+    abstract val input: DirectoryProperty
+
+    @TaskAction
+    fun taskAction() {
+        val renamedNativeDebugMetadataFile = input.get().file("renamed_test_file.dbg").asFile
+        if (!renamedNativeDebugMetadataFile.exists()) {
+            throw RuntimeException("Expected file missing: $renamedNativeDebugMetadataFile")
+        }
+    }
+}

recipes/listenToMultipleArtifact/build-logic/settings.gradle.kts

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+rootProject.name = "build-logic"
+
+pluginManagement {
+    repositories {
+        $AGP_REPOSITORY
+        $PLUGIN_REPOSITORIES
+    }
+}
+
+dependencyResolutionManagement {
+    repositories {
+        $AGP_REPOSITORY
+        $DEPENDENCY_REPOSITORIES
+    }
+}
+
+include(":plugins")

recipes/listenToMultipleArtifact/build.gradle.kts

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+plugins {
+    alias(libs.plugins.android.application) apply false
+    alias(libs.plugins.kotlin.android) apply false
+}