From 618228e45562ad0c25f587470cae4994140b6369 Mon Sep 17 00:00:00 2001 From: "Daniel A. A. Pelsmaeker" Date: Fri, 19 Jul 2024 17:52:39 +0200 Subject: [PATCH] Update docs --- docs/content/conventions/index.md | 11 +++ docs/content/conventions/java.md | 32 +++++++++ docs/content/conventions/junit.md | 48 +++++++++++++ docs/content/conventions/mavenpublish.md | 81 ++++++++++++++++++++++ docs/content/conventions/rootproject.md | 29 ++++++++ docs/content/conventions/settings.md | 37 ++++++++++ docs/content/index.md | 86 +----------------------- docs/mkdocs.yml | 17 +++-- 8 files changed, 252 insertions(+), 89 deletions(-) create mode 100644 docs/content/conventions/index.md create mode 100644 docs/content/conventions/java.md create mode 100644 docs/content/conventions/junit.md create mode 100644 docs/content/conventions/mavenpublish.md create mode 100644 docs/content/conventions/rootproject.md create mode 100644 docs/content/conventions/settings.md diff --git a/docs/content/conventions/index.md b/docs/content/conventions/index.md new file mode 100644 index 0000000..379d697 --- /dev/null +++ b/docs/content/conventions/index.md @@ -0,0 +1,11 @@ +--- +title: "Convention Plugins" +--- +# Convention Plugins +This repository publishes a number of Gradle convention plugins for Spoofax/Metaborg projects. + +- [Java Convention](./java-convention.md) +- [JUnit Convention](./junit-convention.md) +- [Maven Publish Convention](./mavenpublish-convention.md) +- [Root Project Convention](./rootproject-convention.md) +- [Settings Convention](./settings-convention.md) diff --git a/docs/content/conventions/java.md b/docs/content/conventions/java.md new file mode 100644 index 0000000..ee7eea0 --- /dev/null +++ b/docs/content/conventions/java.md @@ -0,0 +1,32 @@ +--- +title: "Java Convention" +--- +# Java Convention Plugin +The Java convention plugin configures a project to be built using Java 11 by default, but this can be overridden. + +To use the plugin, you need to apply both the Java convention plugin and one of the Java plugins (`java-library`, `java`): + +```kotlin title="build.gradle.kts" +plugins { + id("org.metaborg.convention.java") version "" + `java-library` +} +``` + +!!! note "Kotlin" + When using Kotlin, it will automatically use the configured JVM toolchain. + + + +## Configuration +The plugin can be configured using the `javaConvention` extension: + +```kotlin title="build.gradle.kts" +javaConvention { + // The Java version to use + javaVersion.set(JavaLanguageVersion.of(11)) +} +``` + + + diff --git a/docs/content/conventions/junit.md b/docs/content/conventions/junit.md new file mode 100644 index 0000000..6e81039 --- /dev/null +++ b/docs/content/conventions/junit.md @@ -0,0 +1,48 @@ +--- +title: "JUnit Convention" +--- +# JUnit Convention Plugin +The JUnit convention plugin configures a Java project to use JUnit 5 for testing, and also adds a JUnit dependency. + +To use the plugin, you need to apply it to the project: + +```kotlin title="build.gradle.kts" +plugins { + id("org.metaborg.convention.junit") version "" +} +``` + +!!! note "JUnit Dependency" + If a version catalog is configured, this plugin automatically adds the following dependency: + + ```kotlin + dependencies { + testImplementation(libs.junit) + } + ``` + + If the project has no version catalog, it adds the following dependency: + + ```kotlin + dependencies { + testImplementation("org.junit.jupiter:junit-jupiter:") + } + ``` + + +## Configuration +The plugin can be configured using the `junitConvention` extension: + +```kotlin title="build.gradle.kts" +junitConvention { + // The name of the version catalog to use + versionCatalogName.set("libs") + // The alias of the JUnit library in the version catalog + jUnitAlias.set("junit") + // The dependency of JUnit to use if it is not found in the version catalog + jUnitDependency.set("org.junit.jupiter:junit-jupiter:") +} +``` + + + diff --git a/docs/content/conventions/mavenpublish.md b/docs/content/conventions/mavenpublish.md new file mode 100644 index 0000000..b1bb4cc --- /dev/null +++ b/docs/content/conventions/mavenpublish.md @@ -0,0 +1,81 @@ +--- +title: "Maven Publish Convention" +--- +# Maven Publish Convention Plugin +The Maven Publish convention plugin adds metadata to existing publications, and sets up GitHub Packages and Metaborg Artifacts as target publication repositories. A minimal configuration looks like this: + +```kotlin title="build.gradle.kts" +plugins { + id("org.metaborg.convention.maven-publish") version "" +} + +// Group must be set +group = "org.metaborg" + +// The repository owner and name must be set +mavenPublishConvention { + repoOwner.set("metaborg") + repoName.set("convention-plugin-example") +} + +// A publication must have been created +publishing { + publications { + create("mavenJava") { + from(components["java"]) + } + } +} +``` + +The `repoOwner` and `repoName` fields must be set, but usually it is easier to set it once on the root project's `build.gradle.kts` for all projects that apply the Maven Publish convention plugin, like this: + +```kotlin title="build.gradle.kts" +allprojects { + pluginManager.withPlugin("org.metaborg.convention.maven-publish") { + extensions.configure(org.metaborg.convention.MavenPublishConventionExtension::class.java) { + repoOwner.set("metaborg") + repoName.set("convention-plugin-example") + } + } +} +``` + + +## Configuration +The plugin can be configured using the `mavenPublishConvention` extension: + +```kotlin title="build.gradle.kts" +mavenPublishConvention { + // The owner of the GitHub repository + repoOwner.set("") + // The name of the GitHub repository + repoName.set("") + // Whether to publish to GitHub packages. + publishToGitHubPackages.set(true) + // Whether to publish to Metaborg Artifacts. + publishToMetaborgArtifacts.set(true) + + metadata { + // The year the project was started + inceptionYear.set("2021") + // The developers of the project + developers.set( + listOf( + Developer("", "", ""), + ) + ) + // The source control management system + scm.set(SCM.GitHub) + // The license of the project + license.set(OpenSourceLicense.Apache2) + // The HTTP SCM URL format + httpUrlFormat.set("https://github.com/%s/%s") + // The SCM URL format + scmUrlFormat.set("scm:git@github.com:%s/%s.git") + } +} +``` + + + diff --git a/docs/content/conventions/rootproject.md b/docs/content/conventions/rootproject.md new file mode 100644 index 0000000..c993361 --- /dev/null +++ b/docs/content/conventions/rootproject.md @@ -0,0 +1,29 @@ +--- +title: "Root Project Convention" +--- +# Root Project Convention Plugin +The Root Project convention plugin adds tasks that invoke the corresponding tasks on the sub-builds and subprojects. + +```kotlin title="build.gradle.kts" +plugins { + id("org.metaborg.convention.root-project") version "" +} +``` + +## Configuration +The plugin can be configured using the `rootProjectConvention` extension: + +```kotlin title="build.gradle.kts" +rootProjectConvention { + // The suffix for tasks that invoke tasks in subprojects and included builds + taskNameSuffix.set("All") + assembleTaskName.set("assembleAll") + buildTaskName.set("buildAll") + cleanTaskName.set("cleanAll") + publishTaskName.set("publishAll") + publishToMavenLocalTaskName.set("publishAllToMavenLocal") + checkTaskName.set("checkAll") + testTaskName.set("testAll") + tasksTaskName.set("allTasks") +} +``` \ No newline at end of file diff --git a/docs/content/conventions/settings.md b/docs/content/conventions/settings.md new file mode 100644 index 0000000..1cfa68a --- /dev/null +++ b/docs/content/conventions/settings.md @@ -0,0 +1,37 @@ +--- +title: "Root Project Convention" +--- +# Settings Convention Plugin +The Settings convention applies the Gradle Develocity and Foojay plugins, and installs the Metaborg version catalog. + +```kotlin title="settings.gradle.kts" +pluginManagement { + repositories { + maven("https://artifacts.metaborg.org/content/groups/public/") + } +} + +plugins { + id("org.metaborg.convention.settings") version "0.0.11" +} +``` + +!!! warning "" + In contrast to the other plugin, the Settings convention plugin must be applied in the project's `settings.gradle.kts`. + +!!! note "" + After applying the Settings convention plugin, other plugins applied in projects' `build.gradle.kts` files no longer need a version number. + +!!! tip "" + After configuring the plugin, you can use the `libs` version catalog to add dependencies to your project. + See the [Version Catalog](https://github.com/metaborg/metaborg-gradle/blob/main/depman/gradle/libs.versions.toml) to see the defined libraries. + + +## Configuration +The plugin can be configured using the `settingsConvention` extension: + +```kotlin title="settings.gradle.kts" +settingsConvention { + // No options. +} +``` diff --git a/docs/content/index.md b/docs/content/index.md index 22ed6cb..d71ad49 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -1,88 +1,6 @@ --- -title: "Gradle Convention" +title: "Home" --- -# Gradle Convention - +# Metaborg Gradle The Metaborg Gradle convention and development plugins. -## Java Convention -The Java convention plugin configures a project to be built using Java 11 by default, but this can be overridden. - -To apply the plugin: - -```kotlin title="build.gradle.kts" -plugins { - id("org.metaborg.convention.java") version "" - `java-library` -} -``` - -!!! note "Kotlin" - When using Kotlin, it will automatically use the configured JVM toolchain. - - -## Maven Publish Convention -The Maven Publish convention plugin adds metadata to existing publications, and sets up GitHub Packages and Metaborg Artifacts as target publication repositories. A minimal configuration looks like this: - -```kotlin title="build.gradle.kts" -plugins { - id("org.metaborg.convention.maven-publish") version "" -} - -// Group must be set -group = "org.metaborg" - -// The repository owner and name must be set -mavenPublishConvention { - repoOwner.set("metaborg") - repoName.set("convention-plugin-example") -} - -// A publication must have been created -publishing { - publications { - create("mavenJava") { - from(components["java"]) - } - } -} -``` - -The `repoOwner` and `repoName` fields must be set, but usually it is easier to set it once on the root project's `build.gradle.kts` for all projects that apply the Maven Publish convention plugin, like this: - -```kotlin title="build.gradle.kts" -allprojects { - pluginManager.withPlugin("org.metaborg.convention.maven-publish") { - extensions.configure(MavenPublishConventionExtension::class.java) { - repoOwner.set("metaborg") - repoName.set("convention-plugin-example") - } - } -} -``` - - -## Root Project Convention -The Root Project convention plugin adds tasks that invoke the corresponding tasks on the sub-builds and subprojects. - -```kotlin title="build.gradle.kts" -plugins { - id("org.metaborg.convention.root-project") version "" -} -``` - - -## Settings Convention -The Settings convention applies the Gradle Develocity and Foojay plugins, and installs the Metaborg version catalog. - -```kotlin title="settings.gradle.kts" -pluginManagement { - repositories { - maven("https://artifacts.metaborg.org/content/groups/public/") - } -} - -plugins { - id("org.metaborg.convention.settings") version "0.0.11" -} -``` \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 2a77aff..d45d372 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,7 +1,7 @@ --- # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json -site_name: Metaborg Gradle Convention -site_description: Metaborg Gradle Convention +site_name: Metaborg Gradle +site_description: Metaborg Gradle site_author: Daniel A. A. Pelsmaeker docs_dir: content/ @@ -11,18 +11,25 @@ edit_uri: https://github.com/metaborg/metaborg-gradle/edit/main/docs nav: - Home: - index.md + - Conventions: + - conventions/index.md + - conventions/java.md + - conventions/junit.md + - conventions/mavenpublish.md + - conventions/rootproject.md + - conventions/settings.md theme: name: material language: en icon: - logo: fontawesome/solid/book + logo: fontawesome/solid/diagram-project repo: fontawesome/brands/github palette: # Light mode - media: "(prefers-color-scheme: light)" scheme: default - primary: blue grey + primary: indigo accent: orange toggle: icon: material/weather-night @@ -30,7 +37,7 @@ theme: # Dark mode - media: "(prefers-color-scheme: dark)" scheme: slate - primary: blue grey + primary: indigo accent: orange toggle: icon: material/weather-sunny