forbes-0023
1b3f780aa1
Some checks failed
Build and Test / build (push) Has been cancelled
- Update .gitmodules: ztools, silo, and OndselSolver now reference public git.kindred-systems.com URLs instead of internal Gitea - Merge OndselSolver numerical solver with ML solver scaffolding into unified kindred/solver repository - Rewrite README.md for conciseness - Add docs/CI_CD.md with full pipeline documentation - Rework CI/CD workflows for public dockerized runners - Add multi-platform release builds (Linux, macOS, Windows) - Release workflow triggers on v* tags only - Update docs/REPOSITORY_STATE.md and docs/INTEGRATION_PLAN.md
160 lines
10 KiB
Markdown
160 lines
10 KiB
Markdown
# Integration Plan
|
|
|
|
Strategy for integrating ztools and Silo as built-in addons while maintaining clear boundaries with FreeCAD core.
|
|
|
|
## Goals
|
|
|
|
1. **Native feel** -- ztools and Silo behave as first-class citizens, not bolted-on addons
|
|
2. **Clean boundaries** -- Clear separation between FreeCAD core, Kindred extensions, and addon code
|
|
3. **Minimal core modifications** -- Preserve FreeCAD's container models (Part, Body, Assembly)
|
|
4. **Maintainability** -- Easy to pull upstream FreeCAD changes without merge conflicts
|
|
5. **Extensibility** -- Architecture supports future Kindred-specific features
|
|
|
|
## Architecture layers
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Kindred Create Application │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ Layer 4: Kindred Workbenches (mods/) │
|
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
│ │ ztools │ │ Silo │ │
|
|
│ │ Datum Creator │ │ Open/Save/Commit│ │
|
|
│ │ Enhanced Pocket │ │ Part numbering │ │
|
|
│ │ Assembly Patterns│ │ Revision control│ │
|
|
│ │ Spreadsheet fmt │ │ BOM management │ │
|
|
│ └──────────────────┘ └──────────────────┘ │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ Layer 3: Kindred Bootstrap (src/Mod/Create/) │
|
|
│ ┌─────────────────────────────────────────────────────────┐│
|
|
│ │ Addon loading, theme application, global menu/toolbar ││
|
|
│ │ injection via WorkbenchManipulator API ││
|
|
│ └─────────────────────────────────────────────────────────┘│
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ Layer 2: FreeCAD Python API │
|
|
│ ┌─────────────────────────────────────────────────────────┐│
|
|
│ │ FreeCAD, FreeCADGui, Part, PartDesign, Sketcher, ││
|
|
│ │ Assembly, WorkbenchManipulator ││
|
|
│ └─────────────────────────────────────────────────────────┘│
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ Layer 1: FreeCAD Core (C++) │
|
|
│ ┌─────────────────────────────────────────────────────────┐│
|
|
│ │ App::Document, Part::Feature, PartDesign::Body, etc. ││
|
|
│ └─────────────────────────────────────────────────────────┘│
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Boundary definitions
|
|
|
|
### Layer 1: FreeCAD Core -- do not modify
|
|
|
|
FreeCAD's fundamental data structures: `PartDesign::Body`, `PartDesign::Pocket`, `Part::Feature`, `App::Document`, `Sketcher::SketchObject`. Modifying these creates merge conflicts with upstream and risks breaking FCStd file compatibility.
|
|
|
|
### Layer 2: FreeCAD Python API -- use as-is
|
|
|
|
The Python API provides everything needed for feature creation, command registration, and geometry access. ZTools and Silo operate entirely through this layer.
|
|
|
|
### Layer 3: Kindred Bootstrap -- `src/Mod/Create/`
|
|
|
|
The Create module is a thin Python loader that:
|
|
- Adds `mods/` addon paths to `sys.path` and executes their `Init.py`/`InitGui.py` files
|
|
- Installs `SiloMenuManipulator` for global File menu/toolbar injection
|
|
- Sets up deferred Silo dock panels (auth, activity) via `QTimer`
|
|
- Handles first-start configuration
|
|
|
|
This layer does not contain C++ code. It uses FreeCAD's `WorkbenchManipulator` API for menu/toolbar injection.
|
|
|
|
### Layer 4: Kindred Workbenches -- `mods/`
|
|
|
|
Pure Python workbenches following FreeCAD's addon pattern. Self-contained with `InitGui.py`, `Init.py`, and `package.xml`. Developed and versioned independently as git submodules.
|
|
|
|
---
|
|
|
|
## Phase status
|
|
|
|
### Phase 1: Addon auto-loading -- DONE
|
|
|
|
**Implementation:** `src/Mod/Create/Init.py` and `InitGui.py` load workbenches from `mods/` at startup using `exec()`. Addons degrade gracefully if submodule is absent.
|
|
|
|
**Default workbench:** `ZToolsWorkbench` (set in `resources/preferences/KindredCreate/KindredCreate.cfg`).
|
|
|
|
### Phase 2: Enhanced Pocket as C++ feature -- NOT STARTED
|
|
|
|
**Goal:** Replace the Python boolean-operation workaround in `ZTools_EnhancedPocket` with a proper `Create::FlipPocket` C++ feature inheriting from `PartDesign::ProfileBased`.
|
|
|
|
**Rationale:** The current Python implementation creates a standard Pocket then applies a boolean Common. A native feature would integrate properly with the feature tree, support undo/redo correctly, and perform better on complex geometry.
|
|
|
|
**Scope:**
|
|
- `src/Mod/Create/App/FeatureFlipPocket.cpp` -- Feature implementation
|
|
- `src/Mod/Create/Gui/TaskFlipPocket.cpp` -- Task panel
|
|
- `src/Mod/Create/Gui/ViewProviderFlipPocket.cpp` -- View provider
|
|
- Update `ZTools_EnhancedPocket` to create `Create::FlipPocket` instead of the workaround
|
|
|
|
**Decision:** Deferred. The Python approach is functional for current needs. Revisit when performance or feature-tree integration becomes a problem.
|
|
|
|
### Phase 3: Datum C++ helpers -- NOT STARTED (SUPERSEDED)
|
|
|
|
**Original goal:** Create C++ geometry helper functions for datum calculations.
|
|
|
|
**Current state:** The Python implementation now uses FreeCAD's built-in `Part::AttachExtension` for automatic parametric updates. Each datum type maps to a native MapMode (`FlatFace`, `ThreePointsPlane`, `NormalToEdge`, etc.) with appropriate `AttachmentSupport` and `AttachmentOffset`. This eliminates the need for custom geometry calculations.
|
|
|
|
**Decision:** Superseded by the AttachExtension approach. Only `tangent_to_cylinder` still uses manual placement (requires a vertex reference not currently collected by the UI).
|
|
|
|
### Phase 4: Theme system -- PARTIAL
|
|
|
|
**Goal:** Theme applies consistently at startup regardless of active workbench.
|
|
|
|
**Current state:** The Catppuccin Mocha theme is set as the default via the KindredCreate preference pack. Four copies of the QSS file exist and must be kept in sync manually:
|
|
1. `resources/preferences/KindredCreate/KindredCreate.qss` (canonical)
|
|
2. `src/Gui/Stylesheets/KindredCreate.qss`
|
|
3. `src/Gui/PreferencePacks/KindredCreate/KindredCreate.qss`
|
|
4. `mods/ztools/CatppuccinMocha/CatppuccinMocha.qss`
|
|
|
|
**Remaining work:** Eliminate QSS duplication via build-time copy or symlinks. Move theme responsibility out of ztools and into the Create module.
|
|
|
|
### Phase 5: Silo deep integration -- DONE
|
|
|
|
**Goal:** Silo commands available globally, not just in the Silo workbench.
|
|
|
|
**Implementation:** `SiloMenuManipulator` in `src/Mod/Create/InitGui.py` uses `FreeCADGui.addWorkbenchManipulator()` to inject Silo commands into the File menu and toolbar across all workbenches. `Silo_ToggleMode` provides a one-click swap of Ctrl+O/S/N between standard FreeCAD and Silo file commands.
|
|
|
|
**Dock panels:** Database Auth (1500ms) and Database Activity (4000ms) panels are created via deferred QTimers and docked in the right panel area.
|
|
|
|
### Phase 6: Build system integration -- PARTIAL
|
|
|
|
**Goal:** CMake install rules for `mods/` submodules so packages include ztools and Silo automatically.
|
|
|
|
**CI/CD status:** Release workflows (`.gitea/workflows/release.yml`) now build for Linux (AppImage + .deb), macOS (DMG for Intel + Apple Silicon), and Windows (.exe NSIS installer + .7z archive). Builds run on public runners in dockerized mode. Releases are triggered by `v*` tags. See `docs/CI_CD.md` for details.
|
|
|
|
**Remaining work:** CMake install rules should be formalized in `src/Mod/Create/CMakeLists.txt` so that `cmake --install` includes mods/ submodules without relying on the packaging scripts to copy them:
|
|
|
|
```cmake
|
|
install(DIRECTORY ${CMAKE_SOURCE_DIR}/mods/ztools/ztools
|
|
DESTINATION ${CMAKE_INSTALL_DATADIR}/Mod/ztools)
|
|
install(DIRECTORY ${CMAKE_SOURCE_DIR}/mods/ztools/CatppuccinMocha
|
|
DESTINATION ${CMAKE_INSTALL_DATADIR}/Mod/ztools)
|
|
|
|
install(DIRECTORY ${CMAKE_SOURCE_DIR}/mods/silo/pkg/freecad/
|
|
DESTINATION ${CMAKE_INSTALL_DATADIR}/Mod/Silo)
|
|
```
|
|
|
|
---
|
|
|
|
## Design decisions
|
|
|
|
1. **`Create::` namespace prefix.** All Kindred Create features use this prefix to distinguish them from FreeCAD core.
|
|
|
|
2. **No upstream contribution.** Kindred Create is a standalone product. This allows divergent design decisions without upstream coordination.
|
|
|
|
3. **Silo server distributed separately.** Users deploy the Silo server independently. Setup instructions live in `mods/silo/README.md`.
|
|
|
|
4. **Version synchronization via submodule pins.** ztools and Silo versions are pinned git submodule commits. Updates are deliberate:
|
|
```bash
|
|
cd mods/ztools && git pull origin main && cd ../..
|
|
git add mods/ztools && git commit -m "Update ztools submodule"
|
|
```
|
|
|
|
5. **Python-first approach.** C++ extensions are deferred until Python cannot achieve the requirement. The AttachExtension approach for datums validated this strategy.
|
|
|
|
6. **Graceful degradation.** The Create module loads successfully even if submodules are absent. Each addon load is wrapped in try/except with console logging.
|