Merge "Add a recipe to show how to add a generated dir to a MultipleA…

…rtifact" into studio-main

BUILD

@@ -47,6 +47,10 @@ recipe_test(
     name = "allProjectsApkAction",
 )
 
+recipe_test(
+    name = "appendToMultipleArtifact",
+)
+
 recipe_test(
     name = "extendingAgp",
 )

recipes/addMultipleArtifact/README.md

@@ -1,10 +1,13 @@
-# Adding to an instance of `MultipleArtifact`
+# Adding a static directory to an instance of `MultipleArtifact`
 
-This recipe shows how to add a directory to an instance of
+This recipe shows how to add a static directory to an instance of
 [MultipleArtifact](https://developer.android.com/reference/tools/gradle-api/current/com/android/build/api/artifact/MultipleArtifact).
 This recipe uses `MultipleArtifact.NATIVE_DEBUG_METADATA` as an example, but the code is similar
 for other `MultipleArtifact` types.
 
+Note: for an example of adding a *generated* directory to an instance of `MultipleArtifact`, see
+the [appendToMultipleArtifact](../appendToMultipleArtifact) recipe.
+
 This recipe contains the following directories :
 
 | Module                     | Content                                                     |

recipes/addMultipleArtifact/build-logic/plugins/src/main/kotlin/CheckBundleTask.kt

@@ -40,9 +40,11 @@ abstract class CheckBundleTask : DefaultTask() {
 
     @TaskAction
     fun taskAction() {
-        val entries = ZipFile(bundle.get().asFile).entries().asSequence().toList()
-        if (entries.count { it.name.endsWith("extra.so.dbg") } != 4) {
-            throw RuntimeException("Expected bundle file to have exactly 4 extra.so.dbg entries.")
+        ZipFile(bundle.get().asFile).use {
+            val entries = it.entries().asSequence().toList()
+            if (entries.count { it.name.endsWith("extra.so.dbg") } != 4) {
+                throw RuntimeException("Expected bundle file to have exactly 4 extra.so.dbg entries.")
+            }
         }
     }
 }

recipes/addMultipleArtifact/recipe_metadata.toml

@@ -1,7 +1,7 @@
 title = "Add Multiple Artifact"
 
 description ="""
-  Recipe that adds a directory to an instance of MultipleArtifact.
+  Recipe that adds a static directory to an instance of MultipleArtifact.
   """
 
 [agpVersion]

recipes/appendToMultipleArtifact/README.md

@@ -0,0 +1,40 @@
+# Appending a generated directory to an instance of `MultipleArtifact`
+
+This recipe shows how to add a generated directory to an instance of
+[MultipleArtifact](https://developer.android.com/reference/tools/gradle-api/current/com/android/build/api/artifact/MultipleArtifact).
+This recipe uses `MultipleArtifact.NATIVE_DEBUG_METADATA` as an example, but the code is similar
+for the other `MultipleArtifact` types that implement `Appendable`.
+
+Note: for an example of adding a *static* directory to an instance of `MultipleArtifact`, see the
+[addMultipleArtifact](../addMultipleArtifact) recipe.
+
+This recipe contains the following directories :
+
+| Module                     | Content                                                     |
+|----------------------------|-------------------------------------------------------------|
+| [build-logic](build-logic) | Contains the Project plugin that is the core of the recipe. |
+| [app](app)                 | An Android application that has the plugin applied.         |
+
+
+The [build-logic](build-logic) sub-project contains the
+[`CustomPlugin`](build-logic/plugins/src/main/kotlin/CustomPlugin.kt),
+[`GenerateNativeDebugMetadataTask`](build-logic/plugins/src/main/kotlin/GenerateNativeDebugMetadataTask.kt),
+and [`CheckBundleTask`](build-logic/plugins/src/main/kotlin/CheckBundleTask.kt) classes.
+
+[`CustomPlugin`](build-logic/plugins/src/main/kotlin/CustomPlugin.kt) registers an instance of
+`GenerateNativeDebugMetadataTask` per variant and appends its output directory to the
+`MultipleArtifact.NATIVE_DEBUG_METADATA` artifacts as shown below. This automatically creates a
+dependency on this task from any task consuming the MultipleArtifact.NATIVE_DEBUG_METADATA
+artifacts.
+
+```
+variant.artifacts.use(generateNativeDebugMetadataTask)
+    .wiredWith(GenerateNativeDebugMetadataTask::output)
+    .toAppendTo(MultipleArtifact.NATIVE_DEBUG_METADATA)
+```
+
+[`CustomPlugin`](build-logic/plugins/src/main/kotlin/CustomPlugin.kt) also registers an instance of
+the `CheckBundleTask` per variant which verifies that the app bundle contains the expected native
+debug metadata entries.
+
+To run the recipe : `gradlew checkDebugBundle`

recipes/appendToMultipleArtifact/app/build.gradle.kts

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2023 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.addmultipleartifact"
+    compileSdk = $COMPILE_SDK
+    defaultConfig {
+       minSdk = $MINIMUM_SDK
+       targetSdk = $COMPILE_SDK
+       versionCode = 1
+    }
+    buildTypes {
+        debug {
+            ndk {
+                debugSymbolLevel = "FULL"
+            }
+        }
+    }
+}

recipes/appendToMultipleArtifact/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 2023 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/appendToMultipleArtifact/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/appendToMultipleArtifact/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/appendToMultipleArtifact/build-logic/plugins/build.gradle.kts

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2023 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/appendToMultipleArtifact/build-logic/plugins/src/main/kotlin/CheckBundleTask.kt

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2023 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.DirectoryProperty
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.TaskAction
+import java.lang.RuntimeException
+import java.util.zip.ZipFile
+
+/**
+ * This task checks that a variant's app bundle (.aab) output file contains the expected native
+ * debug metadata.
+ */
+abstract class CheckBundleTask : DefaultTask() {
+
+    // In order for the task to be up-to-date when the inputs have not changed,
+    // the task must declare an output, even if it's not used. Tasks with no
+    // output are always run regardless of whether the inputs changed
+    @get:OutputDirectory
+    abstract val output: DirectoryProperty
+
+    @get:InputFile
+    abstract val bundle: RegularFileProperty
+
+    @TaskAction
+    fun taskAction() {
+        ZipFile(bundle.get().asFile).use {
+            val entries = it.entries().asSequence().toList()
+            if (entries.count { it.name.endsWith("extra.so.dbg") } != 4) {
+                throw RuntimeException("Expected bundle file to have exactly 4 extra.so.dbg entries.")
+            }
+        }
+    }
+}

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

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2023 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.artifact.SingleArtifact
+import com.android.build.api.variant.AndroidComponentsExtension
+import com.android.build.gradle.AppPlugin
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.register
+
+/**
+ * This custom plugin creates a task per variant that adds an extra native debug metadata directory
+ * to be packaged in the app bundle.
+ */
+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.
+            val androidComponents =
+                project.extensions.getByType(AndroidComponentsExtension::class.java)
+
+            // Registers a callback to be called, when a new variant is configured
+            androidComponents.onVariants { variant ->
+
+                // Registers a new task to generate native debug metadata
+                val generateNativeDebugMetadataTask =
+                    project.tasks.register<GenerateNativeDebugMetadataTask>(
+                        "generate${variant.name}NativeDebugMetadataTask"
+                    )
+
+                // Adds the task's generated native debug metadata directory to any existing
+                // MultipleArtifact.NATIVE_DEBUG_METADATA artifacts so that the generated native
+                // debug metadata will be packaged in the app bundle. This automatically creates
+                // a dependency on this task from any task consuming the
+                // MultipleArtifact.NATIVE_DEBUG_METADATA artifacts.
+                variant.artifacts.use(generateNativeDebugMetadataTask)
+                    .wiredWith(GenerateNativeDebugMetadataTask::output)
+                    .toAppendTo(MultipleArtifact.NATIVE_DEBUG_METADATA)
+
+                // Registers a new task to verify that the app bundle contains the expected native
+                // debug metadata.
+                val checkBundleTaskName = "check${variant.name}Bundle"
+                project.tasks.register<CheckBundleTask>(checkBundleTaskName) {
+
+                    // Sets this task's input to the SingleArtifact.BUNDLE artifact. This
+                    // automatically creates a dependency between this new task and the task
+                    // generating the app bundle.
+                    bundle.set(variant.artifacts.get(SingleArtifact.BUNDLE))
+                    output.set(
+                        project.layout.buildDirectory.dir("intermediates/$checkBundleTaskName")
+                    )
+                }
+            }
+        }
+    }
+}

recipes/appendToMultipleArtifact/build-logic/plugins/src/main/kotlin/GenerateNativeDebugMetadataTask.kt

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2023 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.DirectoryProperty
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.TaskAction
+import java.io.File
+import java.lang.RuntimeException
+import java.util.zip.ZipFile
+
+/**
+ * This task generates (fake) native debug metadata.
+ */
+abstract class GenerateNativeDebugMetadataTask : DefaultTask() {
+
+    @get:OutputDirectory
+    abstract val output: DirectoryProperty
+
+    @TaskAction
+    fun taskAction() {
+        val outputDir = output.get().asFile
+        for (abi in listOf("arm64-v8a", "armeabi-v7a", "x86", "x86_64")) {
+            val abiDir = File(outputDir, abi).also { it.mkdirs() }
+            File(abiDir, "extra.so.dbg").writeText("fake native debug metadata")
+        }
+    }
+}