Lesson 7. Publishing an Addon: From Folder to GitHub and Addon Manager

Lesson Goal: Prepare the addon for distribution, create metadata, and publish it on GitHub so that any FreeCAD user can install it with a single click.

---

📦 Part 1. What is the Addon Manager?

The Addon Manager is a built-in FreeCAD tool (Tools → Addon Manager) that:

• Shows a catalog of 300+ official addons
• Allows you to install, update, and remove addons without manually copying files
• Works with GitHub repositories

For your addon to appear there, you need to:

1. Upload it to GitHub
2. Add a package.xml file
3. (Optional) Send a PR to FreeCAD-addons

---

🗂 Part 2. Preparing the Repository Structure

Your folder should look like this:

BoxBuilderAddon/                ← repository root
├── Resources/
│   └── icons/
│       ├── box_builder.svg
│       └── create_box.svg
├── InitGui.py
├── box_builder_workbench.py
├── package.xml                 ← REQUIRED!
├── README.md                   ← recommended
└── LICENSE                     ← required for publication

💡 Important: The name of the root folder must match the addon name and be the same as in InitGui.py.

---

📄 Part 3. Creating package.xml

This file describes your addon for the Addon Manager.

Create a package.xml file in the root:

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

🔍 Required fields:

• <name> — must match the folder name
• <version> — in X.Y.Z format
• <license> — specify the LICENSE file and license type
• <url type="repository"> — link to your GitHub
• <icon> — path to the icon (relative to the root)
• <content><workbench>...</workbench></content> — indicates that this is a workbench

💡 A license is mandatory. LGPL-2.1-or-later is recommended (like FreeCAD itself).

---

📄 Part 4. The LICENSE file

Create a LICENSE file with the license text.

Example for LGPL-2.1:

1. Go to: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt
2. Copy the entire text
3. Paste it into the LICENSE file

Or use GitHub: when creating a repository, you can choose a license automatically.

---

📝 Part 5. The README.md file

Create a 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

---

🌐 Part 6. Publishing to GitHub

Steps:

1. Register on GitHub
2. Click New repository
3. Name: BoxBuilderAddon
4. Initialize without README (you’ve already created it)
5. Click Create repository
6. Follow the instructions to upload your local folder:

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

💡 Replace yourname with your GitHub username.

---

🔍 Part 7. Testing the Installation

Now any user can:

1. Open FreeCAD
2. Go to Tools → Addon Manager
3. Click Check for updates
4. Find BoxBuilderAddon and click Install

⚠️ For the addon to appear in the official list, you need to submit a Pull Request to:
🔗 https://github.com/FreeCAD/FreeCAD-addons

But even without this, users can install it via a direct link:

• In Addon Manager: Tools → Addon Manager → … → Install custom addon
• Paste URL: https://github.com/yourname/BoxBuilderAddon

---

🧪 Practical Task

1. Create a GitHub account (if you don’t have one)
2. Prepare the full addon structure with package.xml, LICENSE, README.md
3. Upload the repository to GitHub
4. Install your addon via the Addon Manager on a clean FreeCAD copy (or delete the folder from Mod before installation)

---

✅ Summary

Now you know how to:

• Create full-fledged addons with GUI and settings
• Add icons
• Prepare metadata
• Publish to GitHub
• Make your addon available to the world

---

🎓 What’s next?

You’ve completed the entire course! 🎉
Now you are a FreeCAD addon developer.

Possible next steps:

• Add centering support (from Lesson 5 task)
• Implement multiple input (creating a grid of boxes)
• Integrate with PartDesign to create bodies of revolution
• Write an addon for your own task: bolts, frames, calculations, etc.

---

💬 Conclusion

FreeCAD is not just a CAD program.
It’s a platform for engineering creativity, and you now hold the key to expanding it.

Write addons. Share them. Change the world — one parametric object at a time. 🛠️

---

If you have an idea for a real addon — describe it, and I will help you implement it!