Lezione 7. Pubblicare un addon: dalla cartella a GitHub e all’Addon Manager

📘 Corso di formazione: Creare addon per FreeCAD

Obiettivo della lezione: preparare l’addon per la distribuzione, creare i metadati e pubblicarlo su GitHub, in modo che qualsiasi utente di FreeCAD possa installarlo con un solo clic.

---

📦 Parte 1. Cos’è l’Addon Manager?

L’Addon Manager è uno strumento integrato in FreeCAD (Strumenti → Addon Manager) che:

• Mostra un catalogo di oltre 300 addon ufficiali
• Permette di installare, aggiornare e disinstallare gli addon senza copiare manualmente i file
• Funziona con i repository su GitHub

Affinché il tuo addon appaia lì, devi:

1. Caricarlo su GitHub
2. Aggiungere il file package.xml
3. (Opzionale) Inviare una Pull Request a FreeCAD-addons

---

🗂 Parte 2. Preparazione della struttura del repository

La tua cartella dovrebbe apparire così:

BoxBuilderAddon/                ← radice del repository
├── Resources/
│   └── icons/
│       ├── box_builder.svg
│       └── create_box.svg
├── InitGui.py
├── box_builder_workbench.py
├── package.xml                 ← OBBLIGATORIO!
├── README.md                   ← raccomandato
└── LICENSE                     ← obbligatorio per la pubblicazione

💡 Importante: il nome della cartella radice deve corrispondere al nome dell’addon ed essere lo stesso di InitGui.py.

---

📄 Parte 3. Creazione di package.xml

Questo file descrive il tuo addon per l’Addon Manager.

Crea il file package.xml nella radice:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">
  <name>BoxBuilderAddon</name>
  <description>
    A simple tool to create parametric boxes with custom dimensions and GUI.
    Saves last used values between sessions.
  </description>
  <version>1.0.0</version>
  <date>2025-04-05</date>

  <maintainer email="your.email@example.com">Your Name</maintainer>

  <license file="LICENSE">LGPL-2.1-or-later</license>

  <url type="repository" branch="main">https://github.com/yourname/BoxBuilderAddon</url>
  <url type="bugtracker">https://github.com/yourname/BoxBuilderAddon/issues</url>

  <icon>Resources/icons/box_builder.svg</icon>

  <content>
    <workbench>BoxBuilderAddon</workbench>
  </content>

  <dependencies>
    <freecad>0.20</freecad>
  </dependencies>
</package>

🔍 Campi obbligatori:

• <name> — deve corrispondere alla cartella
• <version> — nel formato X.Y.Z
• <license> — indica il file LICENSE e il tipo di licenza
• <url type="repository"> — link al tuo GitHub
• <icon> — percorso dell’icona (relativo alla radice)
• <content><workbench>...</workbench></content> — indica che si tratta di un ambiente di lavoro

💡 La licenza è obbligatoria. Si raccomanda LGPL-2.1-or-later (come FreeCAD stesso).

---

📄 Parte 4. File LICENSE

Crea il file LICENSE con il testo della licenza.

Esempio per LGPL-2.1:

1. Vai su: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt
2. Copia tutto il testo
3. Incollalo nel file LICENSE

Oppure usa GitHub: quando crei un repository, puoi scegliere automaticamente una licenza.

---

📝 Parte 5. File README.md

Crea un semplice README.md:

# Box Builder Addon per FreeCAD

Uno strumento semplice per creare scatole parametriche con dimensioni personalizzate.

## Caratteristiche
- Finestra di dialogo GUI per inserire lunghezza, larghezza, altezza
- Salva gli ultimi valori utilizzati tra le sessioni
- Nomi degli oggetti unici
- Centratura opzionale sull'origine

## Installazione
1. Apri FreeCAD
2. Vai su **Strumenti → Addon Manager**
3. Cerca "BoxBuilderAddon"
4. Clicca su **Installa**

Oppure installa manualmente copiando la cartella nella tua directory `Mod`.

## Requisiti
- FreeCAD 0.20 o più recente

---

🌐 Parte 6. Pubblicazione su GitHub

Passaggi:

1. Registrati su GitHub
2. Clicca su New repository
3. Nome: BoxBuilderAddon
4. Inizializza senza README (lo hai già creato)
5. Clicca su Create repository
6. Segui le istruzioni per caricare la cartella locale:

git init
git add .
git commit -m "Initial release"
git branch -M main
git remote add origin https://github.com/yourname/BoxBuilderAddon.git
git push -u origin main

💡 Sostituisci yourname con il tuo login GitHub.

---

🔍 Parte 7. Test dell’installazione

Ora qualsiasi utente può:

1. Aprire FreeCAD
2. Andare su Strumenti → Addon Manager
3. Cliccare su Verifica aggiornamenti
4. Trovare BoxBuilderAddon e cliccare su Installa

⚠️ Affinché l’addon appaia nell’elenco ufficiale, è necessario inviare una Pull Request a:
🔗 https://github.com/FreeCAD/FreeCAD-addons

Ma anche senza questo, gli utenti possono installarlo tramite un link diretto:

• Nell’Addon Manager: Strumenti → Addon Manager → … → Installa addon personalizzato
• Incollare l’URL: https://github.com/yourname/BoxBuilderAddon

---

🧪 Esercizio pratico

1. Crea un account GitHub (se non ne hai uno)
2. Prepara la struttura completa dell’addon con package.xml, LICENSE, README.md
3. Carica il repository su GitHub
4. Installa il tuo addon tramite l’Addon Manager su una copia pulita di FreeCAD (o elimina la cartella da Mod prima dell’installazione)

---

✅ Risultato

Ora sai:

• Creare addon completi con GUI e impostazioni
• Aggiungere icone
• Preparare i metadati
• Pubblicare su GitHub
• Rendere l’addon disponibile a tutto il mondo

---

🎓 E adesso?

Hai completato l’intero corso! 🎉
Ora sei uno sviluppatore di addon per FreeCAD.

Possibili passi successivi:

• Aggiungi il supporto per la centratura (dall’esercizio della Lezione 5)
• Implementa l’input multiplo (creazione di una griglia di scatole)
• Integra con PartDesign per creare corpi di rivoluzione
• Scrivi un addon per il tuo compito specifico: bulloni, telai, calcoli, ecc.

---

💬 Conclusione

FreeCAD non è solo un programma CAD.
È una piattaforma per la creatività ingegneristica, e ora possiedi la chiave per espanderla.

Scrivi addon. Condividili. Cambia il mondo — un oggetto parametrico alla volta. 🛠️

---

Se hai un’idea per un addon reale — descrivila, e ti aiuterò a realizzarla!