build.gradle

import gradlebuild.integrationtests.model.GradleDistribution
import org.asciidoctor.gradle.jvm.AsciidoctorTask
import org.gradle.docs.internal.tasks.CheckLinks
import org.gradle.docs.samples.internal.tasks.InstallSample
import org.gradle.internal.os.OperatingSystem

import static gradlebuild.basics.BuildEnvironmentKt.repoRoot
import static gradlebuild.basics.BuildParamsKt.isConfigurationCacheEnabledForDocsTests
import static gradlebuild.basics.BuildParamsKt.shouldRunBrokenForConfigurationCacheDocsTests
import static gradlebuild.basics.Repositories_extensionsKt.googleApisJs

plugins {
    id 'gradlebuild.internal.java'
    // TODO: Apply asciidoctor in documentation plugin instead.
    id 'org.asciidoctor.jvm.convert'
    id 'gradlebuild.documentation'
    id 'gradlebuild.generate-samples'
    id 'gradlebuild.split-docs'
}

repositories { handler ->
    googleApisJs(handler)
}

configurations {
    gradleFullDocsElements {
        attributes {
            attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage, Usage.JAVA_RUNTIME))
            attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category, Category.DOCUMENTATION))
            attribute(DocsType.DOCS_TYPE_ATTRIBUTE, objects.named(DocsType, "gradle-documentation"))
        }
        visible = false
        canBeResolved = false
        canBeConsumed = true
    }
    docsTestRuntimeClasspath.extendsFrom(integTestDistributionRuntimeOnly)
}

dependencies {
    // generate Javadoc for the full Gradle distribution
    runtimeOnly project(":distributions-full")

    userGuideTask 'xalan:xalan:2.7.1'
    userGuideTask 'xerces:xercesImpl:2.11.0'
    userGuideTask 'net.sf.xslthl:xslthl:2.0.1'

    userGuideStyleSheets 'net.sf.docbook:docbook-xsl:1.75.2:resources@zip'

    jquery "jquery:jquery.min:3.5.1@js"

    testImplementation project(":base-services")
    testImplementation project(":core")
    testImplementation libs.jsoup
    testImplementation "org.gebish:geb-spock:2.2"
    testImplementation 'org.seleniumhq.selenium:selenium-htmlunit-driver:2.42.2'
    testImplementation libs.commonsHttpclient
    testImplementation libs.httpmime

    docsTestImplementation platform(project(":distributions-dependencies"))
    docsTestImplementation project(":internal-integ-testing")
    docsTestImplementation project(":base-services")
    docsTestImplementation project(":logging")
    docsTestImplementation libs.junit5Vintage
    docsTestImplementation libs.junit

    integTestDistributionRuntimeOnly project(":distributions-full")
}

configurations.docsTestRuntimeClasspath {
    exclude group: "org.slf4j", module: "slf4j-simple"
}

asciidoctorj {
    version = '2.4.2'
    modules.pdf.version '1.5.4'
}

tasks.withType(AsciidoctorTask).configureEach { task ->
    if (task.name == "userguideSinglePagePdf") {
        task.asciidoctorj.docExtensions(
            project.getDependencies().create(project(":docs-asciidoctor-extensions-base")),
        )
    } else {
        task.asciidoctorj.docExtensions(
            project.getDependencies().create(project(":docs-asciidoctor-extensions")),
            project.getDependencies().create(project.files("src/main/resources"))
        )
    }
}

gradleDocumentation {
    javadocs {
        javaApi = project.uri("https://docs.oracle.com/javase/8/docs/api")
        groovyApi = project.uri("https://docs.groovy-lang.org/docs/groovy-${libs.groovyVersion}/html/gapi")
    }
}

tasks.named("stageDocs") {
    // Add samples to generated documentation
    from(samples.distribution.renderedDocumentation) {
        into("samples")
    }
}

samples {
    templates {
        javaAndroidApplication
        structuringSoftwareProjects
        springBootWebApplication {
            target = "app"
        }
        gradlePluginInJava {
            target = "greeting-plugin"
        }
        gradlePluginInJavaInBuildSrc {
            sourceDirectory = gradlePluginInJava.sourceDirectory
            target = "buildSrc"
        }
        buildSrcPluginJavaModuleTransform

        javaApplication
        javaListLibrary
        javaUtilitiesLibrary
        javaListLibraryInMyLibrary {
            sourceDirectory = javaListLibrary.sourceDirectory
            target = "my-library"
        }
        javaUtilitiesLibraryInMyLibrary {
            sourceDirectory = javaUtilitiesLibrary.sourceDirectory
            target = "my-library"
        }
        javaApplicationAsSubproject {
            sourceDirectory = javaApplication.sourceDirectory
            target = "application"
        }
        javaListLibraryAsSubproject {
            sourceDirectory = javaListLibrary.sourceDirectory
            target = "list"
        }
        javaUtilitiesLibraryAsSubproject {
            sourceDirectory = javaUtilitiesLibrary.sourceDirectory
            target = "utilities"
        }

        javaJunit5TestForApplication {
            target = "application"
        }
        javaJunit5TestForListLibrary {
            target = "list"
        }
        javaJunit5TestForUtilitiesLibrary {
            target = "utilities"
        }
        javaJunit5IntegrationTestForApplication {
            target = "application"
        }
        javaJunit5IntegrationTestForUtilitiesLibrary {
            target = "utilities"
        }

        javaModuleInfoForListLibrary {
            target = "list"
        }
        javaModuleInfoForUtilitiesLibrary {
            target = "utilities"
        }
        javaModuleInfoForApplication {
            target = "application"
        }
        javaJunit5ModuleInfoForUtilitiesLibrary {
            target = "utilities"
        }
        javaJunit5ModuleInfoForApplication {
            target = "application"
        }

        groovyListLibrary
        groovyUtilitiesLibrary
        groovyListLibraryInMyLibrary {
            sourceDirectory = groovyListLibrary.sourceDirectory
            target = "my-library"
        }
        groovyUtilitiesLibraryInMyLibrary {
            sourceDirectory = groovyUtilitiesLibrary.sourceDirectory
            target = "my-library"
        }

        projectInfoPlugin

        precompiledScriptPluginUtils {
            target = "convention-plugins"
        }
        precompiledScriptPluginUtilsInBuildSrc {
            sourceDirectory = precompiledScriptPluginUtils.sourceDirectory
            target = "buildSrc"
        }
    }

    // TODO: Do this lazily so we don't need to walk the filesystem during configuration
    // iterate through each snippets and record their names and locations
    FileFilter directoriesOnly = { it.directory }
    def topLevelDirs = file('src/snippets').listFiles(directoriesOnly)
    def snippetDirs = topLevelDirs*.listFiles(directoriesOnly).flatten().grep {
        new File(it, "kotlin").exists() || new File(it, "groovy").exists()
    }

    snippetDirs.each { File snippetDir ->
        String snippetName = snippetDir.name
        String categoryName = snippetDir.parentFile.name
        def id = org.gradle.docs.internal.StringUtils.toLowerCamelCase("snippet-" + categoryName + "-" + snippetName)
        publishedSamples.create(id) {
            description = "Snippet from $snippetDir"
            category = "Other"
            readmeFile = file("src/snippets/default-readme.adoc")
            sampleDirectory = snippetDir
            promoted = false
        }
    }

    publishedSamples {
        buildingAndroidApps {
            sampleDirectory = samplesRoot.dir("android-application")
            description = "Build a simple Android app."
            category = "Android"
            common {
                from(templates.javaAndroidApplication)
            }
        }
        buildingSpringBootWebApplications {
            sampleDirectory = samplesRoot.dir("spring-boot-web-application")
            description = "Build a simple Spring Boot application."
            category = "Spring"
            common {
                from(templates.springBootWebApplication)
            }
        }

        incubatingJvmMultiProjectWithAdditionalTestTypes {
            sampleDirectory = samplesRoot.dir("incubating/java/jvm-multi-project-with-additional-test-types")
            displayName = "Using additional test types with Test Suites (Incubating)"
            description = "Add an additional test type (e.g. integration tests) to a project using the new Test Suites API."
            category = "Java"

            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaJunit5TestForApplication)
                from(templates.javaJunit5IntegrationTestForApplication)

                from(templates.javaListLibraryAsSubproject)
                from(templates.javaJunit5TestForListLibrary)
                from(templates.javaJunit5IntegrationTestForUtilitiesLibrary)

                from(templates.javaUtilitiesLibraryAsSubproject)
            }
        }
        incubatingJavaModulesMultiProjectWithIntegrationTests {
            sampleDirectory = samplesRoot.dir("incubating/java/modules-multi-project-with-integration-tests")
            displayName = "Building Java Modules with Blackbox Tests with Test Suites (Incubating)"
            description = "Build Java Modules with blackbox integration tests using the new Test Suites API."
            category = "Java Modules"
            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaListLibraryAsSubproject)
                from(templates.javaUtilitiesLibraryAsSubproject)
                from(templates.javaModuleInfoForListLibrary)
                from(templates.javaModuleInfoForUtilitiesLibrary)
                from(templates.javaModuleInfoForApplication)
                from(templates.javaJunit5TestForApplication)
                from(templates.javaJunit5TestForListLibrary)

                from(templates.javaJunit5IntegrationTestForApplication)
                from(templates.javaJunit5ModuleInfoForApplication)
                from(templates.javaJunit5IntegrationTestForUtilitiesLibrary)
                from(templates.javaJunit5ModuleInfoForUtilitiesLibrary)
            }
        }
        incubatingPublishingConventionPlugins {
            sampleDirectory = samplesRoot.dir("incubating/build-organization/publishing-convention-plugins")
            displayName = "Sharing build logic in a multi-repo setup with Test Suites (Incubating)"
            description = "Organize and publish build logic for reuse in other projects using the new Test Suites API."
            category = "Java"
            common {
                from(templates.precompiledScriptPluginUtils)
            }
        }

        jvmMultiProjectWithAdditionalTestTypes {
            sampleDirectory = samplesRoot.dir("java/jvm-multi-project-with-additional-test-types")
            displayName = "Using additional test types"
            description = "Add an additional test type (e.g. integration tests) to a project."
            category = "Java"

            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaJunit5TestForApplication)
                from(templates.javaJunit5IntegrationTestForApplication)

                from(templates.javaListLibraryAsSubproject)
                from(templates.javaJunit5TestForListLibrary)
                from(templates.javaJunit5IntegrationTestForUtilitiesLibrary)

                from(templates.javaUtilitiesLibraryAsSubproject)
            }
        }
        jvmMultiProjectWithToolchains {
            sampleDirectory = samplesRoot.dir("java/jvm-multi-project-with-toolchains")
            displayName = "Using toolchains"
            description = "Use toolchains to configure the JVM to use for compilation and testing."
            category = "Java"

            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaJunit5TestForApplication)
                from(templates.javaJunit5IntegrationTestForApplication)

                from(templates.javaListLibraryAsSubproject)
                from(templates.javaJunit5TestForListLibrary)
                from(templates.javaJunit5IntegrationTestForUtilitiesLibrary)

                from(templates.javaUtilitiesLibraryAsSubproject)
            }
        }
        javaModulesMultiProject {
            sampleDirectory = samplesRoot.dir("java/modules-multi-project")
            displayName = "Building Java Modules"
            description = "Build Java Modules and a modular Java application."
            category = "Java Modules"
            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaListLibraryAsSubproject)
                from(templates.javaUtilitiesLibraryAsSubproject)
                from(templates.javaModuleInfoForListLibrary)
                from(templates.javaModuleInfoForUtilitiesLibrary)
                from(templates.javaModuleInfoForApplication)
                from(templates.javaJunit5TestForApplication)
                from(templates.javaJunit5TestForListLibrary)
            }
        }
        javaModulesMultiProjectWithIntegrationTests {
            sampleDirectory = samplesRoot.dir("java/modules-multi-project-with-integration-tests")
            displayName = "Building Java Modules with Blackbox Tests"
            description = "Build Java Modules with blackbox integration tests."
            category = "Java Modules"
            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaListLibraryAsSubproject)
                from(templates.javaUtilitiesLibraryAsSubproject)
                from(templates.javaModuleInfoForListLibrary)
                from(templates.javaModuleInfoForUtilitiesLibrary)
                from(templates.javaModuleInfoForApplication)
                from(templates.javaJunit5TestForApplication)
                from(templates.javaJunit5TestForListLibrary)

                from(templates.javaJunit5IntegrationTestForApplication)
                from(templates.javaJunit5ModuleInfoForApplication)
                from(templates.javaJunit5IntegrationTestForUtilitiesLibrary)
                from(templates.javaJunit5ModuleInfoForUtilitiesLibrary)
            }
        }
        javaModulesWithTransform {
            sampleDirectory = samplesRoot.dir("java/modules-with-transform")
            displayName = "Building Java Modules with Legacy Libraries"
            description = "Build a modular Java application that integrates legacy libraries."
            category = "Java Modules"
            common {
                from(templates.buildSrcPluginJavaModuleTransform)
            }
        }
        jvmMultiProjectWithCodeCoverageDistribution {
            sampleDirectory = samplesRoot.dir("incubating/java/jvm-multi-project-with-code-coverage-distribution")
            displayName = "Aggregating code coverage with JaCoCo from an application/distribution (Incubating)"
            description = "Report code coverage on the application/distribution of a multi-module project using link:https://www.jacoco.org/jacoco/[JaCoCo]."
            category = "Java"
            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaListLibraryAsSubproject)
                from(templates.javaUtilitiesLibraryAsSubproject)
                from(templates.javaJunit5TestForApplication)
                from(templates.javaJunit5TestForListLibrary)
                from(templates.javaJunit5TestForUtilitiesLibrary)
            }
        }
        jvmMultiProjectWithCodeCoverageStandalone {
            sampleDirectory = samplesRoot.dir("incubating/java/jvm-multi-project-with-code-coverage-standalone")
            displayName = "Aggregating code coverage with JaCoCo using a standalone utility project (Incubating)"
            description = "Report code coverage on a multi-module project using link:https://www.jacoco.org/jacoco/[JaCoCo]."
            category = "Java"
            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaListLibraryAsSubproject)
                from(templates.javaUtilitiesLibraryAsSubproject)
                from(templates.javaJunit5TestForApplication)
                from(templates.javaJunit5TestForListLibrary)
                from(templates.javaJunit5TestForUtilitiesLibrary)
            }
        }
        jvmMultiProjectWithTestAggregationDistribution {
            sampleDirectory = samplesRoot.dir("incubating/java/jvm-multi-project-with-test-aggregation-distribution")
            displayName = "Aggregating test results of an application/distribution (Incubating)"
            description = "Report all test results using the application/distribution of a multi-module project."
            category = "Java"
            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaListLibraryAsSubproject)
                from(templates.javaUtilitiesLibraryAsSubproject)
                from(templates.javaJunit5TestForApplication)
                from(templates.javaJunit5TestForListLibrary)
                from(templates.javaJunit5TestForUtilitiesLibrary)
            }
        }
        jvmMultiProjectWithTestAggregationStandalone {
            sampleDirectory = samplesRoot.dir("incubating/java/jvm-multi-project-with-test-aggregation-standalone")
            displayName = "Aggregating test results using a standalone utility project (Incubating)"
            description = "Report all test results using a standalone utility project as part of a multi-module project."
            category = "Java"
            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaListLibraryAsSubproject)
                from(templates.javaUtilitiesLibraryAsSubproject)
                from(templates.javaJunit5TestForApplication)
                from(templates.javaJunit5TestForListLibrary)
                from(templates.javaJunit5TestForUtilitiesLibrary)
            }
        }
        publishingJavaLibraries {
            sampleDirectory = samplesRoot.dir("java/library-publishing")
            description = "Publish a Java library to a binary repository."
            category = "Java"
            common {
                from(templates.javaListLibraryInMyLibrary)
                from(templates.javaUtilitiesLibraryInMyLibrary)
            }
        }
        publishingGroovyLibraries {
            sampleDirectory = samplesRoot.dir("groovy/library-publishing")
            description = "Publish a Groovy library to a binary repository."
            category = "Groovy"
            common {
                from(templates.groovyListLibraryInMyLibrary)
                from(templates.groovyUtilitiesLibraryInMyLibrary)
            }
        }

        gradlePlugin {
            sampleDirectory = samplesRoot.dir("build-organization/gradle-plugin")
            description = "Organize your build logic into a Gradle plugin written in Java."
            category = "Build organization"
            common {
                from(templates.gradlePluginInJava)
            }
        }

        conventionPlugins {
            sampleDirectory = samplesRoot.dir("build-organization/multi-project-with-convention-plugins")
            displayName = "Sharing build logic between subprojects"
            description = "Organize build logic into reusable pieces"
            category = "Build organization"
            common {
                from(templates.precompiledScriptPluginUtilsInBuildSrc)
            }
        }

        publishingConventionPlugins {
            sampleDirectory = samplesRoot.dir("build-organization/publishing-convention-plugins")
            displayName = "Sharing build logic in a multi-repo setup"
            description = "Organize and publish build logic for reuse in other projects"
            category = "Build organization"
            common {
                from(templates.precompiledScriptPluginUtils)
            }
        }

        sharingConventionPluginsWithBuildLogic {
            sampleDirectory = samplesRoot.dir("build-organization/sharing-convention-plugins-with-build-logic")
            displayName = "Sharing convention plugins with build logic build"
            description = "Reuse convention plugins in both main build and build logic build"
            category = "Build organization"
            common {
                from(templates.javaApplicationAsSubproject)
                from(templates.javaUtilitiesLibraryAsSubproject)
                from(templates.javaListLibraryAsSubproject)
            }
        }

        taskWithArguments {
            sampleDirectory = samplesRoot.dir("writing-tasks/task-with-arguments")
            displayName = "Implementing Tasks with Command-line Arguments"
            description = "Pass arguments to a custom task."
            category = "Writing Custom Tasks"
        }

        tasksWithDependencyResolutionResultInputs {
            sampleDirectory = samplesRoot.dir("writing-tasks/tasks-with-dependency-resolution-result-inputs")
            displayName = "Implementing tasks with dependency resolution result inputs"
            description = "Consume dependency resolution result inputs in tasks."
            category = "Writing Custom Tasks"
        }

        publishingCredentials {
            sampleDirectory = samplesRoot.dir("credentials-handling/publishing-credentials")
            description = "Publish to a password protected repository"
            category = "Using Credentials"
            common {
                from(templates.javaListLibrary)
                from(templates.javaUtilitiesLibrary)
            }
        }

        credentialsForExternalToolViaStdin {
            sampleDirectory = samplesRoot.dir("credentials-handling/pass-credentials-to-external-tool-via-stdin")
            displayName = "Supply credentials to external tool"
            description = "Pass credentials to an external tool via stdin using Gradle properties."
            category = "Using Credentials"
        }

        structuringSoftwareProjects {
            sampleDirectory = samplesRoot.dir("build-organization/structuring-software-projects")
            description = "Structuring a software product project with Gradle"
            category = "Build organization"
            common {
                from(templates.structuringSoftwareProjects)
            }
        }

        compositeBuildsBasics {
            sampleDirectory = samplesRoot.dir("build-organization/composite-builds/basic")
            description = "Defining and using a composite build"
            category = "Build organization"
        }

        compositeBuildsDeclaredSubstitutions {
            sampleDirectory = samplesRoot.dir("build-organization/composite-builds/declared-substitution")
            description = "Applying and testing changes in downstream dependencies without publishing."
            category = "Build organization"
        }

        compositeBuildsHierarchicalMultirepo {
            sampleDirectory = samplesRoot.dir("build-organization/composite-builds/hierarchical-multirepo")
            description = "Defining and using a composite build to combine multiple independent builds."
            category = "Build organization"
        }

        compositeBuildsPluginDevelopment {
            sampleDirectory = samplesRoot.dir("build-organization/composite-builds/plugin-dev")
            description = "Developing a Gradle plugin in a build without publishing."
            category = "Build organization"
        }

        crossProjectOutputSharing {
            sampleDirectory = samplesRoot.dir("build-organization/cross-project-output-sharing")
            displayName = "Sharing task outputs across projects in a multi-project build"
            description = "Sharing a file made by a task in one Gradle project, with a task in another Gradle project."
            category = "Build organization"
        }
    }
}

// Use the version of Gradle being built, not the version of Gradle used to build
tasks.named("generateWrapperForSamples") {
    gradleVersion = project.version
}

// TODO: The rich console to plain text is flaky
tasks.named("checkAsciidoctorSampleContents") {
    enabled = false
}

// exclude (unused and non-existing) wrapper of development Gradle version, as well as README, because the timestamp in the Gradle version break the cache
tasks.withType(InstallSample).configureEach {
    if (name.contains('ForTest')) {
        excludes.add("gradle/wrapper/**")
        excludes.add("README")
    }
}

tasks.named("quickTest") {
    dependsOn("checkDeadInternalLinks")
}

// TODO add some kind of test precondition support in sample test conf
tasks.named("docsTest") { task ->
    maxParallelForks = 2
    // The org.gradle.samples plugin uses Exemplar to execute integration tests on the samples.
    // Exemplar doesn't know about that it's running in the context of the gradle/gradle build
    // so it uses the Gradle distribution from the running build. This is not correct, because
    // we want to verify that the samples work with the Gradle distribution being built.
    def installationEnvProvider = new GradleInstallationForTestEnvironmentProvider(project, task)
    installationEnvProvider.gradleHomeDir.from(configurations.integTestDistributionRuntimeClasspath)
    installationEnvProvider.samplesdir.set(project.layout.buildDirectory.dir("working/samples/testing"))
    jvmArgumentProviders.add(installationEnvProvider)

    // For unknown reason, this is set to 'sourceSet.getRuntimeClasspath()' in the 'org.gradle.samples' plugin
    testClassesDirs = sourceSets.docsTest.output.classesDirs
    // 'integTest.samplesdir' is set to an absolute path by the 'org.gradle.samples' plugin
    systemProperties.clear()
    // Remove as part of fixing https://github.com/gradle/configuration-cache/issues/585
    systemProperties["org.gradle.configuration-cache.internal.test-disable-load-after-store"] = "true"

    filter {
        // workaround for https://github.com/gradle/dotcom/issues/5958
        failOnNoMatchingTests = false
        // Only execute C++ sample tests on Linux because it is the configured target
        if (!OperatingSystem.current().linux) {
            excludeTestsMatching "org.gradle.docs.samples.*.building-cpp-*.sample"
        }
        // Only execute Swift sample tests on OS X because it is the configured target
        if (!OperatingSystem.current().macOsX) {
            excludeTestsMatching "org.gradle.docs.samples.*.building-swift-*.sample"
        }
        // We don't maintain Java 7 on Windows and Mac
        if (OperatingSystem.current().windows || OperatingSystem.current().macOsX) {
            excludeTestsMatching "*java7CrossCompilation.sample"
        }
        // Only execute Groovy sample tests on Java < 9 to avoid warnings in output
        if (javaVersion.java9Compatible) {
            excludeTestsMatching "org.gradle.docs.samples.*.building-groovy-*.sample"
        }
        // disable sanityCheck of 'structuring-software-projects' in any case due to deprecation warning in Android project
        excludeTestsMatching "org.gradle.docs.samples.*.structuring-software-projects*_sanityCheck.sample"

        // Do not execute Java Module tests on JVM < 9
        if (!javaVersion.java9Compatible) {
            excludeTestsMatching "org.gradle.docs.samples.*.java-modules-*.sample"
            excludeTestsMatching "org.gradle.docs.samples.*.incubating-java-modules-*.sample"
            excludeTestsMatching 'org.gradle.docs.samples.*.snippet-java-application*.sample'
            excludeTestsMatching 'org.gradle.docs.samples.*.snippet-java-library-module*.sample'
            excludeTestsMatching 'org.gradle.docs.samples.*.snippet-testing-patch-module*.sample'
        }

        if (OperatingSystem.current().windows && javaVersion.isCompatibleWith(JavaVersion.VERSION_18)) {
            // Disable tests that suffer from charset issues under JDK 18 for now
            excludeTestsMatching "org.gradle.docs.samples.*.snippet-custom-model-internal-views_*_softwareModelExtend-iv-model.sample"
            excludeTestsMatching "org.gradle.docs.samples.*.snippet-model-rules-basic-rule-source-plugin_*_basicRuleSourcePlugin-model-task.sample"
        }

        if (!javaVersion.java11Compatible) {
            // Android requires Java 11+
            excludeTestsMatching "org.gradle.docs.samples.*.building-android-*.sample"
            excludeTestsMatching "org.gradle.docs.samples.*.snippet-kotlin-dsl-android-build_*.sample"
            excludeTestsMatching "org.gradle.docs.samples.*.snippet-kotlin-dsl-android-single-build_*.sample"
            excludeTestsMatching "org.gradle.docs.samples.*.structuring-software-projects*android-app.sample"
            // Umbrella build project contains also Android projects so it requires Java 11+
            excludeTestsMatching "org.gradle.docs.samples.*.structuring-software-projects_*_umbrella-build.sample"
            // This test sets source and target compatibility to 11
            excludeTestsMatching "org.gradle.docs.samples.*.snippet-kotlin-dsl-accessors_*.sample"
        }

        if (javaVersion.isCompatibleWith(JavaVersion.VERSION_12)) {
            excludeTestsMatching "org.gradle.docs.samples.*.snippet-test-kit-gradle-version_*_testKitFunctionalTestSpockGradleDistribution.sample"
        }

        if (OperatingSystem.current().macOsX && System.getProperty("os.arch") == "aarch64") {
            excludeTestsMatching "org.gradle.docs.samples.*.snippet-native*.sample"
            excludeTestsMatching "org.gradle.docs.samples.*.snippet-swift*.sample"
            excludeTestsMatching "org.gradle.docs.samples.*.building-swift*.sample"
            // We don't have Android SDK installed on mac M1 now
            excludeTestsMatching "org.gradle.docs.samples.*.building-android-*.sample"
            excludeTestsMatching "org.gradle.docs.samples.*.structuring-software-projects*android-app.sample"
        }

        // filter tests which won't run on Groovy 4 without updating the Spock version
        if (System.getProperty('bundleGroovy4', 'false') == 'true') {
            excludeTestsMatching 'org.gradle.docs.samples.*.convention-plugins*check.sample'
            excludeTestsMatching 'org.gradle.docs.samples.*.convention-plugins*sanityCheck.sample'
            excludeTestsMatching 'org.gradle.docs.samples.*.incubating-publishing-convention-plugins*publish.sample'
            excludeTestsMatching 'org.gradle.docs.samples.*.publishing-convention-plugins*publish.sample'
            excludeTestsMatching 'org.gradle.docs.samples.*.snippet-configuration-cache-test-kit*configurationCacheTestKit.sample'
            excludeTestsMatching 'org.gradle.docs.samples.*.snippet-developing-plugins-testing-plugins*testPlugin.sample'
        }
    }

    filter {
        // TODO(https://github.com/gradle/gradle/issues/22538)
        excludeTestsMatching "org.gradle.docs.samples.*.snippet-groovy-cross-compilation_*_crossCompilation.sample"
    }

    if (isConfigurationCacheEnabledForDocsTests(project)) {
        systemProperty("org.gradle.integtest.samples.cleanConfigurationCacheOutput", "true")
        systemProperty("org.gradle.integtest.samples.checkLoadingFromConfigurationCache", "true")
        systemProperty("org.gradle.integtest.executer", "configCache")

        filter {
            // Configuration cache samples enable configuration cache explicitly. We're not going to run them with the configuration cache executer.
            excludeTestsMatching "org.gradle.docs.samples.*.snippet-configuration-cache-*.sample"
            excludeTestsMatching "*WithoutCC*.sample"

            // These tests cover features that are not planned to be supported in the first stable release of the configuration cache.
            def testsForUnsupportedFeatures = [
                "building-cpp-applications_groovy_build.sample",
                "building-cpp-applications_kotlin_build.sample",
                "building-cpp-libraries_groovy_build.sample",
                "building-cpp-libraries_kotlin_build.sample",
                "snippet-ant-add-behaviour-to-ant-target_groovy_addBehaviourToAntTarget.sample",
                "snippet-ant-add-behaviour-to-ant-target_kotlin_addBehaviourToAntTarget.sample",
                "snippet-ant-depends-on-ant-target_groovy_dependsOnAntTarget.sample",
                "snippet-ant-depends-on-ant-target_kotlin_dependsOnAntTarget.sample",
                "snippet-ant-depends-on-task_groovy_dependsOnTask.sample",
                "snippet-ant-depends-on-task_kotlin_dependsOnTask.sample",
                "snippet-ant-hello_groovy_antHello.sample",
                "snippet-ant-hello_kotlin_antHello.sample",
                "snippet-ant-rename-task_groovy_renameAntDelegate.sample",
                "snippet-ant-rename-task_kotlin_renameAntDelegate.sample",
                "snippet-ant-use-external-ant-task-with-config_groovy_useExternalAntTaskWithConfig.sample",
                "snippet-ant-use-external-ant-task-with-config_kotlin_useExternalAntTaskWithConfig.sample",
                "snippet-buildlifecycle-task-execution-events_groovy_sanityCheck.sample",
                "snippet-buildlifecycle-task-execution-events_groovy_taskExecutionEvents.groovy.sample",
                "snippet-buildlifecycle-task-execution-events_kotlin_sanityCheck.sample",
                "snippet-buildlifecycle-task-execution-events_kotlin_taskExecutionEvents.kotlin.sample",
                "snippet-custom-model-internal-views_groovy_softwareModelExtend-iv-model.sample",
                "snippet-custom-model-language-type_groovy_softwareModelExtend-components.sample",

                // These snippets are not used in the documentation, but only in the integration tests.
                "snippet-dependency-management-working-with-dependencies-access-metadata-artifact_groovy_accessingMetadataArtifact.sample",
                "snippet-dependency-management-working-with-dependencies-access-metadata-artifact_kotlin_accessingMetadataArtifact.sample",
                "snippet-dependency-management-working-with-dependencies-iterate-artifacts_kotlin_iterating-artifacts.sample",
                "snippet-dependency-management-working-with-dependencies-walk-graph_groovy_walking-dependency-graph.sample",
                "snippet-dependency-management-working-with-dependencies-walk-graph_kotlin_walking-dependency-graph.sample",

                "snippet-ide-eclipse_groovy_wtpWithXml.sample",
                "snippet-ide-eclipse_kotlin_wtpWithXml.sample",
                "snippet-ide-idea-additional-test-sources_groovy_ideaAdditionalTestSources.sample",
                "snippet-ide-idea-additional-test-sources_kotlin_ideaAdditionalTestSources.sample",
                "snippet-ide-idea_groovy_projectWithXml.sample",
                "snippet-ide-idea_kotlin_projectWithXml.sample",
                "snippet-model-rules-basic-rule-source-plugin_groovy_basicRuleSourcePlugin-all.sample",
                "snippet-model-rules-basic-rule-source-plugin_groovy_basicRuleSourcePlugin-model-task.sample",
                "snippet-model-rules-configure-as-required_groovy_modelDslConfigureRuleRunWhenRequired.sample",
                "snippet-model-rules-configure-elements-of-map_groovy_modelDslModelMapNestedAll.sample",
                "snippet-model-rules-initialization-rule-runs-before-configuration-rules_groovy_modelDslInitializationRuleRunsBeforeConfigurationRule.sample",
                "snippet-native-binaries-cpp_groovy_nativeComponentReport.sample",
                "snippet-native-binaries-cunit_groovy_assembleDependentComponents.sample",
                "snippet-native-binaries-cunit_groovy_assembleDependentComponentsReport.sample",
                "snippet-native-binaries-cunit_groovy_buildDependentComponents.sample",
                "snippet-native-binaries-cunit_groovy_buildDependentComponentsReport.sample",
                "snippet-native-binaries-cunit_groovy_completeCUnitExample.sample",
                "snippet-native-binaries-cunit_groovy_dependentComponentsReport.sample",
                "snippet-native-binaries-cunit_groovy_dependentComponentsReportAll.sample",
            ]

            // These tests use third-party plugins at versions that may not support the configuration cache properly.
            // The tests should be removed from this list when the plugin is updated to the version that works with the configuration cache properly.
            def testsWithThirdPartyFailures = [
                "structuring-software-projects_groovy_aggregate-reports.sample",
                "structuring-software-projects_groovy_build-android-app.sample",
                "structuring-software-projects_groovy_build-server-application.sample",
                "structuring-software-projects_groovy_umbrella-build.sample",
                "structuring-software-projects_kotlin_aggregate-reports.sample",
                "structuring-software-projects_kotlin_build-android-app.sample",
                "structuring-software-projects_kotlin_build-server-application.sample",
                "structuring-software-projects_kotlin_umbrella-build.sample",
            ]

            // These tests cover features that the configuration cache doesn't support yet, but we plan to do that before hitting stable.
            // The tests should be removed from this list when the feature becomes supported.
            def testsForNotYetSupportedFeatures = [
                // TODO(https://github.com/gradle/gradle/issues/14880)
                "snippet-dependency-management-working-with-dependencies-iterate-dependencies_groovy_iterating-dependencies.sample",
                "snippet-dependency-management-working-with-dependencies-iterate-dependencies_kotlin_iterating-dependencies.sample",

                // TODO(https://github.com/gradle/gradle/issues/19725) EAR plugin support
                "snippet-ear-ear-customized_groovy_earCustomized.sample",
                "snippet-ear-ear-customized_kotlin_earCustomized.sample",
                "snippet-ear-ear-with-war_groovy_earWithWar.sample",
                "snippet-ear-ear-with-war_kotlin_earWithWar.sample",

                // TODO(https://github.com/gradle/gradle/issues/13469) Ivy Publish plugin support
                "snippet-ivy-publish-conditional-publishing_groovy_publishingIvyConditionally.sample",
                "snippet-ivy-publish-descriptor-customization_groovy_publishingIvyGenerateDescriptor.sample",
                "snippet-ivy-publish-descriptor-customization_kotlin_publishingIvyGenerateDescriptor.sample",
                "snippet-ivy-publish-java-multi-project_groovy_publish-multi-project.sample",
                "snippet-ivy-publish-java-multi-project_kotlin_publish-multi-project.sample",
                "snippet-ivy-publish-quickstart_groovy_publishingIvyPublishLifecycle.sample",
                "snippet-ivy-publish-quickstart_groovy_publishingIvyPublishSingle.sample",
                "snippet-ivy-publish-quickstart_kotlin_publishingIvyPublishLifecycle.sample",
                "snippet-ivy-publish-quickstart_kotlin_publishingIvyPublishSingle.sample",
                "snippet-plugins-publishing_groovy_publishToIvy.sample",
                "snippet-plugins-publishing_kotlin_publishToIvy.sample",
                "snippet-tooling-api-custom-model_groovy_sanityCheck.sample",

                // TODO(https://github.com/gradle/gradle/issues/13470) Signing plugin support
                "snippet-signing-configurations_groovy_signingArchivesOutput.sample",
                "snippet-signing-configurations_kotlin_signingArchivesOutput.sample",
                "snippet-signing-maven-publish_groovy_publishingMavenSignAndPublish.sample",
                "snippet-signing-maven-publish_groovy_signingPluginSignPublication.sample",
                "snippet-signing-maven-publish_kotlin_publishingMavenSignAndPublish.sample",
                "snippet-signing-maven-publish_kotlin_signingPluginSignPublication.sample",
                "snippet-signing-tasks_groovy_signingTaskOutput.sample",
                "snippet-signing-tasks_kotlin_signingTaskOutput.sample",

                // TODO(https://github.com/gradle/gradle/issues/22879) The snippet extracts build logic into a method and calls the method at execution time
                "snippet-tutorial-ant-loadfile-with-method_groovy_antLoadfileWithMethod.sample",
                "snippet-tutorial-ant-loadfile-with-method_kotlin_antLoadfileWithMethod.sample",
            ]

            // Tests that can and has to be fixed to run with the configuration cache enabled.
            // Set the Gradle property runBrokenConfigurationCacheDocsTests=true to run tests from this list or any of the lists above.
            def testsToBeFixedForConfigurationCache = [
                "snippet-build-cache-configure-task_groovy_configureTask.sample",
                "snippet-build-cache-configure-task_kotlin_configureTask.sample",
            ]

            def brokenTests = testsForUnsupportedFeatures + testsWithThirdPartyFailures + testsForNotYetSupportedFeatures + testsToBeFixedForConfigurationCache
            brokenTests.forEach { testName ->
                def testMask = "org.gradle.docs.samples.*.$testName"
                if (shouldRunBrokenForConfigurationCacheDocsTests(project)) {
                    includeTestsMatching testMask
                } else {
                    excludeTestsMatching testMask
                }
            }
        }
    } else {
        filter {
            excludeTestsMatching "*WithCC*.sample"
        }
    }
}

// Publications for the docs subproject:

configurations {
    gradleFullDocsElements {
        // TODO: This breaks the provider
        outgoing.artifact(project.gradleDocumentation.getDocumentationRenderedRoot().get().asFile) {
            builtBy 'docs'
        }
    }
}

tasks.named("check") {
    dependsOn(tasks.named('checkstyleApi'))
}

// TODO there is some duplication with DistributionTest.kt here - https://github.com/gradle/gradle-private/issues/3126
class GradleInstallationForTestEnvironmentProvider implements CommandLineArgumentProvider {
    @Internal
    final ConfigurableFileCollection gradleHomeDir

    @PathSensitive(PathSensitivity.RELATIVE)
    @InputDirectory
    final DirectoryProperty samplesdir

    @Nested
    final GradleDistribution gradleDistribution

    private final FileCollection testTaskClasspath
    private final Directory repoRoot

    GradleInstallationForTestEnvironmentProvider(Project project, Test testTask) {
        this.gradleHomeDir = project.objects.fileCollection()
        this.samplesdir = project.objects.directoryProperty()
        this.gradleDistribution = new GradleDistribution(gradleHomeDir)
        this.testTaskClasspath = testTask.classpath
        this.repoRoot = repoRoot(project)
    }

    @Override
    Iterable<String> asArguments() {
        def distributionName = testTaskClasspath.filter { it.name.startsWith("gradle-runtime-api-info") }.singleFile.parentFile.parentFile.parentFile.name
        ["-DintegTest.gradleHomeDir=${gradleHomeDir.singleFile}",
         "-DintegTest.samplesdir=${samplesdir.get().asFile}",
         "-DintegTest.gradleUserHomeDir=${repoRoot.dir("intTestHomeDir/$distributionName")}"]
    }
}

tasks.withType(CheckLinks).configureEach {
    enabled = !gradle.startParameter.taskNames.contains("docs:docsTest")
}

tasks.register("checkLinks") {
    dependsOn(tasks.withType(CheckLinks))
}