Leçon 1. Préparation de l’environnement de développement

📘 Cours : Création d’addons pour FreeCAD

Objectif de la leçon : configurer tout le nécessaire pour créer, tester et déboguer des addons sans effort superflu.

---

🔧 Étape 1. Assurez-vous que FreeCAD est installé

Exigences :

• FreeCAD version 0.20 ou plus récente (mieux 1.0+)
• Fonctionne sur Windows, Linux ou macOS

👉 Si vous n’avez pas encore FreeCAD, téléchargez-le depuis le site officiel :
🔗 https://www.freecad.org/downloads.php

Choisissez :

• Windows : .exe (installateur) ou .7z (portable)
• Linux : AppImage ou paquet depuis le dépôt
• macOS : .dmg

💡 Conseil : pour l’apprentissage, il est préférable d’utiliser la version installée (via l’installateur), car elle est plus stable et plus facile à configurer.

---

📁 Étape 2. Trouvez le dossier des addons

FreeCAD recherche les addons utilisateur dans un dossier spécial Mod.
Le chemin dépend de votre OS et du type d’installation.

✅ Comment trouver le dossier précisément ?

1. Lancez FreeCAD.
2. Ouvrez la Console Python :
   Affichage → Panneaux → Console Python
3. Entrez la commande :

import FreeCAD
print(FreeCAD.getUserAppDataDir())

4. Appuyez sur Entrée.

Vous verrez un chemin, par exemple :

• Windows (version installée) :
  C:\Users\VotreNom\AppData\Roaming\FreeCAD\
• Windows (portable) :
  D:\FreeCAD\data\
• Linux :
  /home/votre_nom/.local/share/FreeCAD/
• macOS :
  /Users/votre_nom/Library/Application Support/FreeCAD/

➕ Créez le dossier Mod

À l’intérieur de ce répertoire, il doit y avoir un dossier Mod.
S’il n’existe pas, créez-le manuellement.

Exemple pour Windows :

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

💡 Un moyen rapide d’ouvrir le dossier sous Windows :
Appuyez sur Win + R → tapez %APPDATA%\FreeCAD → Entrée

---

🖥 Étape 3. Configurez un éditeur de texte (facultatif, mais fortement recommandé)

Bien qu’il soit possible d’écrire du code dans le Bloc-notes, il est plus pratique d’utiliser un éditeur avec :

• Coloration syntaxique Python
• Autocomplétion
• Possibilité d’exécuter des scripts

🔹 Nous recommandons : Visual Studio Code (VS Code)

1. Téléchargez et installez : https://code.visualstudio.com/
2. Installez l’extension Python (de Microsoft)
3. (Facultatif) Installez l’extension FreeCAD for VS Code – elle ajoute des suggestions pour l’API FreeCAD

🔹 Comment ouvrir le dossier de l’addon dans VS Code ?

1. Lancez VS Code
2. Fichier → Ouvrir un dossier
3. Sélectionnez le dossier Mod (ou un addon individuel à l’intérieur)

Vous pouvez maintenant voir la structure du projet et éditer les fichiers confortablement.

---

🛠 Étape 4. Explorez les outils intégrés de FreeCAD

FreeCAD contient déjà tout ce dont vous avez besoin pour le développement.

1. Console Python

• Menu : Affichage → Panneaux → Console Python
• Permet d’exécuter des commandes en temps réel
• Exemple : tapez App.newDocument() → un nouveau document sera créé

2. Vue Rapport

• Menu : Affichage → Panneaux → Vue Rapport
• Affiche les erreurs, les avertissements, les journaux
• Gardez-la ouverte impérativement lors du test de l’addon !

3. Enregistreur de macros

• Menu : Macro → Macros...
• Bouton Enregistrer – enregistre vos actions en code Python
• Un excellent moyen d’apprendre l’API de FreeCAD

💡 Essayez :

1. Cliquez sur Macro → Démarrer l’enregistrement
2. Créez une boîte (Part → Boîte)
3. Arrêtez l’enregistrement
4. Ouvrez la macro – vous verrez le code réel de création de l’objet !

---

🧪 Étape 5. Vérification : créez un dossier de test

Pour vous assurer que tout fonctionne :

1. Dans le dossier Mod, créez un sous-dossier :

   TestAddon

2. À l’intérieur, créez un fichier __init__.py (il peut être vide) – cela indique à Python que le dossier est un module.
3. Redémarrez FreeCAD.
4. Ouvrez la Vue Rapport.

Si vous ne voyez pas d’erreurs, cela signifie que FreeCAD a scanné le dossier Mod avec succès.

❗ Si une erreur de type ImportError apparaît, vérifiez :

• La correction du nom du dossier (sans espaces ni caractères cyrilliques)
• La présence de __init__.py (pas toujours obligatoire dans les nouvelles versions, mais plus sûr à ajouter)

---

🗂 Structure du dossier de développement (résultat)

À la fin de cette leçon, vous devriez avoir cette structure :

(dossier utilisateur FreeCAD)
└── Mod/
    └── TestAddon/
        └── __init__.py   ← peut être vide

Et vous savez :

• Où se trouve Mod
• Comment ouvrir la Console Python et la Vue Rapport
• Comment utiliser l’Enregistreur de macros
• Comment configurer VS Code (facultatif)

---

✅ Exercice pratique

1. Trouvez le dossier Mod via FreeCAD.getUserAppDataDir()
2. Créez un dossier MyFirstAddon à l’intérieur de Mod
3. Ajoutez-y un fichier __init__.py vide
4. Redémarrez FreeCAD
5. Assurez-vous qu’il n’y a pas d’erreurs dans la Vue Rapport

🎯 Objectif : FreeCAD doit démarrer sans erreurs et « voir » votre dossier.

---

▶️ Et ensuite ?

Dans la Leçon 2, nous créerons un véritable addon fonctionnel :

• Nous ajouterons un bouton
• Nous ferons en sorte qu’il fasse quelque chose
• Nous apprendrons à enregistrer des commandes et des ateliers

« `