Plugin de Maven

Plugin de Maven

Los desarrolladores de Java y Spring Boot no necesitan CommandBox ni una instalación de BoxLang a nivel de sistema para añadir un sitio bx-sites a su propio proyecto - el plugin de Maven io.boxlang:bxsites-maven-plugin descarga todo lo que necesita (el runtime de BoxLang y bx-sites mismo) a una caché local la primera vez que se ejecuta. El único requisito previo es un JDK 21. Es el equivalente en Maven del Plugin de Gradle - ambos envuelven la misma lógica subyacente, así que la cobertura de verbos y el comportamiento se mantienen idénticos entre ambas herramientas de build.

Estado: pre-1.0, aún no publicado en Maven Central - ver maven-plugin/ en el repositorio de bx-sites para el código fuente y las instrucciones actuales de build/pruebas. Esta página documenta lo que hace una vez publicado; la mecánica descrita abajo ya es real y está verificada, solo que todavía no está disponible como coordenada de Maven Central.

Inicio rápido

<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   # renderiza docs/**.md en site/
mvn bxsites:serve   # compila + sirve localmente con recarga en vivo

La forma corta bxsites:<goal> (confirmada que funciona) requiere que el bloque <plugin> de arriba esté declarado concretamente bajo <build><plugins>, no solo en <pluginManagement> - eso es lo que registra io.boxlang como un prefijo de goal resoluble para el proyecto actual. Sin esa declaración, usa la forma totalmente cualificada: mvn io.boxlang:bxsites-maven-plugin:build.

Una configuración por defecto no necesita nada más - el plugin detecta automáticamente el directorio de contenido (docs/, o src/ si no existe) y el directorio de salida (siempre <projectRoot>/site/). El aspecto, tema, navegación y cualquier otro ajuste de tu sitio se controla por completo mediante bxsites.yaml/.toml/.json en la raíz del proyecto, exactamente como se documenta en Configuración - el plugin nunca duplica ese esquema, solo gestiona cómo y cuándo se ejecuta bx-sites desde tu build.

Goals

Cada goal se autoprovisiona (descarga/cachea) lo que necesita, en su primera ejecución - a diferencia del plugin de Gradle, no existe un goal de "provisión" separado que ejecutar antes.

Por defecto ningún goal está vinculado a ninguna fase del lifecycle de Maven - ejecútalos explícitamente. Si quieres que bxsites:build se ejecute automáticamente, vincúlalo tú mismo en un bloque <executions>, por ejemplo a pre-site (una combinación natural con el propio lifecycle site de Maven).

Configuración

<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>

Cada parámetro tiene un valor por defecto razonable - un proyecto nuevo no necesita fijar ninguno de ellos. El directorio de salida no es configurable aquí en absoluto - bx-sites mismo lo fija en <projectRoot>/site/, así que el plugin lo deriva en lugar de exponer un ajuste que de todos modos no se respetaría.

Comprobación de staleness del build

Maven no tiene un motor de build incremental integrado al estilo Gradle, así que bxsites:build implementa su propia comprobación ligera: compara la marca de tiempo (mtime) más reciente bajo el directorio de contenido (más el archivo de configuración, si existe) con la marca de tiempo más reciente ya presente en <projectRoot>/site/. Si nada es más reciente, el goal registra que se está omitiendo y retorna sin volver a invocar bx-sites en absoluto. Fuerza un rebuild de todas formas con:

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

Lo que aún no está construido

• Generación de documentación para Spring Boot (OpenAPI, Javadoc, escaneo de controladores) - planificado.
• El streaming de salida en vivo de bxsites:serve - actualmente almacena en búfer la salida con un timeout de 30 minutos, ambas cosas incorrectas para un goal pensado para ejecutarse indefinidamente.

Consulta la guía del Plugin de Gradle para el equivalente del lado de Gradle - ambos plugins envuelven la misma lógica subyacente, así que la cobertura de verbos y el comportamiento se mantienen idénticos entre ambas herramientas de build.

Generación de documentación BoxLang

bxsites:docbox genera una referencia de API BoxLang/CFML desde DocBox, para un proyecto JVM cuyas fuentes incluyan clases .bx/.cfc. A diferencia de los generadores de Spring Boot, es una envoltura fina sobre el verbo docbox en lugar de un generador dentro de la JVM: la implementación vive en el lado BoxLang, y una sola implementación que ambas herramientas invocan no puede divergir. Solo se pasan las opciones que realmente configuras; el resto sigue lo que diga bxsites.yaml. Consulta Referencia de API con DocBox; el módulo bx-docbox debe estar instalado en el runtime de BoxLang aprovisionado.

No hay tarea de ColdBox, deliberadamente. Una aplicación ColdBox se construye y se ejecuta con CommandBox, nunca con Maven, así que bxSites coldbox sigue siendo cosa de la CLI de bx-sites.