Lektion 7. Addon veröffentlichen: vom Ordner zu GitHub und Addon Manager

📘 Tutorial: FreeCAD Addons erstellen

Ziel der Lektion: Das Addon für die Verteilung vorbereiten, Metadaten erstellen und es auf GitHub veröffentlichen, damit jeder FreeCAD-Benutzer es mit einem Klick installieren kann.

📦 Teil 1. Was ist der Addon Manager?

Der Addon Manager ist ein integriertes FreeCAD-Tool (Extras → Addon Manager), das:

Einen Katalog von über 300 offiziellen Addons anzeigt
Es ermöglicht, Addons zu installieren, zu aktualisieren und zu deinstallieren, ohne Dateien manuell kopieren zu müssen
Mit GitHub-Repositories arbeitet

Damit Ihr Addon dort erscheint, müssen Sie:

Es auf GitHub hochladen
Eine Datei package.xml hinzufügen
(Optional) Einen PR an FreeCAD-addons senden

🗂 Teil 2. Vorbereitung der Repository-Struktur

Ihr Ordner sollte so aussehen:

BoxBuilderAddon/                ← Repository-Wurzel
├── Resources/
│   └── icons/
│       ├── box_builder.svg
│       └── create_box.svg
├── InitGui.py
├── box_builder_workbench.py
├── package.xml                 ← OBLIGATORISCH!
├── README.md                   ← empfohlen
└── LICENSE                     ← obligatorisch für die Veröffentlichung

💡 Wichtig: Der Name des Stammordners muss mit dem Namen des Addons übereinstimmen und derselbe sein wie in InitGui.py.

📄 Teil 3. Erstellen von `package.xml`

Diese Datei beschreibt Ihr Addon für den Addon Manager.

Erstellen Sie die Datei package.xml im Stammverzeichnis:

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

🔍 Obligatorische Felder:

<name> – muss mit dem Ordner übereinstimmen
<version> – im Format X.Y.Z
<license> – gibt die LICENSE-Datei und den Lizenztyp an
<url type="repository"> – Link zu Ihrem GitHub
<icon> – Pfad zum Icon (relativ zum Stammverzeichnis)
<content><workbench>...</workbench></content> – gibt an, dass es sich um eine Arbeitsumgebung handelt

💡 Eine Lizenz ist obligatorisch. LGPL-2.1-or-later (wie bei FreeCAD selbst) wird empfohlen.

📄 Teil 4. Die Datei `LICENSE`

Erstellen Sie eine LICENSE-Datei mit dem Lizenztext.

Beispiel für LGPL-2.1:

Gehen Sie zu: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt
Kopieren Sie den gesamten Text
Fügen Sie ihn in die Datei LICENSE ein

Oder verwenden Sie GitHub: Beim Erstellen eines Repositorys können Sie die Lizenz automatisch auswählen.

📝 Teil 5. Die Datei `README.md`

Erstellen Sie eine einfache README.md:

# Box Builder Addon für FreeCAD

Ein einfaches Werkzeug zum Erstellen parametrischer Boxen mit benutzerdefinierten Abmessungen.

## Funktionen
- GUI-Dialog zur Eingabe von Länge, Breite, Höhe
- Speichert die zuletzt verwendeten Werte zwischen den Sitzungen
- Eindeutige Objektbenennung
- Optionale Zentrierung am Ursprung

## Installation
1. FreeCAD öffnen
2. Gehen Sie zu **Extras → Addon Manager**
3. Suchen Sie nach "BoxBuilderAddon"
4. Klicken Sie auf **Installieren**

Oder installieren Sie manuell, indem Sie den Ordner in Ihr `Mod`-Verzeichnis kopieren.

## Anforderungen
- FreeCAD 0.20 oder neuer

🌐 Teil 6. Veröffentlichung auf GitHub

Schritte:

Registrieren Sie sich auf GitHub
Klicken Sie auf New repository
Name: BoxBuilderAddon
Initialisieren Sie ohne README (Sie haben es bereits erstellt)
Klicken Sie auf Create repository
Befolgen Sie die Anweisungen zum Hochladen des lokalen Ordners:

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

💡 Ersetzen Sie yourname durch Ihren GitHub-Benutzernamen.

🔍 Teil 7. Installation testen

Jetzt kann jeder Benutzer:

FreeCAD öffnen
Zu Extras → Addon Manager gehen
Auf Nach Updates suchen klicken
BoxBuilderAddon finden und auf Installieren klicken

⚠️ Damit das Addon in der offiziellen Liste erscheint, müssen Sie einen Pull Request senden an:
🔗 https://github.com/FreeCAD/FreeCAD-addons

Aber auch ohne dies können Benutzer es über einen direkten Link installieren:

Im Addon Manager: Extras → Addon Manager → … → Benutzerdefiniertes Addon installieren
URL einfügen: https://github.com/yourname/BoxBuilderAddon

🧪 Praktische Aufgabe

Erstellen Sie ein GitHub-Konto (falls noch nicht vorhanden)
Bereiten Sie die vollständige Addon-Struktur mit package.xml, LICENSE, README.md vor
Laden Sie das Repository auf GitHub hoch
Installieren Sie Ihr Addon über den Addon Manager in einer sauberen FreeCAD-Kopie (oder löschen Sie den Ordner aus Mod vor der Installation)

✅ Ergebnis

Jetzt können Sie:

Vollwertige Addons mit GUI und Einstellungen erstellen
Icons hinzufügen
Metadaten vorbereiten
Auf GitHub veröffentlichen
Das Addon der ganzen Welt zugänglich machen

🎓 Was kommt als Nächstes?

Sie haben den gesamten Kurs abgeschlossen! 🎉
Jetzt sind Sie ein FreeCAD Addon-Entwickler.

Mögliche nächste Schritte:

Fügen Sie Unterstützung für die Zentrierung hinzu (aus Aufgabe Lektion 5)
Implementieren Sie die Mehrfacheingabe (Erstellen eines Rasters von Boxen)
Integrieren Sie mit PartDesign zur Erstellung von Rotationskörpern
Schreiben Sie ein Addon für Ihre eigene Aufgabe: Schrauben, Rahmen, Berechnungen usw.

💬 Fazit

FreeCAD ist nicht nur ein CAD-Programm.
Es ist eine Plattform für Ingenieurkreativität, und Sie haben jetzt den Schlüssel zu ihrer Erweiterung.

Schreiben Sie Addons. Teilen Sie sie. Verändern Sie die Welt – ein parametrisches Objekt nach dem anderen. 🛠️