שיעור 7. פרסום תוסף: מתיקייה ל-GitHub ולמנהל התוספים

מדריך: יצירת תוספים עבור FreeCAD

מטרת השיעור: להכין את התוסף להפצה, ליצור קובץ מטא-נתונים, ולפרסם אותו ב-GitHub כך שכל משתמש ב-FreeCAD יוכל להתקין אותו בלחיצה אחת.

חלק 1. מהו מנהל התוספים?
מנהל התוספים הוא כלי מובנה ב-FreeCAD (כלים → מנהל תוספים) ש:

מציג קטלוג של יותר מ-300 תוספים רשמיים
מאפשר להתקין, לעדכן ולהסיר תוספים ללא העתקת קבצים ידנית
עובד עם מאגרי GitHub

כדי שהתוסף שלך יופיע שם, עליך:

להעלות אותו ל-GitHub
להוסיף קובץ package.xml
(אופציונלי) לשלוח בקשת משיכה (Pull Request) למאגר הרשמי של FreeCAD

חלק 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 version="1.0" encoding="UTF-8" standalone="no"?>
<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">
  <name>BoxBuilderAddon</name>
  <description>
    כלי פשוט ליצירת קופסאות פרמטריות עם ממדים מותאמים אישית וממשק גרפי.
    שומר את הערכים האחרונים בין הפעלות.
  </description>
  <version>1.0.0</version>
  <date>2025-04-05</date>
  <maintainer email="your.email@example.com">השם שלך</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:

עבור אל: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt
העתק את כל הטקסט
הדבק לתוך הקובץ LICENSE

או השתמש באפשרות של GitHub: בעת יצירת מאגר, ניתן לבחור רישיון אוטומטית.

חלק 5. קובץ README.md
צור קובץ פשוט בשם README.md:

# תוסף בונה קופסאות עבור FreeCAD

כלי פשוט ליצירת קופסאות פרמטריות עם ממדים מותאמים אישית.

## תכונות
- חלון קלט למימדים: אורך, רוחב, גובה
- שמירת ערכים אחרונים בין הפעלות
- מתן שמות ייחודיים לאובייקטים
- אפשרות למרכז את הקופסה בראשית הצירים

## התקנה
1. פתח את FreeCAD  
2. עבור אל **כלים → מנהל תוספים**  
3. חפש את "BoxBuilderAddon"  
4. לחץ על **התקן**

או התקן ידנית על ידי העתקת התיקייה לתיקיית ה-`Mod`.

## דרישות
- FreeCAD גרסה 0.20 או חדשה יותר

חלק 6. פרסום ב-GitHub
שלבים:

הירשם ב-GitHub
לחץ על New repository
שם: BoxBuilderAddon
אל תאתחל עם README (כבר יצרת אחד)
לחץ Create repository
עקוב אחר ההוראות להעלאת התיקייה המקומית:

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. בדיקת ההתקנה
כעת כל משתמש יכול:

לפתוח את FreeCAD
ללכת אל כלים → מנהל תוספים
ללחוץ על בדוק עדכונים
למצוא את BoxBuilderAddon וללחוץ על התקן

כדי שהתוסף יופיע ברשימה הרשמית, יש לשלוח בקשת משיכה (PR) ל:
https://github.com/FreeCAD/FreeCAD-addons

אך גם ללא זה, משתמשים יכולים להתקין אותו מקישור ישיר:
במנהל התוספים: כלים → מנהל תוספים → … → התקן תוסף מותאם
הדבק את ה-URL: https://github.com/yourname/BoxBuilderAddon

משימה מעשית

צור חשבון GitHub (אם אין לך)
הכן את מבנה התוסף המלא עם package.xml, LICENSE, README.md
העלה את המאגר ל-GitHub
התקן את התוסף דרך מנהל התוספים בגיבוי נקי של FreeCAD (או מחק את התיקייה מ-Mod לפני ההתקנה)

סיכום
כעת אתה יודע כיצד:

ליצור תוספים מלאים עם ממשק גרפי והגדרות
להוסיף סמלים
להכין מטא-נתונים
לפרסם ב-GitHub
להפוך את התוסף שלך זמין לעולם

מה הלאה?
סיימת את כל הקורס!
כעת אתה מפתח תוספי FreeCAD.

הצעדים הבאים יכולים לכלול:

הוספת תמיכה במרכזון (מהמשימה בשיעור 5)
יישום קלט מרובה (למשל יצירת רשת של קופסאות)
אינטגרציה עם PartDesign ליצירת גופי סיבוב
כתיבת תוסף למשימה האישית שלך: ברגים, מסגרות, חישובים וכו'

מסקנה
FreeCAD הוא לא רק תוכנת CAD.
זה פלטפורמה ליצירתיות הנדסית, ואתה מחזיק כעת במפתח להרחיב אותה.

כתוב תוספים. שתף אותם. שנה את העולם — אובייקט פרמטרי אחד בכל פעם.

אם יש לך רעיון לתוסף אמיתי — תאר אותו, ואני אעזור לך לממש אותו!

שיעור 7. פרסום תוסף: מתיקייה ל-GitHub ולמנהל התוספים
מאת hypo69 / 03.10.2025