Gradle-Plugin

Gradle-Plugin

Java- und Spring-Boot-Entwickler brauchen weder CommandBox noch eine systemweite BoxLang-Installation, um dem eigenen Java-Projekt eine bx-sites-Website hinzuzufügen - das Gradle-Plugin io.boxlang.bxsites lädt beim ersten Lauf alles Nötige (die BoxLang-Laufzeitumgebung und bx-sites selbst) in einen lokalen Cache herunter. Die einzige Voraussetzung ist ein JDK 21.

Status: Vor Version 1.0, noch nicht im Gradle Plugin Portal veröffentlicht - siehe gradle-plugin/ im bx-sites-Repository für den Quellcode und die aktuellen Build-/Testanweisungen. Diese Seite beschreibt, was das Plugin nach der Veröffentlichung leistet; die unten beschriebene Funktionsweise ist bereits real und verifiziert, nur eben noch nicht als One-Line-plugins { }-Abhängigkeit verfügbar.

Schnellstart

plugins {
    id("io.boxlang.bxsites") version "<version>"
}

./gradlew bxSitesNew    # erzeugt docs/ + bxsites.yaml
./gradlew bxSitesBuild   # rendert docs/**.md nach site/
./gradlew bxSitesServe   # baut + serviert lokal mit Live-Reload

Ein Standard-Setup benötigt keine weitere Konfiguration - das Plugin erkennt das Content-Verzeichnis (docs/, sonst src/ - außer in einem Projekt mit angewendetem Java-Plugin, wo src/ das eigene Java-Quellverzeichnis ist und niemals als bx-sites-Content verwendet wird) und das Ausgabeverzeichnis (immer <projectRoot>/site/) automatisch. Aussehen, Theme, Navigation und jede andere Einstellung der eigenen Website werden komplett über bxsites.yaml/.toml/.json im Projektroot gesteuert, genau wie unter Konfiguration dokumentiert - das Plugin duplitziert dieses Schema nirgendwo, es regelt nur wie und wann bx-sites aus dem eigenen Build heraus läuft.

Tasks

bxSitesBuild läuft nie automatisch als Teil von assemble, außer man aktiviert das gezielt (siehe hookIntoAssemble unten) - ein Docs-Build ist ein eigenständiges, oft langsameres Anliegen als das Kompilieren des eigentlichen Codes.

Konfiguration

bxSites {
    projectRoot.set(layout.projectDirectory)
    boxlangMiniserverVersion.set("1.18.0-snapshot")   // gepinnte BoxLang-Laufzeitversion
    bxSitesVersion.set("1.0.0-snapshot")               // gepinnte bx-sites-Version
    boxlangHomeDir.set(layout.buildDirectory.dir("bxsites/boxlang-home"))
    hookIntoAssemble.set(false)                        // Opt-in: bxSitesBuild als Teil von assemble ausführen
    hookIntoCheck.set(true)                            // bindet bxSitesLint standardmäßig in `check` ein
}

Jede Eigenschaft hat einen sinnvollen Default. Das Ausgabeverzeichnis ist hier gar nicht einstellbar - bx-sites selbst legt es fest auf <projectRoot>/site/, daher leitet das Plugin es nur ab, statt eine Einstellung anzubieten, die ohnehin nicht beachtet würde.

Was noch nicht gebaut ist

• Spring-Boot-Doku-Generierung (OpenAPI, Javadoc, Controller-Scan) - geplant.
• Live-Output-Streaming von bxSitesServe - puffert derzeit die Ausgabe mit einem 30-Minuten-Timeout, beides falsch für einen Task, der unbegrenzt laufen soll.

Siehe den Guide zum Maven-Plugin für das Gegenstück auf der Maven-Seite - beide Plugins kapseln dieselbe zugrunde liegende Logik, sodass Verb-Abdeckung und Verhalten zwischen den beiden Build-Tools identisch bleiben.

BoxLang-Doku-Generierung

bxSitesDocBoxDoc erzeugt aus DocBox eine BoxLang-/CFML-API-Referenz - für ein JVM-Projekt, dessen Quellen auch .bx/.cfc-Klassen enthalten. Anders als die Spring-Boot-Generatoren ist das ein dünner Wrapper um den docbox-Verb statt eines eigenen Generators in der JVM: die Implementierung lebt auf der BoxLang-Seite, und eine Implementierung, die beide Build-Tools ansteuern, kann nicht auseinander driften. Nur tatsächlich gesetzte Optionen werden durchgereicht, alles andere bleibt bei dem, was bxsites.yaml sagt. Siehe DocBox-API-Referenz; das Modul bx-docbox muss in der bereitgestellten BoxLang-Laufzeit installiert sein.

Einen ColdBox-Task gibt es bewusst nicht. Eine ColdBox-Anwendung wird über CommandBox gebaut und betrieben, nie über Gradle, also bleibt bxSites coldbox Sache der bx-sites-CLI.