Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorLeitwolf2026-11-15 21:08:49 +0300
committerGitHub2026-11-15 21:08:49 +0300
commitfefa7dd76a2a4b575f2d7d867681ecd14758e471 (patch)
tree303fbb9c4faa363c6bb3e3277352f09e1264541c
parentf842210ecb62f5ed797d196b3b8e9cf40a777bf8 (diff)
parentd719e92f9651568a1d756f06811ce53ec5febee7 (diff)
downloadtazel-fefa7dd76a2a4b575f2d7d867681ecd14758e471.tar.gz
Merge branch 'main' into legal/patent-grantlegal/patent-grant
-rw-r--r--.github/workflows/ci.yml16
-rw-r--r--api/build.gradle.kts10
-rw-r--r--api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/BuildStep.kt8
-rw-r--r--api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/Host.kt4
-rw-r--r--api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/PluginExtensions.kt6
-rw-r--r--api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/ProjectPlugin.kt7
-rw-r--r--build.gradle.kts15
-rw-r--r--gradle-plugin/build.gradle.kts10
-rw-r--r--gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginDescriptorTask.kt13
-rw-r--r--gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginPlugin.kt12
-rw-r--r--sources/main/kotlin/com/progmasoft/tazel/driver/CcToolchain.kt2
-rw-r--r--sources/main/kotlin/com/progmasoft/tazel/driver/SourceTools.kt2
12 files changed, 103 insertions, 2 deletions
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c50a990..89bc3ee 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -47,3 +47,19 @@ jobs:
- name: Run the installed Tazel
shell: bash
run: build/install/tazel/bin/tazel version
+
+ # The reference of the API and the Gradle plugin, and the CLI module on its own; every
+ # Dokka warning fails it.
+ - name: Dokka
+ if: matrix.os == 'ubuntu-26.04'
+ shell: bash
+ run: ./gradlew dokkaGenerate :dokkaGenerateModuleHtml --no-daemon
+
+ - name: Keep the reference
+ if: matrix.os == 'ubuntu-26.04'
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+ with:
+ name: tazel-dokka
+ path: build/dokka/html/
+ if-no-files-found: error
+ retention-days: 7
diff --git a/api/build.gradle.kts b/api/build.gradle.kts
index 779c1ed..97e07e1 100644
--- a/api/build.gradle.kts
+++ b/api/build.gradle.kts
@@ -12,6 +12,16 @@ plugins {
kotlin("jvm")
`java-library`
`maven-publish`
+ id("org.jetbrains.dokka")
+}
+
+// The API reference. Every warning fails it, an undocumented public declaration included.
+dokka {
+ dokkaPublications.html { failOnWarning = true }
+ dokkaSourceSets.configureEach {
+ reportUndocumented = true
+ jdkVersion = 25
+ }
}
group = "com.progmasoft.tazel"
diff --git a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/BuildStep.kt b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/BuildStep.kt
index 0cfd280..6a7b264 100644
--- a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/BuildStep.kt
+++ b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/BuildStep.kt
@@ -9,11 +9,13 @@ import java.nio.file.Path
/** Work a plugin adds to the build of a project; see [ExtensionScope.buildStep]. */
fun interface BuildStep {
+ /** Does the work of the step; [context] reaches the project, the host and the output. */
fun run(context: BuildContext)
}
/** What a [BuildStep] runs with. */
interface BuildContext {
+ /** The absolute root directory of the project. */
val projectRoot: Path
/** The project the step builds. */
@@ -22,7 +24,10 @@ interface BuildContext {
/** The absolute directory the build mode of the project writes artifacts to. */
val outputDirectory: Path
+ /** The build mode of the build: debug or release. */
val buildMode: BuildMode
+
+ /** The machine Tazel runs on. */
val host: Host
/**
@@ -37,6 +42,7 @@ interface BuildContext {
message: String,
)
+ /** Prints [message] as a warning; the build goes on. */
fun warn(message: String)
/**
@@ -69,7 +75,9 @@ interface BuildContext {
/** The exit code of a program [BuildContext.capture] ran, and what it printed. */
data class CapturedRun(
+ /** The exit code of the program. */
val exitCode: Int,
+ /** What the program printed, its output and its errors in the order written. */
val output: String,
)
diff --git a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/Host.kt b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/Host.kt
index 9779ed6..986c0e2 100644
--- a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/Host.kt
+++ b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/Host.kt
@@ -5,6 +5,7 @@
package com.progmasoft.api.tazel.dsl.plugin
+/** The operating system of a [Host]. */
enum class OperatingSystem {
LINUX,
MACOS,
@@ -15,6 +16,7 @@ enum class OperatingSystem {
UNKNOWN,
}
+/** The processor architecture of a [Host]. */
enum class Architecture {
X86_64,
AARCH64,
@@ -25,7 +27,9 @@ enum class Architecture {
/** The machine Tazel runs on. */
data class Host(
+ /** The operating system. */
val os: OperatingSystem,
+ /** The processor architecture. */
val architecture: Architecture,
) {
/** The extension the host gives an executable file: `.exe` on Windows, none elsewhere. */
diff --git a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/PluginExtensions.kt b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/PluginExtensions.kt
index 931aa66..5cc8936 100644
--- a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/PluginExtensions.kt
+++ b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/PluginExtensions.kt
@@ -36,7 +36,10 @@ object PluginExtensions {
/** What the block of an extension can add to its project. */
interface ExtensionScope {
+ /** The absolute root directory of the project. */
val projectRoot: Path
+
+ /** The machine Tazel runs on. */
val host: Host
/**
@@ -52,5 +55,8 @@ interface ExtensionScope {
/** Provided by Tazel, which [PluginExtensions] finds as a service. Plugins do not implement it. */
interface ExtensionHost {
+ /**
+ * The scope of [extension] in the project whose file is running; see [PluginExtensions.require].
+ */
fun require(extension: String): ExtensionScope
}
diff --git a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/ProjectPlugin.kt b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/ProjectPlugin.kt
index 9e479d9..01cf567 100644
--- a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/ProjectPlugin.kt
+++ b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/ProjectPlugin.kt
@@ -25,11 +25,13 @@ const val PROJECT_PLUGIN_API_VERSION = 1
* JAR are checked before it is activated; its code is not sandboxed.
*/
fun interface ProjectPlugin {
+ /** Activates the plugin for one project, before its project files run. */
fun apply(context: ProjectPluginContext)
}
/** What a plugin can do while it is activated for one project. */
interface ProjectPluginContext {
+ /** The absolute root directory of the project. */
val projectRoot: Path
/** The machine Tazel runs on. */
@@ -53,8 +55,13 @@ interface ProjectPluginContext {
/** The project as a plugin sees it once its project file has run. */
interface ProjectSummary {
+ /** The name the project file gives the project, or `null`. */
val name: String?
+
+ /** The version the project file gives the project, or `null`. */
val version: String?
+
+ /** The build mode of the build. */
val buildMode: BuildMode
/** The directory the build mode writes artifacts to, relative to the project root. */
diff --git a/build.gradle.kts b/build.gradle.kts
index 069d56d..85fa035 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -9,6 +9,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
plugins {
kotlin("jvm") version "2.4.0"
id("com.diffplug.spotless") version "8.9.0"
+ id("org.jetbrains.dokka") version "2.3.0"
application
jacoco
}
@@ -26,6 +27,20 @@ dependencies {
implementation("org.jetbrains.kotlin:kotlin-scripting-jvm:2.4.0")
implementation("org.jetbrains.kotlin:kotlin-scripting-jvm-host:2.4.0")
testImplementation(kotlin("test"))
+ // One reference for Tazel, its plugin API and its Gradle plugin.
+ dokka(project(":tazel-api"))
+ dokka(project(":tazel-gradle-plugin"))
+}
+
+// The reference of Tazel with its API and Gradle plugin. Every warning fails it; the modules of
+// the API and the Gradle plugin also fail on an undocumented public declaration, the CLI not yet.
+dokka {
+ moduleName = "Tazel"
+ dokkaPublications.html { failOnWarning = true }
+ dokkaSourceSets.configureEach {
+ reportUndocumented = false
+ jdkVersion = 25
+ }
}
kotlin {
diff --git a/gradle-plugin/build.gradle.kts b/gradle-plugin/build.gradle.kts
index 9de8c5b..48c1aba 100644
--- a/gradle-plugin/build.gradle.kts
+++ b/gradle-plugin/build.gradle.kts
@@ -13,6 +13,16 @@ plugins {
kotlin("jvm")
`java-gradle-plugin`
id("com.gradle.plugin-publish") version "2.0.0"
+ id("org.jetbrains.dokka")
+}
+
+// The API reference. Every warning fails it, an undocumented public declaration included.
+dokka {
+ dokkaPublications.html { failOnWarning = true }
+ dokkaSourceSets.configureEach {
+ reportUndocumented = true
+ jdkVersion = 25
+ }
}
group = "com.progmasoft.tazel"
diff --git a/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginDescriptorTask.kt b/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginDescriptorTask.kt
index da24708..b1c4305 100644
--- a/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginDescriptorTask.kt
+++ b/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginDescriptorTask.kt
@@ -26,31 +26,44 @@ import org.gradle.api.tasks.TaskAction
@CacheableTask
abstract class TazelPluginDescriptorTask : DefaultTask() {
// A required field is optional to Gradle, so the task reports it as a tazelPlugin setting.
+ /** [TazelPluginExtension.group]; required. */
@get:Input @get:Optional abstract val pluginGroup: Property<String>
+ /** [TazelPluginExtension.name]; required. */
@get:Input @get:Optional abstract val pluginName: Property<String>
+ /** [TazelPluginExtension.version]; required. */
@get:Input @get:Optional abstract val pluginVersion: Property<String>
+ /** [TazelPluginExtension.pluginClass]; required. */
@get:Input @get:Optional abstract val pluginClass: Property<String>
+ /** [TazelPluginExtension.imports]. */
@get:Input abstract val imports: ListProperty<String>
// `description` is a property of every task already.
+ /** [TazelPluginExtension.description]. */
@get:Input @get:Optional abstract val description_: Property<String>
+ /** [TazelPluginExtension.authors]. */
@get:Input abstract val authors: ListProperty<String>
+ /** [TazelPluginExtension.license]. */
@get:Input @get:Optional abstract val license: Property<String>
+ /** [TazelPluginExtension.homepage]. */
@get:Input @get:Optional abstract val homepage: Property<String>
+ /** [TazelPluginExtension.repository]. */
@get:Input @get:Optional abstract val repository: Property<String>
+ /** The version of the plugin API the plugin is built for. */
@get:Input abstract val apiVersion: Property<Int>
+ /** The directory the task writes `META-INF/` into, added to the resources of the JAR. */
@get:OutputDirectory abstract val outputDirectory: DirectoryProperty
+ /** Checks the settings and writes the descriptor and the service entry. */
@TaskAction
fun write() {
val group = required(pluginGroup, "group")
diff --git a/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginPlugin.kt b/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginPlugin.kt
index 274bf8d..93bf6bf 100644
--- a/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginPlugin.kt
+++ b/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginPlugin.kt
@@ -23,6 +23,7 @@ import org.gradle.api.provider.Property
* `tazelApi()` takes the API of that version.
*/
class TazelPluginPlugin : Plugin<Project> {
+ /** Adds the repository, `tazelApi()`, `tazelPlugin { }` and the descriptor task to [project]. */
override fun apply(project: Project) {
project.pluginManager.apply("java-library")
project.repositories.maven { repository ->
@@ -57,8 +58,12 @@ class TazelPluginPlugin : Plugin<Project> {
}
}
+ /** The repository, group, API version and version this Gradle plugin uses. */
companion object {
+ /** The Maven repository of the Tazel API. */
const val REPOSITORY = "https://maven.progmasoft.com/tazel"
+
+ /** The group of the Tazel API, the only group taken from [REPOSITORY]. */
const val GROUP = "com.progmasoft.tazel"
/** The plugin API of the Tazel this Gradle plugin belongs to. */
@@ -100,13 +105,19 @@ abstract class TazelPluginExtension {
/** Packages or classes the project file imports by default, such as `com.example.cmake.*`. */
abstract val imports: ListProperty<String>
+ /** One sentence about the plugin, shown on Tazel Portal. */
abstract val description: Property<String>
+
+ /** The authors of the plugin, such as `Ada Lovelace <[email protected]>`. */
abstract val authors: ListProperty<String>
/** An SPDX license expression, such as `MIT`. */
abstract val license: Property<String>
+ /** The web page of the plugin. */
abstract val homepage: Property<String>
+
+ /** The source repository of the plugin. */
abstract val repository: Property<String>
}
@@ -115,6 +126,7 @@ abstract class TazelPluginExtension {
* its tests use. It is not bundled; Tazel provides it at run time.
*/
abstract class TazelApiDependency @Inject constructor(private val project: Project) {
+ /** Adds the API to `compileOnly` and `testImplementation`. */
operator fun invoke() {
val coordinate = "${TazelPluginPlugin.GROUP}:tazel-api:${TazelPluginPlugin.VERSION}"
project.dependencies.add("compileOnly", coordinate)
diff --git a/sources/main/kotlin/com/progmasoft/tazel/driver/CcToolchain.kt b/sources/main/kotlin/com/progmasoft/tazel/driver/CcToolchain.kt
index 5b20912..e1f148e 100644
--- a/sources/main/kotlin/com/progmasoft/tazel/driver/CcToolchain.kt
+++ b/sources/main/kotlin/com/progmasoft/tazel/driver/CcToolchain.kt
@@ -109,7 +109,7 @@ fun zigTriple(triple: TargetTriple): String {
private val VENDORS = setOf("unknown", "pc", "apple", "w64", "none", "suse", "redhat")
-/** The file names a triple gives the outputs of a target named [name]. */
+/** The file names a triple gives the outputs of a target, from the name of the target. */
object OutputNames {
fun executable(name: String, os: Os) = if (os == Os.WINDOWS) "$name.exe" else name
diff --git a/sources/main/kotlin/com/progmasoft/tazel/driver/SourceTools.kt b/sources/main/kotlin/com/progmasoft/tazel/driver/SourceTools.kt
index 81724cc..1a1ce3d 100644
--- a/sources/main/kotlin/com/progmasoft/tazel/driver/SourceTools.kt
+++ b/sources/main/kotlin/com/progmasoft/tazel/driver/SourceTools.kt
@@ -197,7 +197,7 @@ private fun json(text: String): String {
}
/**
- * Runs clang-tidy on translation units, with the compilation database in [database], [jobs] at a
+ * Runs clang-tidy on translation units, with the compilation database [lint] is given, [jobs] at a
* time.
*/
class Linter(