Add recipe for ScopedArtifactsOperation.toAppend API

Bug: n/a
Test: this is a test
Change-Id: I0ff42623ae1cdb88499ea5a798de859bc1928f76

BUILD

@@ -165,3 +165,7 @@ recipe_test(
 recipe_test(
     name = "listenToMultipleArtifact",
 )
+
+recipe_test(
+    name = "appendToScopedArtifacts",
+)

recipes/appendToScopedArtifacts/README.md

@@ -0,0 +1,47 @@
+# Appending to scoped artifacts
+
+This recipe shows how to add a task per variant to add a directory or file to [ScopedArtifact](https://developer.android.com/reference/tools/gradle-api/current/com/android/build/api/artifact/ScopedArtifact).
+This recipe uses `ScopedArtifact.CLASSES` as an example, but the code is similar for other
+`ScopedArtifact` types. The API used is `toAppend()` which is defined in [ScopedArtifactsOperation](https://developer.android.com/reference/tools/gradle-api/current/com/android/build/api/variant/ScopedArtifactsOperation)
+
+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) and [`CheckClassesTask`](build-logic/plugins/src/main/kotlin/CheckClassesTask.kt) classes.
+
+[`CustomPlugin`](build-logic/plugins/src/main/kotlin/CustomPlugin.kt) registers instances of two append tasks (`AddDirectoryClassTask` and `AddJarClassTask`) per
+variant and sets its `CLASSES` inputs via the code below, which automatically adds a dependency on any tasks producing
+`CLASSES` artifacts. It specifies the scope for each task using `forScope()`. Additionally, the
+[`CheckClassesTask`](build-logic/plugins/src/main/kotlin/CheckClassesTask.kt) is registered per variant to validate the classes have been added to the `ScopedArtifact`.
+
+Below is a snippet that demonstrates the usage of the `toAppend()` API, for different scopes and both a directory and
+file:
+
+```
+variant.artifacts
+    .forScope(ScopedArtifacts.Scope.PROJECT)
+    .use(addDirectoryClassTaskProvider)
+    .toAppend(
+        ScopedArtifact.CLASSES,
+        AddDirectoryClassTask::outputDirectory
+    )
+
+variant.artifacts
+    .forScope(ScopedArtifacts.Scope.ALL)
+    .use(addJarClassTaskProvider)
+    .toAppend(
+        ScopedArtifact.CLASSES,
+        AddJarClassTask::outputJar
+    )
+```
+
+In practice, a task could consider only the `PROJECT` scope or only the `ALL` scope (though
+the `PROJECT` scope is a subset of the `ALL` scope).
+
+[`CheckClassesTask`](build-logic/plugins/src/main/kotlin/CheckClassesTask.kt) does a trivial verification of the classes.
+
+To run the recipe : `gradlew checkDebugClasses`

recipes/appendToScopedArtifacts/app/build.gradle.kts

@@ -0,0 +1,37 @@
+/*
+ * 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.append_to_scoped_artifacts"
+    compileSdk = $COMPILE_SDK
+    defaultConfig {
+       minSdk = $MINIMUM_SDK
+       targetSdk = $COMPILE_SDK
+       versionCode = 1
+    }
+}
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(17))
+    }
+}

recipes/appendToScopedArtifacts/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/appendToScopedArtifacts/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/appendToScopedArtifacts/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/appendToScopedArtifacts/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/appendToScopedArtifacts/build-logic/plugins/src/main/kotlin/CheckClassesTask.kt

@@ -0,0 +1,84 @@
+/*
+ * 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.file.RegularFile
+import org.gradle.api.provider.ListProperty
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.TaskAction
+import java.lang.RuntimeException
+
+/**
+ * This task does a trivial check of a variant's classes.
+ */
+abstract class CheckClassesTask: 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
+
+    /**
+     * Project scope, not including dependencies.
+     */
+    @get:InputFiles
+    abstract val projectDirectories: ListProperty<Directory>
+
+    /**
+     * Project scope, not including dependencies.
+     */
+    @get:InputFiles
+    abstract val projectJars: ListProperty<RegularFile>
+
+    /**
+     * Full scope, including project scope and all dependencies.
+     */
+    @get:InputFiles
+    abstract val allDirectories: ListProperty<Directory>
+
+    /**
+     * Full scope, including project scope and all dependencies.
+     */
+    @get:InputFiles
+    abstract val allJars: ListProperty<RegularFile>
+
+    /**
+     * This task does a trivial check of the classes, but a similar task could be written to perform useful
+     * verification.
+     */
+    @TaskAction
+    fun taskAction() {
+        // Check that the appended directory is present in projectDirectories
+        if (projectDirectories.get().isEmpty()) {
+            throw RuntimeException("Expected projectDirectories not to be empty")
+        }
+        projectDirectories.get().firstOrNull()?.let {
+            if (!it.asFile.walk().toList().any { file -> file.name == "New.class" }) {
+                throw RuntimeException("Expected New.class in projectDirectories")
+            }
+        }
+
+        // Check that the appended jar is present in allJars
+        val allJarFileNames = allJars.get().map { it.asFile.name }
+        if (!allJarFileNames.contains("classes.jar")) {
+            throw RuntimeException("Expected allJars to contain classes.jar")
+        }
+    }
+}

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

@@ -0,0 +1,136 @@
+/*
+ * 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.ScopedArtifact
+import com.android.build.api.variant.ApplicationAndroidComponentsExtension
+import com.android.build.api.variant.ScopedArtifacts
+import com.android.build.gradle.AppPlugin
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.register
+import java.io.File
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.OutputFile
+import org.gradle.api.tasks.TaskAction
+import org.gradle.configurationcache.extensions.capitalized
+
+/**
+ * This custom plugin creates tasks that append to ScopedArtifact and verifies it.
+ */
+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(ApplicationAndroidComponentsExtension::class.java)
+
+            // Registers a callback to be called, when a new variant is configured
+            androidComponents.onVariants { variant ->
+
+                val addDirectoryClassTaskProvider =
+                    project.tasks.register("add${variant.name.capitalized()}DirectoryClass", AddDirectoryClassTask::class.java)
+                val addJarClassTaskProvider =
+                    project.tasks.register("add${variant.name.capitalized()}JarClass", AddJarClassTask::class.java)
+                // Append the directory to the PROJECT scope classes
+                variant.artifacts
+                    .forScope(ScopedArtifacts.Scope.PROJECT)
+                    .use(addDirectoryClassTaskProvider)
+                    .toAppend(
+                        ScopedArtifact.CLASSES,
+                        AddDirectoryClassTask::outputDirectory
+                    )
+                // Append the jar file to the ALL scope classes
+                variant.artifacts
+                    .forScope(ScopedArtifacts.Scope.ALL)
+                    .use(addJarClassTaskProvider)
+                    .toAppend(
+                        ScopedArtifact.CLASSES,
+                        AddJarClassTask::outputJar
+                    )
+
+                // -- Verification --
+                // the following is just to validate the recipe and is not actually part of the recipe itself
+                val taskName = "check${variant.name.capitalized()}Classes"
+                val checkClassesTaskProvider = project.tasks.register<CheckClassesTask>(taskName) {
+                    output.set(
+                        project.layout.buildDirectory.dir("intermediates/$taskName")
+                    )
+                }
+
+                // Sets the task's projectJars and projectDirectories inputs to the
+                // ScopeArtifacts.Scope.PROJECT ScopedArtifact.CLASSES artifacts. This automatically creates a
+                // dependency between this task and any tasks generating classes in the PROJECT scope.
+                variant.artifacts
+                    .forScope(ScopedArtifacts.Scope.PROJECT)
+                    .use(checkClassesTaskProvider)
+                    .toGet(
+                        ScopedArtifact.CLASSES,
+                        CheckClassesTask::projectJars,
+                        CheckClassesTask::projectDirectories,
+                    )
+                // Sets this task's allJars and allDirectories inputs to the ScopeArtifacts.Scope.ALL
+                // ScopedArtifact.CLASSES artifacts. This automatically creates a dependency between this task
+                // and any tasks generating classes.
+                variant.artifacts
+                    .forScope(ScopedArtifacts.Scope.ALL)
+                    .use(checkClassesTaskProvider)
+                    .toGet(
+                        ScopedArtifact.CLASSES,
+                        CheckClassesTask::allJars,
+                        CheckClassesTask::allDirectories,
+                    )
+            }
+        }
+    }
+}
+
+/**
+ * This task appends a directory containing a class file to the ScopedArtifact.
+ */
+abstract class AddDirectoryClassTask: DefaultTask() {
+
+    @get:OutputDirectory
+    abstract val outputDirectory: DirectoryProperty
+
+    @TaskAction
+    fun taskAction() {
+        // Adds a new file to the directory that is being added to the ScopedArtifact.CLASSES
+        File(outputDirectory.get().asFile, "New.class").createNewFile()
+    }
+}
+
+/**
+ * This task appends a jar file to the ScopedArtifact.
+ */
+abstract class AddJarClassTask: DefaultTask() {
+
+    @get:OutputFile
+    abstract val outputJar: RegularFileProperty
+
+    @TaskAction
+    fun taskAction() {
+        // Create the jar file being added to the ScopedArtifact.CLASSES
+        outputJar.get().asFile.createNewFile()
+    }
+}