7f02fd182e
All checks were successful
Build and Test / build (pull_request) Successful in 24m46s
Root documentation: - README.md: add Datums description, update addon load order and SDK references, fix project structure tree, update issue reporting guidance - CONTRIBUTING.md: update submodule table (remove ztools, add gears/datums/solver), fix QSS guidance (single canonical source, not three copies) - docs/ARCHITECTURE.md: update bootstrap flow (5 addons, split deferred timers between Create core and Silo addon), update load order and source layout - docs/COMPONENTS.md: add Datums and Solver sections, update Gears description, fix Silo origin registration reference - docs/KNOWN_ISSUES.md: create missing file referenced by CLAUDE.md and CONTRIBUTING.md - docs/INTEGRATION_PLAN.md: update layer 5 diagram, fix load order references, update Phase 6 install rules, fix Layer 2/3/5 descriptions - docs/OVERVIEW.md: add datums submodule entry - docs/UPSTREAM.md: update Phase 1 directory table and Phase 4 submodule list mdBook documentation (docs/src/): - SUMMARY.md: replace dead architecture/ links with existing reference pages, remove deleted silo-server files, add new silo-server pages - introduction.md: rewrite — replace ztools with current addons (Silo, Gears, Datums, KCSDK), update version to v0.1.5/FreeCAD 1.2.0 - guide/getting-started.md: update first-run addon list - guide/installation.md: update verification console output - guide/workbenches.md: rewrite — replace ztools with Gears, Datums, Solver - guide/building.md: update submodule table, fix error message guidance - development/contributing.md: fix scope example and issue reporting - development/repo-structure.md: rewrite — add SDK, datums, gears, solver, reference/ folder; update submodule and key files tables - development/writing-an-addon.md: fix priority range table - reference/create-module-bootstrap.md: rewrite — reflect addon_loader system, split deferred timers between Create core and Silo addon - reference/datum-creator.md: update from ZTools to datums addon paths and naming - reference/glossary.md: add KCSDK entry, update FreeCAD version, remove ztools entry, update repository URLs table
147 lines
8.1 KiB
Markdown
147 lines
8.1 KiB
Markdown
# Architecture
|
|
|
|
## Bootstrap flow
|
|
|
|
```
|
|
FreeCAD startup
|
|
└─ src/Mod/Create/Init.py
|
|
└─ addon_loader.load_addons(gui=False)
|
|
├─ scan_addons("mods/") — find package.xml manifests
|
|
├─ parse_manifest() — extract <kindred> extensions
|
|
├─ validate_manifest() — check min/max_create_version
|
|
├─ resolve_load_order() — topological sort by <dependency>
|
|
└─ for each addon in order:
|
|
├─ add addon dir to sys.path
|
|
├─ exec(Init.py)
|
|
└─ register in AddonRegistry (FreeCAD.KindredAddons)
|
|
|
|
└─ src/Mod/Create/InitGui.py
|
|
├─ addon_loader.load_addons(gui=True)
|
|
│ └─ for each addon in order:
|
|
│ └─ exec(InitGui.py)
|
|
│ ├─ sdk (priority 0): logs "SDK loaded"
|
|
│ ├─ solver (priority 10): registers KindredSolverBackend
|
|
│ ├─ gears (priority 40): registers GearsWorkbench
|
|
│ ├─ datums (priority 45): registers Create_DatumCreator
|
|
│ └─ silo (priority 60): registers SiloWorkbench
|
|
│ └─ schedules deferred Silo setup (overlay, panels, observer)
|
|
├─ EditingContextResolver singleton created (MainWindow constructor)
|
|
│ ├─ registers built-in contexts (PartDesign, Sketcher, Assembly, Spreadsheet)
|
|
│ ├─ connects to signalInEdit/signalResetEdit/signalActiveDocument/signalActivateView
|
|
│ └─ BreadcrumbToolBar connected to contextChanged signal
|
|
└─ Deferred setup (QTimer):
|
|
Create core (src/Mod/Create/InitGui.py):
|
|
├─ 500ms: _register_kc_format() → .kc file format
|
|
└─ 10000ms: _check_for_updates() → update checker (Gitea API)
|
|
Silo addon (mods/silo/InitGui.py):
|
|
├─ 500ms: kindred:// URL handler
|
|
├─ 600ms: document observer (.kc tree building)
|
|
├─ 2000ms: auth dock panel (via kindred_sdk.register_dock_panel)
|
|
├─ 2500ms: Silo overlay registration → "Silo Origin" toolbar overlay
|
|
├─ 3000ms: first-start settings check
|
|
└─ 4000ms: activity dock panel (via kindred_sdk.register_dock_panel)
|
|
```
|
|
|
|
### Addon lifecycle
|
|
|
|
Each addon in `mods/` provides a `package.xml` manifest with a `<kindred>` extension block:
|
|
|
|
```xml
|
|
<kindred>
|
|
<min_create_version>0.1.0</min_create_version>
|
|
<load_priority>50</load_priority>
|
|
<pure_python>true</pure_python>
|
|
<dependencies>
|
|
<dependency>sdk</dependency>
|
|
</dependencies>
|
|
</kindred>
|
|
```
|
|
|
|
The loader (`addon_loader.py`) processes addons in this order:
|
|
|
|
1. **Scan** — find all `mods/*/package.xml` files
|
|
2. **Parse** — extract `<kindred>` metadata (version bounds, priority, dependencies)
|
|
3. **Validate** — reject addons incompatible with the current Create version
|
|
4. **Resolve** — topological sort by `<dependency>` declarations, breaking ties by `<load_priority>`
|
|
5. **Load** — execute `Init.py` (console) then `InitGui.py` (GUI) for each addon
|
|
6. **Register** — populate `FreeCAD.KindredAddons` registry with addon state
|
|
|
|
Current load order: **sdk** (0) → **solver** (10) → **gears** (40) → **datums** (45) → **silo** (60)
|
|
|
|
## Key source layout
|
|
|
|
```
|
|
src/Mod/Create/ Kindred Create module
|
|
├── Init.py Console bootstrap — loads addons via manifest-driven loader
|
|
├── InitGui.py GUI bootstrap — loads addons, Silo integration, update checker
|
|
├── addon_loader.py Manifest-driven addon loader with dependency resolution
|
|
├── kc_format.py .kc file format round-trip preservation
|
|
├── version.py.in CMake template → version.py (build-time)
|
|
├── update_checker.py Checks Gitea releases API for updates
|
|
├── CreateGlobal.h C++ export macros (CreateExport, CreateGuiExport)
|
|
├── App/ C++ App library (CreateApp.so)
|
|
│ ├── AppCreate.cpp Module entry point — PyMOD_INIT_FUNC(CreateApp)
|
|
│ └── AppCreatePy.cpp Python module object (Py::ExtensionModule)
|
|
└── Gui/ C++ Gui library (CreateGui.so)
|
|
├── AppCreateGui.cpp Module entry point — PyMOD_INIT_FUNC(CreateGui)
|
|
└── AppCreateGuiPy.cpp Python module object (Py::ExtensionModule)
|
|
|
|
mods/sdk/ [dir] Kindred addon SDK — stable API contract
|
|
├── package.xml Manifest (priority 0, no dependencies)
|
|
├── kindred_sdk/
|
|
│ ├── __init__.py Public API re-exports
|
|
│ ├── context.py Editing context wrappers (register_context, register_overlay, ...)
|
|
│ ├── theme.py YAML-driven palette system (get_theme_tokens, load_palette, Palette)
|
|
│ ├── origin.py FileOrigin registration (register_origin, unregister_origin)
|
|
│ ├── dock.py Deferred dock panel helper (register_dock_panel)
|
|
│ ├── compat.py Version detection (create_version, freecad_version)
|
|
│ └── palettes/
|
|
│ └── catppuccin-mocha.yaml 26 colors + 14 semantic roles
|
|
└── Init.py / InitGui.py Minimal log messages
|
|
|
|
mods/gears/ [submodule → gears.git] Gears workbench
|
|
├── package.xml Manifest (priority 40, depends on sdk)
|
|
└── ... Parametric gear generation
|
|
|
|
mods/solver/ [submodule → solver.git] Solver addon
|
|
└── ... Solver plugin support
|
|
|
|
mods/datums/ [submodule → datums.git] Unified datum creator
|
|
├── package.xml Manifest (priority 45, depends on sdk)
|
|
├── Init.py / InitGui.py Bootstrap
|
|
└── datums/ Python package (command, core, panel, detection, edit_panel)
|
|
|
|
mods/silo/ [submodule → silo-mod.git] PLM workbench
|
|
├── package.xml Manifest (priority 60, depends on sdk)
|
|
├── Init.py sys.path setup for silo-client
|
|
├── InitGui.py Consolidated GUI bootstrap (workbench, panels, observer, overlay)
|
|
├── silo-client/ [submodule → silo-client.git] shared API client
|
|
│ └── silo_client/ SiloClient, SiloSettings, CATEGORY_NAMES
|
|
└── freecad/ FreeCAD workbench (Python)
|
|
├── silo_commands.py Commands + FreeCADSiloSettings adapter
|
|
└── silo_origin.py FileOrigin backend for Silo (via SDK)
|
|
|
|
src/Gui/SDK/ KCSDK C++ shared library (libKCSDK.so)
|
|
├── KCSDKGlobal.h DLL export macros
|
|
├── Types.h Plain C++ types (ContextDef, DockArea, PanelPersistence)
|
|
├── IPanelProvider.h Abstract dock panel interface
|
|
├── WidgetBridge.h/.cpp PySide QWidget <-> C++ QWidget* (via Gui::PythonWrapper)
|
|
├── SDKRegistry.h/.cpp Singleton registry — contexts, panels, providers
|
|
└── bindings/ pybind11 module (kcsdk.so)
|
|
├── kcsdk_py.cpp Module definition — enums, functions, classes
|
|
├── PyIPanelProvider.h Trampoline for Python subclassing
|
|
└── PyProviderHolder.h GIL-safe forwarding wrapper
|
|
|
|
src/Gui/EditingContext.h/.cpp EditingContextResolver singleton + context registry
|
|
src/Gui/BreadcrumbToolBar.h/.cpp Color-coded breadcrumb toolbar (Catppuccin Mocha)
|
|
src/Gui/FileOrigin.h/.cpp FileOrigin base class + LocalFileOrigin
|
|
src/Gui/CommandOrigin.cpp Origin_Commit/Pull/Push/Info/BOM commands
|
|
src/Gui/OriginManager.h/.cpp Origin lifecycle management
|
|
src/Gui/OriginSelectorWidget.h/.cpp UI for origin selection
|
|
|
|
src/Gui/Stylesheets/ QSS themes and SVG assets
|
|
src/Gui/PreferencePacks/ KindredCreate preference pack (cfg + build-time QSS)
|
|
```
|
|
|
|
See [INTEGRATION_PLAN.md](INTEGRATION_PLAN.md) for architecture layers and phase status.
|