KiCad 10: il DRC da riga di comando regge davvero dentro una pipeline?

La prova l'ho fatta pensando ad una pipeline vera

Se avete già letto il mio articolo precedente su Python e kicad-cli saprete certamente che lì mi interessava soprattutto mostrare come KiCad 10 possa uscire dall'interfaccia grafica ed entrare in un flusso automatizzato, qui invece voglio fermarmi su una sola cosa ovvero il DRC (Design Rules Check), perché scrivere che "si può lanciare da terminale" è facile ma la domanda interessante arriva subito dopo: POSSO FIDARMI ABBASTANZA DA FAR FALLIRE UNA BUILD?

Per questa verifica ho preso come riferimento KiCad 10.0.6, release stabile pubblicata il 29 agosto 2026, e non una nightly o una build di sviluppo. Il comando che considero adatto ad una pipeline è questo:

BLOCCO0

La scelta degli switch non è casuale. --format json produce un risultato destinato alle macchine invece del normale report testuale, --severity-all include errori, warning ed esclusioni, --exit-code-violations rende il risultato utilizzabile direttamente da una shell, --refill-zones forza il ricalcolo delle zone prima del controllo ed --schematic-parity aggiunge il confronto fra PCB e schema. Senza queste opzioni il comando funziona lo stesso, ma il significato del suo PASS può essere diverso da quello che avevo in testa.

Il codice di uscita è la prima cosa da capire

La parte più utile per una pipeline è anche la più semplice: con --exit-code-violations KiCad restituisce 0 quando non trova violazioni e 5 quando ne trova almeno una. Questo significa che in Bash, GitLab CI, GitHub Actions, Jenkins oppure in un semplice hook Git non devo cercare una frase nello stdout per capire se il controllo è passato, posso lasciare che sia il codice di uscita del processo a decide. Se invece tolgo --exit-code-violations, il comando può terminare correttamente dal punto di vista dell'esecuzione pur avendo generato un report contenente violazioni, ed è proprio uno di quei dettagli che in un test manuale sembrano innocui e dentro una CI diventano pericolosi.

L'output sul terminale resta sintetico, mentre il contenuto interessante finisce nel file JSON. Un report conforme allo schema DRC v1 contiene campi come kicad_version, violations, unconnected_items, schematic_parity, coordinate_units, included_severities ed ignored_checks. La struttura reale è di questo tipo:

BLOCCO1

Il frammento riprende la struttura realmente prodotta da kicad-cli e documentata dallo schema ufficiale; la descrizione Silkscreen clipped by board edge compare anche in un report reale pubblicato nel bug tracker di KiCad, mentre qui ho ridotto apposta gli oggetti interni per non trasformare mezzo articolo in un dump JSON.

Pass oppure fail, ma decidendo prima cosa significhi davvero pass

Il punto è che io non farei dipendere una pipeline seria soltanto dal fatto che il processo restituisca 0 oppure 5, perché --severity-all può far comparire nel report anche warning ed esclusioni che non necessariamente voglio trattare tutti allo stesso modo. Preferisco usare il codice di uscita come primo semaforo e poi leggere il JSON con uno script piccolo, controllando almeno violations, unconnected_items e schematic_parity, quindi separando gli errori dai warning secondo la politica del progetto. In questo modo posso decidere che un errore blocchi sempre la build, che un warning venga registrato ma non la blocchi oppure, per un progetto destinato alla produzione, che anche un nuovo warning faccia fallire il job.

La parte bella è che non serve fare parsing fragile del testo destinato agli esseri umani. KiCad 10 espone un report JSON con uno schema dichiarato, quindi posso verificarne la versione, contare le violazioni, leggere la severity ed archiviare il file come artefatto della build. Se domani un tecnico mi domanda perché il commit di venerdì non ha prodotto i Gerber, non devo cercare nella cronologia della console ma posso aprire esattamente il report DRC generato da quella revisione.

Il primo risultato che mi ha sorpreso: il DRC CLI non rifà automaticamente tutto ciò che faccio nella GUI

Qui arriva la parte che secondo me vale più del comando stesso. Nel PCB Editor l'opzione per riempire nuovamente tutte le zone prima del DRC è ben visibile e la documentazione avverte che disattivarla può produrre risultati non corretti quando le zone non sono aggiornate, da riga di comando invece il refill va richiesto esplicitamente con --refill-zones. Mi ha sorpreso perché istintivamente avevo considerato il DRC CLI come la versione senza finestra dello stesso pulsante, mentre in una pipeline devo essere io a dichiarare anche questo comportamento.

La conseguenza pratica è semplice: se una modifica ha spostato una pista, una via oppure il contorno di una zona ma il file contiene ancora un riempimento precedente, lanciare il DRC senza refill può farmi confrontare una situazione diversa da quella che vedrei aprendo il progetto e rifacendo le zone prima del controllo. Per una CI io quindi considero --refill-zones praticamente obbligatorio, mentre eviterei --save-board a meno che non abbia un motivo preciso per voler modificare il file della scheda durante il job, perché una pipeline di verifica dovrebbe possibilmente LEGGERE IL PROGETTO E PRODURRE ARTEFATTI, non riscrivere silenziosamente i sorgenti.

Anche la parità con lo schema non arriva da sola

Il secondo punto da non perdere è --schematic-parity. Il DRC del PCB può controllare differenze fra schema e board, ma nella CLI questo controllo va richiesto, quindi un job che esegue soltanto kicad-cli pcb drc progetto.kicad_pcb non equivale necessariamente al controllo completo che io posso avere configurato nell'interfaccia. Nel report JSON esiste infatti una sezione schematic_parity separata dalle normali violazioni e dagli elementi non connessi, ed è proprio questa separazione che conviene sfruttare durante il parsing.

Questo è uno dei casi nei quali dire che il DRC "mente" sarebbe ingiusto, perché in realtà sta facendo esattamente quello che gli ho chiesto. Ma una pipeline può mentire A ME se io interpreto un controllo parziale come un controllo completo, ed è una distinzione importante: l'automazione non elimina le decisioni, le rende soltanto ripetibili, comprese quelle sbagliate.

Gli ignored checks sono un'altra zona nella quale il verde può ingannare

KiCad permette di impostare la severità di una determinata classe di violazioni su Ignore, ed in quel caso quel controllo viene sostanzialmente disattivato. Nelle versioni recenti il report JSON include anche ignored_checks, che trovo utilissimo proprio in CI perché un report con zero errori non dice molto se contemporaneamente metà dei controlli che mi interessano sono stati messi su Ignore. Per questo in un job destinato alla produzione non controllerei soltanto che violations sia vuoto, controllerei anche quali verifiche sono state ignorate e confronterei quel gruppo con una lista ammessa dal progetto.

Le esclusioni meritano un discorso simile. Una violazione esclusa può essere perfettamente legittima, per esempio perché un dettaglio geometrico è voluto e documentato, ma se eseguo il DRC con --severity-all voglio che quelle esclusioni restino visibili nel report. Il principio che seguirei è semplice: una cosa esclusa non deve bloccare la build soltanto perché esiste, ma deve essere VISIBILE, perché un'esclusione dimenticata per mesi può diventare molto più pericolosa di un warning nuovo.

Quanto tempo aggiunge davvero alla pipeline

Qui non voglio inventare un benchmark attribuendolo ad una mia scheda che non ho materialmente misurato in questa sessione. Su un PCB medio nell'ordine di un centinaio di componenti, senza geometrie particolarmente patologiche, un DRC completo su una workstation moderna è ragionevolmente un'operazione nell'ordine di pochi secondi, non di minuti, e KiCad 10.0.6 contiene inoltre interventi specifici per migliorare le prestazioni del DRC parallelizzando i provider, indicizzando spazialmente i courtyard ed ottimizzando le custom rules. Il dato esatto che conta sul mio progetto però va misurato con la board reale, ad esempio anteponendo time al comando, perché numero di footprint, complessità delle zone, regole personalizzate e geometria possono cambiare parecchio il risultato.

Preferisco scriverlo così piuttosto che mettere un elegante 1,7 s inventato. In una pipeline vera il tempo di riferimento lo misurerei sulla stessa macchina del runner e lo conserverei assieme alla versione di KiCad, perché se dopo una modifica alle regole il DRC passa da tre secondi a quaranta non è soltanto una curiosità statistica, può essere il segnale che abbiamo introdotto una regola molto costosa oppure una geometria che costringe il motore a fare molto più lavoro.

Parsing del report senza costruire un altro software

Un piccolo script Python è sufficiente. Apro build/drc.json, verifico che kicad_version sia quella prevista dalla pipeline, conto gli oggetti nelle sezioni che mi interessano e decido il risultato. In pratica arriviamo a separare due responsabilità: KiCad deve trovare e descrivere le violazioni, il mio script deve decidere QUALI DI QUELLE VIOLAZIONI BLOCCANO IL PROGETTO. È molto più robusto che cercare stringhe come Found 0 violations nell'output testuale ed evita che una variazione di wording oppure di lingua rompa il job.

Un controllo minimale può essere concettualmente questo:

BLOCCO2

Non serve renderlo più elegante del necessario. In un progetto reale aggiungerei il controllo della versione, una whitelist per warning ed esclusioni note e magari il confronto con il report della revisione precedente, così una pipeline potrebbe accettare il debito tecnico già noto ma bloccare QUALSIASI NUOVA VIOLAZIONE.

Dentro un hook Git oppure dentro la CI

Per un pre-commit hook locale userei il controllo soltanto su progetti relativamente piccoli, perché un hook che impiega troppo tempo viene inevitabilmente aggirato. In quel caso uno script shell può creare build, lanciare kicad-cli con le stesse opzioni della CI e terminare con il suo codice di uscita. Personalmente trovo però più affidabile il pre-push oppure, ancora meglio, il job sul server CI, perché lì posso bloccare realmente merge e produzione degli artefatti senza dipendere dalla configurazione della workstation del singolo sviluppatore.

L'ordine che userei è DRC, eventuale ERC, generazione Gerber e drill soltanto dopo il superamento dei controlli, quindi archiviazione del report JSON assieme agli artefatti. Il concetto è esattamente quello che avevo accennato nel mio precedente articolo su Python e CLI applicati a KiCad 10, ma qui diventa molto più concreto: il file Gerber non dovrebbe essere "quello che ho esportato ieri sera", dovrebbe essere QUELLO GENERATO AUTOMATICAMENTE DAL COMMIT CHE HA SUPERATO IL DRC.

Il verdetto dopo averlo guardato come strumento di automazione

Il DRC di KiCad 10.0.6 via kicad-cli è abbastanza maturo da stare dentro una pipeline reale e, anzi, il supporto JSON lo rende più comodo da integrare di parecchi strumenti nati quando CI/CD ed elettronica non si incontravano quasi mai. Ma non userei mai il comando più corto possibile per poi fidarmi del semaforo verde, perché refill delle zone, parità con lo schema, severity, esclusioni ed ignored checks fanno parte del significato del risultato e vanno dichiarati oppure controllati.

È questo il punto che mi ha convinto maggiormente ed allo stesso tempo mi ha fatto cambiare idea rispetto alla prima impressione: kicad-cli non è un pulsante DRC teletrasportato nel terminale, è un'interfaccia con la quale devo costruire IO il contratto della verifica. Una volta fatto, posso legare quella verifica ad un hook ed alla CI, conservare il report, bloccare gli artefatti sbagliati ed arrivare a produrre Gerber soltanto da una revisione verificata, USANDO IL DRC COME PARTE DEL PROCESSO E NON COME ULTIMO CLIC PRIMA DI MANDARE LA SCHEDA IN FABBRICA!