# Building from Source

## Prerequisites

- **git** with submodule support
- **[pixi](https://pixi.sh)** — conda-based dependency manager and task runner

Pixi handles all other dependencies (CMake, compilers, Qt6, OpenCASCADE, etc.).

## Clone

```bash
git clone --recursive ssh://git@git.kindred-systems.com:2222/kindred/create.git
cd create
```

If cloned without `--recursive`:
```bash
git submodule update --init --recursive
```

The repository includes several submodules:

| Submodule | Path | Source |
|-----------|------|--------|
| silo-mod | `mods/silo` | `git.kindred-systems.com/kindred/silo-mod` |
| gears | `mods/gears` | `git.kindred-systems.com/kindred/gears` |
| datums | `mods/datums` | `git.kindred-systems.com/kindred/datums` |
| solver | `mods/solver` | `git.kindred-systems.com/kindred/solver` |
| OndselSolver | `src/3rdParty/OndselSolver` | `git.kindred-systems.com/kindred/solver` |
| GSL | `src/3rdParty/GSL` | `github.com/microsoft/GSL` |
| AddonManager | `src/Mod/AddonManager` | `github.com/FreeCAD/AddonManager` |
| googletest | `tests/lib` | `github.com/google/googletest` |

## Build

```bash
pixi run configure
pixi run build
pixi run install
pixi run freecad
```

By default these target the **debug** configuration. For release builds:

```bash
pixi run configure-release
pixi run build-release
pixi run install-release
pixi run freecad-release
```

## All pixi tasks

| Task | Description |
|------|-------------|
| `initialize` | `git submodule update --init --recursive` |
| `configure` | CMake configure (debug) |
| `configure-debug` | CMake configure with debug preset |
| `configure-release` | CMake configure with release preset |
| `build` | Build (debug) |
| `build-debug` | `cmake --build build/debug` |
| `build-release` | `cmake --build build/release` |
| `install` | Install (debug) |
| `install-debug` | `cmake --install build/debug` |
| `install-release` | `cmake --install build/release` |
| `test` | Run tests (debug) |
| `test-debug` | `ctest --test-dir build/debug` |
| `test-release` | `ctest --test-dir build/release` |
| `freecad` | Launch FreeCAD (debug) |
| `freecad-debug` | `build/debug/bin/FreeCAD` |
| `freecad-release` | `build/release/bin/FreeCAD` |

## CMake presets

The project provides presets in `CMakePresets.json` for each platform and build type:

- `conda-linux-debug` / `conda-linux-release`
- `conda-macos-debug` / `conda-macos-release`
- `conda-windows-debug` / `conda-windows-release`

All presets inherit from a `common` base that enables `CMAKE_EXPORT_COMPILE_COMMANDS` and configures job pools. The `conda` presets use the Ninja generator and pick up compiler paths from the pixi environment.

## Platform notes

**Linux:** Uses clang from conda-forge. Requires kernel-headers, mesa, X11, and libspnav (all provided by pixi). Uses the mold linker for faster link times.

**macOS:** Minimal extra dependencies — pixi provides nearly everything. Tested on both Intel and Apple Silicon.

**Windows:** Requires pthreads-win32 and MSVC. The conda preset configures the MSVC toolchain automatically when run inside a pixi shell.

## Caching

The build uses **ccache** for compilation caching:
- Maximum cache size: 4 GB
- Compression: zlib level 6
- Sloppiness mode enabled for faster cache hits

ccache is auto-detected by CMake at configure time.

## Common problems

**Submodules not initialized:** If you see missing file errors for addon modules, run `pixi run initialize` or `git submodule update --init --recursive`.

**Pixi not found:** Install pixi from <https://pixi.sh>.

**ccache full:** Clear with `ccache -C` or increase the limit in your ccache config.

**Preset not found:** Ensure you are running CMake from within a pixi shell (`pixi shell`) so that conda environment variables are set.