Leçon 7. Publier un addon : du dossier à GitHub et au gestionnaire d’addons

📘 Tutoriel : Créer des addons pour FreeCAD

Objectif de la leçon : préparer l’addon à la distribution, créer des métadonnées et le publier sur GitHub, afin que tout utilisateur de FreeCAD puisse l’installer en un seul clic.

---

📦 Partie 1. Qu’est-ce que le gestionnaire d’addons ?

Le gestionnaire d’addons est un outil intégré à FreeCAD (Outils → Gestionnaire d'addons) qui :

• Affiche un catalogue de plus de 300 addons officiels
• Permet d’installer, mettre à jour et désinstaller des addons sans copier manuellement les fichiers
• Fonctionne avec les dépôts GitHub

Pour que votre addon y apparaisse, vous devez :

1. Le télécharger sur GitHub
2. Ajouter un fichier package.xml
3. (Optionnel) Soumettre une PR à FreeCAD-addons

---

🗂 Partie 2. Préparer la structure du dépôt

Votre dossier doit ressembler à ceci :

BoxBuilderAddon/                ← racine du dépôt
├── Resources/
│   └── icons/
│       ├── box_builder.svg
│       └── create_box.svg
├── InitGui.py
├── box_builder_workbench.py
├── package.xml                 ← OBLIGATOIRE !
├── README.md                   ← recommandé
└── LICENSE                     ← obligatoire pour la publication

💡 Important : le nom du dossier racine doit correspondre au nom de l’addon et être le même que dans InitGui.py.

---

📄 Partie 3. Créer package.xml

Ce fichier décrit votre addon pour le gestionnaire d’addons.

Créez un fichier package.xml à la racine :

<?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>

🔍 Champs obligatoires :

• <name> — doit correspondre au dossier
• <version> — au format X.Y.Z
• <license> — indiquez le fichier LICENSE et le type de licence
• <url type="repository"> — lien vers votre GitHub
• <icon> — chemin vers l’icône (relatif à la racine)
• <content><workbench>...</workbench></content> — indique qu’il s’agit d’un atelier

💡 La licence est obligatoire. LGPL-2.1-or-later est recommandée (comme FreeCAD lui-même).

---

📄 Partie 4. Fichier LICENSE

Créez un fichier LICENSE avec le texte de la licence.

Exemple pour LGPL-2.1 :

1. Allez sur : https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt
2. Copiez tout le texte
3. Collez-le dans le fichier LICENSE

Ou utilisez GitHub : lors de la création d’un dépôt, vous pouvez choisir la licence automatiquement.

---

📝 Partie 5. Fichier README.md

Créez un simple README.md :

# Box Builder Addon for FreeCAD

A simple tool to create parametric boxes with custom dimensions.

## Features
- GUI dialog for entering length, width, height
- Saves last used values between sessions
- Unique object naming
- Optional centering on origin

## Installation
1. Open FreeCAD
2. Go to **Tools → Addon Manager**
3. Search for "BoxBuilderAddon"
4. Click **Install**

Or install manually by copying the folder to your `Mod` directory.

## Requirements
- FreeCAD 0.20 or newer

---

🌐 Partie 6. Publication sur GitHub

Étapes :

1. Inscrivez-vous sur GitHub
2. Cliquez sur New repository
3. Nom : BoxBuilderAddon
4. Initialiser sans README (vous l’avez déjà créé)
5. Cliquez sur Create repository
6. Suivez les instructions pour télécharger le dossier local :

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

💡 Remplacez yourname par votre nom d’utilisateur GitHub.

---

🔍 Partie 7. Tester l’installation

Maintenant, tout utilisateur peut :

1. Ouvrir FreeCAD
2. Aller dans Outils → Gestionnaire d’addons
3. Cliquer sur Vérifier les mises à jour
4. Trouver BoxBuilderAddon et cliquer sur Installer

⚠️ Pour que l’addon apparaisse dans la liste officielle, vous devez envoyer une Pull Request à :
🔗 https://github.com/FreeCAD/FreeCAD-addons

Mais même sans cela, les utilisateurs peuvent l’installer via un lien direct :

• Dans le gestionnaire d’addons : Outils → Gestionnaire d’addons → … → Installer un addon personnalisé
• Coller l’URL : https://github.com/yourname/BoxBuilderAddon

---

🧪 Exercice pratique

1. Créez un compte GitHub (si vous n’en avez pas)
2. Préparez la structure complète de l’addon avec package.xml, LICENSE, README.md
3. Téléchargez le dépôt sur GitHub
4. Installez votre addon via le gestionnaire d’addons sur une copie propre de FreeCAD (ou supprimez le dossier de Mod avant l’installation)

---

✅ Résultat

Vous savez maintenant :

• Créer des addons complets avec GUI et paramètres
• Ajouter des icônes
• Préparer les métadonnées
• Publier sur GitHub
• Rendre l’addon accessible au monde entier

---

🎓 Et après ?

Vous avez terminé tout le cours ! 🎉
Vous êtes maintenant un développeur d’addons FreeCAD.

Prochaines étapes possibles :

• Ajoutez la prise en charge du centrage (de l’exercice de la leçon 5)
• Implémentez la saisie multiple (création d’une grille de boîtes)
• Intégrez avec PartDesign pour créer des corps de révolution
• Écrivez un addon pour votre propre tâche : boulons, cadres, calculs, etc.

---

💬 Conclusion

FreeCAD n’est pas seulement un programme de CAO.
C’est une plateforme de créativité en ingénierie, et vous détenez maintenant la clé de son extension.

Écrivez des addons. Partagez-les. Changez le monde — un objet paramétrique à la fois. 🛠️

---

Si vous avez une idée pour un véritable addon — décrivez-la, et je vous aiderai à la réaliser !