Lezione 1. Preparazione dell’ambiente di sviluppo

📘 Corso di formazione: Creazione di addon per FreeCAD

Obiettivo della lezione: configurare tutto il necessario per creare, testare ed eseguire il debug di addon senza sforzo.

---

🔧 Passo 1. Assicurati di avere FreeCAD installato

Requisiti:

• FreeCAD versione 0.20 o successiva (meglio 1.0+)
• Funziona su Windows, Linux o macOS

👉 Se non hai ancora FreeCAD, scaricalo dal sito ufficiale:
🔗 https://www.freecad.org/downloads.php

Scegli:

• Windows: .exe (installazione) o .7z (portable)
• Linux: AppImage o pacchetto dal repository
• macOS: .dmg

💡 Consiglio: per l’apprendimento è meglio usare la versione installata (tramite l’installer), poiché è più stabile e più facile da configurare.

---

📁 Passo 2. Trova la cartella degli addon

FreeCAD cerca gli addon personalizzati in una cartella speciale Mod.
Il percorso dipende dal tuo sistema operativo e dal tipo di installazione.

✅ Come trovare la cartella esattamente?

1. Avvia FreeCAD.
2. Apri la Console Python:
   Visualizza → Pannelli → Console Python
3. Inserisci il comando:

import FreeCAD
print(FreeCAD.getUserAppDataDir())

4. Premi Invio.

Vedrai un percorso, ad esempio:

• Windows (versione installata):
  C:\Users\IlTuoNome\AppData\Roaming\FreeCAD\
• Windows (portable):
  D:\FreeCAD\data\
• Linux:
  /home/il_tuo_nome/.local/share/FreeCAD/
• macOS:
  /Users/il_tuo_nome/Library/Application Support/FreeCAD/

➕ Crea la cartella Mod

All’interno di questa directory deve esserci una cartella Mod.
Se non c’è, creala manualmente.

Esempio per Windows:

C:\Users\IlTuoNome\AppData\Roaming\FreeCAD\Mod\

💡 Un modo rapido per aprire la cartella su Windows:
Premi Win + R → digita %APPDATA%\FreeCAD → Invio

---

🖥 Passo 3. Configura un editor di testo (opzionale, ma altamente raccomandato)

Anche se puoi scrivere codice nel Blocco Note, è più comodo usare un editor con:

• Evidenziazione della sintassi Python
• Completamento automatico
• Possibilità di eseguire script

🔹 Consigliamo: Visual Studio Code (VS Code)

1. Scarica e installa: https://code.visualstudio.com/
2. Installa l’estensione Python (di Microsoft)
3. (Opzionale) Installa l’estensione FreeCAD for VS Code — aggiunge suggerimenti per l’API di FreeCAD

🔹 Come aprire la cartella dell’addon in VS Code?

1. Avvia VS Code
2. File → Apri cartella
3. Seleziona la cartella Mod (o un singolo addon al suo interno)

Ora puoi vedere la struttura del progetto e modificare i file comodamente.

---

🛠 Passo 4. Esplora gli strumenti integrati di FreeCAD

FreeCAD contiene già tutto il necessario per lo sviluppo.

1. Console Python

• Menu: Visualizza → Pannelli → Console Python
• Permette di eseguire comandi in tempo reale
• Esempio: digita App.newDocument() → verrà creato un nuovo documento

2. Vista Report

• Menu: Visualizza → Pannelli → Vista Report
• Mostra errori, avvisi, log
• Tienila sempre aperta durante il test dell’addon!

3. Registratore di Macro

• Menu: Macro → Macro...
• Pulsante Registra — registra le tue azioni in codice Python
• Ottimo modo per imparare l’API di FreeCAD

💡 Prova:

1. Clicca su Macro → Avvia registrazione
2. Crea una scatola (Parte → Scatola)
3. Ferma la registrazione
4. Apri la macro — vedrai il codice reale per la creazione dell’oggetto!

---

🧪 Passo 5. Verifica: crea una cartella di test

Per assicurarti che tutto funzioni:

1. Nella cartella Mod crea una sottocartella:

   TestAddon

2. Al suo interno crea un file __init__.py (può essere vuoto) — questo dice a Python che la cartella è un modulo.
3. Riavvia FreeCAD.
4. Apri la Vista Report.

Se non vedi errori — significa che FreeCAD sta scansionando correttamente la cartella Mod.

❗ Se appare un errore del tipo ImportError — controlla:

• La correttezza del nome della cartella (senza spazi e caratteri cirillici)
• La presenza di __init__.py (nelle nuove versioni non è sempre obbligatorio, ma è più sicuro aggiungerlo)

---

🗂 Struttura della cartella dello sviluppatore (risultato)

Alla fine di questa lezione dovresti avere una struttura simile:

(cartella FreeCAD dell'utente)
└── Mod/
    └── TestAddon/
        └── __init__.py   ← può essere vuoto

E sai:

• Dove si trova Mod
• Come aprire la Console Python e la Vista Report
• Come usare il Registratore di Macro
• Come configurare VS Code (opzionale)

---

✅ Esercizio pratico

1. Trova la cartella Mod tramite FreeCAD.getUserAppDataDir()
2. Crea una cartella MyFirstAddon all’interno di Mod
3. Aggiungi un file vuoto __init__.py al suo interno
4. Riavvia FreeCAD
5. Assicurati che non ci siano errori nella Vista Report

🎯 Obiettivo: FreeCAD dovrebbe avviarsi senza errori e “vedere” la tua cartella.

---

▶️ Cosa succede dopo?

Nella Lezione 2 creeremo un vero addon funzionante:

• Aggiungeremo un pulsante
• Faremo in modo che faccia qualcosa
• Impareremo a registrare comandi e ambienti di lavoro

“`