| config | ||
| scripts | ||
| tests | ||
| ZZZ_AutoSetup | ||
| .gitignore | ||
| comfaccad_update.py | ||
| get_comfaccad.py | ||
| MAINTAINING.md | ||
| manifest-nightly.json | ||
| manifest.json | ||
| README.md | ||
ComfacCAD Core Engine
Download the latest version
Latest stable release — this link always opens the newest release, so there is no version number to look up.
ComfacCAD is a set of workbenches for FreeCAD 1.1. Install FreeCAD first, then pick one route.
Already running ComfacCAD? There is nothing to download. It checks for a new release each time FreeCAD starts and asks before updating.
One command (needs Python 3)
Windows (PowerShell or Command Prompt):
curl.exe -LO https://git.comfac-it.net/comfac-dist/ComfacCAD/raw/branch/main/get_comfaccad.py
python get_comfaccad.py --install
Linux / macOS:
curl -LO https://git.comfac-it.net/comfac-dist/ComfacCAD/raw/branch/main/get_comfaccad.py
python3 get_comfaccad.py --install
This fetches the latest release, checks every file against its published sha256, and adds the workbenches to FreeCAD's Mod folder. Then start FreeCAD. It never replaces a workbench that is already installed.
| Command | What it does |
|---|---|
get_comfaccad.py --install |
Download the latest release and add it to FreeCAD |
get_comfaccad.py |
Only download the latest release, into ./ComfacCAD-<version>/ (e.g. to carry to an offline PC) |
get_comfaccad.py --list |
Show what the latest release contains |
get_comfaccad.py --install --mod-dir <folder> |
Install into a specific Mod folder instead of the detected one |
By hand (no Python)
- Open the latest stable release and download
ZZZ_AutoSetup.zip— the updater. It is the only file you need. - Unzip it, and rename the folder inside from
ZZZ_AutoSetup-<version>to exactlyZZZ_AutoSetup. - Move that folder into FreeCAD's
Modfolder (createModif it is not there yet):- Windows:
%APPDATA%\FreeCAD\v1-1\Mod - Linux:
~/.local/share/FreeCAD/v1-1/Mod
- Windows:
- Start FreeCAD. The updater downloads the workbenches in the background (progress is in the Report view); restart FreeCAD once it has finished so they load.
The rename in step 2 matters: the updater looks for a folder named ZZZ_AutoSetup, and installs a second copy of itself if it does not find one.
What a release contains
One zip per workbench, the updater (ZZZ_AutoSetup.zip) and the theme. FreeCAD itself is not included, and the full Windows installer (FreeCAD plus the CFD tools in one .exe) is not published on this page.
Testing builds live on the rolling nightly release, whose files are replaced in place. To follow it, switch the channel in FreeCAD under Edit → Preferences → ComfacCAD.
About this repository
This repository is the central management hub for ComfacCAD, a custom-tailored engineering ecosystem built on top of the portable distribution of FreeCAD v1.1.3.
This project uses a decoupled, hybrid architecture to manage its massive deployment footprints:
- Lightweight Git Fingerprint: Heavy pre-compiled dependencies and binary toolchains are tracked locally and excluded from Git using
.gitignoreto maintain peak Forgejo performance. - Build-Time Assembly: A localized Python pipeline combines the core application with heavy binaries right before compiling into a unified Windows 10/11
.exeinstaller via Inno Setup. - Runtime Asynchronous Auto-Updater: Developer workbenches are decoupled entirely from the core installer. A multi-threaded startup script queries a centralized manifest on this repo, downloading and syncing modules directly on user launch.
📂 Repository Structure
ComfacCAD/
├── 📁 config/ # Channel markers + per-channel manifests
│ ├── 📄 channel-stable.txt # "stable" marker
│ ├── 📄 channel-nightly.txt # "nightly" marker
│ ├── 📄 manifest-stable.json # stable first-run manifest
│ └── 📄 manifest-nightly.json # nightly first-run manifest
│
├── 📁 scripts/ # Build + release tooling
│ ├── 📄 assemble_build.py # Compiles the installer via Inno Setup
│ ├── 📄 nightly_release.py # Nightly build + optional upload
│ ├── 📄 publish_release.py # Stable release (publish → verify → manifest)
│ ├── 📄 Installer_Config.iss # Inno Setup script
│ └── 📄 try_update_prompt.py # Sandboxed update-consent prompt launcher
│
├── 📁 tests/ # Offline test suites
│ └── 📄 updater_consent_test.py # Updater consent-flow tests
│
├── 📁 ZZZ_AutoSetup/ # Runtime auto-updater bootstrap
│ ├── 📄 InitGui.py # Async network update & dependency injector
│ └── 📄 ComfacUpdatePrefs.py # Preferences page
│
├── 📄 get_comfaccad.py # End users: download / install the latest release
├── 📄 comfaccad_update.py # Single entry point (maintenance menu)
├── 📄 manifest.json # [TRACKED BY GIT] Central workbench index (source of truth)
├── 📄 manifest-nightly.json # Committed nightly manifest
├── 📄 MAINTAINING.md # Maintenance runbook
└── 📄 README.md # This file
ComfacCAD Installer — Tooling Guide
This workspace builds and publishes the ComfacCAD distribution: a custom FreeCAD v1.1.3 payload compiled into a Windows installer, with four auto-updating workbenches decoupled from the core installer.
Everything is driven from a single entry point: comfaccad_update.py.
Prerequisites
| Requirement | Why |
|---|---|
| Python 3 | Runs the scripts |
Inno Setup 7 (ISCC.exe at C:\Program Files\Inno Setup 7\) |
Compiles the installer (menu option 2) |
Git (with access to git.comfac-it.net) |
Builds release archives / publishes releases (options 5, 6) |
.env at the project root with FORGEJO_TOKEN |
Fetch private cgg/* sources and publish to comfac-dist/ComfacCAD (options 5 publish, 6 upload) |
ComfacCAD\ staging folder (portable FreeCAD + dependencies\) |
The installer payload |
ComfacCAD-repo\ComfacCAD\ clone |
Source of truth for the manifest + bootstrap |
A live install at C:\ComfacCAD\Mod (Windows) |
Source for "Update ComfacCAD tools" (option 1) |
The .env token needs read on cgg/* and write on
comfac-dist/ComfacCAD (only required for --upload / publish_release.py).
Running it
cd "C:\ComfacCAD installer"
python comfaccad_update.py
This opens an interactive menu. Pick a number and press Enter.
Menu reference
| # | Option | What it does | Talks to Forgejo? |
|---|---|---|---|
| 1 | Update ComfacCAD tools | Mirrors selected workbenches from the live install (C:\ComfacCAD\Mod) into the staging ComfacCAD\Mod. Skips ZZZ_AutoSetup (that's staged from the repo). |
❌ No |
| 2 | Update installer | Full pipeline: mirror all tools → stage bootstrap → regenerate manifests → compile the stable installer via Inno Setup (output to installer-out\). |
❌ No |
| 3 | Update versions | Bumps a workbench's version.txt (major / minor / patch), interactively. |
❌ No |
| 4 | Update manifest only | Regenerates config\manifest-stable.json, config\manifest-nightly.json, and the channel-*.txt markers from the repo's manifest.json. |
❌ No |
| 5 | Build + publish stable release | Builds the four stable workbench zips from each repo's git tag (git archive) into release\, then prompts to publish them (publish_release.py). |
⚠️ Only if you answer y |
| 6 | Publish nightly workbenches | Runs scripts\nightly_release.py: fetches each workbench's dev branch, stamps version.txt, hashes, writes zips to nightly-out\ + manifest-nightly.json. Prompts whether to upload to the rolling nightly release. |
⚠️ Only if you answer y |
| 7 | Quit | Exits the menu. | ❌ No |
IMPORTANT — branches vs tags
Option 5's archive build is tag-driven, not branch-driven. It runs
git archive <tag> where the tag is vX.Y.Z read from that workbench's
version.txt in C:\ComfacCAD\Mod. It does not care which branch is checked
out in that repo — the only requirement is that the tag exists (has been
fetched) in the local C:\ComfacCAD\Mod\<workbench> repo. The tag normally points
at the stable main commit, but git archive reads the tag directly, so the
checked-out branch is irrelevant.
Option 6 ("Publish nightly workbenches") is branch-driven. Each workbench's
source branch (develop/dev) must exist on Forgejo, as configured in
scripts\nightly_release.py's WORKBENCHES list. If a branch is missing, that
workbench aborts with a "has no '' branch" error.
Non-interactive flags
You can skip the menu for scripted runs:
| Flag | Effect |
|---|---|
--update-manifest |
Mirror + regenerate manifest variants and channel files, then exit |
--pin-tags |
Pin stable manifest entries to archive/vX.Y.Z.zip (needs published tags) |
--refresh-checksums |
Download each archive and record its sha256 in the source manifest |
--build-archives |
Build each workbench's release zip from its version tag, then exit |
Examples:
python comfaccad_update.py --build-archives
python comfaccad_update.py --update-manifest --pin-tags
python comfaccad_update.py --update-manifest --refresh-checksums
Typical workflows
Update a workbench and rebuild the installer (stable)
- Edit the workbench code in the live install (
C:\ComfacCAD\Mod\<workbench>). - Run
python comfaccad_update.py, choose 1 (mirror the changed workbench). - Choose 2 (rebuild the stable installer). Output lands in
installer-out\.
Ship a stable release
- Choose 3 to bump
version.txt(if needed). - Choose 5 — build the
release\zips. - Answer y when prompted to publish (upload + verify + write
manifest.json). - Commit + push
manifest.jsontomain, then choose 2 to rebuild the installer.
Refresh the nightly channel
- Choose 6 — build all nightlies; answer
yto also upload the-nightlyassets, then commit + pushmanifest-nightly.jsontomain.
Channels
The installer ships in two channels, selected at compile time:
- stable — the default; pinned, permanent releases.
- nightly — rolling; assets are replaced in place.
The channel artifacts live in config\:
channel-stable.txt/channel-nightly.txt— one-word markers.manifest-stable.json/manifest-nightly.json— per-channel first-run manifests.
The menu option 2 builds stable. To compile a nightly installer directly:
python scripts\assemble_build.py --channel nightly
Key paths
| Path | Purpose |
|---|---|
scripts\assemble_build.py |
Compiles the installer via Inno Setup |
scripts\nightly_release.py |
Nightly build + optional upload |
scripts\publish_release.py |
Stable release (publish → verify → manifest) |
scripts\Installer_Config.iss |
Inno Setup script; OutputDir = installer-out\ |
config\ |
Channel markers + manifests |
release\ |
Stable workbench zips |
nightly-out\ |
Nightly workbench zips |
installer-out\ |
Compiled .exe installers |
ComfacCAD\ |
Installer payload (FreeCAD + Mod + dependencies) |
ComfacCAD-repo\ComfacCAD\ |
Dist repo clone (manifest + bootstrap source) |
Gotchas
- Never commit
.env. It holds the Forgejo token and is excluded from the installer payload bycomfaccad_update.py. - Option 5 builds, then prompts before publishing. Answer
nto stop at the zips (left inrelease\); answeryto cut the release. - Option 2 requires Inno Setup at
C:\Program Files\Inno Setup 7\ISCC.exeand a populatedComfacCAD\+ComfacCAD\dependencies\staging tree. - Publishing (option 5
y, option 6 upload) needs write access tocomfac-dist/ComfacCAD; a read-only token only covers plain nightly builds (option 6 withn).