автор: hypo69 / 03/10/2025

Мета лекції: Підготувати доповнення для розповсюдження, створити метадані та опублікувати його на GitHub, щоб будь-який користувач FreeCAD міг встановити його одним кліком.

In Questo Articolo

У цій статті
- 📦 Частина 1. Що таке Менеджер доповнень?
- 📁 Частина 2. Підготовка структури репозиторію
Можливості
Встановлення
Вимоги

У цій статті

Частина 1. Що таке Менеджер доповнень?
Частина 2. Підготовка структури репозиторію
Частина 3. Створення файлу package.xml
- Обов’язкові поля
Частина 4. Файл LICENSE
Частина 5. Файл README.md
Частина 6. Публікація на GitHub
- Кроки
Частина 7. Тестування інсталяції
Практичне завдання
Підсумок
Що далі?
- Можливі наступні кроки
Висновок

📦 Частина 1. Що таке Менеджер доповнень?

Менеджер доповнень — це вбудований інструмент FreeCAD (Інструменти → Менеджер доповнень), який:

Показує каталог з понад 300 офіційних доповнень.
Дозволяє встановлювати, оновлювати та видаляти доповнення без ручного копіювання файлів.
Працює з репозиторіями GitHub.

Щоб ваше доповнення з’явилося там, вам потрібно:

Завантажити його на GitHub.
Додати файл package.xml.
(Опціонально) Надіслати Pull Request (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`**

Цей файл описує ваше доповнення для Менеджера доповнень.

Створіть файл `package.xml` у кореневому каталозі:

xml

BoxBuilderAddon Простий інструмент для створення параметричних коробок з власними розмірами та GUI. Зберігає останні використані значення між сесіями. 1.0.0 2025-04-05 Your Name LGPL-2.1-or-later https://github.com/yourname/BoxBuilderAddon https://github.com/yourname/BoxBuilderAddon/issues Resources/icons/box_builder.svg BoxBuilderAddon 0.20

#### **🔍 Обов'язкові поля:**

*   `<name>` — має збігатися з назвою папки
*   `<version>` — у форматі X.Y.Z
*   `<license>` — вказує на файл `LICENSE` та тип ліцензії
*   `<url type="repository">` — посилання на ваш GitHub
*   `<icon>` — шлях до іконки (відносно кореня)
*   `<content><workbench>...</workbench></content>` — вказує, що це робочий стіл (workbench)

> **💡 Ліцензія є обов'язковою.** Рекомендується **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`:

markdown

Доповнення Box Builder для FreeCAD

Простий інструмент для створення параметричних коробок з власними розмірами.

Можливості

Діалогове вікно GUI для введення довжини, ширини, висоти
Зберігає останні використані значення між сесіями
Унікальні імена об’єктів
Опціональне центрування в точці початку координат

Встановлення

Відкрийте FreeCAD
Перейдіть до Інструменти → Менеджер доповнень
Знайдіть “BoxBuilderAddon”
Натисніть Встановити

Або встановіть вручну, скопіювавши папку у ваш каталог Mod.

Вимоги

FreeCAD 0.20 або новіший“`

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

Кроки:

Зареєструйтесь на GitHub.
Натисніть New repository (Новий репозиторій).
Назва: BoxBuilderAddon.
Ініціалізуйте без файлу README (ви його вже створили).
Натисніть Create repository (Створити репозиторій).
Дотримуйтесь інструкцій, щоб завантажити вашу локальну папку:

git init
git add .
git commit -m "Перший реліз"
git branch -M main
git remote add origin https://github.com/yourname/BoxBuilderAddon.git
git push -u origin main

💡 Замініть yourname на ваше ім’я користувача GitHub.

✔️ Частина 7. Тестування інсталяції

Тепер будь-який користувач може:

Відкрити FreeCAD.
Перейти до Інструменти → Менеджер доповнень.
Натиснути Перевірити наявність оновлень.
Знайти BoxBuilderAddon і натиснути Встановити.

❗️ Щоб доповнення з’явилося в офіційному списку, вам потрібно надіслати Pull Request до:
https://github.com/FreeCAD/FreeCAD-addons

Але навіть без цього, користувачі можуть встановити його за прямим посиланням:

У Менеджері доповнень: Інструменти → Менеджер доповнень → … → Встановити власне доповнення
Вставте URL: https://github.com/yourname/BoxBuilderAddon

✍️ Практичне завдання

Створіть обліковий запис на GitHub (якщо у вас його немає).
Підготуйте повну структуру доповнення з package.xml, LICENSE, README.md.
Завантажте репозиторій на GitHub.
Встановіть своє доповнення через Менеджер доповнень на чистій копії FreeCAD (або видаліть папку з Mod перед встановленням).

✅ Підсумок

Тепер ви знаєте, як:

Створювати повноцінні доповнення з GUI та налаштуваннями.
Додавати іконки.
Готувати метадані.
Публікувати на GitHub.
Робити ваше доповнення доступним для всього світу.

🎓 Що далі?

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

Можливі наступні кроки:

Додайте підтримку центрування (із завдання в Лекції 5).
Реалізуйте множинне введення (створення сітки коробок).
Інтегруйте з PartDesign для створення тіл обертання.
Напишіть доповнення для власного завдання: болти, рами, розрахунки тощо.

💬 Висновок

FreeCAD — це не просто програма CAD.
Це платформа для інженерної творчості, і тепер ви тримаєте ключ до її розширення.

Пишіть доповнення. Діліться ними. Змінюйте світ — по одному параметричному об’єкту за раз. 🛠️

Якщо у вас є ідея для справжнього доповнення — опишіть її, і я допоможу вам її реалізувати

Лекція 7. Публікація доповнення: Від папки до GitHub та Менеджера доповнень