No description
Find a file
2026-11-20 14:17:33 +08:00
config 261021/update: folder stucture, readme, and manifest-nightly 2026-10-21 09:14:33 +08:00
scripts update: comfaccad 1.1.1 2026-11-13 13:50:46 +08:00
tests Add a "Check for updates now" button to the ComfacCAD preferences page 2026-11-20 06:04:30 +00:00
ZZZ_AutoSetup Add a "Check for updates now" button to the ComfacCAD preferences page 2026-11-20 06:04:30 +00:00
.gitignore added .gitignore 2026-10-22 09:04:04 +08:00
comfaccad_update.py update 1.1.1 hotfix 2026-11-13 14:27:06 +08:00
get_comfaccad.py Add a version-free download path: README section + get_comfaccad.py 2026-11-20 06:03:47 +00:00
MAINTAINING.md Add a "Check for updates now" button to the ComfacCAD preferences page 2026-11-20 06:04:30 +00:00
manifest-nightly.json updated: weekly 261120-2 2026-11-20 14:17:33 +08:00
manifest.json update 1.1.1 hotfix 2026-11-13 14:27:06 +08:00
README.md Add a version-free download path: README section + get_comfaccad.py 2026-11-20 06:03:47 +00:00

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)

  1. Open the latest stable release and download ZZZ_AutoSetup.zip — the updater. It is the only file you need.
  2. Unzip it, and rename the folder inside from ZZZ_AutoSetup-<version> to exactly ZZZ_AutoSetup.
  3. Move that folder into FreeCAD's Mod folder (create Mod if it is not there yet):
    • Windows: %APPDATA%\FreeCAD\v1-1\Mod
    • Linux: ~/.local/share/FreeCAD/v1-1/Mod
  4. 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:

  1. Lightweight Git Fingerprint: Heavy pre-compiled dependencies and binary toolchains are tracked locally and excluded from Git using .gitignore to maintain peak Forgejo performance.
  2. Build-Time Assembly: A localized Python pipeline combines the core application with heavy binaries right before compiling into a unified Windows 10/11 .exe installer via Inno Setup.
  3. 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)

  1. Edit the workbench code in the live install (C:\ComfacCAD\Mod\<workbench>).
  2. Run python comfaccad_update.py, choose 1 (mirror the changed workbench).
  3. Choose 2 (rebuild the stable installer). Output lands in installer-out\.

Ship a stable release

  1. Choose 3 to bump version.txt (if needed).
  2. Choose 5 — build the release\ zips.
  3. Answer y when prompted to publish (upload + verify + write manifest.json).
  4. Commit + push manifest.json to main, then choose 2 to rebuild the installer.

Refresh the nightly channel

  • Choose 6 — build all nightlies; answer y to also upload the -nightly assets, then commit + push manifest-nightly.json to main.

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 by comfaccad_update.py.
  • Option 5 builds, then prompts before publishing. Answer n to stop at the zips (left in release\); answer y to cut the release.
  • Option 2 requires Inno Setup at C:\Program Files\Inno Setup 7\ISCC.exe and a populated ComfacCAD\ + ComfacCAD\dependencies\ staging tree.
  • Publishing (option 5 y, option 6 upload) needs write access to comfac-dist/ComfacCAD; a read-only token only covers plain nightly builds (option 6 with n).