diff options
| author | aSemy <897017+aSemy@users.noreply.github.com> | 2023-03-07 23:26:06 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-03-07 23:26:06 +0100 |
| commit | 62c980707d23d2d451c75330f7ed1ba613777cf3 (patch) | |
| tree | 2dd732bdaa23713d665a07bcc28c2ab152dc8096 | |
| parent | ded804e5772399f1495016d598573cb20b673b58 (diff) | |
| download | dokka-62c980707d23d2d451c75330f7ed1ba613777cf3.tar.gz dokka-62c980707d23d2d451c75330f7ed1ba613777cf3.tar.bz2 dokka-62c980707d23d2d451c75330f7ed1ba613777cf3.zip | |
Use buildSrc convention plugins to configure the Dokka subprojects (#2704)
45 files changed, 769 insertions, 301 deletions
diff --git a/.github/workflows/gh-actions-artifacts-snapshots.yml b/.github/workflows/gh-actions-artifacts-snapshots.yml index e073dae3..99b00636 100644 --- a/.github/workflows/gh-actions-artifacts-snapshots.yml +++ b/.github/workflows/gh-actions-artifacts-snapshots.yml @@ -18,7 +18,7 @@ jobs: - uses: actions/setup-java@v3 with: distribution: 'zulu' - java-version: 12 + java-version: 11 cache: 'maven' - name: Document coroutines uses: gradle/gradle-build-action@v2 @@ -44,7 +44,7 @@ jobs: - uses: actions/setup-java@v3 with: distribution: 'zulu' - java-version: 12 + java-version: 11 cache: 'maven' - name: Document serialization uses: gradle/gradle-build-action@v2 @@ -70,7 +70,7 @@ jobs: - uses: actions/setup-java@v3 with: distribution: 'zulu' - java-version: 12 + java-version: 11 cache: 'maven' - name: Document biojava-core uses: gradle/gradle-build-action@v2 diff --git a/.github/workflows/s3-snapshots.yml b/.github/workflows/s3-snapshots.yml index 43efbf63..6a170211 100644 --- a/.github/workflows/s3-snapshots.yml +++ b/.github/workflows/s3-snapshots.yml @@ -18,7 +18,7 @@ jobs: - uses: actions/setup-java@v3 with: distribution: 'zulu' - java-version: 12 + java-version: 11 cache: 'maven' - name: Document coroutines uses: gradle/gradle-build-action@v2 @@ -48,7 +48,7 @@ jobs: - uses: actions/setup-java@v3 with: distribution: 'zulu' - java-version: 12 + java-version: 11 cache: 'maven' - name: Document serialization uses: gradle/gradle-build-action@v2 @@ -78,7 +78,7 @@ jobs: - uses: actions/setup-java@v3 with: distribution: 'zulu' - java-version: 12 + java-version: 11 cache: 'maven' - name: Document biojava-core uses: gradle/gradle-build-action@v2 diff --git a/build.gradle.kts b/build.gradle.kts index 1deb02f6..08373920 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -1,76 +1,21 @@ -import org.jetbrains.* -import org.jetbrains.kotlin.gradle.tasks.KotlinCompile +import org.jetbrains.ValidatePublications +import org.jetbrains.publicationChannels plugins { - kotlin("jvm") apply false - id("java") - id("org.jetbrains.dokka") version "1.8.10" + org.jetbrains.conventions.base + id("org.jetbrains.dokka") id("io.github.gradle-nexus.publish-plugin") -} - -val dokka_version: String by project - -allprojects { - configureDokkaVersion() - group = "org.jetbrains.dokka" - version = dokka_version - - - val language_version: String by project - tasks.withType(KotlinCompile::class).all { - kotlinOptions { - freeCompilerArgs = freeCompilerArgs + listOf( - "-opt-in=kotlin.RequiresOptIn", - "-Xjsr305=strict", - "-Xskip-metadata-version-check", - // need 1.4 support, otherwise there might be problems with Gradle 6.x (it's bundling Kotlin 1.4) - "-Xsuppress-version-warnings" - ) - allWarningsAsErrors = true - languageVersion = language_version - apiVersion = language_version - jvmTarget = "1.8" - } - } - - repositories { - mavenCentral() - } + id("org.jetbrains.kotlinx.binary-compatibility-validator") } -subprojects { - apply { - plugin("org.jetbrains.kotlin.jvm") - plugin("java") - plugin("signing") - plugin("org.jetbrains.dokka") - } - - // Gradle metadata - java { - @Suppress("UnstableApiUsage") - withSourcesJar() - targetCompatibility = JavaVersion.VERSION_1_8 - } - - tasks { - val dokkaOutputDir = "$buildDir/dokka" +val dokka_version: String by project - dokkaHtml { - onlyIf { !isLocalPublication } - outputDirectory.set(file(dokkaOutputDir)) - } +group = "org.jetbrains.dokka" +version = dokka_version - register<Jar>("javadocJar") { - archiveClassifier.set("javadoc") - dependsOn(dokkaHtml) - from(dokkaOutputDir) - } - } -} -println("Publication version: $dokka_version") +logger.lifecycle("Publication version: $dokka_version") tasks.register<ValidatePublications>("validatePublications") nexusPublishing { @@ -82,8 +27,28 @@ nexusPublishing { } } -tasks.maybeCreate("dokkaPublish").run { +val dokkaPublish by tasks.registering { if (publicationChannels.any { it.isMavenRepository() }) { finalizedBy(tasks.named("closeAndReleaseSonatypeStagingRepository")) } } + +apiValidation { + // note that subprojects are ignored by their name, not their path https://github.com/Kotlin/binary-compatibility-validator/issues/16 + ignoredProjects += setOf( + // NAME PATH + "search-component", // :plugins:search-component + "frontend", // :plugins:base:frontend + + "kotlin-analysis", // :kotlin-analysis + "compiler-dependency", // :kotlin-analysis:compiler-dependency + "intellij-dependency", // :kotlin-analysis:intellij-dependency + + "integration-tests", // :integration-tests + "gradle", // :integration-tests:gradle + "cli", // :integration-tests:cli + "maven", // integration-tests:maven + + "test-utils", // :test-utils + ) +} diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts index 90ccf158..00733d64 100644 --- a/buildSrc/build.gradle.kts +++ b/buildSrc/build.gradle.kts @@ -1,13 +1,32 @@ +import java.util.* + plugins { `kotlin-dsl` } -repositories { - gradlePluginPortal() +kotlin { + jvmToolchain { + languageVersion.set(JavaLanguageVersion.of(8)) + } +} + +// TODO define versions in Gradle Version Catalog https://github.com/Kotlin/dokka/pull/2884 +val properties = file("../gradle.properties").inputStream().use { + Properties().apply { load(it) } } +val kotlinVersion = properties["kotlin_version"] + dependencies { - implementation("com.github.jengelman.gradle.plugins:shadow:2.0.4") - implementation("org.jetbrains.kotlinx:binary-compatibility-validator:0.10.1") + // Import Gradle Plugins that will be used in the buildSrc pre-compiled script plugins, and any `build.gradle.kts` + // files in the project. + // Use their Maven coordinates (plus versions), not Gradle plugin IDs! + // This should be the only place that Gradle plugin versions are defined, so they are aligned across all build scripts + + implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion") + implementation("gradle.plugin.com.github.johnrengelman:shadow:7.1.2") + implementation("org.jetbrains.kotlinx:binary-compatibility-validator:0.12.1") implementation("io.github.gradle-nexus:publish-plugin:1.1.0") + implementation("org.jetbrains.dokka:dokka-gradle-plugin:1.8.10") + implementation("com.gradle.publish:plugin-publish-plugin:0.20.0") } diff --git a/buildSrc/settings.gradle.kts b/buildSrc/settings.gradle.kts new file mode 100644 index 00000000..2144de34 --- /dev/null +++ b/buildSrc/settings.gradle.kts @@ -0,0 +1,17 @@ +rootProject.name = "buildSrc" + +pluginManagement { + repositories { + gradlePluginPortal() + mavenCentral() + } +} + +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + repositories { + mavenCentral() + google() + gradlePluginPortal() + } +} diff --git a/buildSrc/src/main/kotlin/org/jetbrains/binaryCompatibility.kt b/buildSrc/src/main/kotlin/org/jetbrains/binaryCompatibility.kt deleted file mode 100644 index 0b8386b6..00000000 --- a/buildSrc/src/main/kotlin/org/jetbrains/binaryCompatibility.kt +++ /dev/null @@ -1,29 +0,0 @@ -package org.jetbrains - -import kotlinx.validation.ApiValidationExtension -import org.gradle.api.Project -import org.gradle.kotlin.dsl.configure - -internal object BinaryCompatibilityConfig { - val ignoredPublications = setOf("kotlinAnalysisIntelliJ", "kotlinAnalysis", "kotlinAnalysisCompiler") - val ignoredSubprojects = setOf( - "search-component", - "compiler-dependency", - "intellij-dependency", - "kotlin-analysis", - "frontend" - ) -} - -internal fun Project.registerBinaryCompatibilityCheck(publicationName: String) { - if (publicationName !in BinaryCompatibilityConfig.ignoredPublications) { - if (tasks.findByName("apiBuild") == null) { - plugins.apply(kotlinx.validation.BinaryCompatibilityValidatorPlugin::class.java) - configure<ApiValidationExtension> { - ignoredProjects.addAll( - BinaryCompatibilityConfig.ignoredSubprojects.intersect(allprojects.map { it.name }.toSet()) - ) - } - } - } -}
\ No newline at end of file diff --git a/buildSrc/src/main/kotlin/org/jetbrains/conventions/base-java.gradle.kts b/buildSrc/src/main/kotlin/org/jetbrains/conventions/base-java.gradle.kts new file mode 100644 index 00000000..3addac74 --- /dev/null +++ b/buildSrc/src/main/kotlin/org/jetbrains/conventions/base-java.gradle.kts @@ -0,0 +1,22 @@ +package org.jetbrains.conventions + +/** + * Base configuration for Java projects. + * + * This convention plugin contains shared Java config for both the [KotlinJvmPlugin] convention plugin and + * the Gradle Plugin subproject (which cannot have the `kotlin("jvm")` plugin applied). + */ + +plugins { + `java` +} + +java { + toolchain { + languageVersion.set(JavaLanguageVersion.of(8)) + } +} + +java { + withSourcesJar() +} diff --git a/buildSrc/src/main/kotlin/org/jetbrains/conventions/base.gradle.kts b/buildSrc/src/main/kotlin/org/jetbrains/conventions/base.gradle.kts new file mode 100644 index 00000000..c4352d16 --- /dev/null +++ b/buildSrc/src/main/kotlin/org/jetbrains/conventions/base.gradle.kts @@ -0,0 +1,12 @@ +package org.jetbrains.conventions + +plugins { + base +} + +// common Gradle configuration that should be applied to all projects + +if (project != rootProject) { + project.group = rootProject.group + project.version = rootProject.version +} diff --git a/buildSrc/src/main/kotlin/org/jetbrains/conventions/dokka-integration-test.gradle.kts b/buildSrc/src/main/kotlin/org/jetbrains/conventions/dokka-integration-test.gradle.kts new file mode 100644 index 00000000..612502cd --- /dev/null +++ b/buildSrc/src/main/kotlin/org/jetbrains/conventions/dokka-integration-test.gradle.kts @@ -0,0 +1,75 @@ +package org.jetbrains.conventions + +import org.gradle.api.tasks.testing.logging.TestExceptionFormat +import org.gradle.api.tasks.testing.logging.TestLogEvent + +plugins { + id("org.jetbrains.conventions.kotlin-jvm") +} + +val integrationTestSourceSet = sourceSets.create("integrationTest") { + compileClasspath += sourceSets.main.get().output + runtimeClasspath += sourceSets.main.get().output +} + +val integrationTestImplementation by configurations.getting { + extendsFrom(configurations.implementation.get()) +} + +val integrationTestRuntimeOnly by configurations.getting { + extendsFrom(configurations.runtimeOnly.get()) +} + +/** + * Dokka's integration test task is not cacheable because the HTML outputs + * it produces when running the tests are used for showcasing resulting documentation, + * which does not work well with caching. + * + * At the moment there are two problems that do not allow to make it cacheable: + * + * 1. The task's inputs are such that changes in Dokka's code do not invalidate the cache, + * because it is run with the same version of Dokka (`"DOKKA_VERSION"`) on the same + * test project inputs. + * 2. The tests generate HTML output which is then used to showcase documentation. + * The outputs are usually copied to a location from which it will be served. + * However, if the test is cacheable, it produces no outputs, so no documentation + * to showcase. It needs to be broken into two separate tasks: one cacheable for running + * the tests and producing HTML output, and another non-cacheable for copying the output. + * + * @see [org.jetbrains.dokka.it.TestOutputCopier] for more details on showcasing documentation + */ +@DisableCachingByDefault(because = "Contains incorrect inputs/outputs configuration, see the KDoc for details") +abstract class NonCacheableIntegrationTest : Test() + +val integrationTest by tasks.registering(NonCacheableIntegrationTest::class) { + maxHeapSize = "2G" + description = "Runs integration tests." + group = "verification" + useJUnit() + + testClassesDirs = integrationTestSourceSet.output.classesDirs + classpath = integrationTestSourceSet.runtimeClasspath + + setForkEvery(1) + project.properties["dokka_integration_test_parallelism"]?.toString()?.toIntOrNull()?.let { parallelism -> + maxParallelForks = parallelism + } + environment( + "isExhaustive", + project.properties["dokka_integration_test_is_exhaustive"]?.toString()?.toBoolean() + ?: System.getenv("DOKKA_INTEGRATION_TEST_IS_EXHAUSTIVE")?.toBoolean() + ?: false.toString() + ) + + testLogging { + exceptionFormat = TestExceptionFormat.FULL + events(TestLogEvent.SKIPPED, TestLogEvent.FAILED) + showExceptions = true + showCauses = true + showStackTraces = true + } +} + +tasks.check { + dependsOn(integrationTest) +} diff --git a/buildSrc/src/main/kotlin/org/jetbrains/conventions/dokka.gradle.kts b/buildSrc/src/main/kotlin/org/jetbrains/conventions/dokka.gradle.kts new file mode 100644 index 00000000..9a193cbb --- /dev/null +++ b/buildSrc/src/main/kotlin/org/jetbrains/conventions/dokka.gradle.kts @@ -0,0 +1,13 @@ +package org.jetbrains.conventions + +import org.gradle.kotlin.dsl.invoke +import org.jetbrains.isLocalPublication + +plugins { + id("org.jetbrains.dokka") +} + +tasks.dokkaHtml { + onlyIf { !isLocalPublication } + outputDirectory.set(layout.buildDirectory.dir("dokka").map { it.asFile }) +} diff --git a/buildSrc/src/main/kotlin/org/jetbrains/conventions/kotlin-jvm.gradle.kts b/buildSrc/src/main/kotlin/org/jetbrains/conventions/kotlin-jvm.gradle.kts new file mode 100644 index 00000000..bd33df22 --- /dev/null +++ b/buildSrc/src/main/kotlin/org/jetbrains/conventions/kotlin-jvm.gradle.kts @@ -0,0 +1,29 @@ +package org.jetbrains.conventions + +import org.jetbrains.configureDokkaVersion +import org.jetbrains.kotlin.gradle.tasks.KotlinCompile + +plugins { + id("org.jetbrains.conventions.base") + id("org.jetbrains.conventions.base-java") + kotlin("jvm") +} + +configureDokkaVersion() + +val language_version: String by project + +tasks.withType<KotlinCompile>().configureEach { + kotlinOptions { + freeCompilerArgs += listOf( + "-opt-in=kotlin.RequiresOptIn", + "-Xjsr305=strict", + "-Xskip-metadata-version-check", + // need 1.4 support, otherwise there might be problems with Gradle 6.x (it's bundling Kotlin 1.4) + "-Xsuppress-version-warnings" + ) + allWarningsAsErrors = true + languageVersion = language_version + apiVersion = language_version + } +} diff --git a/buildSrc/src/main/kotlin/org/jetbrains/conventions/maven-publish.gradle.kts b/buildSrc/src/main/kotlin/org/jetbrains/conventions/maven-publish.gradle.kts new file mode 100644 index 00000000..7007fd9e --- /dev/null +++ b/buildSrc/src/main/kotlin/org/jetbrains/conventions/maven-publish.gradle.kts @@ -0,0 +1,30 @@ +package org.jetbrains.conventions + +plugins { + id("org.jetbrains.conventions.base") + `maven-publish` + signing + id("org.jetbrains.conventions.dokka") +} + +val javadocJar by tasks.registering(Jar::class) { + group = JavaBasePlugin.DOCUMENTATION_GROUP + description = "Assembles a Javadoc JAR using Dokka HTML" + archiveClassifier.set("javadoc") + from(tasks.dokkaHtml) +} + +publishing { + repositories { + // Publish to a project-local Maven directory, for verification. To test, run: + // ./gradlew publishAllPublicationsToMavenProjectLocalRepository + // and check $rootDir/build/maven-project-local + maven(rootProject.layout.buildDirectory.dir("maven-project-local")) { + name = "MavenProjectLocal" + } + } + + publications.withType<MavenPublication>().configureEach { + artifact(javadocJar) + } +} diff --git a/buildSrc/src/main/kotlin/org/jetbrains/publication.kt b/buildSrc/src/main/kotlin/org/jetbrains/publication.kt index eb45e255..60d91c33 100644 --- a/buildSrc/src/main/kotlin/org/jetbrains/publication.kt +++ b/buildSrc/src/main/kotlin/org/jetbrains/publication.kt @@ -2,9 +2,13 @@ package org.jetbrains import com.github.jengelman.gradle.plugins.shadow.ShadowExtension import org.gradle.api.Project +import org.gradle.api.plugins.JavaBasePlugin import org.gradle.api.publish.PublishingExtension import org.gradle.api.publish.maven.MavenPublication import org.gradle.api.publish.maven.tasks.PublishToMavenRepository +import org.gradle.api.tasks.TaskContainer +import org.gradle.api.tasks.TaskProvider +import org.gradle.api.tasks.bundling.Jar import org.gradle.kotlin.dsl.* import org.gradle.plugins.signing.SigningExtension import org.jetbrains.DokkaPublicationChannel.* @@ -33,7 +37,6 @@ fun Project.registerDokkaArtifactPublication(publicationName: String, configure: artifact(tasks["sourcesJar"]) } } - artifact(tasks["javadocJar"]) configurePom("Dokka ${project.name}") } } @@ -42,7 +45,6 @@ fun Project.registerDokkaArtifactPublication(publicationName: String, configure: configureSpacePublicationIfNecessary(publicationName) configureSonatypePublicationIfNecessary(publicationName) createDokkaPublishTaskIfNecessary() - registerBinaryCompatibilityCheck(publicationName) } fun Project.configureSpacePublicationIfNecessary(vararg publications: String) { diff --git a/core/build.gradle.kts b/core/build.gradle.kts index 41db29d3..1d7c1f17 100644 --- a/core/build.gradle.kts +++ b/core/build.gradle.kts @@ -2,7 +2,8 @@ import org.jetbrains.dokkaVersion import org.jetbrains.registerDokkaArtifactPublication plugins { - `maven-publish` + org.jetbrains.conventions.`kotlin-jvm` + org.jetbrains.conventions.`maven-publish` } dependencies { diff --git a/core/content-matcher-test-utils/build.gradle.kts b/core/content-matcher-test-utils/build.gradle.kts index 07d4bed9..1a95f1cd 100644 --- a/core/content-matcher-test-utils/build.gradle.kts +++ b/core/content-matcher-test-utils/build.gradle.kts @@ -1,3 +1,7 @@ +plugins { + org.jetbrains.conventions.`kotlin-jvm` +} + dependencies { implementation(project(":core:test-api")) implementation(kotlin("stdlib-jdk8")) diff --git a/core/test-api/build.gradle.kts b/core/test-api/build.gradle.kts index cb36dc20..b3f57010 100644 --- a/core/test-api/build.gradle.kts +++ b/core/test-api/build.gradle.kts @@ -1,7 +1,8 @@ import org.jetbrains.registerDokkaArtifactPublication plugins { - `maven-publish` + org.jetbrains.conventions.`kotlin-jvm` + org.jetbrains.conventions.`maven-publish` } dependencies { diff --git a/integration-tests/build.gradle.kts b/integration-tests/build.gradle.kts index 226b4b6f..80c07b37 100644 --- a/integration-tests/build.gradle.kts +++ b/integration-tests/build.gradle.kts @@ -1,80 +1,5 @@ -import org.gradle.api.tasks.testing.logging.TestExceptionFormat -import org.gradle.api.tasks.testing.logging.TestLogEvent - -subprojects { - sourceSets { - create("integrationTest") { - compileClasspath += sourceSets.main.get().output - runtimeClasspath += sourceSets.main.get().output - } - } - - configurations.getByName("integrationTestImplementation") { - extendsFrom(configurations.implementation.get()) - } - - configurations.getByName("integrationTestRuntimeOnly") { - extendsFrom(configurations.runtimeOnly.get()) - } - - dependencies { - implementation(project(":integration-tests")) - } - - /** - * Dokka's integration test task is not cacheable because the HTML outputs - * it produces when running the tests are used for showcasing resulting documentation, - * which does not work well with caching. - * - * At the moment there are two problems that do not allow to make it cacheable: - * - * 1. The task's inputs are such that changes in Dokka's code do not invalidate the cache, - * because it is run with the same version of Dokka ("DOKKA_VERSION") on the same - * test project inputs. - * 2. The tests generate HTML output which is then used to showcase documentation. - * The outputs are usually copied to a location from which it will be served. - * However, if the test is cacheable, it produces no outputs, so no documentation - * to showcase. It needs to be broken into two separate tasks: one cacheable for running - * the tests and producing HTML output, and another non-cacheable for copying the output. - * - * @see [org.jetbrains.dokka.it.TestOutputCopier] for more details on showcasing documentation - */ - @DisableCachingByDefault(because = "Contains incorrect inputs/outputs configuration, see the KDoc for details") - abstract class NonCacheableIntegrationTest : Test() - - val integrationTest by tasks.register<NonCacheableIntegrationTest>("integrationTest") { - maxHeapSize = "2G" - description = "Runs integration tests." - group = "verification" - useJUnit() - - - testClassesDirs = sourceSets["integrationTest"].output.classesDirs - classpath = sourceSets["integrationTest"].runtimeClasspath - - setForkEvery(1) - project.properties["dokka_integration_test_parallelism"]?.toString()?.toIntOrNull()?.let { parallelism -> - maxParallelForks = parallelism - } - environment( - "isExhaustive", - project.properties["dokka_integration_test_is_exhaustive"]?.toString()?.toBoolean() - ?: System.getenv("DOKKA_INTEGRATION_TEST_IS_EXHAUSTIVE")?.toBoolean() - ?: false.toString() - ) - - testLogging { - exceptionFormat = TestExceptionFormat.FULL - events(TestLogEvent.SKIPPED, TestLogEvent.FAILED) |
