---
title: Plugin Gradle
order: 6.3
icon: phosphor-duotone:gear-six
tags: [guide, java, gradle, integration]
---

# Plugin Gradle

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 Gradle `io.boxlang.bxsites`
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.

> **Stato:** pre-1.0, non ancora pubblicato sul Gradle Plugin Portal -
> vedi
> [`gradle-plugin/`](https://github.com/ortus-boxlang/bx-sites/tree/development/gradle-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 dipendenza `plugins { }` a riga singola.

## Avvio rapido

```kotlin title="build.gradle.kts"
plugins {
    id("io.boxlang.bxsites") version "<version>"
}
```

```bash
./gradlew bxSitesNew    # crea docs/ + bxsites.yaml
./gradlew bxSitesBuild   # renderizza docs/**.md in site/
./gradlew bxSitesServe   # compila + serve localmente con live reload
```

Una configurazione predefinita non richiede altro - il plugin rileva
automaticamente la directory dei contenuti (`docs/`, altrimenti `src/` -
tranne in un progetto con il plugin Java applicato, dove `src/` è la
propria directory dei sorgenti Java e non viene mai usata come contenuto
di bx-sites) 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](../configuration.md) - il plugin non duplica mai quello
schema, si limita a gestire *come* e *quando* bx-sites viene eseguito dal
tuo build.

## Task

| Task | Cosa fa |
|---|---|
| `bxSitesNew` | Genera un nuovo progetto bx-sites. Non collegato ad alcun lifecycle - eseguilo una volta, esplicitamente. |
| `bxSitesBuild` | Renderizza il sito. Controllo reale di aggiornamento: viene rieseguito solo quando i contenuti, la configurazione o le versioni fissate cambiano davvero. |
| `bxSitesServe` | Compila e serve il sito localmente con live reload. Viene eseguito in foreground finché non viene interrotto. |
| `bxSitesClean` | Rimuove la directory `site/` generata. |
| `bxSitesSearchIndex` | Ricostruisce `site/search-index.json` senza un build completo del sito. |
| `bxSitesLint` | Esegue il lint dei sorgenti Markdown in docs/. Collegato a `check` di default (vedi `hookIntoCheck` più sotto). |
| `bxSitesDeploy` | Compila il sito e lo distribuisce alla destinazione configurata. |
| `bxSitesPublish` | Compila il sito e lo pubblica su bxSites Cloud. |
| `bxSitesPackage` | Compila il sito e lo comprime in `site.zip`. |
| `bxSitesStats` | Riporta il conteggio di pagine/parole e altre statistiche sul sito compilato. |
| `bxSitesDoctor` | Esegue la diagnostica di salute del progetto propria di bx-sites. |

`bxSitesBuild` non viene mai eseguito automaticamente come parte di
`assemble` a meno che non lo si attivi esplicitamente (vedi
`hookIntoAssemble` più sotto) - un build della documentazione è
un'attività distinta, spesso più lenta, rispetto alla compilazione del
codice vero e proprio.

## Configurazione

```kotlin title="build.gradle.kts"
bxSites {
    projectRoot.set(layout.projectDirectory)
    boxlangMiniserverVersion.set("1.18.0-snapshot")   // versione fissata del runtime BoxLang
    bxSitesVersion.set("1.0.0-snapshot")               // versione fissata di bx-sites
    boxlangHomeDir.set(layout.buildDirectory.dir("bxsites/boxlang-home"))
    hookIntoAssemble.set(false)                        // opzionale: esegue bxSitesBuild come parte di assemble
    hookIntoCheck.set(true)                            // collega bxSitesLint a `check` di default
}
```

Ogni proprietà ha un default sensato. 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.

## Cosa non è ancora stato costruito

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

Vedi la guida al [Plugin Maven](maven-plugin.md) per l'equivalente sul
lato Maven - 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

`bxSitesDocBoxDoc` genera un riferimento API BoxLang/CFML da
[DocBox](https://docbox.ortusbooks.com), 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](docbox.md); 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 Gradle, quindi
[`bxSites coldbox`](coldbox.md) resta una questione della CLI di bx-sites.