Tworzenie dodatków do FreeCAD.

Lekcja 1. Konfiguracja środowiska programistycznego

Cel lekcji: Skonfiguruj wszystko, co niezbędne do łatwego tworzenia, testowania i debugowania dodatków.

---

W tym artykule

1. Krok 1. Upewnij się, że masz zainstalowany FreeCAD
   • Wymagania
2. Krok 2. Znajdź folder z dodatkami
   • Jak precyzyjnie zlokalizować folder?
   • Utwórz folder Mod
3. Krok 3. Skonfiguruj edytor tekstu (opcjonalne, ale wysoce zalecane)
   • Polecamy: Visual Studio Code (VS Code)
   • Jak otworzyć folder z dodatkami w VS Code?
4. Krok 4. Poznaj wbudowane narzędzia FreeCAD
   • 1. Konsola Python
   • 2. Widok raportu
   • 3. Rejestrator makr
5. Krok 5. Weryfikacja: Utwórz folder testowy
6. Podsumowanie struktury folderów deweloperskich
7. Zadanie praktyczne
8. Co dalej?

---

🔧 Krok 1. Upewnij się, że masz zainstalowany FreeCAD

Wymagania:

• FreeCAD w wersji 0.20 lub nowszej (zalecana wersja 1.0+)
• Działa w systemach Windows, Linux lub macOS

Jeśli jeszcze nie masz FreeCAD, pobierz go z oficjalnej strony internetowej:

https://www.freecad.org/downloads.php

Wybierz:

• Windows: .exe (instalator) lub .7z (wersja przenośna)
• Linux: AppImage lub pakiet z repozytorium
• macOS: .dmg

💡 Wskazówka: Do nauki lepiej jest używać wersji instalowanej (za pomocą instalatora), ponieważ jest ona bardziej stabilna i łatwiejsza w konfiguracji.

---

📂 Krok 2. Znajdź folder z dodatkami

FreeCAD szuka dodatków zdefiniowanych przez użytkownika w specjalnym folderze o nazwie Mod. Ścieżka do tego folderu zależy od systemu operacyjnego i typu instalacji.

✅ Jak precyzyjnie zlokalizować folder?

1. Uruchom FreeCAD.
2. Otwórz konsolę Python:
   Widok → Panele → Konsola Python
3. Wpisz polecenie:
   python import FreeCAD print(FreeCAD.getUserAppDataDir())
4. Naciśnij Enter.

Zobaczysz ścieżkę, na przykład:

• Windows (wersja instalowana):
  C:\Users\TwojaNazwa\AppData\Roaming\FreeCAD\
• Windows (wersja przenośna):
  D:\FreeCAD\data\
• Linux:
  /home/twoja_nazwa/.local/share/FreeCAD/
• macOS:
  /Users/twoja_nazwa/Library/Application Support/FreeCAD/

➕ Utwórz folder Mod

Wewnątrz tego katalogu musi znajdować się folder o nazwie Mod. Jeśli go nie ma, utwórz go ręcznie.

Przykład dla systemu Windows:
C:\Users\TwojaNazwa\AppData\Roaming\FreeCAD\Mod\

💡 Szybki sposób na otwarcie folderu w systemie Windows:
Naciśnij Win + R → wpisz %APPDATA%\FreeCAD → naciśnij Enter

---

💻 Krok 3. Skonfiguruj edytor tekstu (opcjonalne, ale wysoce zalecane)

Chociaż możesz pisać kod w Notatniku, znacznie wygodniej jest używać edytora, który oferuje:

• Podświetlanie składni Pythona
• Autouzupełnianie
• Możliwość uruchamiania skryptów

🔹 Polecamy: Visual Studio Code (VS Code)

1. Pobierz i zainstaluj: https://code.visualstudio.com/
2. Zainstaluj rozszerzenie Python (od Microsoft)
3. (Opcjonalnie) Zainstaluj rozszerzenie FreeCAD for VS Code – dodaje ono podpowiedzi API FreeCAD

🔹 Jak otworzyć folder z dodatkami w VS Code?

1. Uruchom VS Code
2. Plik → Otwórz folder
3. Wybierz folder Mod (lub konkretny dodatek w jego wnętrzu)

Teraz możesz wygodnie przeglądać strukturę projektu i edytować pliki.

---

🛠️ Krok 4. Poznaj wbudowane narzędzia FreeCAD

FreeCAD zawiera już wszystko, czego potrzebujesz do programowania.

1. Konsola Python

• Menu: Widok → Panele → Konsola Python
• Umożliwia wykonywanie poleceń w czasie rzeczywistym
• Przykład: wpisz App.newDocument() → zostanie utworzony nowy dokument

2. Widok raportu

• Menu: Widok → Panele → Widok raportu
• Pokazuje błędy, ostrzeżenia, logi
• Zawsze miej go otwartego podczas testowania dodatku!

3. Rejestrator makr

• Menu: Makro → Makra...
• Przycisk Nagrywaj – rejestruje Twoje działania jako kod w języku Python
• Doskonały sposób na naukę API FreeCAD

💡 Wypróbuj to:

1. Kliknij Makro → Rozpocznij nagrywanie
2. Utwórz sześcian (Part → Sześcian)
3. Zatrzymaj nagrywanie
4. Otwórz makro – zobaczysz rzeczywisty kod do tworzenia obiektu!

---

🧪 Krok 5. Weryfikacja: Utwórz folder testowy

Aby upewnić się, że wszystko działa:

1. W folderze Mod utwórz podfolder:
   TestAddon
2. Wewnątrz utwórz plik __init__.py (może być pusty) – informuje on Pythona, że folder jest modułem.
3. Uruchom ponownie FreeCAD.
4. Otwórz Widok raportu.

Jeśli nie widzisz żadnych błędów, oznacza to, że FreeCAD pomyślnie przeskanował folder Mod.

❗️ Jeśli pojawi się ImportError – sprawdź:

• Poprawność nazwy folderu (bez spacji i znaków cyrylicy)
• Obecność pliku __init__.py (nie zawsze jest obowiązkowy w nowszych wersjach, ale bezpieczniej go dodać)

---

📑 Podsumowanie struktury folderów deweloperskich

Pod koniec tej lekcji powinieneś mieć następującą strukturę:

(folder użytkownika FreeCAD)
└── Mod/
    └── TestAddon/
        └── __init__.py   <-- może być pusty

I wiesz już:

• Gdzie znajduje się folder Mod
• Jak otworzyć konsolę Python i widok raportu
• Jak używać rejestratora makr
• Jak (opcjonalnie) skonfigurować VS Code

---

✅ Zadanie praktyczne

1. Znajdź folder Mod za pomocą FreeCAD.getUserAppDataDir()
2. Utwórz w nim folder MyFirstAddon
3. Dodaj do niego pusty plik __init__.py
4. Uruchom ponownie FreeCAD
5. Upewnij się, że w Widoku raportu nie ma błędów

🎯 Cel: FreeCAD powinien uruchomić się bez błędów i „zobaczyć” Twój folder.

---

▶️ Co dalej?

W Lekcji 2 stworzymy prawdziwy, działający dodatek:

• Dodamy przycisk
• Sprawimy, by coś robił
• Nauczymy się rejestrować polecenia i warsztaty (workbenches)