Plugin Maven

Plugin Maven

Gli sviluppatori Java e Spring Boot non hanno bisogno di CommandBox né di un'installazione di BoxLang a livello di sistema per aggiungere un sito bx-sites al proprio progetto - il plugin Maven io.boxlang:bxsites-maven-plugin scarica tutto ciò di cui ha bisogno (il runtime BoxLang e bx-sites stesso) in una cache locale la prima volta che viene eseguito. L'unico requisito è un JDK 21. È la controparte Maven del Plugin Gradle - entrambi racchiudono la stessa logica sottostante, quindi la copertura dei verbi e il comportamento restano identici tra i due build tool.

Stato: pre-1.0, non ancora pubblicato su Maven Central - vedi maven-plugin/ nel repository bx-sites per il codice sorgente e le istruzioni attuali di build/test. Questa pagina documenta cosa farà una volta pubblicato; i meccanismi descritti qui sotto sono già reali e verificati, solo non ancora disponibili come coordinata Maven Central.

Avvio rapido

<build>
  <plugins>
    <plugin>
      <groupId>io.boxlang</groupId>
      <artifactId>bxsites-maven-plugin</artifactId>
      <version>&lt;version&gt;</version>
    </plugin>
  </plugins>
</build>

mvn bxsites:new     # crea docs/ + bxsites.yaml
mvn bxsites:build   # renderizza docs/**.md in site/
mvn bxsites:serve   # compila + serve localmente con live reload

La forma breve bxsites:<goal> (confermata funzionante) richiede che il blocco <plugin> sopra sia dichiarato specificamente sotto <build><plugins>, non solo in <pluginManagement> - è questo che registra io.boxlang come prefisso di goal risolvibile per il progetto corrente. Senza quella dichiarazione, usa la forma completamente qualificata: mvn io.boxlang:bxsites-maven-plugin:build.

Una configurazione predefinita non richiede altro - il plugin rileva automaticamente la directory dei contenuti (docs/, altrimenti src/) e la directory di output (sempre <projectRoot>/site/). L'aspetto, il tema, la nav e qualsiasi altra impostazione del proprio sito sono controllati interamente da bxsites.yaml/.toml/.json nella root del progetto, esattamente come documentato in Configurazione - il plugin non duplica mai quello schema, si limita a gestire come e quando bx-sites viene eseguito dal tuo build.

Goal

Ogni goal si autoprovvisiona (scarica/cache) ciò di cui ha bisogno, alla prima esecuzione - a differenza del plugin Gradle, non esiste un goal di "provisioning" separato da eseguire prima.

Per default nessun goal è collegato a nessuna fase del lifecycle Maven - eseguili esplicitamente. Se vuoi che bxsites:build venga eseguito automaticamente, collegalo tu stesso in un blocco <executions>, ad esempio a pre-site (un abbinamento naturale con il lifecycle site integrato di Maven).

Configurazione

<plugin>
  <groupId>io.boxlang</groupId>
  <artifactId>bxsites-maven-plugin</artifactId>
  <configuration>
    <projectRoot>${project.basedir}</projectRoot>
    <boxlangMiniserverVersion>1.18.0-snapshot</boxlangMiniserverVersion>
    <bxSitesVersion>1.0.0-snapshot</bxSitesVersion>
    <boxlangHomeDir>${project.build.directory}/bxsites/boxlang-home</boxlangHomeDir>
  </configuration>
</plugin>

Ogni parametro ha un default sensato - un progetto nuovo non deve impostarne nessuno. La directory di output non è affatto configurabile qui - bx-sites stesso la fissa a <projectRoot>/site/, quindi il plugin la deriva invece di esporre un'impostazione che comunque non verrebbe rispettata.

Controllo di staleness del build

Maven non ha un motore di build incrementale integrato in stile Gradle, quindi bxsites:build implementa un proprio controllo leggero: confronta il timestamp (mtime) più recente sotto la directory dei contenuti (più il file di configurazione, se presente) con il timestamp più recente già presente in <projectRoot>/site/. Se nulla è più recente, il goal registra che sta saltando l'esecuzione e ritorna senza invocare affatto bx-sites. Forza comunque un rebuild con:

mvn bxsites:build -Dbxsites.build.forceRebuild=true

Cosa non è ancora stato costruito

• Generazione di documentazione per Spring Boot (OpenAPI, Javadoc, scansione dei controller) - pianificato.
• Lo streaming dell'output live di bxsites:serve - attualmente bufferizza l'output con un timeout di 30 minuti, entrambi sbagliati per un goal pensato per l'esecuzione indefinita.

Vedi la guida al Plugin Gradle per l'equivalente sul lato Gradle - entrambi i plugin racchiudono la stessa logica sottostante, quindi la copertura dei verbi e il comportamento restano identici tra i due build tool.

Generazione della documentazione BoxLang

bxsites:docbox genera un riferimento API BoxLang/CFML da DocBox, per un progetto JVM le cui sorgenti includano classi .bx/.cfc. A differenza dei generatori Spring Boot è un wrapper sottile attorno al verbo docbox e non un generatore interno alla JVM: l'implementazione vive sul lato BoxLang, e una sola implementazione guidata da entrambi gli strumenti non può divergere. Vengono passate solo le opzioni effettivamente impostate; il resto resta come dice bxsites.yaml. Vedi Riferimento API con DocBox; il modulo bx-docbox deve essere installato nel runtime BoxLang predisposto.

Non esiste un task ColdBox, di proposito. Un'applicazione ColdBox si costruisce e si esegue con CommandBox, mai con Maven, quindi bxSites coldbox resta una questione della CLI di bx-sites.