phase 1: copy Kindred-only files onto upstream/main (FreeCAD 1.2.0-dev)

Wholesale copy of all Kindred Create additions that don't conflict with
upstream FreeCAD code:

- kindred-icons/ (1444 Catppuccin Mocha SVG icon overrides)
- src/Mod/Create/ (Kindred Create workbench)
- src/Gui/ Kindred source files (FileOrigin, OriginManager,
  OriginSelectorWidget, CommandOrigin, BreadcrumbToolBar, EditingContext)
- src/Gui/Icons/ (Kindred branding and silo icons)
- src/Gui/PreferencePacks/KindredCreate/
- src/Gui/Stylesheets/ (KindredCreate.qss, images_dark-light/)
- package/ (rattler-build recipe)
- docs/ (architecture, guides, specifications)
- .gitea/ (CI workflows, issue templates)
- mods/silo, mods/ztools submodules
- .gitmodules (Kindred submodule URLs)
- resources/ (kindred-create.desktop, kindred-create.xml)
- banner-logo-light.png, CONTRIBUTING.md
This commit is contained in:
forbes
2026-02-13 14:03:58 -06:00
parent 5d81f8ac16
commit 87a0af0b0f
1566 changed files with 32071 additions and 6155 deletions

View File

@@ -0,0 +1,72 @@
# Build System
Kindred Create uses **CMake** for build configuration, **pixi** (conda-based) for dependency management and task running, and **ccache** for compilation caching.
## Overview
- **CMake** >= 3.22.0
- **Ninja** generator (via conda presets)
- **pixi** manages all dependencies — compilers, Qt6, OpenCASCADE, Python, etc.
- **ccache** with 4 GB max, zlib compression level 6, sloppy mode
- **mold** linker on Linux for faster link times
## CMake configuration
The root `CMakeLists.txt` defines:
- **Kindred Create version:** `0.1.0` (via `KINDRED_CREATE_VERSION`)
- **FreeCAD base version:** `1.0.0` (via `FREECAD_VERSION`)
- CMake policy settings for compatibility
- ccache auto-detection
- Submodule dependency checks
- Library setup: yaml-cpp, fmt, ICU
### Version injection
The version flows from CMake to Python via `configure_file()`:
```
CMakeLists.txt (KINDRED_CREATE_VERSION = "0.1.0")
→ src/Mod/Create/version.py.in (template)
→ build/*/Mod/Create/version.py (generated)
→ update_checker.py (imports VERSION)
```
## CMake presets
Defined in `CMakePresets.json`:
| Preset | Platform | Build type |
|--------|----------|------------|
| `conda-linux-debug` | Linux | Debug |
| `conda-linux-release` | Linux | Release |
| `conda-macos-debug` | macOS | Debug |
| `conda-macos-release` | macOS | Release |
| `conda-windows-debug` | Windows | Debug |
| `conda-windows-release` | Windows | Release |
All presets inherit from a hidden `common` base and a hidden `conda` base (Ninja generator, conda toolchain).
## cMake/ helper modules
The `cMake/` directory contains CMake helper macros inherited from FreeCAD:
- **FreeCAD_Helpers** — macros for building FreeCAD modules
- Platform detection modules
- Dependency finding modules (Find*.cmake)
## Dependencies
Core dependencies managed by pixi (from `pixi.toml`):
| Category | Packages |
|----------|----------|
| Build | cmake, ninja, swig, compilers (clang/gcc) |
| CAD kernel | occt 7.8, coin3d, opencamlib, pythonocc-core |
| UI | Qt6 6.8, PySide6, pyside6 |
| Math | eigen, numpy, scipy, sympy |
| Data | hdf5, vtk, smesh, ifcopenshell |
| Python | 3.11 (< 3.12), pip, freecad-stubs |
Platform-specific extras:
- **Linux:** clang, kernel-headers, mesa, X11, libspnav
- **macOS:** sed
- **Windows:** pthreads-win32

View File

@@ -0,0 +1,40 @@
# Code Quality
## Formatting and linting
### C/C++
- **Formatter:** clang-format (config in `.clang-format`)
- **Static analysis:** clang-tidy (config in `.clang-tidy`)
### Python
- **Formatter:** black with 100-character line length
- **Linter:** pylint (config in `.pylintrc`)
## Pre-commit hooks
The repository uses [pre-commit](https://pre-commit.com/) to run formatters and linters automatically on staged files:
```bash
pip install pre-commit
pre-commit install
```
Configured hooks (`.pre-commit-config.yaml`):
- `trailing-whitespace` — remove trailing whitespace
- `end-of-file-fixer` — ensure files end with a newline
- `check-yaml` — validate YAML syntax
- `check-added-large-files` — prevent accidental large file commits
- `mixed-line-ending` — normalize line endings
- `black` — Python formatting (100 char lines)
- `clang-format` — C/C++ formatting
## Scope
Pre-commit hooks are configured to run on specific directories:
- `src/Base/`, `src/Gui/`, `src/Main/`, `src/Tools/`
- `src/Mod/Assembly/`, `src/Mod/BIM/`, `src/Mod/CAM/`, `src/Mod/Draft/`, `src/Mod/Fem/`, and other stock modules
- `tests/src/`
Excluded: generated files, vendored libraries (`QSint/`, `Quarter/`, `3Dconnexion/navlib`), and binary formats.

View File

@@ -0,0 +1,52 @@
# Contributing
Kindred Create is maintained at [git.kindred-systems.com/kindred/create](https://git.kindred-systems.com/kindred/create). Contributions are submitted as pull requests against the `main` branch.
## Getting started
```bash
git clone --recursive ssh://git@git.kindred-systems.com:2222/kindred/create.git
cd create
pixi run configure
pixi run build
pixi run freecad
```
See [Building from Source](../guide/building.md) for the full development setup.
## Branch and PR workflow
1. Create a feature branch from `main`:
```bash
git checkout -b feat/my-feature main
```
2. Make your changes, commit with conventional commit messages (see below).
3. Push and open a pull request against `main`.
4. CI builds and tests run automatically on all PRs.
## Commit messages
Use [Conventional Commits](https://www.conventionalcommits.org/):
| Prefix | Purpose |
|--------|---------|
| `feat:` | New feature |
| `fix:` | Bug fix |
| `chore:` | Maintenance, dependencies |
| `docs:` | Documentation only |
| `art:` | Icons, theme, visual assets |
Scope is optional but encouraged:
- `feat(ztools): add datum point creation mode`
- `fix(gui): correct menu icon size on Wayland`
- `chore: update silo submodule`
## Reporting issues
Report issues at the [issue tracker](https://git.kindred-systems.com/kindred/create/issues). When reporting:
1. Note whether the issue involves Kindred Create additions (ztools, Silo, theme) or base FreeCAD
2. Include version info from **Help > About FreeCAD > Copy to clipboard**
3. Provide reproduction steps and attach example files (FCStd as ZIP) if applicable
For base FreeCAD issues, also check the [FreeCAD issue tracker](https://github.com/FreeCAD/FreeCAD/issues).

View File

@@ -0,0 +1,239 @@
# Gui Module Build Integration
The `FreeCADGui` shared library is the main GUI module. It contains the origin system, toolbar widgets, 3D viewport, command dispatch, and the Python bridge layer. This page explains how it is built, what it links against, and how to add new source files.
## Target overview
```cmake
add_library(FreeCADGui SHARED)
```
Built when `BUILD_GUI=ON` (the default). The output is a shared library installed to `${CMAKE_INSTALL_LIBDIR}`.
**CMake file:** `src/Gui/CMakeLists.txt`
## Dependency chain
```
FreeCADGui (SHARED)
├── FreeCADApp (core application module)
├── libfastsignals (STATIC, from src/3rdParty/FastSignals/)
├── Qt6::Core, Widgets, OpenGL, OpenGLWidgets, Network,
│ PrintSupport, Svg, SvgWidgets, UiTools, Xml
├── Coin3D / Quarter (3D scene graph)
├── PySide6 / Shiboken6 (Python-Qt bridge, if FREECAD_USE_PYSIDE=ON)
├── PyCXX (C++-Python interop, header-only)
├── Boost (various components)
├── OpenGL
├── yaml-cpp
├── ICU (Unicode)
└── (optional) 3Dconnexion, Tracy profiler, VR
```
### fastsignals
fastsignals is built as a **static library** with position-independent code:
```
src/3rdParty/FastSignals/
└── libfastsignals/
├── CMakeLists.txt # builds libfastsignals.a (STATIC, -fPIC)
├── include/fastsignals/ # public headers (INTERFACE include dir)
└── src/ # implementation
```
Linked into FreeCADGui via:
```cmake
target_link_libraries(FreeCADGui ... libfastsignals ...)
target_include_directories(FreeCADGui SYSTEM PRIVATE ${FastSignals_INCLUDE_DIRS})
```
The `fastsignals/signal.h` header is also included in `src/Gui/PreCompiled.h` so it is available without explicit `#include` in any Gui source file.
## Source file organisation
Source files are grouped into named blocks in `CMakeLists.txt`. Each group becomes a Visual Studio filter / IDE source group.
| Group variable | Contains | Origin system files in this group |
|----------------|----------|-----------------------------------|
| `Command_CPP_SRCS` | Command classes | `CommandOrigin.cpp` |
| `Widget_CPP_SRCS` | Toolbar/dock widgets | `OriginSelectorWidget.h/.cpp` |
| `Workbench_CPP_SRCS` | Workbench infrastructure | `OriginManager.h/.cpp`, `OriginManagerDialog.h/.cpp` |
| `FreeCADGui_CPP_SRCS` | Core Gui classes | `FileOrigin.h/.cpp`, `FileOriginPython.h/.cpp` |
All groups are collected into `FreeCADGui_SRCS` and added to the target:
```cmake
target_sources(FreeCADGui PRIVATE ${FreeCADGui_SRCS})
```
## Adding new source files
1. Create your `.h` and `.cpp` files in `src/Gui/`.
2. Add them to the appropriate source group in `src/Gui/CMakeLists.txt`. For origin system code, follow the existing pattern:
- Widget → `Widget_CPP_SRCS`
- Command → `Command_CPP_SRCS`
- Manager/infrastructure → `Workbench_CPP_SRCS`
- Core class → `FreeCADGui_CPP_SRCS`
```cmake
SET(FreeCADGui_CPP_SRCS
...
MyNewOrigin.cpp
MyNewOrigin.h
...
)
```
3. If the file has a `Q_OBJECT` macro, CMake's `AUTOMOC` handles MOC generation automatically. No manual steps needed.
4. If adding Python bindings via PyCXX, add the `.pyi` stub and register it:
```cmake
generate_from_py(MyNewOrigin)
```
5. If linking a new external library:
```cmake
list(APPEND FreeCADGui_LIBS MyNewLibrary)
```
6. Reconfigure and build:
```bash
pixi run configure
pixi run build
```
No changes are needed to `CommandOrigin.cpp`, `OriginSelectorWidget.cpp`, or `Workbench.cpp` when adding a new origin — those modules discover origins dynamically through `OriginManager` at runtime.
## Qt integration
### Modules linked
QtCore, QtWidgets, QtOpenGL, QtOpenGLWidgets, QtPrintSupport, QtSvg, QtSvgWidgets, QtNetwork, QtUiTools, QtXml. Qt version `>=6.8,<6.9` is specified in `pixi.toml`.
### MOC (Meta Object Compiler)
Handled automatically by CMake's `AUTOMOC` for any header containing `Q_OBJECT`. Exception: `GraphvizView` has manual MOC commands due to moc-from-cpp requirements.
### UI files
~100 `.ui` files are compiled by Qt's `uic` into C++ headers. Declared in the `Gui_UIC_SRCS` block.
### Resources
Icons are embedded via `Icons/resource.qrc`. Translations use Qt Linguist (`.ts` → `.qm`) with auto-generated resource files.
## Theme and stylesheet build
Stylesheets are **copied, not compiled**. The canonical stylesheet is `src/Gui/Stylesheets/KindredCreate.qss`.
`src/Gui/Stylesheets/CMakeLists.txt` defines a custom target that copies `.qss` files and SVG/PNG images to the build tree:
```cmake
fc_copy_sources(Stylesheets_data
"${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_DATADIR}/Gui/Stylesheets"
${Stylesheets_Files} ${Images_Files} ...)
```
`src/Gui/PreferencePacks/CMakeLists.txt` copies the same stylesheet into the preference pack directory using `configure_file(... COPYONLY)`, avoiding a duplicate source:
```cmake
configure_file(
${CMAKE_CURRENT_SOURCE_DIR}/../Stylesheets/KindredCreate.qss
${CMAKE_BINARY_DIR}/.../PreferencePacks/KindredCreate/KindredCreate.qss
COPYONLY)
```
Edit only the canonical file in `Stylesheets/` — the preference pack copy is generated.
## Version constants
Defined in the top-level `CMakeLists.txt` and injected as compiler definitions:
```cmake
set(KINDRED_CREATE_VERSION "0.1.0")
set(FREECAD_VERSION "1.0.0")
add_definitions(-DKINDRED_CREATE_VERSION="${KINDRED_CREATE_VERSION}")
add_definitions(-DFREECAD_VERSION="${FREECAD_VERSION}")
```
Available in C++ code as preprocessor macros. The Python update checker uses `version.py` generated from `version.py.in` at build time with `configure_file()`.
## Precompiled headers
Controlled by `FREECAD_USE_PCH` (off by default in conda builds):
```cmake
if(FREECAD_USE_PCH)
target_precompile_headers(FreeCADGui PRIVATE
$<$<COMPILE_LANGUAGE:CXX>:"PreCompiled.h">)
endif()
```
`PreCompiled.h` includes `<fastsignals/signal.h>`, all Qt headers (via `QtAll.h`), Coin3D headers, Boost, and Xerces. QSint and Quarter sources are excluded from PCH via `SKIP_PRECOMPILE_HEADERS`.
## Build presets
Defined in `CMakePresets.json`:
| Preset | Platform | Build type |
|--------|----------|------------|
| `conda-linux-debug` | Linux | Debug |
| `conda-linux-release` | Linux | Release |
| `conda-macos-debug` | macOS | Debug |
| `conda-macos-release` | macOS | Release |
| `conda-windows-debug` | Windows | Debug |
| `conda-windows-release` | Windows | Release |
All presets use the conda/pixi environment for dependency resolution.
## ccache
Enabled by default (`FREECAD_USE_CCACHE=ON`). CMake searches the system PATH for `ccache` at configure time and sets it as the compiler launcher:
```cmake
set(CMAKE_C_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
```
Disable with `-DFREECAD_USE_CCACHE=OFF` if needed. Clear the cache with `ccache -C`.
## Pixi tasks
Common build workflow:
```bash
pixi run initialize # git submodule update --init --recursive
pixi run configure # cmake --preset conda-linux-debug (or platform equivalent)
pixi run build # cmake --build build/debug
pixi run install # cmake --install build/debug
pixi run freecad # launch the built binary
pixi run test-kindred # run Kindred addon tests (no build needed)
```
Release variants: `configure-release`, `build-release`, `install-release`, `freecad-release`.
## Key CMake variables
| Variable | Default | Effect |
|----------|---------|--------|
| `BUILD_GUI` | ON | Build FreeCADGui at all |
| `FREECAD_USE_CCACHE` | ON | Compiler caching |
| `FREECAD_USE_PCH` | OFF (conda) | Precompiled headers |
| `FREECAD_USE_PYSIDE` | auto | PySide6 Python-Qt bridge |
| `FREECAD_USE_SHIBOKEN` | auto | Shiboken6 binding generator |
| `BUILD_VR` | OFF | Oculus VR support |
| `BUILD_TRACY_FRAME_PROFILER` | OFF | Tracy profiler integration |
## See also
- [Build System](./build-system.md) — general build instructions
- [Signal Architecture](../architecture/signal-architecture.md) — how fastsignals integrates at runtime
- [Creating a Custom Origin (C++)](../reference/cpp-custom-origin-guide.md) — what to link when adding an origin

View File

@@ -0,0 +1,73 @@
# Repository Structure
```
create/
├── src/
│ ├── App/ # Core application (C++)
│ ├── Base/ # Base classes (C++)
│ ├── Gui/ # GUI framework and stylesheets (C++)
│ ├── Main/ # Application entry points
│ ├── Mod/ # FreeCAD modules (~37)
│ │ ├── Create/ # Kindred bootstrap module
│ │ ├── Assembly/ # Assembly workbench (Kindred patches)
│ │ ├── PartDesign/ # Part Design workbench
│ │ ├── Sketcher/ # Sketcher workbench
│ │ ├── AddonManager/ # Addon manager (submodule)
│ │ └── ... # Other stock FreeCAD modules
│ └── 3rdParty/
│ ├── OndselSolver/ # Assembly solver (submodule)
│ └── GSL/ # Guidelines Support Library (submodule)
├── mods/ # Kindred addon workbenches (submodules)
│ ├── ztools/ # ztools workbench
│ └── silo/ # Silo parts database
├── kindred-icons/ # SVG icon library (~200 icons)
├── resources/ # Branding, desktop integration
│ ├── branding/ # Logo, splash, icon generation scripts
│ └── icons/ # Platform icons (.ico, .icns, hicolor)
├── package/ # Packaging scripts
│ ├── debian/ # Debian package
│ ├── ubuntu/ # Ubuntu-specific
│ ├── fedora/ # RPM package
│ ├── rattler-build/ # Cross-platform bundles (AppImage, DMG, NSIS)
│ └── WindowsInstaller/ # NSIS installer definition
├── .gitea/workflows/ # CI/CD pipelines
│ ├── build.yml # Build + test on push/PR
│ └── release.yml # Release on tag push
├── tests/ # Test suite
│ ├── src/ # C++ test sources
│ └── lib/ # Google Test framework (submodule)
├── cMake/ # CMake helper modules
├── docs/ # Documentation (this book)
├── tools/ # Dev utilities (build, lint, profile)
├── contrib/ # IDE configs (VSCode, CLion, debugger)
├── data/ # Example and test data
├── CMakeLists.txt # Root build configuration
├── CMakePresets.json # Platform build presets
├── pixi.toml # Pixi environment and tasks
├── CONTRIBUTING.md # Contribution guide
├── README.md # Project overview
├── LICENSE # LGPL-2.1-or-later
└── .pre-commit-config.yaml # Code quality hooks
```
## Git submodules
| Submodule | Path | Source | Purpose |
|-----------|------|--------|---------|
| ztools | `mods/ztools` | `git.kindred-systems.com/forbes/ztools` | Unified workbench |
| silo-mod | `mods/silo` | `git.kindred-systems.com/kindred/silo-mod` | Parts database |
| OndselSolver | `src/3rdParty/OndselSolver` | `git.kindred-systems.com/kindred/solver` | Assembly solver |
| GSL | `src/3rdParty/GSL` | `github.com/microsoft/GSL` | C++ guidelines library |
| AddonManager | `src/Mod/AddonManager` | `github.com/FreeCAD/AddonManager` | Extension manager |
| googletest | `tests/lib` | `github.com/google/googletest` | Test framework |
## Key files
| File | Purpose |
|------|---------|
| `src/Mod/Create/Init.py` | Console-phase bootstrap — loads addons |
| `src/Mod/Create/InitGui.py` | GUI-phase bootstrap — registers workbenches, deferred setup |
| `src/Gui/FileOrigin.h` | Abstract file origin interface (Kindred addition) |
| `src/Gui/Stylesheets/KindredCreate.qss` | Catppuccin Mocha theme |
| `pixi.toml` | Build tasks and dependencies |
| `CMakeLists.txt` | Root CMake configuration |