Урок 7. Публикация аддона: от папки к GitHub и Addon Manager

📘 Учебный курс: Создание аддонов для FreeCAD

Цель урока: подготовить аддон к распространению, создать метаданные и опубликовать его на GitHub, чтобы любой пользователь FreeCAD мог установить его одним кликом.

---

📦 Часть 1. Что такое Addon Manager?

Addon Manager — встроенный инструмент FreeCAD (Tools → Addon Manager), который:

• Показывает каталог из 300+ официальных аддонов
• Позволяет устанавливать, обновлять и удалять аддоны без ручного копирования файлов
• Работает с репозиториями на GitHub

Чтобы ваш аддон появился там — нужно:

1. Выложить его на GitHub
2. Добавить файл package.xml
3. (Опционально) Отправить PR в FreeCAD-addons

---

🗂 Часть 2. Подготовка структуры репозитория

Ваша папка должна выглядеть так:

BoxBuilderAddon/                ← корень репозитория
├── Resources/
│   └── icons/
│       ├── box_builder.svg
│       └── create_box.svg
├── InitGui.py
├── box_builder_workbench.py
├── package.xml                 ← ОБЯЗАТЕЛЬНО!
├── README.md                   ← рекомендуется
└── LICENSE                     ← обязательно для публикации

💡 Важно: название корневой папки должно совпадать с именем аддона и быть таким же, как в InitGui.py.

---

📄 Часть 3. Создание package.xml

Этот файл описывает ваш аддон для Addon Manager.

Создайте файл package.xml в корне:

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

🔍 Обязательные поля:

• <name> — должно совпадать с папкой
• <version> — в формате X.Y.Z
• <license> — указываете файл LICENSE и тип лицензии
• <url type="repository"> — ссылка на ваш GitHub
• <icon> — путь к иконке (относительно корня)
• <content><workbench>...</workbench></content> — указывает, что это рабочая среда

💡 Лицензия обязательна. Рекомендуется LGPL-2.1-or-later (как у самого FreeCAD).

---

📄 Часть 4. Файл LICENSE

Создайте файл LICENSE с текстом лицензии.

Пример для LGPL-2.1:

1. Перейдите на: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt
2. Скопируйте весь текст
3. Вставьте в файл LICENSE

Или используйте GitHub: при создании репозитория можно выбрать лицензию автоматически.

---

📝 Часть 5. Файл README.md

Создайте простой 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

---

🌐 Часть 6. Публикация на GitHub

Шаги:

1. Зарегистрируйтесь на GitHub
2. Нажмите New repository
3. Название: BoxBuilderAddon
4. Инициализировать без README (вы уже создали его)
5. Нажмите Create repository
6. Следуйте инструкциям по загрузке локальной папки:

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

💡 Замените yourname на ваш GitHub-логин.

---

🔍 Часть 7. Тестирование установки

Теперь любой пользователь может:

1. Открыть FreeCAD
2. Перейти в Tools → Addon Manager
3. Нажать Check for updates
4. Найти BoxBuilderAddon и нажать Install

⚠️ Чтобы аддон появился в официальном списке, нужно отправить Pull Request в:
🔗 https://github.com/FreeCAD/FreeCAD-addons

Но даже без этого пользователи могут установить его по прямой ссылке:

• В Addon Manager: Tools → Addon Manager → … → Install custom addon
• Вставить URL: https://github.com/yourname/BoxBuilderAddon

---

🧪 Практическое задание

1. Создайте аккаунт на GitHub (если нет)
2. Подготовьте полную структуру аддона с package.xml, LICENSE, README.md
3. Загрузите репозиторий на GitHub
4. Установите свой аддон через Addon Manager на чистой копии FreeCAD (или удалите папку из Mod перед установкой)

---

✅ Итог

Теперь вы умеете:

• Создавать полноценные аддоны с GUI и настройками
• Добавлять иконки
• Подготавливать метаданные
• Публиковать на GitHub
• Делать аддон доступным для всего мира

---

🎓 Что дальше?

Вы прошли весь курс! 🎉
Теперь вы — разработчик аддонов FreeCAD.

Возможные следующие шаги:

• Добавьте поддержку центрирования (из задания Урока 5)
• Реализуйте множественный ввод (создание сетки коробок)
• Интегрируйте с PartDesign для создания тел вращения
• Напишите аддон для своей задачи: болты, рамы, расчёты и т.д.

---

💬 Заключение

FreeCAD — это не просто CAD-программа.
Это платформа для инженерного творчества, и вы теперь обладаете ключом к её расширению.

Пишите аддоны. Делитесь ими. Меняйте мир — по одному параметрическому объекту за раз. 🛠️

---

Если у вас есть идея для реального аддона — опишите её, и я помогу реализовать!