Dependency build scripts (Cargo, vcpkg, pip) run third-party code, so MitCad is built and tested only in isolated environments. Source and git stay on the host; the working tree is mirrored one way into the build environment before each build.
- Windows host: a WSL distro (no interop, no Windows drives) for Linux, a Hyper-V VM over SSH for Windows.
- Linux host: any Ubuntu 24.04 container or VM;
install-packages.shandsetup-user.shwork there. A host with a newer system builds releases in an Ubuntu 24.04 build root (Linux on a newer host). - Mac host (Apple Silicon): a macOS guest VM over SSH for macOS (macOS: the build VM).
One-time setup (<repo> is the checkout as seen from the distro):
wsl --install Ubuntu-24.04 --name mitcad-dev
wsl -d mitcad-dev -u root -e sh -c "cp '/mnt/c/<repo>/tools/dev-env/wsl.conf' /etc/wsl.conf"
wsl --terminate mitcad-devThen, from Git Bash:
tools/dev-env/sync-to-wsl.sh
wsl -d mitcad-dev --cd "~/src/mitcad" -- sudo tools/dev-env/install-packages.sh
wsl -d mitcad-dev --cd "~/src/mitcad" -- bash -lc "tools/dev-env/setup-user.sh"
wsl -d mitcad-dev --cd "~/src/mitcad" -- bash -lc "cmake --preset dev && cmake --build --preset dev && ctest --preset dev"Script (tools/dev-env) |
Use |
|---|---|
sync-to-wsl.sh [distro] [dir] |
Mirrors tracked and non-ignored untracked files into the distro (default mitcad-dev, ~/src/mitcad). Only files whose content differs are replaced and get the sync time, so switching branches rebuilds exactly what changed. Deletes removed files; keeps build/ and CMakeUserPresets.json. |
install-packages.sh |
System packages (compilers, CMake, Ninja, ccache, rsync, X11/OpenGL headers, gdb, Xvfb, xdotool, rsvg-convert, ImageMagick; mosquitto for the live updates' tests, its service disabled; libsecret's headers for QtKeychain and GNOME's keyring for the keychain's test; the system libraries CEF's runtime loads, for the web browser component). Run as root. |
setup-user.sh |
Pinned per-user toolchain: Rust from rust-toolchain.toml, cargo-deny, vcpkg at vcpkg.json's builtin-baseline, Qt via aqtinstall, the pinned CEF distribution (fetch-cef.sh, MITCAD_CEF_ROOT in ~/.profile; the web browser component), the render worker's Cycles with its CUDA device and Open Image Denoise (build-cycles.sh --cuda, once; MITCAD_RENDER_CUDA=0 without CUDA); writes CMakeUserPresets.json (dev = Linux debug). Under WSLg sets GALLIUM_DRIVER=d3d12; MITCAD_GPU_ADAPTER=NVIDIA picks a GPU. |
install-appimage-tools.sh |
AppImage tools into ~/appimage-tools (MITCAD_APPIMAGE_TOOLS), see below. |
build-root.sh |
An Ubuntu 24.04 build root on a newer Linux host, entered with bubblewrap, see below. |
Parallel checkouts: sync-to-wsl.sh mitcad-dev src/mitcad-<name> and copy
CMakeUserPresets.json from the first one.
Gotchas:
- Use a login shell (
bash -lc,bash -l -s) so cargo is onPATH. wsl.exeexpands$on the Windows side. In Git Bash setMSYS_NO_PATHCONV=1and pipe anything non-trivial as a script:wsl -d mitcad-dev -- bash -l -s < script.sh. From PowerShell usecmd /c 'wsl ... < script.sh'(a PowerShell pipe adds a BOM and\r)./tmpin WSL can be emptied mid-session; keep files in~.- Keep
sudopassword-protected; install as root withwsl -d mitcad-dev -u root ....
The Linux AppImage takes glibc and libstdc++ from the user's system, so it
needs those of the system it was built on
(Linux AppImage). A Linux host newer than Ubuntu 24.04
builds the release in an Ubuntu 24.04 build root
(tools/dev-env/build-root.sh): a debootstrapped noble file system that
bubblewrap (bwrap, with unprivileged user namespaces) enters as the
host's own user, with a home folder of its own that holds the toolchain
built against the root's glibc. Builds and tests run there unchanged:
check-all.sh, the presets and appimage-test.sh see an Ubuntu 24.04
system.
# As root, once (again later to update the root's packages):
tools/dev-env/build-root.sh create <root>
# As the user, once: Rust, vcpkg, Qt, the render worker's libraries (with
# CUDA) and the AppImage tools into <home>; CMakeUserPresets.json in
# <home>/src/mitcad
tools/dev-env/build-root.sh setup --bind <data folder> <root> <home> <checkout>
# Any command in the root (default: a login shell)
tools/dev-env/build-root.sh run --bind <data folder> <root> <home> bash -lc 'cmake --preset dev && ...'run mounts the root's /usr, /etc and /var read-only and binds
<home>, each --bind folder (at the same path), /tmp (shared, so
Xvfb display numbers do not clash with the host's), the user's runtime
folder (so check-all.sh gets its memory-capped systemd-run --user
scope) and the network. The test runner's history (<home>/.mitcad, the
time and memory of each test, tools/testrun)
is the user's own ~/.mitcad, shared both ways: a new root schedules from
what the host's runs learnt, its runs add to it, and neither side falls
back to an older copy. The environment is cleared but for the MITCAD_*
variables (corpora, test slots) and the build parallelism
(CMAKE_BUILD_PARALLEL_LEVEL, CARGO_BUILD_JOBS,
VCPKG_MAX_CONCURRENCY); a MITCAD_* path outside the bound folders is
reported, since the root cannot see it. The user's /etc/passwd entry
names <home> as the home folder. Copy the checkout's
CMakeUserPresets.json from <home>/src/mitcad, not from the host,
whose render prefix and toolchain are the host's.
On such a host, check-all.sh also compiles the C++ files a change
touches with the root's GCC (the root-compile row of
the check script) when MITCAD_LINUX_BUILD_ROOT names
the root, so that code only the host's newer compiler accepts fails before
a merge rather than in the release.
build-root.sh create --plain <root> makes a second root with only what an
Ubuntu 24.04 desktop has for running MitCad (glibc, libstdc++, X11/xcb,
Mesa, GLVND's libOpenGL, fontconfig, D-Bus, GLib) plus Xvfb and
xdotool: a clean 24.04 to start an AppImage on once, on a hidden display.
Memory: the root's GCC 13 and ld need more than a newer toolchain
(about 2.5 GB per AVX-512 compile of a render library and per link of a
debug test executable). Under a memory cap, lower VCPKG_MAX_CONCURRENCY
and MITCAD_RENDER_JOBS for setup, and CMAKE_BUILD_PARALLEL_LEVEL
(or a link job pool, -DCMAKE_JOB_POOLS=link=1 -DCMAKE_JOB_POOL_LINK=link) for a fresh build.
A Hyper-V VM with Visual Studio 2022+ (C++ desktop tools) and OpenSSH:
tools/dev-env/sync-to-vm.sh <user>@<vm-host>
ssh -i <key> <user>@<vm-host> "powershell -ExecutionPolicy Bypass -File C:\dev\src\mitcad\tools\dev-env\setup-windows.ps1"
ssh -i <key> <user>@<vm-host> "cd /d C:\dev\src\mitcad && tools\dev-env\msvc.cmd cmake --preset dev -DMITCAD_MESA_DIR=C:/dev/mesa/bin && tools\dev-env\msvc.cmd cmake --build --preset dev && tools\dev-env\msvc.cmd ctest --preset dev"| Script | Use |
|---|---|
sync-to-vm.sh [user@host] [dir] |
Like sync-to-wsl.sh, over SSH. Defaults: MITCAD_VM, MITCAD_VM_DIR (C:/dev/src/mitcad), MITCAD_VM_KEY (~/.ssh/mitcad_vm). |
setup-windows.ps1 [-Repo <dir>] |
Installs Git, CMake, Ninja, Rustup, Python, NSIS (winget), ccache, the pinned Rust toolchain, cargo-deny, vcpkg, Qt and the pinned CEF distribution (fetch-cef.ps1, the user's MITCAD_CEF_ROOT) under C:\dev, the render worker's libraries (build-cycles.ps1 -Cuda, once; MITCAD_RENDER_CUDA=0 without CUDA); writes CMakeUserPresets.json (dev = Windows release). Run as administrator. |
setup-ccache-windows.ps1 [-Dir] [-MaxSize] |
ccache into C:\dev\ccache, on the machine PATH, cache limit 4G (a build with the render worker; 2G was cleaned over and over). |
setup-mesa-windows.ps1 [-Out] [-Vcpkg] [-Jobs] |
Builds Mesa's llvmpipe (~20 min) into <Out>\bin (default C:\dev\mesa). Needed in a VM without a GPU (Windows offers only OpenGL 1.1). |
msvc.cmd <command> |
Runs a command in the VS x64 environment, rebuilding PATH from the registry first (SSH sessions keep a stale one). |
-DMITCAD_MESA_DIR=<dir>/bin copies Mesa's DLLs next to mitcad.exe
(development only, never in a release) and enables the Windows UI tests.
A second checkout in the VM needs its own directory and preset file.
An arm64 macOS guest on Apple's Virtualization.framework, e.g. with lume (MIT) or UTM; nothing is built on the host:
brew install lume
lume config telemetry disable
lume create mitcad-mac --cpu 8 --memory 16 --disk-size 150 \
--display 2880x1800 --ipsw latest --unattended tahoe
lume run mitcad-mac --detach --display none --vnc disabled
lume get mitcad-mac # the guest's IP addressNo shared folders or clipboard; turn on Remote Login and install the Xcode
Command Line Tools with the macOS 27 SDK or newer, including the Metal SDK
headers and frameworks. The deployment target remains macOS 14.4; newer
AppKit APIs use runtime availability checks. The
CPU and Metal dependency builds use those tools. Open Image Denoise's
Metal device additionally needs Apple's offline metal and metallib
tools, supplied by Xcode or a separately installed Metal toolchain. Check
xcrun --sdk macosx metal --version in the build environment; the dependency
builder stops with setup instructions if the tools are missing. Cycles
compiles its own Metal kernels through the system's runtime compiler. Metal rendering still
needs a device and driver that can compile and execute those kernels;
see rendering.md. The UI tests need a user
logged in at the console (the unattended setup logs in lume) and a
screen of at least 2880 x 1800, or macOS shrinks their 1280 x 800 window.
Without a GPU, OpenGL runs on Apple's software renderer: enough for the
tests, but slow.
export MITCAD_MAC=<user>@<guest>
tools/dev-env/sync-to-mac.sh
ssh -i ~/.ssh/mitcad_mac $MITCAD_MAC "~/src/mitcad/tools/dev-env/setup-macos.sh"
ssh -i ~/.ssh/mitcad_mac $MITCAD_MAC "cd ~/src/mitcad && cmake --preset dev && cmake --build --preset dev && ctest --preset dev"| Script | Use |
|---|---|
sync-to-mac.sh [user@host] [dir] |
Like sync-to-vm.sh: stages the archive, compares contents and replaces only changed files with the sync time; unchanged files keep their times, and deleted files disappear. Keeps build/ and CMakeUserPresets.json; no ._* files or extended attributes. Defaults: MITCAD_MAC, MITCAD_MAC_DIR (~/src/mitcad), MITCAD_MAC_KEY (~/.ssh/mitcad_mac). |
setup-macos.sh [--compiler-caches-only] |
CMake, Ninja, ccache (universal) and sccache (arm64) release archives into ~/.local (not Homebrew), the pinned Rust toolchain, cargo-deny, vcpkg at vcpkg.json's baseline, Qt via aqtinstall (~/Qt/<version>/macos), the pinned CEF distribution (fetch-cef.sh), the render worker's libraries (build-cycles-macos.sh, once); writes CMakeUserPresets.json (dev = macos-debug). Downloads are checked against the SHA-256 pins in versions.sh; an empty pin stops it unless MITCAD_SKIP_HASH=1. The optional flag installs only the two compiler caches, leaving other dependencies, shell files and presets alone. |
tools/dev-env/versions.sh holds the pins setup-user.sh and
setup-macos.sh share; the Windows script mirrors them by hand. The
presets macos-debug and macos-release build for arm64 with deployment
target 14.4 (the Qt 6.12 minimum) and the overlay triplet
triplets/arm64-osx-dynamic.cmake (OCCT as dylibs, the same deployment
target for vcpkg's libraries).
The Darwin arm64 target of AppleClang 21.0.0 and Rust 1.99.0 (LLVM 23.1.1)
already selects apple-m1. The former's driver command and the latter's
target specification were inspected with a macOS 14.4 deployment target;
Rust also enables dotprod, fp16 and lse. An absent explicit -mcpu
or target-cpu flag therefore does not imply generic AArch64 code in
this toolchain. OCCT and the renderer use the same AppleClang arm64
default. Adding the same flag would not change that CPU baseline and
does not justify rebuilding the dependency prefix. Never use native
for shipped binaries; recheck the compiler defaults when changing tools.
MITCAD_MACOS_THIN_LTO defaults to ON for arm64-only Mac builds and
affects their Release and RelWithDebInfo configurations. CMake IPO uses
ThinLTO for C++; explicit release-only compile/link options cover
Objective-C++, since CMake 3.31 does not emit IPO flags for its objects.
The option requires a successful C++ IPO link probe and both languages'
ThinLTO support; an unsupported compiler stops configuration instead of
silently dropping LTO. Set MITCAD_MACOS_THIN_LTO=OFF to disable it.
Debug, Rust profiles, Linux and Windows remain unchanged. Neither vcpkg
nor the Cycles/OIDN build inputs change, so the existing compatible
dependency prefix remains usable. Inspect generated compile commands,
including Objective-C++, when changing this configuration.
A controlled release comparison on the physical M1 Max with the toolchain above used one synthetic 17-feature design and the CPU renderer's built-in 640 x 360, 32-sample scene. Five alternating CLI/render observations per configuration gave these medians:
| Workload | Baseline | ThinLTO candidate |
|---|---|---|
| CLI recompute | 551.9 ms | 551.8 ms |
| CLI process wall time | 0.71 s | 0.71 s |
| CPU render, including denoising | 1.804 s | 1.758 s |
| Render-worker process wall time | 1.93 s | 1.89 s |
The candidate included an experimental Rust release profile with ThinLTO and four codegen units. It did not improve this geometry-dominated CLI fixture, so that Rust change was rejected. The render worker does not link Rust: its 2.55% render-time improvement supports retaining C++/Objective-C++ ThinLTO independently. This is a narrow CPU result, not a general CAD or Metal speedup. Repeated C++ and Objective-C++ compiler commands hit ccache. The combined experimental rebuild took 518.85 s plus 11.17 s for the explicit Objective-C++ correction; those include the discarded Rust experiment and are not a clean build-time comparison of the retained setting. The candidate geometry CTest passed in 194.27 s. Application and packaging acceptance are separate checks; this measurement alone does not establish them.
Final validation of the retained C++/Objective-C++ setting used a warning-free native arm64 Qt Release-configuration application build with the original Rust profile restored. Its render-worker SHA-256 stayed identical to the measured candidate, confirming that the renderer gain does not depend on the rejected Rust experiment. The geometry binary also stayed identical to the one that passed the geometry CTest. Application unit tests, CLI rendering, the 36-case IOSurface shader test, SPDX checks and the complete Qt modelling/version-history workflow passed. Required physical-Metal/OIDN preview, orbit, zoom, picking, resize and shutdown passed without fallback or capability skips. Generated Debug commands contain no LTO flags and no Cargo profile override; Qt remains the default frontend. This scoped validation does not claim a new signed release or package acceptance.
Compiler caches persist outside checkouts and build folders. ccache uses
~/Library/Caches/ccache by default (ccache --show-config shows any user
override); CMake enables its launcher for both C++ and Objective-C++,
including the macOS sources built with -fobjc-arc, unless that language
already has a launcher. MITCAD_COMPILER_CACHE=OFF disables these automatic
launchers. Linking, bundle assembly and hardened-runtime signing still run
normally; no cache executable is installed into the application bundle.
MITCAD_RUST_COMPILER_CACHE defaults to ON on macOS and OFF elsewhere.
When sccache is found, both Corrosion's Rust targets and the Cargo test-build
fixtures (debug and release, plus doctests) use it through RUSTC_WRAPPER,
with CARGO_INCREMENTAL=0 and the cache in
~/Library/Caches/Mozilla.sccache. A missing tool is reported at configure;
a wrapper/server failure fails the build, even if the shell sets
SCCACHE_IGNORE_SERVER_IO_ERROR=1. A different explicit RUSTC_WRAPPER
requires disabling the option. Direct cargo commands retain the shell's
configuration. After changing a running sccache server's cache directory,
stop it once with sccache --stop-server before the next build.
Use ccache --show-stats and sccache --show-stats to inspect cache use.
sccache caches eligible library compilations; binaries, test harnesses,
procedural macros and other compilations that call the linker still run.
The pinned sccache's Rust keys also include the working directory and
Cargo's manifest paths: workspace crates in a different checkout may miss
even when registry dependencies hit. Its SCCACHE_BASEDIRS setting does
not normalize those Rust keys. Cache hits across checkouts therefore need
actual validation and are not guaranteed for every crate; see upstream's
Rust limitations
and Rust key implementation.
MITCAD_CARGO_TARGET_DIR (a path; empty by default) keeps cargo's builds
outside the build folder, so that a new build folder reuses the Rust
crates built before while its C++ tree starts clean (release builds:
a fresh build folder, a persistent cargo folder). Empty, Corrosion builds
the library in <build>/cargo and the crates' test fixtures in
<build>/core/cargo-test. Set, they go to separate subfolders:
| Folder | What |
|---|---|
<dir>/lib |
the library build (Corrosion: mitcad_ffi, mitcad-release) |
<dir>/test-debug |
core.cargo_build and core.doctests |
<dir>/test-release |
core.cargo_build_release and core.doctests_release |
Corrosion always gives cargo a --target-dir inside the build folder, so
configure makes <build>/cargo a link to <dir>/lib: a symbolic link, or
a directory junction on Windows (no privilege needed). Delete such a build
folder with a tool that does not follow links (rmdir /s /q on Windows,
not Windows PowerShell 5.1's Remove-Item -Recurse, which descends into
junctions). Configure refuses a real <build>/cargo folder left by a build
without the variable, needs a single-configuration generator (the Ninja
presets), and removes the link again when the variable is cleared. The
lists of test binaries stay in <build>/core/cargo-test. Builds sharing
the folder wait for each other on cargo's lock. cargo's fingerprints and
Corrosion's folder name (<dir>/lib/core_<hash>, a hash of the manifest's
path) depend on the checkout's path: reuse needs the same source path, or
everything builds again beside the old builds. The test builds' folders
are swept after each build (below); the library's folder only grows, and
its owner trims it (e.g. deletes it when it passes a size limit or when
rust-toolchain.toml changes).
cargo keeps every unit it has built in its target folder: each change of a
dependency's version, of the selected packages' features, of flags or
environment, of the toolchain or of the checkout's path builds the units
again under new hashes (<name>-<hash> in deps/, .fingerprint/,
build/) beside the old ones, and the test folder grew to tens of GB
(mitcad#796). Three things keep <build>/core/cargo-test (or
<dir>/test-debug, <dir>/test-release) near the size of one build:
- Sweep. After a successful
core.cargo_build/core.cargo_build_release,core/cargo-tests.cmakereads the units the build named in its JSON messages (everycompiler-artifact, built or fresh, andbuild-script-executed) and removes from that profile's folder (debug/orrelease/underCARGO_TARGET_DIR) what they do not name:deps/files and folders<name>-<hash>.*of other hashes,.fingerprint/andbuild/folders of other hashes, and theincremental/sessions of crates no longer built (and a crate's oldest sessions beyond its number of units). It logs the count and size by kind. Programs' files and fingerprints stay (cargo's messages name a program only by its copy outsidedeps/), as does anything written after the build started. Nothing the build used is removed, so the next build of the same sources compiles nothing.MITCAD_CARGO_SWEEP=0in the environment turns the sweep off; do that when several checkouts share oneMITCAD_CARGO_TARGET_DIR, as each build would otherwise remove the others' units. - Jobs by memory. Unless
CARGO_BUILD_JOBSis set, the test builds run one cargo job per 2.5 GiB of the memory available when the build starts (at least one, at most the logical cores;MITCAD_CARGO_JOB_MIBchanges the 2.5 GiB): a rustc job of these builds (a large crate, or a test binary's link) takes up to about 2.5 GiB, and a job per core ran a Windows VM of 10-19 GB out of memory once the crates were split. On Linux a memory limit of the build's cgroup (check-all's slice, mitcad-testrun's scopes) counts as well. - Fixed incremental setting.
CARGO_INCREMENTALis part of the units' hashes, so one inherited from the shell built every MitCad crate a second time. The test builds and doctests set it themselves: on for debug, off for release (cargo's defaults), off for debug too with-DMITCAD_CARGO_TEST_INCREMENTAL=OFF(smaller folder, slower rebuilds of a changed crate) or with the Rust compiler cache. ACARGO_INCREMENTALin the shell no longer affects them. Other variables that change the hashes,RUSTFLAGSandCARGO_PROFILE_*/CARGO_BUILD_*among them, are still taken from the environment: keep them the same between runs. - Debug information.
[profile.test]incore/Cargo.tomlkeeps line tables only (debug = "line-tables-only"): panics and backtraces still show files and lines, while the test binaries, their.pdbfiles and their links shrink. The application's builds keep full debug information for the crash reports.CARGO_PROFILE_TEST_DEBUG=truebuilds the tests with full debug information for a debugger (as a second build; the sweep removes it after the next normal build).
The C++ programs link the Rust code as one static library,
<build>/core/libmitcad_ffi.a. In a Linux debug build it is about
2.1 GB: with split-debuginfo unpacked each crate's rlib carries its
.dwo files as members, the static library takes them all (about 4,200
.dwo members, 1.2 GB, which the linker never reads; debuggers read the
.dwo files in cargo's deps/ folder), and the 4,500 object members are
about 0.9 GB. Fourteen programs link it (the application, mitcad-cli and
twelve tests), and all of them become ready the moment the library is
built.
Each of those links with GNU ld charges about 1.5 GB to the build's
cgroup (test_bridge: 26-30 s, 1.8 GB peak RSS, of which 1.5 GB charged;
the application 62 s, 2.9 GB peak RSS). In mitcad#1441 two builds under systemd memory
limits started 22 such links at once; the memory went past the limits'
MemoryHigh with little swap allowed, and the kernel throttled every
ld in its reclaim instead of failing it: they ran at about 90 % CPU,
read nothing more and never finished. The same link of test_bridge in a
scope with MemoryHigh=1200M and no swap made no progress in 5 minutes;
with MemoryHigh=1600M it finished in 26 s. The library's size was not
the cause: GNU ld 2.46 links test_bridge against a copy of the library
padded to 3.2 GB (150,000 of its 267,000 symbol-table offsets past 2^31)
in the same 30 s, and without its .dwo members (0.93 GB) with the same
memory and 4 s faster.
So a Linux Ninja debug build runs these links in a job pool of their own,
mitcad_rust_link (cmake/RustLinkPool.cmake; configure prints
"Links with the Rust library: 14 programs, 3 at once"): three at a time,
at most about 7 GB together (the application and two tests), whatever
the build's parallelism, instead of about 25 GB for all fourteen. A fresh
dev build (CMAKE_BUILD_PARALLEL_LEVEL=8, in a 10 GB scope) linked all
fourteen against a 2.143 GB library in about 4 minutes after the library
was built. The other links and the compiles keep the build's parallelism.
-DMITCAD_RUST_LINK_JOBS=<n> changes the depth (0: no pool, every link at
once as before). Windows, macOS, the release builds and other generators
are unchanged. The pool finds the programs by their links (directly or
through a library that links mitcad_ffi), so a new program that links
the bridge joins it without a change here.
The pinned OCCT 8.0.1 defaults to USE_MMGR_TYPE=NATIVE. In this build,
Standard::Allocate calls calloc, and Standard::AllocateOptimal calls
malloc; MMGT_OPT does not select an allocator. Its environment
variable is read only when OCCT is compiled with USE_MMGR_TYPE=FLEXIBLE.
That configuration maps MMGT_OPT=0 to the system allocator, 1 to OCCT's
pool and 2 to the scalable allocator. The last option requires USE_TBB:
without it, OCCT's scalable-allocation calls fall back to the system
allocator. Inspect the actual build cache and
Standard.cxx
before comparing settings. A changed environment variable alone is not
evidence that the allocator changed.
Keep experimental libraries in a separate prefix. Verify the loaded
TKernel and Standard::GetAllocatorType() after the first OCCT allocation.
A process-wide malloc replacement is a different experiment: inspect
malloc_zone_from_ptr/malloc_get_zone_name on ordinary and OCCT allocations
as well as the loaded libraries. For mimalloc, also check heap membership
with mi_is_in_heap_region. Its upstream
macOS override instructions
use a shared library; loading it successfully alone does not prove that
allocations reached it.
Use a fixed optimized CLI and one synthetic design, for example the saved
tools/cli/tests/perf_join_pattern.json fixture. Run each candidate in a
fresh process with info <design> --timings, without a result store. Report
the feature recompute times separately from process wall time and peak
resident memory (/usr/bin/time -l on macOS reports the latter in bytes).
The CLI's --timings report does not measure viewport meshing or display.
MITCAD_TEST_ONLY selects guarded geometry tests by a name substring;
test_geometry --part <name> runs one part of the suite (--list names
them; each is the ctest geometry.suite.<name>, mitcad#832). The long
thread and sweep groups are numbered parts of about equal time
(thread.1-thread.3, sweeps.1-sweeps.5, mitcad#870); a test of a
second or more prints its time, for moving a test between them.
Legacy groups that call their cases directly still run, so inspect the
test entry point before treating a filtered invocation as one isolated
case. Keep workload, compiler flags, thread
limits and successful assertions equal across candidates. No allocator is
adopted merely from these setup checks; timings, memory and allocation
failure handling decide whether a replacement is worth shipping.
The bounded comparison on 24 October 2026 used a physical M1 Max
(10 CPU cores, 32 GiB), macOS 27.0.1 (26A434), AppleClang 21.0.0 and
the optimized 0.26.0 CLI/geometry binaries at 378aec0c. Each row is the
median of five fresh processes; the candidate order rotated between
repetitions and no build ran concurrently. The design was the synthetic
90-pin join fixture above. The geometry workload was test_geometry with
MITCAD_TEST_ONLY=test_the_check_where_changed_gives_the_whole_checks_answer:
the perforated-plate case from test_large_bodies.cpp plus the legacy
groups that do not use guarded (996 input-checked operations in total).
Its time and RSS include those groups, not just the plate. RSS is the median of
each process's maximum resident size, in MiB.
| Allocator | Recompute ms | CLI wall s | CLI RSS MiB | Geometry wall s | Geometry RSS MiB |
|---|---|---|---|---|---|
| Shipped native/system | 547.9 | 0.71 | 75.38 | 7.02 | 185.48 |
| Native + mimalloc 3.5.3 override | 526.0 | 0.70 | 77.98 | 6.74 | 190.34 |
FLEXIBLE, system (0) |
562.0 | 0.73 | 77.41 | 7.07 | 185.41 |
FLEXIBLE, OCCT pool (1) |
855.9 | 1.04 | 91.47 | 11.04 | 217.27 |
FLEXIBLE, TBB (2) |
553.2 | 0.72 | 79.84 | 7.06 | 182.59 |
The separate FLEXIBLE TKernel used the same patched OCCT 8.0.1 source,
arm64, deployment target 14.4 and -O3, with TBB 2023.1.0 enabled.
Only that uninstalled TKernel was substituted; the three FLEXIBLE rows
share the identical binary. Enabling TBB also changes OCCT's parallel
runtime, so comparisons with the shipped non-TBB binary are not solely
allocator comparisons. Loaded-library and allocator-type probes verified
all three selections. The mimalloc override was pinned to the existing
vcpkg baseline and its source hash; probes of ordinary, aligned and OCCT
allocations verified the mimalloc zone and heap membership in the actual
CLI process. Diagnostic probes were absent from the timed runs.
The pinned TBB malloc proxy loaded and registered a tbbmalloc zone on
this OS, but ordinary and OCCT allocations still used DefaultMallocZone.
That ineffective process-wide override is excluded from the table; it is
different from the verified FLEXIBLE/TBB row.
Decision: retain the system allocator. The pool is slower and larger; TBB brings no speed gain here. Mimalloc improves feature recompute and the geometry case by about 4%, but CLI wall time changes by only 0.01 s and median RSS increases in both workloads. The geometry maximum RSS across the five runs rises from 187.95 to 200.28 MiB. This narrow benefit does not justify adding a process-wide shipped allocator and its packaging/failure-handling obligations. All 50 timed workload invocations completed successfully. No dependency, allocator, out-of-memory policy or package signature was changed. These are synthetic workload results, not a corpus, viewport-meshing or rendering speedup claim.
- macOS uses the shared Qt UI only (owner 6.11.2026,
macos-shared-qt.md): the macOS presets
(
macos-debug, so the VM'sdev, andmacos-release) setMITCAD_MACOS_SHARED_QT_UI=ON, andMITCAD_MACOS_NATIVE_UI=ONis a configure error: the AppKit frontend is not built until native UI work resumes (native-macos-ui.md keeps its design and state).#ifdef Q_OS_MACOSis for behaviour the system or the keyboard needs; the 0.48 macOS presentation is underMITCAD_MAC_UI, built only with-DMITCAD_MACOS_SHARED_QT_UI=OFFfor comparison. - The macOS UI tests (
app.ui-macos*) run the Qt frontend; run GUI tests in the isolated VM, wheremacos_desktoplets one at a time hold the window server. The macOS release check istools/release-check-macos.sh(macos-shared-qt.md). - The app is a
MACOSX_BUNDLE(mitcad.app) withapp/packaging/macos/Info.plist.in.MITCAD_BUNDLE_ID(defaultfi.nocodo.mitcad) is a placeholder: fix it before the first release, since preferences and signatures are keyed on it.Mitcad.icnsis built fromapp/packaging/icon/mitcad.svgbymitcad-iconsetandiconutil. cmake --install <build> --prefix <dir>deploys Qt withmacdeployqt, copies the vcpkg dylibs intoContents/Frameworksand the licence texts intoContents/Resources/licenses. It also installs the render workermitcad-render(every build has it) inContents/MacOS, its dependencies and Open Image Denoise's runtime-loaded CPU/BNNS and Metal modules inContents/Frameworks, and their licence texts. The complete Cycles Metal runtime source tree is installed inContents/Resources/cycles/source.setup-macos.shprepares the pinned CPU and Metal rendering and denoising dependencies usingtools/dev-env/build-cycles-macos.shin the guest; see rendering.md.tools/package-macos.sh [build dir]installs, signs ad hoc, checks and makes a.dmg. Developer ID signing (MITCAD_SIGN_IDENTITY) and notarisation (MITCAD_NOTARY_PROFILE) need an Apple Developer account. The Finder's Quick Look thumbnail extension (Contents/PlugIns/MitCadThumbnails.appex, mitcad#1696) is signed again after the deep signature with its own entitlements (the App Sandbox,app/packaging/macos/QuickLookThumbnails.entitlements), then the application around it.tools/check-bundle-macos.sh <Mitcad.app>: only system and bundled libraries linked, relative rpaths, arm64 everywhere, andInfo.plist, icon, licence texts, the complete Metal source manifest, thelibqmacstylestyle plug-in (without it Qt falls back to its own cross-platform style) and the sandboxed Quick Look thumbnail extension for.mitcadpresent.app/platform/macos/*.mmis Objective-C++ with ARC, linked with AppKit, as warning-free as C++ (mitcad_warnings); AppKit calls newer than 14.4 are guarded with@available.--chrome=docked|floatingtries both layouts; the log's start-up lines say which was chosen. In the VM, look with the test driver (MITCAD_TEST_INPUT,TestDriver.hpp):screenshotandscreenshot-dialoggrab widgets,screenshot-screenthe composed windows;screenshot-screensaves the app's own windows as the window server shows them (no Screen Recording permission; software GL may be blank there, so glass is checked on hardware: checklist).screencaptureandosascriptdo not work over SSH. Check both appearances (defaults write -g AppleInterfaceStyle Dark,defaults delete -g AppleInterfaceStyle) and restore light.
Build tools that are neither Ubuntu nor winget packages are downloaded from a pinned GitHub release and checked against GitHub's published SHA-256 digest. None is linked into MitCad; only the AppImage runtime is shipped.
| Tool | Script, folder | Release asset | SHA-256 |
|---|---|---|---|
| ccache 4.14.1 for Windows | setup-ccache-windows.ps1, C:\dev\ccache |
https://github.com/ccache/ccache/releases/download/v4.14.1/ccache-4.14.1-windows-x86_64.zip | 6219f3865ca59aec41ee4b678df171d5d35855ecb2b6dbbbd20690b3a68af7b4 |
| ccache 4.14.2 for macOS (universal) | setup-macos.sh, ~/.local/bin |
https://github.com/ccache/ccache/releases/download/v4.14.2/ccache-4.14.2-darwin.tar.gz | cf240009630b605b775c7c5c7b7105a3b196c79f31af322c1557969aa28003fc |
| sccache 0.18.0 for Apple Silicon | setup-macos.sh, ~/.local/bin |
https://github.com/mozilla/sccache/releases/download/v0.18.0/sccache-v0.18.0-aarch64-apple-darwin.tar.gz | 308184519b646f5125289e8515b36f6ca65a13a041923994aebe702348674e8e |
| linuxdeploy 1-alpha-20251107-1 | install-appimage-tools.sh, ~/appimage-tools |
https://github.com/linuxdeploy/linuxdeploy/releases/download/1-alpha-20251107-1/linuxdeploy-x86_64.AppImage | c20cd71e3a4e3b80c3483cef793cda3f4e990aca14014d23c544ca3ce1270b4d |
| linuxdeploy-plugin-qt, continuous build of 22 August 2026 | install-appimage-tools.sh, ~/appimage-tools |
https://github.com/linuxdeploy/linuxdeploy-plugin-qt/releases/download/continuous/linuxdeploy-plugin-qt-x86_64.AppImage | cfc1055b2b9dbc08412b579f20990b7b41a17b61beaa5847dc9477c96c9e9617 |
| appimagetool 1.9.1 | install-appimage-tools.sh, ~/appimage-tools |
https://github.com/AppImage/appimagetool/releases/download/1.9.1/appimagetool-x86_64.AppImage | ed4ce84f0d9caff66f50bcca6ff6f35aae54ce8135408b3fa33abfc3cb384eb0 |
| ISPC 1.31.0 (compiles Open Image Denoise) | build-cycles.sh, <prefix>/src |
https://github.com/ispc/ispc/releases/download/v1.31.0/ispc-v1.31.0-linux.tar.gz | d74089c835e10fd7e2c4b9225ced38b87d1fb53d35c7ceabd48cdf035da11b11 |
| ISPC 1.31.0 for Apple Silicon (compiles Open Image Denoise) | build-cycles-macos.sh, <prefix>/src |
https://github.com/ispc/ispc/releases/download/v1.31.0/ispc-v1.31.0-macOS.arm64.tar.gz | eac8009da38d41074d0adcf1fad4a3412fc9644a81ee5a49efeb07eac505b6ec |
build-cycles.sh --cuda (#50; setup-user.sh passes it unless
MITCAD_RENDER_CUDA=0) fetches the CUDA compiler's
components (cuda_nvcc 12.9.86, cuda_cudart 12.9.79, cuda_cccl
12.9.27 of CUDA 12.9.1) from
https://developer.download.nvidia.com/compute/cuda/redist/ and checks
them against the SHA-256 digests NVIDIA lists in redistrib_12.9.1.json
there (pins in versions.sh); when no GCC of version 14 or older is
installed, it unpacks the distribution's g++-14 packages
(apt-get download). build-cycles.ps1 -Cuda (#202;
setup-windows.ps1 likewise) fetches the same components' Windows
archives (CUDA_*_WINDOWS_SHA256, from the same JSON) and uses MSVC as
the host compiler. All are build tools only; see
rendering.md.
QtKeychain (BSD-3-Clause; the live updates' credentials in the system's
keychain, #89) is built by CMake on every platform from its release's
source archive (cmake/Keychain.cmake, FetchContent as for Corrosion),
pinned in versions.sh (QTKEYCHAIN_VERSION 0.17.0, QTKEYCHAIN_SHA256 of
https://github.com/frankosterfeld/qtkeychain/archive/refs/tags/0.17.0.tar.gz),
as a static library against the build's Qt: the packages carry no library
of its own, only its licence text. On Linux it needs Qt's D-Bus module and
libsecret's headers (libsecret-1-dev); libsecret itself is loaded at run
time when the system has it, so MitCad starts without it.
build-cycles.sh also builds the render worker's libraries from pinned
sources (versions.sh): Open Image Denoise 2.5.1's source release
(SHA-256 e71fd043…c36) and Cycles at tag v5.2.0 (commit 3b97e190…);
see rendering.md. Those are linked; ISPC is not.
On Windows build-cycles.ps1 does the same with MSVC and reads the pins
of versions.sh; it takes ISPC's Windows release (SHA-256
9a187938…140a, ISPC_WINDOWS_SHA256); see
rendering.md.
linuxdeploy-plugin-qt publishes digests only for its continuous build, so
the check fails whenever it is rebuilt; update the digest in the script.
The tools are extracted (--appimage-extract, no FUSE). The AppImage
runtime is taken from the start of appimagetool's own AppImage (with its
update-information and signature sections cleared), so packing downloads
nothing.
Built in the VM from a release build with CPack (cmake/Packaging.cmake):
tools\dev-env\msvc.cmd cmake --build --preset dev --target package
powershell -ExecutionPolicy Bypass -File tools\installer-windows-test.ps1 -MesaDir C:\dev\mesa\binpackage writes mitcad-<version>-windows-x64.exe (NSIS 3) and the same
files as a .zip. The installer script is our own,
packaging/windows/NSIS.template.in
(CPack finds it through CPACK_MODULE_PATH). It runs as the user
(RequestExecutionLevel user) and installs either
- just for me (the default): into
%LOCALAPPDATA%\Programs\Mitcad, with the Start menu shortcut, the.mitcadfile type with Explorer's thumbnail handlermitcad-thumbnails.dll(mitcad#1695, filetype.nsh: its COM class in the 64-bit view) and the uninstall entry underHKCU; no administrator rights, so no UAC prompt; - for all users: into
Program Files\Mitcad, registered underHKLM(32-bit view, as earlier releases). Only this choice asks for elevation: the installer starts itself again elevated (runas) with/AllUsers /Elevated.
The page Choose Users after the licence offers the choice; it starts on
For all users only when MitCad is installed for all users and not for
the current user.
An earlier version in the same scope is uninstalled first (its own
uninstaller, silently, in place). Silent installs: /S installs just for
the current user, /S /AllUsers for all users (/CurrentUser says the
default explicitly), and /D=<dir> (last, without quotes) sets the folder
in both. A silent install whose /D is the folder of the installation
for all users, which is what the updater of an earlier release runs,
stays for all users. The installer writes the scope into
<dir>\installation.ini ([Installation], Scope=user or all), which
the uninstaller and the automatic updates read; an
installation without it is an earlier release's, which was for all users.
The uninstaller removes the files and the keys of its own scope only;
for all users it elevates as the installer does.
No file is replaced while a program from the installation runs
(mitcad#1454). A running program keeps its executable and its DLLs
locked, and an update that skipped them once left a new mitcad.exe with
the previous release's OCCT DLLs (an MCP bridge, mitcad-cli mcp --connect, loads all of OCCT and ran for days). Before the earlier
version is uninstalled, the installer lists the processes whose program
is in the installation folder (K32EnumProcesses,
QueryFullProcessImageNameW through the System plugin), asks the MCP
bridges among them to end (each waits on the event
Local\MitcadBridgeQuit-<pid>, app/update/RunningPrograms.hpp)
and gives everything up to five seconds. With pages, what still runs is
named in a task dialog (XPStyle on for the common controls 6; a message
box with Yes, No and Cancel without them), with End Them, Retry
and Cancel (back to the folder page), mitcad#1584: End Them ends the
programs from bin of the installer's session except mitcad.exe
(TerminateProcess) and asks each MitCad to close as quitting it does
(WM_CLOSE to its first design window, titled <design> - MitCad <version>), so that MitCad asks about unsaved changes; a MitCad that
still runs then is named with End Anyway, which ends it too. A silent
install ends with exit code 3 and changes no file, and ends no program,
unless /EndPrograms is given: the updater passes it only after the
person chose End Them and Install (updates.md), and the
installer then ends the programs from bin of its session except
mitcad.exe first, with its own rights (elevated for all users; the
elevation passes the switch on). AllowSkipFiles off:
a file that cannot be written is never skipped (Retry or Cancel; a
silent install aborts). Exit codes: 0 done, 1 cancelled, 2 aborted (also
when the earlier version could not be uninstalled or a file could not be
written), 3 programs from the installation are running (silent; nothing
changed; with /EndPrograms, programs it could not end, such as a
MitCad or another session's program), 740 elevated but still without
administrator rights, 1223 elevation refused.
mitcad.exe and mitcad-cli.exe check at start-up that the OCCT DLLs
they loaded are the ones they were built with
(app/update/InstallationCheck.cpp):
the build (cmake/OcctBuildStamp.cmake)
records the link time stamp and image size from each OCCT DLL's PE
header, and the loaded modules' headers must match. On a mismatch MitCad
names the DLLs and the programs still running from bin, asks to close
them and install again, and starts nothing else (exit code 3);
mitcad-cli prints the same and exits with 4. MITCAD_SKIP_INSTALLATION_CHECK=1
turns the check off, should it ever be wrong about an installation.
Contents: bin (executables, Qt, vcpkg DLLs,
VC++ runtime, qt.conf), plugins (via windeployqt), licences
(LICENSE, THIRD-PARTY-NOTICES.txt, licenses\ with the font and every
vcpkg port's copyright), uninstaller. Never included: Mesa, Qt's
software OpenGL, PDBs. The render worker
mitcad-render.exe is installed with its DLLs (Open Image Denoise's too, its
CUDA device with -Cuda),
its CUDA kernels in bin\cycles\lib (a render prefix built with -Cuda)
and the licences of Cycles (with cuew's) and Open Image Denoise
(rendering.md).
tools/installer-windows-test.ps1 (ctest app.installer-windows once
the installer exists) checks that the installer asks for no elevation,
then in each scope (-Scope both|user|all) installs silently into a
folder of the test's own and checks the scope's registration (uninstall
entry, installation.ini, file type, the thumbnail handler's registration
with test_thumbnail_handler --registered getting thumbnails through it,
Start menu shortcut, nothing in the other scope). Just for the current user it checks the files, runs
mitcad-cli, mitcad.exe --version and the render worker (a test render,
--list-devices; the build's GPU kernels installed) with a system-only PATH,
checks that the installed mitcad-updater.exe does not run an installer
whose SHA-256 is not the given --sha256, or without one (mitcad#603),
checks files in use (mitcad#1454: with a mitcad-cli mcp from bin
running, the silent installer ends with code 3, ends nothing and no file
of bin changes; the updater asks whether to end it, and on Cancel
changes nothing and its log names mitcad-cli.exe; a running
mitcad-cli mcp --connect is asked to end and the install replaces every
file with the package's; mitcad#1584: the silent installer with
/EndPrograms ends a mitcad-cli mcp and installs, and the updater's
End Them and Install ends it and installs every file of the package;
the test answers the updater's task dialog by posting TDM_CLICK_BUTTON),
and, with -MesaDir, renders a screenshot and checks that End Them and
Install asks a MitCad with an unsaved design to close, which asks to
save and is not ended (Cancel then changes nothing); for all users it reinstalls with
only /D= as an earlier release's updater does. With -MesaDir it tests
the automatic update in both scopes (updates.md;
-NoUpdate skips it) in a build configured with
-DMITCAD_UPDATE_TEST_HOOKS=ON; a build without it (the dev preset that
inherits windows-release) is checked to ignore the update tests'
variables (updates.md). Then it uninstalls and checks that no key of that
scope is left. It changes the .mitcad file type under HKCU and HKLM
and replaces an installation of either scope: run it only in the VM.
Session 0 cannot show a UAC prompt, so the test runs with administrator
rights and the elevation itself is not exercised.
Signing a release: updates.md.
Icons: edit app/branding/mitcad.svg (64 px and up) and
mitcad-small.svg (below 64 px), then run tools/make-icons.sh in the
distro; the PNGs and mitcad.ico it writes are committed.
Not done yet: Authenticode signing (SmartScreen warns) and bundling the licence texts of compiled-in Rust crates.
Mitcad-<version>-x86_64.AppImage, built in the distro:
tools/dev-env/install-appimage-tools.sh # once
cmake --build --preset dev --target appimageThe target (cmake/AppImage.cmake,
packaging/linux/make-appimage.sh)
installs into build/dev/appimage/AppDir (executables, desktop file,
icons, licences incl. packaging/linux/THIRD-PARTY-NOTICES.txt), then:
- linuxdeploy copies needed libraries into
usr/liband gives every executable inusr/binand every library an$ORIGINRUNPATH, so none of them loads a system's Qt; its Qt plugin adds the X11/GLX platform, image formats, SVG icons and TLS backends. glibc, libstdc++, X11/xcb, OpenGL, fontconfig and FreeType stay the system's, and so do GLib, libcups and the GPU drivers (make-appimage.shexcludes them for the Qt plugin too, throughLINUXDEPLOY_EXCLUDED_LIBRARIES, and fails when one is inusr/lib). GLib (mitcad#1654): Insert › Component from Web's web browser component, loaded at run time from the user's data folder, takes libgobject and libgio from the system; with the build root's GLib 2.80 bundled, the system's libgobject ran on the bundled libglib, and on GLib 2.86 or newer the module did not load (undefined symbol: g_string_copy). Libraries nothing in the AppDir needs (those an excluded library needs, such as libmount of libgio) are removed; what is loaded by name (--library: libssl, Open Image Denoise's device modules) stays.appimage-test.shloads the component in the running AppImage (--browser, or the build'sbrowser-component). - OpenSSL comes as a pair of one build (mitcad#954): the render worker
links vcpkg's
libcrypto.so.3(minizip-ng's), solibssl.so.3from the same folder goes in too, and Qt's OpenSSL TLS backend, which loads both by name at run time, finds them inusr/lib(libQt6Core's$ORIGINRUNPATH) before the system's. With libcrypto alone it took the system's libssl on top of the bundled libcrypto, two OpenSSL builds in one process, and on some distributions no TLS at all. The bundled libcrypto'sENGINESDIRandMODULESDIR, vcpkg's install folder on the build machine (they follow the install prefix), are rewritten to/nonexistent/…, so no other OpenSSL's modules load into it;OPENSSLDIRstays/etc/ssl(the system'sopenssl.cnf), and Qt reads the system's CA certificates itself (Fedora's/etc/pki/tls/certs/ca-bundle.crtamong them). Where the system'sopenssl.cnfdoes not load in the bundled OpenSSL (mitcad#1208: an option only the distribution's patched OpenSSL knows, such as openSUSE'srh-allow-sha1-signatures), MitCad loads the AppImage's own minimal configuration in its place (usr/share/mitcad/openssl.cnf, frompackaging/linux/openssl.cnf; TLS 1.2 or newer) and logsTLS: the system's OpenSSL configuration failed to load (<first error>); using the AppImage's own; a configuration that loads is used as before (app/update/OpenSslConfiguration.hpp). The header ofmake-appimage.shgives the reasons. - The render worker
mitcad-rendergoes in with its libraries (and Open Image Denoise's CPU device module) and their licences (rendering.md). - ELF files are stripped.
- appimagetool packs it with the pinned runtime. No AppImage update information and no GPG signature: MitCad's own manifest signature is what counts.
Release AppImages come from a linux-release-based preset, built on
Ubuntu 24.04 (a 24.04 distro, VM or container: glibc 2.39), the
oldest supported system. The AppImage needs the glibc of the system it
was built on, so a release built on a newer distribution does not start
on 24.04 or the distributions based on it (mitcad#789); a newer Linux
host builds it in an Ubuntu 24.04 build root
(Linux on a newer host). Without FUSE run
it with --appimage-extract-and-run.
At each start the AppImage writes its desktop file (Exec = the
AppImage, StartupWMClass=Mitcad) and icons into $XDG_DATA_HOME if they
differ, so docks show the icon, and with them the file managers'
thumbnails of designs (mitcad#1539): the bundled mitcad-thumbnailer
copied to $XDG_DATA_HOME/mitcad/bin, its entry
(thumbnailers/mitcad.thumbnailer, from
packaging/linux/mitcad.thumbnailer)
running that copy and the MIME type application/x-mitcad
(mime/packages/mitcad.xml, then update-mime-database)
(app/framework/DesktopEntry.cpp). No
GTK is bundled, so it uses the xdgdesktopportal platform theme unless
QT_QPA_PLATFORMTHEME is set.
The AppImage's entry point is
packaging/linux/AppRun (mitcad#1170), in place
of linuxdeploy's link to usr/bin/mitcad: MitCad.AppImage cli <arguments> runs the bundled mitcad-cli, anything else MitCad. AI
assistants register the AppImage file that way ("$APPIMAGE" cli mcp --connect), since the mount folder changes on each start; inside MitCad
the bundled executables are found from /proc/self/exe
(executableDirectory() in
app/mcp/AssistantSetup.cpp), as Qt names
the AppImage file's folder as the application's.
tools/appimage-test.sh (ctest app.appimage once the AppImage exists)
checks that every ELF resolves its libraries inside the AppImage or from
system folders (an ELF on which ldd fails fails the test), then two
static checks of seconds: no ELF needs a GLIBC_, GLIBCXX_ or
CXXABI_ symbol version newer than GLIBC_FLOOR (2.39),
GLIBCXX_FLOOR (3.4.33) and CXXABI_FLOOR (1.3.15): Ubuntu 24.04's
glibc and the libstdc++ of its libstdc++6 package (GCC 14's), and every ELF that links Qt finds each libQt6* inside the AppImage,
through its own $ORIGIN RUNPATH and in ldd's view without
LD_LIBRARY_PATH, never the system's Qt; it names the ELF that fails.
libssl.so.3 and libcrypto.so.3 must be bundled both or neither, and
no file may name a library folder of the build machine (vcpkg's install
trees, the render libraries' prefix, the built executables' RUNPATHs).
Then it runs the AppImage with an empty environment, renders with its
render worker when it has one, checks the bundled mitcad-cli as
assistants start it (cli --version; the chat panel's bridge; the
command Connect AI Assistant registers, run with mcp --list-instances,
lists the running window), and updates it to itself from a locally
signed manifest, over the bundled OpenSSL: the log line
Update check: TLS OpenSSL <version> … names the bundled libcrypto's
version, and the running MitCad has loaded libssl and libcrypto from the
AppImage only. That last step needs a build with the update test hooks
(-DMITCAD_UPDATE_TEST_HOOKS=ON, on in the debug presets); a release's
AppImage, without them, is checked to ignore the update tests' variables
instead (updates.md).
Insert › Component from Web (mitcad#1579, app/COMMANDS.md)
runs its browser on the Chromium Embedded Framework (CEF), in a component
that MitCad downloads on first use and that no installer, AppImage or disk
image carries: the module mitcad-webbrowser (the window), CEF's
subprocess helper and CEF's runtime.
- CEF. The official binary distribution, pinned in
tools/dev-env/versions.sh(CEF_VERSION, the "minimal" distribution, its SHA-1 per platform), fetched and unpacked bytools/dev-env/fetch-cef.sh(Linux, macOS:~/cef/<version>/…) ortools/dev-env/fetch-cef.ps1(Windows:C:\dev\cef\<version>\…); the setup scripts run them. The build takesMITCAD_CEF_ROOT(the environment's, else that folder).libcef_dll_wrapperis built from the distribution's sources with its own CMake files, with the DLL runtime on Windows and without CEF's sandbox. - The build (
app/webbrowser/CMakeLists.txt, a directory scope of its own: CEF's CMake files change their directory's compiler flags, which reach neither MitCad's other targets nor the module):MITCAD_BROWSER_COMPONENTAUTO(default) builds the component where the distribution is,ONrequires it,OFFleaves it out. Built, it is staged in<build>/browser-componentas the package unpacks it (component.json, the module, the helper, CEF's runtime, its resources and locales, the noticespackaging/browser/THIRD-PARTY-NOTICES.txtand CEF's licence);MITCAD_BROWSER_COMPONENT_DIR=<build>/browser-componentmakes a build's MitCad use it without a download (the UI testapp.ui-<platform>-component-webdoes). The targetbrowser-packagezips it asmitcad-browser-<MITCAD_BROWSER_VERSION>-<platform>.zip. The module's own code is C++17, compiled as C++20 for CEF's headers, which are included as system headers. - Its interface.
kComponentBrowserAbiinapp/webbrowser/ComponentBrowserHost.hppis the module's interface version and the package's (component.json'sabi, the manifest's): raise it with every change of that header. A MitCad loads only its own. - A release builds the package only when what it is built from
changed:
tools/browser-package.sh <build> <latest update-manifest.json> <release public key>(Linux, macOS;tools/browser-package.ps1on Windows in the MSVC environment) compares the fingerprint (the CEF version, the interface, the module's sources) with the latest manifest's package (mitcad-release browser), and either keeps it (unchanged) or builds a new package versioned by the build's time (YYYY.MDD.HMM), signed on macOS, and writes the line thatmitcad-release manifest --browser … <url>takes (updates.md). - No build machine's folders in the package (mitcad#1658). Before it
signs and zips,
browser-package.shstrips the module's and the helpers' debug information (strip --strip-unneededon Linux, asmake-appimage.shstrips the AppImage;strip -S -xon macOS, whose app has no dSYM either: no release keeps symbols aside), then fails ifstringsover them finds the source tree, the build folder or CEF's distribution. The file names CEF's logging macros compile in (__FILE__,__builtin_FILE()), which stripping leaves, are relative:app/webbrowser/CMakeLists.txtmaps CEF's folder tocef/forlibcef_dll_wrapper(-ffile-prefix-map) and the source tree and CEF's folder for the module's and the helpers' macros only (-fmacro-prefix-map; their debug information keeps the real paths for a debugger in a build). A build'sbrowser-componentis not stripped.tools/appimage-test.sh --browser <package zip> <AppImage> <built mitcad>checks a package the same way before it loads it (section 2d). Windows keeps its paths in the PDBs, which are not packaged. - Licences. CEF and Chromium are BSD-3-Clause with Chromium's bundled
components under their own (FFmpeg's LGPL-2.1 inside libcef, a shared
library of its own in the package); the package carries its notices and
CEF's licence. Nothing of CEF is linked into
mitcad.
Tolerance: every geometric comparison in a test (lengths, positions, distances, areas and volumes by their length scale) allows at least 0.000 001 mm (1e-6) unless the test says why it needs a tighter one. A deviation within that, on any platform, is fixed by relaxing the test to it; a larger one is a fault to fix or a case to agree on, not a reason to relax silently. UI tests are not relaxed for one platform: the interface differs by platform, and a failure there is a fault.
Run in the isolated environments:
ctest --preset dev: geometry, bridge, model, solver, import,mitcad-cliscripts (tools/cli/tests), SPDX headers, dependency licences.core.vcs.*andcli.remoteuse a bare repository in a temp folder and a fakessh; no network; skipped without git.cli.librarymakes a small parts library of fasteners withtools/libraries/make-fastener-library.pyin the build tree, then one of every size with the smallest and largest rows inserted (needs git and Python 3; skipped without them);cli.fastener-tableschecks that generator's dimension tables (sizes, pitches, length series, each standard's rows, the earlier versions' rows kept; Python 3 only);cli.profile-librarylikewise one of BUILD parts withtools/libraries/make-profile-library.pyfrom sections it makes;cli.library-previewsrenders two fasteners' previews with both generators and the render worker (skipped where it cannot render).- The crates' tests (
core.model,core.vcs.*, ...): the fixturescore.cargo_buildandcore.cargo_build_releasebuild every crate's test binaries in one cargo run (cargo test --no-run, one lock on the target directory, the crates compiled in parallel), and the tests run the binaries directly, at the same time (core/cargo-tests.cmake; on Windows each run hasTMPandTEMPin a folder of its own under%LOCALAPPDATA%\mitcad-tests, removed when it passes, as Storage Sense deletes the empty folders of git repositories just made in the system's temporary folder; the folder is named after the ctest, the package and the arguments, socore.model.assemblyandcore.model.assembly.workers, the same binary at the same time, do not remove each other's, mitcad#1017);core.doctestsandcore.doctests_releaserun the documentation tests. The fixtures limit cargo's jobs by the memory available and sweep the stale units from their target folder after the build (see the crates' test builds). A large crate's tests run in parts by module (mitcad_cargo_test(... PARTS <part> <filter>...)incore/CMakeLists.txt):core.vcs.remote,.sync,.libraryand.rest(everything else, so a new module is tested before it gets a part), andcore.vcs.partschecks with the binaries'--listthat the parts hold each test exactly once. cargo fmt --check,cargo clippy --all-targets -- -D warningsincore/.tools/check-dependencies.sh:cargo denywithcore/deny.toml, including RustSec advisories, and the licence texts of the native libraries the build fetches from source and links (QtKeychain's BSD-3-Clause, inbuild/dev/_deps;MITCAD_BUILD_DIRfor another build).- Performance:
UI_APP=build/rel/app/mitcad tools/perf-measure.sh design.mitcad d3 21 20on a release build;mitcad-cli info design.mitcad --timings [--result-store <dir> --diagnostics].cli.perf_recompute,cli.perf_join_recomputeandcli.perf_holes_recomputeguard against large slowdowns, andcli.perf_holes_meshthe display meshing of planes with many holes (mitcad-cli mesh-comparewith each face's time in--report).mitcad-cli run script.json --timingsprints each step's time ("Timing steps[i] : ms");cli.perf_sketch_patternruns it on a sketch with a 10 x 10 circle pattern (tools/cli/tests/perf_sketch_pattern_{5,10,20}.json, mitcad#670), andUI_APP=build/rel/app/mitcad UI_PATTERN_SIZE=10 tools/ui-sketch-pattern-speed-test.shtimes a window selection and drags of that sketch in the application (UI_SCALE=2for a device pixel ratio of 2) and checks that each drag step reads the sketch from the model once (the "sketch query" lines, mitcad#679). The regions of 400 disjoint circles are guarded in the model's tests (sketch::regions_tests, mitcad#678);cargo test --release -p mitcad-model regions_timings -- --ignored --nocaptureprints the times of 25, 100 and 400 circles.mitcad-cli info design.mitcad --namesprints the names of every body's faces and edges, to compare the topology two builds (or one build with and withoutMITCAD_NO_FAR_FEATURES=1) give a design. - Display meshing (mitcad#644):
mitcad-cli mesh-compare design --report report.json [--a variant] [--b variant]meshes every body of a design (opened, or imported as the application imports it) twice as the view's final tier does, each time with one variant of the planes' triangulation (default: the default insertion, the final tier before mitcad#644;delabella: Delabella unchecked, the interactive tier;checked: Delabella checked, the final tier now; (a)defaultand (b)delabellaunless given), and compares them face by face (triangles, deviation, area against the face's own, folds, faces left without a triangulation, time);mitcad-cli mesh-compare --summary <folder>...totals the reports of many designs (performance.md). tools/repo-growth.sh <work dir> design.mitcad...measures git repository growth of the design file formats over 50 saves.- Live updates (#89):
core.vcsruns the MQTT client's scenarios against a broker inside the test and against mosquitto when it is installed (install-packages.sh;setup-macos.shwith Homebrew,setup-windows.ps1with winget; skipped without it), each test with its own broker on free ports; the TLS test makes its certificate authority withopenssl(skipped without it). Fuzz targets of the packet decoder and the message readers (cargo-fuzz, nightly Rust; by hand, not in the check script): incore/vcs/fuzz,cargo +nightly fuzz run mqtt_packetsandmqtt_messages(itsCargo.tomlhas the steps); the normal tests run a seeded random sample of the same input. The application's side istools/ui-live-test.sh(skipped without mosquitto): the trust question, Live and Live offline, two instances (who has a design open, a version arriving at once), Preferences' switch and Forget, signing in to a TLS broker of the test's own (openssl,MITCAD_TEST_LIVE_CA) without a keychain and, when GNOME's keyring anddbus-daemonare installed, with one in a D-Bus session of the test's own.
core/fuzz (mitcad#939) holds cargo-fuzz targets for every reader of a
file MitCad opens or imports, one per entry point, each on arbitrary
bytes. Like core/vcs/fuzz it is a workspace of its own, outside
core/Cargo.toml, core/Cargo.lock and cargo-deny, and nothing of it is
built into MitCad. Each target asserts that an input is read, refused or
reported within a budget of 10 s (core/fuzz/src/lib.rs) and that it
never panics; a panic, an overflow (the fuzz build keeps debug
assertions), an allocation over libFuzzer's limit or a timeout is a
finding.
| Target | Entry point |
|---|---|
zip_archive |
mitcad_zip::Archive::new and read of every entry |
cfb_compound |
mitcad_cfb::CompoundFile::parse and read of every stream |
dxf_read |
mitcad_dxf::read (bytes) |
package_3mf |
mitcad_3mf::read_package and mitcad_3mf::read |
design_file |
Document::from_json (the mock kernel, nothing evaluated) |
project_settings |
SharedSettings::from_json and LocalSettings::from_json |
rvt_schema |
mitcad_rvt::schema::Schema::parse |
rvt_walk |
mitcad_rvt::walk of one record (the first byte picks the schema of a synthetic project, family or building file) |
rvt_file |
RvtFile::parse, the schema and elements::Model::read |
asm_blob |
AsmFile::parse, its history and convert::convert_file |
ipt_file |
IptFile::parse and what the .ipt/.iam worker reads before it builds geometry |
dwg_file |
mitcad_dwg::read, the scene and its plan, the solids' ASM bodies |
ifc_text |
IfcFile::read, model::Model::read and the decoder's items |
freecad_document |
Document::parse and GuiDocument::parse, sketches, sheets and expressions |
freecad_file |
FcstdFile::from_bytes and each object's shape data |
f3d_file |
F3dFile::from_bytes, its segments and body blobs, nested documents |
solidcraft_file |
SolidcraftFile::from_bytes and each feature's inputs |
model_3dm |
File3dm::read, each object's conversion to the neutral B-rep model, the render meshes (mitcad#1715) |
The .ipt, .dwg, .3dm, IFC and FreeCAD targets stop where the import workers
hand the data to OCCT: the geometry built from it is the kernel's.
They need a nightly toolchain and cargo-fuzz. The full check
(tools/check-all.sh --full, the check script)
runs each target for 60 s (MITCAD_FUZZ_SECONDS) after its other steps
when both are installed, each target a row of the table, and skips them
with a note when they are not; the scoped check never runs them. By
hand, from core/ (--fuzz-dir fuzz: cargo-fuzz does not take the core
workspace's manifest as the project whose fuzz/ it looks for):
rustup toolchain install nightly --profile minimal
cargo install cargo-fuzz
cd core
cargo run --manifest-path fuzz/Cargo.toml --example write_seeds
cargo +nightly fuzz list --fuzz-dir fuzz
cargo +nightly fuzz run --fuzz-dir fuzz -O zip_archive -- -max_total_time=60 -timeout=20 -rss_limit_mb=2048-max_total_time=60 runs a target for 60 seconds; -timeout stops an
input that never returns and -rss_limit_mb (also the largest single
allocation) one that takes too much memory. A finding is saved under
core/fuzz/artifacts/<target>/; cargo +nightly fuzz run --fuzz-dir fuzz <target> <file> runs it again, and a fix gets a unit test of the reader
with the same input made small or built from the reader's own synthetic
files (the first findings: a .dwg data storage record sliced past the
section's end, every_cut_of_a_data_storage_is_refused_or_read; a broker
address whose scheme's length ended inside a character,
broker_addresses_cut_inside_a_character_are_refused).
The seed corpora are synthetic: core/fuzz/examples/write_seeds.rs
writes them with the readers' own writers and the crates' test builders
(mitcad_zip::Writer, mitcad_cfb::Writer, mitcad_3mf::write, the
DXF writer, the model's test_support fixtures and the documented
version 1 example, mitcad_rvt::testfile, mitcad_asm::testdata,
mitcad_ipt::testdata and testassembly, mitcad_dwg::testfile,
mitcad_ifc::testdata, the FreeCAD reader's tests/data documents and
the .solidcraft reader's tests/designs), never model files. They go
to core/fuzz/corpus/<target>/seed-*, the corpus cargo-fuzz reads and
adds what it finds to; the folder is git-ignored, so neither the seeds
nor what a run adds are committed (the gate refuses model files and files
over 3 MB anyway). write_seeds takes another folder as its argument.
Beside the fuzz targets, the readers have unit tests of damaged input:
every cut of a synthetic file, a wrong signature, and lengths or counts
declared beyond what the file holds, in tests/malformed.rs of the
zip, cfb, dxf, rvt, ipt, dwg, ifc, freecad and
solidcraft crates and in the 3MF reader's
cut_packages_and_other_files_are_refused; the design file's are
model-tests/files (malformed_files_are_rejected, limits_tests.rs).
Parallel branches used to append to the same lists and conflict at every merge. These tests now register themselves, each in a file of its own (mitcad#1925); a new test adds files and edits none of the lists:
- A Windows UI test (
app.ui-windows-<name>): itsadd_testandset_tests_properties, with the comment that says what it checks, incmake/ui-tests/windows/ui-windows-<name>.cmake.cmake/MesaRuntime.cmakeincludes every file there, in sorted order, whereMITCAD_MESA_DIRandBUILD_TESTINGare set; the file needs no condition of its own beyond its test's (anif(TARGET …)for a target it needs). - A macOS UI test (
app.ui-macos-<name>): likewise incmake/ui-tests/macos/ui-macos-<name>.cmake, whichcmake/MacUiTests.cmakeincludes in sorted order. Each file carries its own whole condition, as the existing ones do (if(APPLE AND BUILD_TESTING AND MITCAD_MACOS_UI_TESTS AND TARGET mitcad AND TARGET mitcad-cli AND BASH_EXECUTABLE);BASH_EXECUTABLEand Python are found before the files are included). A test of the AppKit frontend goes in the same file as its Qt twin, underif(MITCAD_MACOS_NATIVE_UI); the native labels and the harness scheduling run after every file. - An app.unit test (
test_app,app/tests/): the test fileapp/tests/<file>.cppends its entry point withMITCAD_UNIT_TEST(<entry point>);(#include "UnitTests.hpp"; the entry point isint <name>Tests()and returns its failed checks), and its sources go inapp/tests/unit/<file>.cmake(target_sources(test_app PRIVATE tests/<file>.cpp …)and anything it links), whichapp/CMakeLists.txtincludes at its end.test_app.cppruns the registered entry points in the order of their names, so an entry point must not depend on another one having run before it. The application's own sources still go inapp/CMakeLists.txt.
A file name is the test's name (without app.) or the test file's stem,
so a test is found by its name. Linux UI tests are scripts
(tools/ui-*-test.sh) and need no registration. The selection-card tests
(cmake/SelectionUiTests.cmake) stay in their own module: one
registration there serves Linux, Windows and macOS alike.
Translations: a branch that adds or changes texts does not refresh
app/translations/*.ts itself. The catalogues are refreshed once at the
merge into the target branch (tools/translations-update.cmake, the
target update_translations, translations.md), so that
two branches' new texts do not conflict in the same files; only a
translation's own work (filling in <translation> entries) edits them.
mitcad-testrun (tools/testrun, mitcad#790; built with the project
beside its other programs: build\dev\mitcad-testrun.exe on Windows,
build/dev/core/mitcad-testrun on Linux and macOS) runs a build tree's ctests, each as
its own ctest -R ^name$, measures each (wall and CPU time, peak memory of
the process tree, the kind of result) and keeps the machine's profiles and
failure scores in ~/.mitcad/test-profiles.json (MITCAD_TEST_PROFILES,
--profiles), outside the build trees and mirrors so that they survive
fresh builds. On Linux tools/check-all.sh runs its ctests and its corpus
group through it (the check script); macOS merge and
release checks use tools/test-macos.sh. The Windows release script takes
it into use on its machine.
--measure(the default): a fixed number of tests at once (-j, by default the cores / 2), recording only.--schedule: a memory budget (85 % of the memory) as the hard limit with a floor of real available memory (1.5 GiB), a CPU gate (no start above 90 % load), longest first with complementary pairing, a priority lane for the tests with the highest failure scores, timing-sensitive tests only on a calm machine, a hard memory limit per test of at least 4 GiB and twice its history's peak (none for RUN_SERIAL tests or a widely spread history; one rerun alone without a limit after it), a disk floor. Tests with no history borrow the median of their fixture or label siblings, else a guess by kind (UI 1 GiB, corpus 2 GiB, others 512 MiB), and while most tests have no history at most the cores / 2 run at once.--changed FILE: the changed files, a path a line asgit diff --name-only <base>prints them; the tests related to them (the files and folders their commands name, the areas their scripts declare in# check-all sources:lines, a changed crate's tests, a test program's own sources) join the priority lane with a failure's raised place.- UI entries at once (the ctests
app.ui-*or labelledui) are learnt from the same runs, without a measuring run: each UI entry's run records how many other UI entries ran beside it. A failure beside others that passes alone is a contention failure (+2 to the failure score, not +10): it halves that test's room (the UI entries it may have beside it); a run in which two or more UI entries fail so lowers the machine's cap (per platform, in the profile file) by one (mitcad#872: one test that is sensitive to load holds back only itself); two clean runs that reached the cap raise it by one. A machine opts in by giving the bound,--ui-maxorMITCAD_UI_JOBS: then the scheduler holds UI entries to the cap (which starts at the bound and never goes above it) and to their rooms, and reruns a UI entry that failed beside others alone after them, soMITCAD_UI_JOBSis the ceiling, no longer the number at once. Without a bound the runs only record and learn (within 4); UI entries are scheduled as before. For the Linux UI tests thattools/check-all.shruns itself,mitcad-testrun --ui-capprints the cap to run at,--ui-roomsthe tests' rooms, which it keeps as the scheduler does, and--record-ui FILEtakes the runs back (name, exit status, seconds, UI entries beside it). --dry-runlists the tests in their starting order with predictions.
The budget's basis is MITCAD_TEST_MEMORY when set, else the larger of
the physical memory (on Linux the lowest memory limit on the runner's
cgroup path where lower) and, on Windows, the commit limit. A VM with
dynamic memory (the Hyper-V Windows VM) reports only its current
assignment as physical memory: run it with --memory-budget 24G (a size
is used as given) or MITCAD_TEST_MEMORY set to the VM's maximum memory.
On bare metal --memory-budget free (mitcad#872; tools/check-all.sh
gives it there) follows the free memory instead: a test starts while the
memory available exceeds a reserve (--memory-reserve, default the larger
of 4G and a tenth of the memory) by its prediction and the running tests'
growth still to come, read again before each start, at most 85 % of the
basis above; the end report gives the budget's range over the run.
macOS merge checks and the release gate use tools/test-macos.sh:
tools/test-macos.sh --build build/macos-release -R '^(app.unit|app.ui-macos)$'
# First take-up: profile the checks already needed, at serial parallelism.
tools/test-macos.sh --build build/macos-release --measure -R '^tools.testrun$'The default is --schedule --memory-budget free --corpus-children, with
history-based concurrency, a 90% CPU gate and current available memory
less a desktop reserve (at least 4 GiB). macOS samples process-group and
descendant RSS; this is accounting rather than a kernel memory limit.
Profiles remain outside the disposable build tree, by default in
~/.mitcad/test-profiles.json. --measure still defaults to one test.
Qt component workflows that inspect controls, model values and saved
files run on Qt's offscreen platform with MITCAD_TEST_HEADLESS=1.
They keep the real document/model and widget event handlers, but never
render the OpenGL viewport. Their captures show Qt components, not native
window chrome or the 3D scene. The driver verifies the offscreen platform,
Qt frontend and absence of an OpenGL context. These tests have the macos_headless
label: they do not acquire Aqua's lock, consume a desktop/UI lane or
inherit old desktop-contention restrictions. Normal memory and CPU
admission still apply. Each harness owns its settings, files and a virtual
screen configuration. MITCAD_MACOS_HEADLESS_TESTS=OFF at configure time
runs these same commands and assertions in the normal GUI for comparison.
The hidden view still logs its laid-out View area, so scripts that wait
for the window's layout run; any pointer step in the view fails there.
screenshot-screen composes the visible Qt windows instead of asking the
window server. The list is mitcad_macos_headless_tests() in
cmake/MacTestScheduling.cmake: a Qt workflow joins it once it passes
unchanged headless. What still needs the desktop does so for a reason the
offscreen platform cannot give: the 3D view (expect-viewport, picks,
sketch and profile hits), or window-server bounds (two Projects cases keep these).
The remaining Aqua tests share macos_desktop and the shell's per-user
GUI lock, protecting focus, menus and native input across checkouts.
Audited macos_gui_harness workflows may prepare fixtures or verify files
in parallel, acquiring Aqua only for each application lifetime. Viewport
pixels/picking, native controls, system dialogs and physical input retain
their actual platform tests. Headless XPC and offscreen unit tests need no
desktop exclusion. Cargo test builds share cargo_build, reserve compiler
memory and allow at most two compiler jobs; timed Metal checks remain
serial. repo.macos-test-resources checks the actual registrations and
repo.macos-ui-lock checks both desktop exclusion and headless overlap.
Windows (the VM, from the build's folder, ctest on PATH through
tools\dev-env\msvc.cmd): a Job Object per test.
tools\dev-env\msvc.cmd build\dev\mitcad-testrun.exe --build build\dev --schedule. Linux: a systemd user scope per test where the user's systemd
runs (cgroup v2: the working set, memory.max), else rusage, the scopes in
the slice the runner itself runs in and the budget a share of the lowest
memory limit on its cgroup path;
build/dev/core/mitcad-testrun --build build/dev --schedule. macOS:
rusage. Failures are printed at once and appended to
<build>/testrun/status.txt; the end report (report.txt: totals,
resource use, the critical path, failures by kind, profiles that changed
much) and results.tsv go to the same folder. Details, the profile
file's format and what is left: tools/testrun/README.md.
| Variable | Effect |
|---|---|
MITCAD_LOG_PICKS=1, MITCAD_LOG_VOLUMES=1, MITCAD_LOG_TIMING=1 |
Log pick positions, body volumes after changes, step durations. |
MITCAD_MESH_TRACE=1 |
Log the view's display meshings (faces kept, reused, meshed, BRepMesh's phases, the slowest faces, planes the final tier triangulated again after Delabella, mitcad#644) and, on standard error, any meshing a presentation does on the UI thread (mitcad#635; also test_preview_meshing --bench). |
MITCAD_SETTINGS_DIR |
Settings as an INI file in this folder. |
MITCAD_AUTOSAVE_DIR, MITCAD_TEST_AUTOSAVE_SECONDS |
Recovery folder and autosave interval. |
MITCAD_TEST_RECOMPUTE_DELAY_MS=n[,job=m...] |
Every feature computed in a job takes n ms longer (400,undo=800), to exercise the progress dialog. |
MITCAD_COMPUTE_INLINE=1 |
Jobs on the UI thread, for a debugger. |
MITCAD_TEST_OCCT_CRASH=<operation> |
That kernel operation (e.g. fillet, or Section Analysis' clip and section) crashes like an access violation in OCCT; also in mitcad-cli. |
MITCAD_TEST_KERNEL_HANG=<seconds> |
Every kernel call that may not return (fillets, chamfers, shells and offsets, sweeps, lofts, healing: core/ffi/src/kernel/abandon.rs, mitcad#1922) first waits that long, deaf to any cancel and limit, as a call that does not return; with MITCAD_KERNEL_TIME_LIMIT=<seconds> (0: none, 300 by default) it is given up at that limit (mitcad#1917; cli.kernel_time_limit, tools/ui-kernel-cancel-test.sh). |
MITCAD_TEST_OCCT_OUT_OF_MEMORY=<operation> |
An allocation in that kernel operation (e.g. extrude) fails with std::bad_alloc: the operation fails "out of memory" (#80). |
MITCAD_TEST_OCCT_ALLOCATION_FAILS=<operation> |
An allocation of OCCT's collections fails in that kernel operation (e.g. extrude) or in the healing of a body built from B-rep data (heal), and is caught there as OCCT's checker catches its failures: only OCCT's count of failed allocations tells, and the operation or the body's build fails "out of memory" (#132). |
MITCAD_DRAWING_TRACE=1 |
Print a line per drawing view projected, sheet drawn and view added on standard error, with the phases of the hidden-line removal (compare and parts also time the other algorithm and each body alone; performance, mitcad#962). |
MITCAD_CHECK_INPUTS=1 |
Report operations that modify their input shapes (architecture). |
MITCAD_NO_FAR_FEATURES=1 |
Booleans on perforated bodies work on the whole body and cut a pattern's copies at once (architecture), for comparisons. |
MITCAD_NO_PATTERN_RUNS=1 |
Patterns of features join or cut each feature's copies on their own instead of a run of features in one boolean (architecture, mitcad#855), for comparisons. |
MITCAD_NO_NEAR_COPIES=1 |
A mirror's combine joins every image with its body whole, also a near copy of it (commands.md), for comparisons. |
MITCAD_RESULT_STORE |
Result store folder; off disables it. |
MITCAD_RESULT_STORE_MIN_MS |
Store results that took at least this long (default 100); quicker ones only when cheaper to restore than to evaluate (mitcad#882). |
MITCAD_STORE_QUICK=0 |
Store no quicker results than MITCAD_RESULT_STORE_MIN_MS (also in mitcad-cli), for comparisons. |
MITCAD_DISPLAY_MESH_WRITER=0 |
An open stores its display meshes in its own job instead of after the open on the writer's thread (mitcad#880). |
MITCAD_MESH_DURING_RECOMPUTE=0 |
An open meshes its bodies for display only after its recompute, not each body once no later feature changes it (mitcad#881). |
MITCAD_PROJECTS_DIR |
Where New Project creates projects instead of Documents/Mitcad. |
MITCAD_GIT |
git program for remotes (Preferences sets it for the app). |
MITCAD_LIBRARIES_DIR |
Where fetched component libraries are kept (default: libraries in the user's local data folder). |
MITCAD_TEXTURES_DIR |
The texture cache of Edit Appearances' texture sources: thumbnails and fetched maps (default: textures in the user's local data folder; #315). |
MITCAD_TEXTURE_FIXTURES |
The online texture sources' requests answered by files of this folder (<folder>/<host>/<path>, the query left out; a missing file is HTTP 404) instead of the network: UI tests (tools/ui-appearance-polyhaven-test.sh, #313). |
MITCAD_TEST_REMOTE_RETRY_SECONDS |
First push retry delay instead of a minute. |
MITCAD_TEST_REMOTE_CHANGE_CHECK_SECONDS |
Age of the last fetch after which the first change refetches (default two minutes). |
MITCAD_TEST_LIVE_RETRY_MS |
The live updates' first delay before connecting again to a broker (default one second, doubling up to five minutes; with this, up to 20 times it). |
MITCAD_MOSQUITTO |
The mosquitto program for the live updates' tests, when it is not on PATH or in the usual places. |
MITCAD_TEST_LIVE_CA |
A PEM file of certificate authorities the app's live updates trust besides the system's (the test broker's, tools/ui-live-test.sh). |
MITCAD_NO_UPDATE_CHECK=1 |
No update checks; update test variables, read only by a build with MITCAD_UPDATE_TEST_HOOKS: updates.md. |
MITCAD_TEST_PREFERENCES_SHOTS |
A folder where the Preferences pages whose list takes the page's height (Navigation, Cloud) save a picture of their window each time they log their layout, navigation-<area height>.png, cloud-<area height>.png (mitcad#1394, tools/ui-preferences-test.sh, app.ui-windows-preferences). |
MITCAD_SKETCH_FIRST_DIMENSION_SCALE=0 |
Preferences › Sketch › Scale the sketch to its first dimension is off until it is saved (mitcad#860); the UI test libraries set it, so that their drawn sketches keep their sizes. |
MITCAD_REMEMBER_PANEL_VALUES=0 |
Command panels start from their definitions' defaults and keep nothing on OK: no remembered Fillet Radius or Chamfer Distance (mitcad#1028, app/COMMANDS.md), and no Thread starting from the last thread's settings on a face of its size (mitcad#1298); the UI test libraries set it, so that a value one step gives never changes where a later step's panel starts. |
MITCAD_START_PAGE=0, MITCAD_START_PAGE=1 |
0: MitCad never starts on the Start tab (mitcad#1258, app/COMMANDS.md); the UI test libraries set it, so that every test starts on an empty design. 1: the Start tab at launch by its Show start page at launch, also in a UI test script's run (MITCAD_TEST_INPUT), which without the variable starts without it. |
MITCAD_NEW_DESIGN_VIEW=0 |
A new design opens as before mitcad#1683, in the exact isometric view with its origin hidden, not looking at Top with the origin shown and centred, and a design opened at the start stays in that view instead of the default view of mitcad#1698 (app/COMMANDS.md); the UI test libraries and the Python UI tests set it, as their tests were written for; tools/ui-new-design-start-test.sh sets 1. |
MITCAD_LANGUAGE=en|fi|xx |
The interface language, over Preferences › General › Language; --language comes first (mitcad#1460, translations.md). The UI test libraries and the Python UI tests set en, so that every test reads English texts whatever the machine's language; xx is a test build's pseudo-language. |
MITCAD_LOG_UNTRANSLATED=1 |
Every text no catalogue translated is logged once, Untranslated: <context>: <text>, and every text found only without its context, Fallback: <context>: <text> (in a language other than English; translations.md). |
MITCAD_TEST_LOG_URLS=1 |
Addresses the app would open in the browser (a report's issue form) are logged, not opened; the UI test library sets it. |
MITCAD_LOG_TYPED_TEXT=1 |
Text fields are logged as they change: File dialog <title>: <text> (Qt's file dialog's file name), Dialog field <title>: <text> and Panel field <input>: <text> (typed into another dialog's field or a command panel's input; never a password); the UI test libraries set it (app/framework/TypedTextLog.hpp). |
MITCAD_TEST_CRASH=app|app-exception|model-worker|import-worker|render-worker |
That process (or the model's worker thread) crashes as an access violation would (app-exception: the application throws an exception nothing catches, mitcad#773), for the crash reports' tests (app/COMMANDS.md). |
MITCAD_TEST_PARSER_PANIC=<file name or path> |
The reader of that file panics as a parser bug would (mitcad#922; core/model-base/src/reader_guard.rs): in the application's guarded readers (dxf_info, svg_info, the DXF and SVG inserts, the print settings' read) the panic becomes their error; in the import process's listings (--list-references, --list-links) it ends that process (core.bridge, tools/ui-import-listing-test.sh). |
MITCAD_CRASH_DIR |
Where crash reports go instead of crashes in the local app data (the app sets it for its workers, with MITCAD_CRASH_PARENT). |
MITCAD_CORE_DUMPS=1 |
Linux: mitcad-cli, mitcad_run_parallel and the corpus tests may leave core dumps (see Core dumps below). |
MITCAD_RENDER_SAMPLES, MITCAD_RENDER_TEST_SCENE=1, MITCAD_RENDER_WORKER |
The rendered view's samples per pixel; the fixed test scene instead of the document; another render worker than mitcad-render next to the app, also over the one picked in Preferences (rendering.md). |
MITCAD_CARGO_SWEEP=0, MITCAD_CARGO_JOB_MIB |
The crates' test builds (core.cargo_build*): no sweep of stale units after the build; MiB of available memory per cargo job instead of 2560 (the crates' test builds). |
MITCAD_TEST_PRINT_PDF=<file> |
File › Print (mitcad#1089) shows no system print dialog: it prints to this PDF file through QPrinter (printing::askPrinter, logged Print dialog skipped (test): printing to <file>): tools/ui-paper-print-test.sh, app.ui-windows-paper-print, the print steps of tools/ui-drawings-test.sh and tools/ui-build-test.sh. |
MITCAD_TEST_BUILD_UPGRADE_REFUSED=1 |
build_upgrade refuses a design with BUILD connectors of the first placing rule, as a refused edit would: opening such a design still works, with a warning (cli.build_upgrade_refused, mitcad#1151). |
App options for tests: --demo (a ready block), --screenshot <png>,
--no-recovery, --no-native-dialogs (Qt's file dialogs, so paths can
be typed), --open <file>, --set d3=35, --language en|fi|xx.
tools/ui-*-test.sh start the app on a hidden Xvfb display and drive it
with real input (xdotool), checking the app's log and screenshots
(tools/ui-test-lib.sh). Each test takes its own
display, so they run in parallel. MITCAD_UI_VISIBLE=1 shows a run on the
current display, UI_APP picks another build. Never start the app
visibly on a desktop in use.
- No fixed sleeps.
ui_syncsends Pause; the app (started withMITCAD_TEST_SYNC=1) answersSync <n>once preceding input and delayed logs are handled (app/COMMANDS.md,app/framework/TestSync.hpp). Fixed pauses only where a test checks that nothing happens, lets a long operation start before cancelling, paces drags, or avoids a double-click (ui_apart). - Typed text is confirmed. A path or a value typed into a dialog goes
through
ui_type_path "<title>" <path>(focus the dialog, select all, type, Enter) orui_type_field "<title>" <text>/ui_type_text <text>(the dialogui_focus_dialogfocused last), a command panel's input throughui_type_in: they wait until the app has logged exactly the typed text for the field (MITCAD_LOG_TYPED_TEXT), and type once more if a character was lost or the field had not taken the keyboard (#102). ui_stepwaits until no job runs (ui_wait_idle), since the window takes no input while the progress dialog shows; a test that cancels a job sends Esc without a step.- Isolation: each test has its own
XDG_CONFIG_HOME,XDG_DATA_HOME(autosave folder) and git config (GIT_CONFIG_GLOBAL,GIT_CONFIG_NOSYSTEM). Tests start the app with--no-recovery;UI_RECOVERY=1re-enables the recovery prompt. - The layout:
ui_start_appstarts the app Docked (--chrome=docked), which the tests were written for, although Floating is the default (mitcad#429), unless the test's arguments choose a layout (--chrome…) orUI_DEFAULT_CHROME=1leaves it to the preference and the default (ui-chrome-layout-test.sh,ui-browser-rows-test.sh). Tests that start the app themselves pass--chrome=dockedtoo. - The result store is off (
MITCAD_RESULT_STORE=off) because stored results would change how many features later steps compute; tests of it setMITCAD_RESULT_STORE=<dir>andMITCAD_RESULT_STORE_MIN_MS=0. - No network: update checks are off (
MITCAD_NO_UPDATE_CHECK=1);ui-update-test.shuses its own local HTTPS server. - Xvfb runs with
-noresetso a restarted app finds the display at once. The screen is 1600 x 1000 logical pixels; a test of a tall dialog setsUI_SCREEN_HEIGHTbeforeui_start_display. - The app runs without gdb: gdb loads the debug build's symbols (about
1 GB) at every start, and the app's crash handler logs a crash's signal
and stack itself.
UI_GDB=1starts it under gdb for gdb's backtrace. - Logged places are clicked as logged, so log a place a click really
takes: a check box stretched over its row takes clicks only on its box
and label, so its logged place is its box, not the row's middle; a tab
bar squeezed by its neighbours hides tabs under its scroll arrows.
Log places again when the layout or the camera moves them, and wait for
the settled place after a change of layout (a
settledhelper that sees the last place stay across a sync), not the first line logged. - Leave a mode by its own control when Esc does several things in turn: in a drawing Esc ends the tool, then clears the selection, then closes the drawing, so the tests close it with Close Drawing.
ctest app.ui-windows and app.ui-windows-workflow (configured with
MITCAD_MESA_DIR), with their own MITCAD_SETTINGS_DIR and
MITCAD_AUTOSAVE_DIR. An SSH session runs in session 0 without an input
desktop: SendInput and UI Automation do not work, so the tests post
window messages, and popups (command search, menus) are unavailable, so
commands go through shortcuts. As on Linux, a step waits for the app's
answer to the sync key (MITCAD_TEST_SYNC; the library posts Pause), and
a key's modifiers stay in the keyboard state until the app logs that it
took the key (MITCAD_LOG_KEYS): while a model job runs, Qt keeps the
input for later. As on Linux, Ui-StartApp starts the app Docked unless
the arguments choose a layout or -DefaultChrome leaves it to the
preference and the default (Floating, mitcad#429). See
tools/ui-windows-lib.ps1.
Not a test: tools/ui-windows-window-shots.ps1 -App <mitcad.exe> -Out <dir>
saves screenshots of the whole main window in the Docked chrome on the light
and the dark theme (the demo block, a feature selected, Extrude's panel
open), through the test driver in the same session, for comparing the
window's look before and after a change. Likewise
tools/ui-windows-print-settings-shots.ps1 -App <mitcad.exe> -Out <dir>
saves screenshots of the print settings UI (mitcad#655): 3D Print after
Import from Slicer…, Import Details, the profile editors, Materials,
Property Sets' print settings and an update bar, on data it makes with
mitcad-cli.
Not a test either: tools/ui-windows-place-shots.ps1 -App <mitcad.exe> -Out <dir>
saves screenshots of placement by picked geometry (mitcad#656): Box and Hole
on a face with their in-view dimensions and value boxes, a pulley on a shaft
and its Check Belt, a cylinder at a sketch point, Gear Pair and Belt Drive
with their candidate lists, an earlier version's gear opened for editing,
and Gear Pair in the Docked chrome, on data it makes with mitcad-cli.
ctest app.ui-macos (cmake/MacUiTests.cmake, option
MITCAD_MACOS_UI_TESTS) runs the bundle's binary with --demo, --open
and --screenshot and checks the screenshots with
tools/ui-image-stats.py --shot, as app.ui-windows does. The app renders
offscreen and nothing is clicked, so no Accessibility or Screen Recording
permission is needed, but a window server is: without one the test exits
with 77 and is skipped (MITCAD_UI_REQUIRE_GUI=1 fails instead). Settings,
recovery, projects and thumbnails go to a temp folder, and
QT_FORCE_STDERR_LOGGING=1 brings Qt's log to the test's logs.
MITCAD_UI_LLDB=1 runs the app under lldb --batch for a crash's stack.
app.ui-macos-workflow runs step scripts (tools/ui-scripts/*.mitcad-ui)
through the in-process test driver (MITCAD_TEST_INPUT), so it works over
SSH. Helpers: tools/ui-macos-lib.sh (bash 3.2,
BSD userland).
app.ui-macos-native-print-managers exercises Materials, Printers and
Processes by place (mitcad#1158). Its macOS wrapper creates a synthetic box
in a project, separate project and user print items, and a local base
library fetched from a temporary Git repository. It needs neither the
network nor an installed component library. The native input checks both
profile windows at once, place counts and search, the project's editing
line, F2 name selection and Return, settings edits, Copy to, New, Use in
this design, and the built-in read-only state with Duplicate's destination
menu. Materials additionally checks actual appearance swatches, Default,
and Delete/Backspace. Three fixed-size Printer captures show the divider
before and after a genuine pointer drag and after choosing a library
printer whose dialect rebuilds the settings rows. The orchestrator
visually compares the divider positions; this is evidence for manual
review, not an automated width assertion. The wrapper verifies the written
library files, then starts a fresh application without a design and checks the remaining
library groups and editing. Screenshots and logs stay in the test output;
the shared macOS harness owns the Aqua lock for each application run.
Before focus-widget attempts focus, its diagnostics record Qt's active
popup, active window, target and lookup window. Every matching named field
reports visibility, enabled state, geometry, its actual window, GlassCard
host and parent chain. This distinguishes an open popup or a hidden
duplicate from a command field that the presenter has not shown. The
diagnostics do not dismiss popups, change visibility or bypass the existing
visible/enabled checks.
qt-choice sends real pointer move, press and release events to a populated
combo popup. Each phase resolves the persistent item's current visual
rectangle and screen point again: selecting a motion type can resize its
floating command card during the press. Before opening and before each
phase it waits, within six seconds, until the popup is visible and the
active popup and the row is laid out, inside its viewport and hit there:
under load a popup can be visible to Qt while it is still being shown or
its rows lack their geometry. A row that stays unavailable fails with the
phase and each of those conditions, plus the window's exposure, which is
reported only (a Windows service session never reports it). The log records each phase's
rectangle, screen point, popup visibility and current caption. The driver
then requires the original popup's actual closure within six seconds before
advancing. It logs the resulting caption without assuming that an action
such as New Printer keeps its temporary menu label. It never selects the model item or
hides the popup directly; a dialog opened by the selected action remains
available to subsequent script steps.
app.ui-macos-print-occurrences and its native counterpart exercise
3MF occurrence selection and Send in both appearances (mitcad#856, #857): one
selected placement, two placements independently put on their print bed
faces, and a selected parent component sent as assembled by its button or
turned together onto a picked green face. Escape ends only the question,
sends nothing and leaves the panel open; a second Escape cancels it.
Nothing is exported or launched before the face choice is answered. A local
recording program stands in for the external slicer. The checks read its actual 3MF
ZIP/XML, placements, normals and build objects, verify visible status text
and unchanged model/undo state, and retain a capture per case. No external
GUI or network is opened.
All ui_run_app launches share the per-user kernel advisory lock at
~/.mitcad/macos-ui.lock, across checkouts and independent CTest runs.
The reserved shell descriptor 9 and the actual application share ownership;
no PID file, stale-lock removal or environment opt-out is involved. The
lock is acquired before the per-application UI_TIMEOUT clock starts and
released after that application is reaped. An interrupted waiter is
cleaned up; if its shell is killed, a still-running application retains
the lock until it exits. The application remains UI_PID, so existing
cancellation and crash handling keep targeting the real child.
Coordinate whole GUI queues one at a time: this per-application lock
is a backstop, and an outer CTest deadline still includes time queued for
it. Existing test deadlines are unchanged. Frozen older release checkouts
without this helper must finish their GUI queue before another starts.
repo.macos-ui-lock exercises the actual helper with processes that open
no windows: cross-process exclusion, queue time outside UI_TIMEOUT,
direct child identity, nonzero exit, interrupted waiting, a killed shell
with a live child, and application timeout cleanup. A real TestDriver: FAIL
line gives a lingering application up to one second to exit within its
existing deadline, then stops that
owned application and reports the assertion while preserving its actual
exit code and log. Script traces quoting that text do not trigger cleanup;
explicit LLDB runs retain their debugger lifecycle. The process regression
also covers this failure cleanup, trace exclusion and subsequent lock use.
The native slicer and table/configuration parity workflows also exercise
an actual NSOpenPanel. macOS hosts that chooser's editor in an XPC
service, so these workflows use the driver's native-system-key and
native-system-type steps for its Go to Folder field and Open action.
Those steps post real WindowServer keyboard/Unicode events and require
Accessibility / event-posting permission for the Mitcad test app in
System Settings, Privacy & Security. A missing permission fails clearly;
it is never treated as a successful import or replaced with a model API
call. An explicitly authorized local run can set
MITCAD_TEST_REQUEST_EVENT_ACCESS=1 to request permission from Mitcad;
ordinary runs only preflight the existing grant. These input steps require
MITCAD_TEST_INPUT, an actual native file panel, and this app as the
active/frontmost key-window owner. A changed target stops the input.
native-file-state [label] records the panel's public selection and focus
state alongside the event-access and target-frame diagnostics.
The ordinary in-process UI and screenshot checks retain their existing
permission requirements.
app.ui-macos-dialogs checks the default Qt command search and parameter
sheet with real keyboard input in both light and dark appearance. It saves
focused captures, checks filtering and native shortcut text, and exercises
parameter creation, inline editing, validation and deletion. The colour
scheme request applies only to the test process. Set
MITCAD_UI_REQUIRE_RETINA=1 to require a backing scale of at least 2 for
Retina acceptance; ordinary runs also support a 1x display.
Real .f3d designs are never committed. These tests read local data and
are skipped without it:
MITCAD_F3D_CORPUS(default~/f3d-corpus):.f3d/.f3zfiles, searched recursively. ctestsf3d.corpus_occt,f3d.corpus_meshes,f3d.corpus_import,f3d.corpus_timeline(debug builds sample every n-th file),core/f3d/tests/corpus.rs,design_corpus.rs, and the.f3dpart ofui-import-test.sh(MITCAD_F3D_UI_PART, else the smallest part).MITCAD_F3D_DESIGN_REF(default~/f3d-design-ref): an independent decoder's JSON per design, compared field by field indesign_corpus.rs.MITCAD_F3D_MODELS(default~/f3d-models): reference models<id>/<id>.f3dwith external dumps<id>/<id>.json(SCHEMA.md). ctestf3d.models_loftandcore/f3d/tests/design_models.rs.
Full corpus runs need a release build: test_f3d_import --corpus [dir] [--reports DIR] [--time-limit S] (core/import/README.md)
and test_brep_import --corpus (core/f3d/CORPUS_REPORT.md).
The corpus runs (test_f3d_import --corpus and --models,
test_brep_import --corpus, test_exchange --corpus, freecad.corpus,
ipt.corpus)
import each file in a child process of its own, several at once, the
largest files first (core/tests/parallel_runs.hpp).
OCCT's global state stays per file, and a crash, a hang or too much memory
ends only that file, which is reported and counted as failed. The lines
come in the files' order and the totals are those of a run in one
process, so outputs compare line by line (apart from the times, and a line
on standard error that sums up the children).
| Option | Environment | Default |
|---|---|---|
--jobs N |
MITCAD_CORPUS_JOBS |
the cores / 4, at most the memory available / the limit; 1: every file in the one process, as before |
--memory SIZE |
MITCAD_CORPUS_MEMORY |
4G per child: what it may commit (RLIMIT_DATA on Linux, inherited by its children; a job object's process memory limit on Windows; not enforced on macOS); none |
--file-timeout S |
MITCAD_CORPUS_TIMEOUT |
3600 s per child; 0: none |
A child that cannot allocate fails its file, or hangs in a thread that could not allocate until its time is up: keep the limit well above what a file needs (the line on standard error gives the largest peak).
On Linux, mitcad-cli (every command), mitcad_run_parallel and the
corpus tests that start themselves per file (test_f3d_import,
test_brep_import, test_exchange) make themselves non-dumpable at
start (prctl(PR_SET_DUMPABLE, 0)), unless MITCAD_CORE_DUMPS=1: a
child that runs out of its memory limit aborts (a Rust allocation that
fails ends the process with SIGABRT), and WSL captures core dumps
through a pipe in core_pattern, which ulimit -c 0 does not stop. Each
dump was the size of the process (gigabytes), was written to the host,
and took the WSL service down with every distribution in it. The flag is
per process and execve sets it again, so each program clears it itself;
the crash and its report are as before. A process that is not dumpable
cannot be attached to with gdb -p either: start it under gdb, or set
MITCAD_CORE_DUMPS=1 (only where core dumps go to a file).
Real .ipt part files are never committed. MITCAD_IPT_CORPUS (a
PATH-like list of folders) points at them; without it the tests skip:
the ctest ipt.corpus (tools/cli/ipt-corpus.cmake: every file imported
with mitcad-cli import-ipt, compared with a STEP file of the same part
next to it, <name>.stp, within 1e-6 or the limit the folder's
references.tsv gives the file), core/ipt/tests/corpus.rs and a step
of ui-import-test.sh (the smallest file). Files run as the other corpus
tests do (the options above). The assembly tests iam.corpus and
iam.corpus_reorient read MITCAD_IAM_CORPUS, or MITCAD_IPT_CORPUS when
it is unset, so that the assemblies' folders (with the parts they refer
to) need not also be ipt.corpus's parts. See
core/import/docs/ipt.md.
Real .dwg drawings are never committed. MITCAD_DWG_CORPUS points at a
folder; every index.tsv under it lists drawings (a header row naming the
columns: file, relative to the index, and data sheet values to check:
length_mm, chord_distance_mm, tube_diameter_mm, tube_wall_mm,
mass_kg, density_kg_m3, volume_mm3, solids, components; other
columns are notes). The ctest dwg.corpus (tools/cli/dwg-corpus.cmake)
imports each with mitcad-cli import-dwg --check: every body built and
valid, every 3D entity taken, the bodies within the drawing's extents,
and the row's values (see
core/dwg/README.md); it skips without the
variable. Each drawing is imported in a child process of its own, several
at once, as the other corpus tests do (mitcad#875; the options above).
Real .3dm models are never committed. MITCAD_3DM_CORPUS points at a
folder of them (subfolders too): openly licensed sample models, each
with its source and licence in an index.tsv (mitcad#1715). The cargo
test core.3dm reads and converts each .3dm file without OCCT (every
object read, every B-rep's faces on a surface and its loops closed, every
SubD's net a Form's cage), and
the ctest 3dm.corpus (tools/cli/3dm-corpus.cmake) imports each model
an index.tsv lists (column file; check no for a model with
objects left out on purpose) with mitcad-cli import-3dm --check, a
model a child process, several at once, as the .dwg corpus does: every
body built and valid, every solid, surface and mesh taken. A row may add
expect, a regular expression the import's text must match (no ;, [
or ]), and edit, a mitcad-cli run script beside the index run on
the imported design. Both skip without the variable.
The SubD model of the corpus (mitcad#1810; content id 98400d4d, MIT,
written by the format's own application at archive version 80) uses
both: its row expects the Form line 8 vertices, 6 faces, 8 creased edges, 1 corners, closed (five edges creased for good, three semi-sharp,
one corner vertex), the note on its one edge whose sharpness changes
along it, and every check passing; its script checks the Form's stored
cage against the file (the vertices at their points in millimetres with
the file's ids, the six faces' ids, the corner, each crease and the
semi-sharp ones' sharpness 1, 3 and 1.5), the body (24 faces, its box
from the corner vertex at the origin to within the cage's box of 10 mm,
0.01 mm allowed), and that a vertex moved with form.move rebuilds it.
Real glTF files are never committed (the committed sample,
core/gltf/samples, is written for the tests). MITCAD_GLTF_CORPUS
points at a folder of openly licensed sample files (subfolders too),
each with its source and licence in an index.tsv and the attribution
in a licence file beside it (mitcad#1826). The ctest gltf.corpus
(tools/cli/gltf-corpus.cmake) imports each file an index.tsv lists
(column file) through OCCT with mitcad-cli run, in the index's
folder so that a .gltf file's buffers and images beside it are read.
The column check names the file's script of commands and expectations
beside the index: it imports the file and checks facts read from the
file itself (the gltf_file query's nodes, meshes, triangles, materials
and images; the bodies and components the import makes, their
placements, volumes and bounding boxes; the materials as appearances).
A row whose check is empty or no is only imported. Skipped without
the variable; not one of the release's required corpora.
Real .serp files are never committed (the import's test file is
written by mitcad-cli serp-test-file). MITCAD_SERP_CORPUS points at a
folder of the files' writer's published examples (subfolders too), each
with its source and licence in an index.tsv (mitcad#1870). The ctest
serp.corpus (tools/cli/serp-corpus.cmake) imports each file an
index.tsv lists (column file) through OCCT with mitcad-cli run, in
the index's folder. The column check names the file's script of
commands and expectations beside the index: it imports the file and
checks facts read from the file itself (as many bodies as it holds
solids, surfaces and meshes, their volumes and bounding boxes, the
components of its blocks). A row whose check is empty or no is only
imported. Skipped without the variable; not one of the release's
required corpora.
FreeCAD documents are never committed (they contain B-rep files, and FreeCAD's examples are LGPL). Reference data is made with FreeCAD itself, in the distro only:
tools/freecad-export/install-freecad.sh: FreeCAD 0.21.2, 1.0.2 and 1.1.4 AppImages, checksum-verified, extracted to~/freecad/<version>/.tools/freecad-export/run_all.sh [--no-examples] [version...]runs FreeCAD headless (xvfb-run): each script intools/freecad-export/models/is saved as~/fcstd-models/<version>/<id>.FCStdwith a dump<id>.json(dump.py: objects, enumerations, placements, stored shapes' properties, sketches as FreeCAD reads them, expression values). Model families:sketch_*,pd_*,part_*,expr_*. Script directives:# Mitcad expects: no fallback(the corpus test fails if any feature falls back) and# Mitcad change: Width = 60 mmwith a FreeCAD-made variant<id>_changed.FCStd(variant()in_prelude.py). FreeCAD's bundled examples go to~/fcstd-examples/<version>/.enums.pyandmerge_enums.pyproduce~/fcstd-models/enums.json, the source ofcore/freecad/data/enums.json.MITCAD_FCSTD_CORPUS(aPATH-like list): ctestfreecad.corpus(tools/cli/fcstd-corpus.cmake) imports every file withmitcad-cli import-fcstd, compares with the dump (--reference) and replays variants (--set), each file in a child process of its own (mitcad_run_parallel, the options above through the environment;MITCAD_CORPUS_JOBS=1checks them in the script's process). The ctestfreecad.corpus_designs(tools/cli/fcstd-designs.cmake) checks single documents, found by their content ids under those folders and their parent folders, against their expectations (no fallback, the volume).core/freecad/tests/sketch_corpus.rscompares every sketch with FreeCAD's reading. Example:MITCAD_FCSTD_CORPUS=~/fcstd-models:~/fcstd-examples ctest -R freecad.MITCAD_GEOMETRY_CASES(a folder): geometry kernel cases made of bodies cut from reported models, which are not committed, each in a folder of its own as B-rep files.geometry/tests/test_boolean.cppreadscaliper-pad028/body.brepandpad.brep(a join that loses volume, mitcad#964), andtest_chamfer_kernel.cppreadschamfer-open-shell/body.brep(a chamfer that healing made an open shell, mitcad#1182); skipped with a message without the variable. The ctestcli.geometry_cases(tools/cli/geometry-cases-test.cmake) opens designs of such cases withmitcad-cli infoand checks that the features it lists build without a warning: infillet-corner-overhang/, a three-fillet corner (fillet-corner.mitcadFillet3, 0.057 mm on R3) and a rim rounding built as a ring (fillet-corner-ring.mitcadFillet4), mitcad#1327; skipped without them.MITCAD_STEP_REPORTED(a folder): STEP files of parts from issue reports, never committed, named after their report (github-<issue>-…).geometry/tests/test_fillet_step_corner.cpp(ctestgeometry.fillet_step_corner) reads the first body ofgithub-130-…and checks the fillets of its corner edge and of what is left of it after the floor is rounded: one clean blend face at every radius, without a warning (mitcad#1253, port patch 1240 of mitcad#1256); skipped with a message without it. A synthetic body with the same corner in the same test covers patch 1240 without the file.MITCAD_MITCAD_REPORTED(a folder): MitCad designs from issue reports, never committed, named after their report (github-<issue>-…).geometry/tests/test_join_many_bodies.cpp(ctestgeometry.join_many_bodies) reads bodies of the base feature ofgithub-133-…(their B-rep data from the design file) and checks the union of a nut lying inside a threaded carriage, which OCCT's exact union gave without a solid: one valid solid of the expected volume (mitcad#1273); skipped with a message without it. Its synthetic test of unions in groups runs without the file. It also joins all 257 bodies, logs the union's time, and checks its solids, shells, volume, that its faces are merged (port patch 1285 of mitcad#1280) and points sampled in every body's box, and checks Cut and Intersect of the design's two back plates against their union, also by sampled points (mitcad#1278); a synthetic row of blocks with a near miss runs without the file. ctestcli.drawing_tangent_edges_reported(tools/cli/drawing-tangent-edges-test.cmake) writes the drawing ofgithub-177-…and its body as a.brepfile, whichtest_drawing --tangent-edgesprojects in seven views: no line along a tangent edge or a seam with Tangent Edges off, exact and polygonal, thin ones with it on, every other sharp line still drawn, the body unchanged (mitcad#1438); skipped with a message without it. A synthetic filleted block ingeometry.drawingruns the same checks without the file. ctestcli.thread_fit_reported(tools/cli/thread-fit-reported-test.cmake) finds a design by its content id in the folder's project subsets (the folder may hold them in subfolders, each with its.mitcad/store), runs Auto Fix on its thread on a bore too small for it and checks that it is refused as the design is (a chamfer on the step between the bore and the thread's crest would fail) and, with that chamfer suppressed, that the bore's radius dimension72/2becomes73.835/2, the wall dimension stays 3 mm and no feature newly fails (mitcad#1632); skipped with a message without it. The mock kernel's model tests (thread_autofix_tests) cover the same case without the file. ctestcli.placements_reported(tools/cli/placements-reported-test.cmake) finds two archives ingithub-253/by their content ids, unpacks each into the build folder and opens the jointed mechanism in it by its content id (the second one's linked parts, which the archive renamed with_for#, copied back to the names its links give): the first opens with nothing to straighten, the second, which older builds' drift had made unopenable, with six placements straightened and a warning each; saved, each opens again without a placement to straighten (mitcad#1664); skipped with a message without them. The mock kernel's model tests (occurrence_placement_tests, the many-drags test injoint_solver_tests) cover the same without the files. ctestcli.assembly_context_reported(tools/cli/assembly-context-reported-test.cmake) finds the archive ingithub-253/by its content id, unpacks it into the build folder and runsassembly_context_reported.jsonon the jointed mechanism in it: the two links' joints on their hole edges resolve, and the link bodies keep the volume and faces of their own design files through two drags of the primary lever, since the other links' and rods' automatic cuts leave alone what moves against them through joints (mitcad#1667); skipped with a message without it. The mock kernel's model tests (joint_motion_cut_tests,inserted_cut_scope_tests) cover the rule and inserted cuts without the file.
SolidCraft designs are never committed except the import's own test
designs, written by hand (core/solidcraft/tests/designs, with their
expected values worked out from SolidCraft's definitions; SolidCraft is
not built or run for them). MITCAD_SOLIDCRAFT_CORPUS (a PATH-like
list of folders) points at real ones: ctest solidcraft.corpus
(tools/cli/solidcraft-corpus.cmake) imports every .sc and .solidcraft with
mitcad-cli import-solidcraft and checks one with <name>.expected.json
next to it (SolidCraft's solidcraft-cli eval of it) against it; a folder's
known.txt (file name, a tab, the reason) lists files allowed to fail
their check. core/solidcraft/tests/corpus.rs reads every file. Skipped
without the variable.
MITCAD_DESIGN_CORPUS (a PATH-like list) names folders of MitCad
projects saved by earlier versions (each design with its project's
.mitcad/brep store), never committed. ctest designs.corpus
(tools/cli/designs-corpus.cmake) opens every .mitcad with mitcad-cli info and fails when any feature of one fails (mitcad#1613): a sketch
such as a linked projection whose source changed shape since (#249),
or a feature an earlier version built, such as a chamfer refused since. A
feature that legitimately fails (the design was saved with it failing) is
listed in a known.txt in the design's project folder or any folder of
the corpus: a line per feature with three tab-separated columns, the
design's path relative to the known.txt's folder (forward slashes), the
feature's uid and the reason (# starts a comment). The test counts such
a feature as known, and reports a listed feature that builds again so
that its line is removed. Skipped without the corpus.
Real slicer projects are never committed. MITCAD_3MF_CORPUS (a
PATH-like list of folders) points at them; each folder's index.tsv
lists its projects (a header row naming the columns, then a row per
project; projects named by their content id). The ctest 3mf.corpus
(core/model-tests/print/src/print_files_corpus.rs, a test ignored in
core.model.print and run with --ignored) imports each project's print
settings into a
fresh design as Import from Slicer... does (import_print_profile),
checks the row's columns where it gives them: bytes, dialect,
printers, processes and materials (how many came in), printer
and process (their names) and problems (the values not read as the
import's summary lists them, separated by |; empty or none for
none), then exports a body of each material in the same dialect and
reads the export back: every value read into MitCad's keys must come
back alike (numbers within 1e-6). Other columns are notes. Skipped
without the variable. Example:
MITCAD_3MF_CORPUS=~/3mf-corpus ctest --preset dev -R 3mf.corpus.
USDZ export (#123, commands.md)
writes the binary USD layer with MitCad's own code; the tests read it back
with mitcad-usdz's reader (the package's 64-byte alignment, the layer's
header and metadata, prims, points, indices, normals, materials, subsets,
texture coordinates and transforms). The format was checked once with
OpenUSD's own validators when the export was written (#123); no USD
library is needed to build or test.
Animated USDZ (mitcad#1597,
commands.md) is read
back the same way (the time samples and the layer's time code range and
rate). OpenUSD's own reading of the samples is a manual check, run in an
isolated environment (the Linux distro or a VM, never the host) when the
writer's time samples change, with OpenUSD's Python package (usd-core,
in a virtual environment):
python3 -m venv ~/usd-check && ~/usd-check/bin/pip install usd-core
MITCAD_USDZ_ANIMATED_SAMPLE=$HOME/animated.usdz \
cargo test --manifest-path core/Cargo.toml -p mitcad-usdz animated_sample_for_validators
~/usd-check/bin/python tools/usdz-check/check-animation.py \
~/animated.usdz tools/usdz-check/animated-sample.json
# The CLI's two-box design with OCCT (ctest cli.export_usdz_animation):
~/usd-check/bin/python tools/usdz-check/check-animation.py \
build/dev/tools/cli/usdz-animation/two_boxes.usdz tools/usdz-check/two-boxes.json
The script opens the package with OpenUSD, checks the stage's time code
range and rate, reads each listed prim's xformOp:transform samples
(their count and times) and its local transform at the first, middle and
last samples against the expected poses (MitCad's layout), and runs
OpenUSD's validators on it (usdchecker's: the UsdValidation
framework, all registered validators, as usd-core 26 has it; the
older UsdUtils.ComplianceChecker where that framework is missing); it
prints OK or each difference and exits non-zero on any.
The development repository has three long-lived branches, so that large features do not hold up fixes and fixes reach releases without waiting for features:
feature branch ─────────► features ──► dev ──► main ──► release/X.Y.Z
fix or improvement branch ───────────► dev
release fix ─────────────────────────────────► main ──► dev ──► features
- dev takes bug fixes, small improvements, chores, documentation and
tests. Start such a branch from
dev, and open its pull request againstdev. - features takes new capabilities and large rewrites. Start them from
featuresand open their pull requests againstfeatures. A change that grows into a rewrite moves tofeaturesbefore it is merged.featuresis merged intodevwhen it passes the full check, at least once a day. - main is the last release plus its fixes.
devis merged into it when a release starts, and the release branchrelease/X.Y.Zis cut from it. A fix found while a release is being built goes tomainfirst and then flows back intodevand from there intofeatures.
Releases are published as before: one snapshot commit per version tag.
For development and merges into dev, features or main the check is
scoped and fast; an occasional miss is accepted:
- On Linux:
tools/check-all.shin its default mode (add--freshwhen CMake files changed), e.g. in the distro aftersync-to-wsl.sh:wsl -d mitcad-dev --cd "~/src/mitcad" -- bash -lc tools/check-all.sh. It runs only the ctests, UI tests and corpus the change affects. - Windows or macOS only when the change touches that platform's own
code (
app/platform/,Q_OS_*branches, packaging, its scripts): a warning-free build andctestthere. - Commit in steps that build and pass the tests.
Before a release build, the full check: tools/check-all.sh --full on
Linux, a warning-free build with ctest in the Windows VM (with
MITCAD_MESA_DIR), and tools/release-check-macos.sh on macOS (build,
no AppKit, every ctest, the package;
macos-shared-qt.md).
tools/check-all.sh [--full] [--ui-jobs N] [--ui auto|all] [--ctest auto|all] [--ctest-jobs N] [--testrun auto|off] [--corpus auto|always|never] [--corpus-tests N] [--corpus-jobs N] [--memory SIZE|auto] [--overlap auto|off] [--fresh] [--only STEP,...] [--release-passed DIR --release-tag X.Y.Z-rcN [--all-geometry]]
It checks at two depths:
- By default (development, and before a merge to
mainon a Linux machine; a Windows or macOS machine checks on its own platform) the check is scoped to the change and fast: a test runs only when what it depends on differs from every run in which it passed on the machine, a few long ctests that seldom catch anything are left out, and a UI test depends only on the areas it exercises (below). Now and then a fault slips through to the full check; that is accepted. --full(or--release), the check before a release build, runs everything: every ctest (--ctest all, with the release builds' doctests andapp.appimage), the corpus (--corpus always) and every UI test (--ui all), and at the end each fuzz target of the file readers for 60 s (MITCAD_FUZZ_SECONDS; rowsfuzz-seeds,fuzz-build,fuzz:<target>) when cargo-fuzz and a nightly toolchain are installed, a skippedfuzzrow with a note otherwise (the fuzz targets). Release builds are checked only this way.
| Step | |
|---|---|
| configure, build | Compiler warnings fail the check (an incremental build only shows those of what it compiled). |
| fmt, clippy, deps | Beside the ctest step (--overlap auto, below). clippy's target dir is build/dev/clippy, kept across syncs, or, where build/dev/cargo links into a persistent cargo folder (MITCAD_CARGO_TARGET_DIR, as in the release builds, whose build folder starts fresh), clippy/ beside it there, so that a release does not check every crate from nothing. |
| guide | The user guide's table of contents against its ## and ### headings (tools/check-guide-contents.py, mitcad#1032): its self-test, then the guide; a table that differs fails the step, which prints the expected table. After a heading of docs/user-guide.md changes, tools/check-guide-contents.py --write writes the table. Beside the ctest step with fmt, clippy and deps. |
| root-compile | On a host whose GCC is newer than the Linux release's build root's, the C and C++ files the change touches compiled with the root's GCC, -fsyntax-only (tools/check-root-compile.py, mitcad#1551), so that code the host's compiler accepts and the release's refuses fails here rather than in the release (0.53.0-rc1 and 0.54.0-rc1 failed on an OCCT handle of a derived class copy-initialized or returned as a handle of its base, which GCC 15 accepts and GCC 13 refuses). The files: those that differ from the merge base with the nearest of origin/dev, origin/features and origin/main (committed or not) and have compile commands, and for a changed header the sources whose dependencies name it (ninja -t deps); with --full every source file of geometry/, core/cpp/ and app/. Each runs in the root (build-root.sh run) with the dev build's compile_commands.json flags, so the tree, its generated headers and the build's packages are the same and only the compiler and its system headers are the root's; include folders outside /usr, /etc and /var (a Qt installation, the render prefix) are bound in at their real paths. An error or a warning fails the row (the release's build fails on warnings too) and its log, check-logs/root-compile.log, shows the compiler's output per file. The root is MITCAD_LINUX_BUILD_ROOT, the variable the release reads: export it in the login profile of a machine that has a root. The row is skipped, with the reason as its line, without that variable or root, when the build's compiler is not GCC or not newer than the root's (inside the root itself, as in the release's own check), or without bwrap. Beside the ctest step with fmt, clippy, deps and guide. tools/check-root-compile.py --list names the files without compiling; --base REF measures the change from another ref. |
| ctest | The tests whose sources changed (below), without the corpus group, through the test runner (below); cli.perf_* run serially. The Linux UI ctests (app.ui-linux-*, each on a hidden X server of its own) run beside the others, within the runner's UI entries at once (mitcad#832). The geometry suite runs as one ctest per part (geometry.suite.<part>). |
| corpus | f3d.corpus*, f3d.models_loft, freecad.corpus*, ipt.corpus, several at once (--corpus-tests), each importing several files at once (--corpus-jobs, MITCAD_CORPUS_JOBS). By default the test runner gives each corpus test its files at once from its profile (mitcad-testrun --corpus-children, mitcad#832; tools/testrun/README.md): every run records each file's time and peak, and the next starts the longest files first and shares the machine's cores and the run's memory budget among the corpus tests by their work, a long test more children and a short one fewer, each child's memory limit twice its test's largest file's peak, never below MITCAD_CORPUS_MEMORY (1536M). A test without that history yet, every test with --corpus-jobs, and ctest -j without the runner take the fixed plan: all their children together fit the run's memory limit less 1G at MITCAD_CORPUS_MEMORY each, and the cores of a test slot; about the square root of that many tests run at once (12G, 32 cores and three slots: two tests, three files each). Each child runs within 300 s (MITCAD_CORPUS_TIMEOUT); f3d.corpus_designs checks its designs one after another in one process since 0.32.0 (at once, under the full check's load in the Linux release's build root, an item ran out of its item time), and a debug build's imports try an item from its own start, the route tried first, three times as long (--own-start-time-scale, mitcad#847); the runner then plans it by its own history, not by children (mitcad#872). With the budget from the free memory (--memory auto on bare metal, below) a child beside others starts only while the memory available exceeds the reserve by the child's file's last peak (MITCAD_CORPUS_RESERVE). The corpus step runs beside the UI tests (--overlap auto). Every corpus test is a row of the table. auto runs them only when CORPUS_SOURCES or the corpus files differ from every passing run on the machine (~/.cache/mitcad/corpus-passed). CORPUS_SOURCES: the readers and the import, the bridge's kernel and import files (core/ffi/src/kernel, *_import.rs, ipt_history.rs, exchange.rs, memory.rs, core/cpp; not lib.rs or other families' files), the geometry, mitcad-cli's imports (tools/cli/import.cpp, not main.cpp), the build files, the OCCT port, and the resolved dependencies of the import's crates (cargo tree of CORPUS_CRATES, instead of Cargo.toml and Cargo.lock, so a crate added for something else does not count). Changes in core/model alone don't trigger it: use --corpus always when they may affect imports. |
ui-<name> |
The tools/ui-*-test.sh whose sources changed (below), --ui-jobs at a time (below), longest first, 30 min limit each (UI_TIMEOUT); with the test runner the machine's learnt cap within MITCAD_UI_JOBS, and each test's learnt room (mitcad-testrun --ui-rooms: the most other UI tests it may have beside it after it failed beside more and passed alone) is kept: such a test waits until few enough run, while the others go on (mitcad#872). The tests' waits for a log line (ui_expect_log, ui_expect_new) do not count the time the application computes (a job logged Computing ... started and not its end), up to 60 s more, so that a preview that takes longer under load is not a failure. ui-compute runs alone at the end (flaky under load), after the corpus step that ran beside the others. A test that fails among the others without crashing runs once more alone after them: a pass shows as ok-again and counts, so load flakiness stays visible without failing the check; a second failure, or a crash, fails it (mitcad#657). |
ctests by what changed (--ctest auto, the default; #134): each
ctest has a fingerprint of what it depends on, and is skipped (an
indented ctest:<name> row, skipped) when it passed with that
fingerprint on the machine before (~/.cache/mitcad/ctest-passed/<name>,
shared by the checkouts). tools/ctest-fingerprints.py finds the
dependencies from the build itself, not from a list kept by hand: ctest's
own listing (--show-only=json-v1), CMake's file API (check-all asks for
it before configuring; the targets, their folders, sources and
dependencies) and cargo metadata (the crates' dependencies). A test's
fingerprint covers:
- its registration (command, properties), without the checkout's paths, so that the checkouts share the passes;
- the files its command names: a cli test's JSON script or design, a
cmake -Pscript, a Python or shell script and the files beside it; - each program its command runs or names (the test executable,
mitcad-clias-DCLI=...): the CMake targets it is built from, through their dependencies. For each target its folder (less the folders of other CMake directories and of Rust crates, and less the files tests name, so that a cli test's JSON counts only for that test), its listed sources, and for a crate Corrosion builds (mitcad_ffi,mitcad-release) that crate's Rust closure; with them the build files (the top-level CMake files,cmake/,triplets/,third_party/with the OCCT port,vcpkg.json,rust-toolchain.toml), the compiler and the build's options; - for a crate's tests (
core.vcs.*,core.model, ...; the fixturescore.cargo_build*; the doctests) the Rust closure of the package: the workspace crates it depends on (with its dev-dependencies), the files theyinclude_str!(socore.mcpfollowscommands.md), the external crates with their versions and features,core/Cargo.tomlandrust-toolchain.toml; core.dependencies(cargo-deny): the manifests,Cargo.lockanddeny.toml;repo.spdx: every file but documents;- the fingerprints of the fixtures it requires (
cli.exportfollowscli.exchange's), but not of the fixtures that build the crates' test binaries.
A test whose program none of this recognises depends on the whole tree,
as does every test when the file API's reply is missing. Markdown
documents count only through an include_str!. So a documentation change
runs no ctest, one in core/vcs the vcs tests and what links the bridge
(cli.*, core.bridge, ...), one in geometry/ the geometry tests and
what links it, and one in a cli test's JSON only that test (and the tests
whose fixtures it sets up). FULL_ONLY tests (app.appimage,
core.doctests_release) run only with --ctest all. A test named in
--only (--only ctest:core.model) always runs; --only ctest:<name>
without ctest runs only the tests named. ctest still brings in the
fixtures a test needs (core.cargo_build before a crate's test), and
the tests run in one ctest call, in parallel. check-logs/ctest-plan.tsv
lists each test's decision; tools/ctest-fingerprints.py plan ... --explain <test> prints what a fingerprint is made of, and
tools/check-all.sh --dry-run lists the ctests, the corpus and the UI
tests that would run for the working tree, building and running nothing.
The release gates' geometry tests (mitcad#1822): --full runs every
ctest, but the Linux release gate gives it --release-passed DIR --release-tag X.Y.Z-rcN, and the ctest step's test runner then skips a
geometry* ctest whose fingerprint is one with which it passed in an
earlier release gate on Linux (an indented ctest:<name> row,
skipped), and keeps the fingerprints of this run's passes with the
release's name. The Windows and macOS release gates do the same in their
full ctest. The fingerprint is the one above, computed by mitcad-testrun
itself (in Rust, the same on every platform), with the release's version
left out of the files every release changes; the passes are kept per
platform outside the build folders, and the platforms' records never mix.
--all-geometry runs them all; a platform without records (the first
release with fingerprints) runs them all to record them, and every
release's report lists
the skipped tests with the release in which each last passed
(tools/testrun/README.md).
Development checks never skip by release fingerprints, and no other test
group is skipped this way.
UI tests by what changed (--ui auto, the default): a UI test is skipped
(a skipped row) when its fingerprint is one it passed with on the
machine, kept in ~/.cache/mitcad/ui-passed/<name> and shared by the
checkouts as the corpus's are. The fingerprint is of the files' contents
(Markdown documents left out, here and in the corpus's, since no UI test
or corpus test reads them):
- the areas the test exercises, which it declares in its header,
# check-all sources: app/sketch core/solver tools/cli(several such lines add up), which must exist: the parts ofapp/it drives (app/sketch,app/commands,app/files,app/render, ...), the crates and bridge files of its family (core/vcs, the import's crates),tools/cliwhen it makes its designs withmitcad-cli; - the build files (
UI_BASE:third_party/, the top-level CMake files andcmake/,triplets/,rust-toolchain.toml,vcpkg.json) and the build's options (MITCAD_*switches such asMITCAD_COMPILER_CACHE, the build type); - its script and the test library (
UI_LIBRARY:tools/ui-test-lib.sh,ui-image-stats.py,xwd2png.py); - the main window's layout as the built application lays it out:
tools/ui-layout.shstarts MitCad with the demo design on a hidden Xvfb display once per check (also in a dry run, with the last build) and takes itsWindow layout:line, the window's size and minimum size and where the menu bar, the toolbars, the docks, the status bar and the 3D view are (kept ascheck-logs/ui-layout.txt). Every UI test clicks and takes screenshots in that window, so a change that moves or resizes any of it reruns every UI test, whichever files it was in (mitcad#412: a row added to the sketch palette made the window 9 px taller, andui-report, which declares onlyapp/report, was skipped until main failed). When the layout cannot be read, no UI test is skipped and no pass is kept; - for the smoke set (
UI_SMOKE:ui-smoke,ui-workflow,ui-command,ui-file) also everything the application is built from (UI_COMMON:app/,geometry/,core/).
So a change in app/sketch reruns the sketch tests and the smoke set, one
in app/MainWindow.cpp, geometry/ or core/model only the smoke set
(the full check runs the rest), and one only in core/vcs the tests that
declare it and the smoke set; a change anywhere that alters the window's
layout reruns them all. A test that comes to exercise another area
must declare it, else changes there skip it until the full check. The
rule for what to declare: the areas whose behaviour the test checks (the
dialogs, panels and commands it drives, the crates behind them, the tools
that make its designs); what every test shares, the window and its
layout, is covered by the layout line, so a test does not declare
app/MainWindow.cpp only because it runs in the window. A panel or page
that is longer than its dock scrolls (command panels, the docked sketch
palette) rather than raising the window's minimum size, so adding rows to
it leaves the layout, and the other tests, as they were.
--ui all runs every UI test; a test named in --only (--only ui-sketch) always runs. Passes of the ctests, the UI tests and the corpus
are kept only from runs that built (the build step ran), so a run on an
older build does not count for newer sources.
Results: build/dev/check-timings.tsv (plus ctest tests ≥ 10 s as
ctest:<name>, every corpus test, and the ctests skipped), history in build/dev/check-timings-history.tsv (the same rows with each run's start, so a corpus test's time can be compared between runs), logs in
build/dev/check-logs/<step>.log. Exit 0 only if all steps pass.
--only ui-compute or --only build,ctest reruns single steps. A UI
test that fails keeps the application's whole log there too
(ui-<name>.app.log, MITCAD_UI_LOG_DIR), and a rerun of a failed UI
test first renames its logs to ui-<name>.failed.log and
ui-<name>.failed.app.log, so the failure's logs stay for a look. A
UI test that crashed runs once more under gdb (UI_GDB=1), its log
ui-<name>.gdb.log and the app's in ui-<name>.gdb/; the test stays
failed whatever that run gives. UI tests run --ui-jobs at once, by
default the test runner's learnt cap within MITCAD_UI_JOBS, else 4
(each takes about 0.5 G without gdb), each within its learnt room.
The ctest and corpus steps run through the test runner
(mitcad-testrun, --schedule) when it
is built (build/dev/core/mitcad-testrun; --testrun off or
MITCAD_TESTRUN=off turns it off): each test in a systemd scope of its
own, as many at once as the memory budget and the CPU gate allow (the
corpus group at most --corpus-tests at once), the longest first and the
tests that failed lately early. Its output is the step's log, followed by
the output of each test that did not pass (lines marked | ) and its
results in ctest's form (result lines, the summary, The following tests FAILED:), which the table's ctest:<name> rows, the passes kept for
--ctest auto and the release scripts read as before; its own report
(report.txt: resource use, the critical path, failures by kind),
results.tsv, status.txt and each test's log are in
build/dev/testrun/<step>/, the machine's profiles in
~/.mitcad/test-profiles.json. When the runner is not built or does not
finish (it cannot list the tests, it stops), the step runs as
ctest -j in a test slot instead (its output kept as
check-logs/<step>.testrun.log).
The UI tests, and the ctest and corpus steps without the runner, hold one
of two machine-wide slots (flock on MITCAD_TEST_LOCK, default
~/.mitcad-test.lock and .2; MITCAD_TEST_SLOTS), so at most two checks
test concurrently; the runner needs none, as it starts a test only within
the memory left. Each run has a memory limit (--memory,
MITCAD_CHECK_MEMORY, none to disable): the run goes into
a systemd slice of its own with that limit (no swap), made beneath the
slice the check was started in, so that a job slice's ceiling above it
holds too, and the runner's test scopes go into the same slice, so that
the limit covers the tests as well and the runner's budget is a share of
it (85 %). The slice goes when the run ends or is stopped. Without
busctl the run is a scope with the limit in the caller's slice, as
before.
The memory, by default (--memory auto, mitcad#872), depends on where
the check runs, and the run's first lines say which applied:
- On bare metal the budget follows the free memory: the runner runs
with
--memory-budget free, and starts a test only while the memory available (MemAvailable, or less where a slice above it, the job slice among them, is nearer its limit) exceeds a reserve for the desktop and the other jobs by what the test is predicted to take and the running tests are still predicted to grow into, read again before each start; the corpus tests' children do the same (MITCAD_CORPUS_RESERVE). So a check backs off while another job (an agent's build) takes memory and uses the room when it ends; the tests' own hard limits stay as the safety net. The reserve isMITCAD_CHECK_RESERVE, else the larger of 4G and a tenth of the memory; the run's slice is limited to the memory less the reserve. - In a virtual machine (
systemd-detect-virt --vm, WSL, or the hypervisor flag in/proc/cpuinfo), whose free memory can read low until it asks for more (dynamic memory, ballooning), it is a fixed 12G as before. - A size given with
--memoryorMITCAD_CHECK_MEMORYis used as given anywhere (the old behaviour).
The steps overlap (--overlap auto, MITCAD_CHECK_OVERLAP; mitcad#872)
when the test runner runs the tests: the lint steps run beside the ctest
step, and the corpus step beside the UI tests (before ui-compute and the
UI tests that run again alone, the run waits for it; a wait for <group>
row gives that wait). Each group runs in the background, its output
printed when it ends (check-logs/<group>.out) and its rows added to the
table. In 0.33.0's Linux release check the corpus step (8 min, 1.6 tests
at once, 18 % of the CPU) and the UI tests (10.5 min) ran one after the
other; beside each other they take the longer of the two. --overlap off
runs one step after another. Build and lint use half the cores unless
CMAKE_BUILD_PARALLEL_LEVEL / CARGO_BUILD_JOBS are set.
- The Linux
devpreset builds MitCad as Debug but links OCCT's release libraries (MITCAD_OCCT_RELEASE_IN_DEBUG, default on; not on Windows, where debug and release runtimes don't mix). Set itOFFto step into OCCT. Cargo's dev profile optimises dependencies atopt-level = 2and MitCad crates at 1 (core/Cargo.toml). - C++ and macOS Objective-C++ go through ccache when installed (
MITCAD_COMPILER_CACHE, default on). Paths are hashed relative to the checkout, so side-by-side checkouts share the cache. MSVC uses/Z7(CMP0141) because ccache can't cache shared PDBs. Rust can use sccache withMITCAD_RUST_COMPILER_CACHE(default on for macOS, off elsewhere), disabling incremental compilation only while that cache is active; see the macOS cache setup and limitations. - OCCT comes from the overlay port in
third_party/vcpkg-ports(patched: speed-ups of booleans and the checker, and the fillet's edge overflow, #121, which changes results; see its README), so vcpkg builds it from source, debug and release, on the first configure of a machine and after every change to the port: about 15 min in the WSL distro and 19 min in the Windows VM (both at once, vcpkg limited to 12 jobs withVCPKG_MAX_CONCURRENCY), with build trees of about 5 GB in the distro and 14 GB in the VM. They go to$VCPKG_ROOT/buildtreesandpackagesunless-DVCPKG_INSTALL_OPTIONS=--x-buildtrees-root=<dir>;--x-packages-root=<dir>moves them (in the VM, under the checkout'sbuildfolder, which the sync keeps), and can be deleted afterwards: every later configure, in any checkout, restores OCCT from vcpkg's binary cache (an archive of 0.3 GB on Linux, 0.55 GB on Windows). macOS builds it the same way.
- Code, comments, UI texts, docs and commit messages in English.
- C++17, warning-free with MSVC
/W4and GCC-Wall -Wextra -Wpedantic, no compiler-specific constructs, no Windows path assumptions; builds and runs on Windows, Linux and macOS. - Every source file starts with an SPDX line (
// SPDX-License-Identifier: MITor# ...), checked bytools/check-spdx.sh. - Narrow strings (
std::string,char*, paths) are UTF-8 on every platform. On Windows a new executable gets the UTF-8 code page withmitcad_utf8_code_page(<target>)(cmake/Utf8CodePage.cmake), so that itsargvand file names are UTF-8 too. - A
QSettingskey never uses the groupgeneral(in any case): an INI file (the settings on Linux) writes it as Qt's[%General]section and reads it back asGeneral/..., so the value is lost after a restart there (mitcad#1190). Give the setting a group of its own. - Match the surrounding style and comment density.
- Terms (project, design, component, occurrence, body), the names of
controls and the style of every user-facing text (capitalization,
ellipsis, American spelling, messages, severity, colors) follow the
UI conventions; the ctest
repo.ui-stringschecks what a pattern can (retired words, Title Case's short words, "×" and "°", AppKit texts throughtr(), the core's'{x}'quoting). - An error, warning, refusal or notice a person reads never names
topological names (
E{…},V{…},F3:side(…),F1:top), sketch region keys (r{…}), internal ids (k5,p15,F57,F2.b0) or coordinates (UI conventions, "What a message says", mitcad#1612). Write it in words and put the place into the error's places and the names into its detail for agents: in the modelnotice::FeatureError::new(message).at(place).with_detail(…)(ornotice::placed), in the geometryplaced_error(message, detail, places)(mitcad/geometry/user_error.hpp). The application shows a notice'smessageoruserText(…)of an error, never a modelerrorstring as it is. The model's tests assert it (user_text_leaks) and the ctestgeometry.user-text-scanrefuses thrown text ingeometry/src/*.cppthat names an edge or a face, or prints a point, outsideplaced_error. The 3D sketches' sources (core/sketch/src/spatial*.rs,core/model/src/features/spatial_*.rs, their document and api files) are scanned likewise bycore/model-tests/api/src/sketch3d_user_text_tests.rs(mitcad#1644): a message that puts an id or a source into its text is refused unlessnotice::said,said_at,said_afterorsaid_aroundpairs it with plain words. - A color the user sees is a role of the role table
(
themeColor,viewColorinapp/framework/Theme.hpp), never a literal: the ctestrepo.ui-colors(tools/ui-colors-check) fails on a hex color or aQColor(r, g, b)inapp/outside the table and its recorded exceptions (kAllowed, each with its reason). - A list or tree (
QTreeView,QTreeWidget) takes its indentation frompanel::setCompactIndentation(view, kind)inapp/framework/PanelTree.hpp(a tree, a grouped list or a flat list), never the style's default or a number of its own: the ctestrepo.tree-indentation(tools/tree-indentation-check) fails on a view made without it (UI conventions). - Every user-facing text goes through
tr()(orQCoreApplication::translate,QT_TRANSLATE_NOOP), so that the interface languages can translate it; log lines, JSON keys, ids and file names stayQStringLiteral. A text is one whole sentence with placeholders (tr("%1 of %2")), never glued from translated pieces, and a count uses Qt's plural forms (tr("%n body(s)", nullptr, n)). The catalogues (app/translations, Qt's Linguist tools from the Qt the build uses) are refreshed with the targetupdate_translations, andrepo.translationschecks them (translations.md). - A tooltip says in one short line what the control is or does: a
command's (
CommandDef::tooltip, the ribbon and the menus) at most 80 characters, an input's or any other control's at most 100. No usage instructions, no parenthesised asides, no lists of exceptions; a short shortcut hint ("Place timber members (Enter places)") is allowed and counts. The detail goes into the user guide. The ctestrepo.tooltips(tools/tooltip-check) checks the texts inapp/. - The user guide's table of contents is written by
tools/check-guide-contents.py --write, never by hand: after adding, renaming or moving a##or###heading, run it; check-all's stepguidefails until the table matches. - Dialogs, message boxes and menus go through
app/framework/Dialogs.hpp(execDialog,openDialog,sheetWarning,execMenu, ...), never Qt's ownexec(),open()or static dialog functions. (With the AppKit frontend paused,repo.native-coverageandnative-coverage.txtare not checked; they return with it, coverage.) - Metric defaults everywhere (architecture).
- A dialog that holds its form in a scroll area uses
FittingScrollAreaand sizes itself withfitWindowToContents(app/framework/FitToScreen.hpp):QScrollArea's own size hint stops at 24 text lines andQWidget::adjustSizeat two thirds of the screen, so the dialog would scroll although the screen has room. The scroll bar is for a screen too low for the form. - Vector arithmetic on
[f64; 3]comes fromcore/vec3(mitcad_vec3::{add, sub, dot, cross, norm, unit, …}), never from a private copy in a module; where a caller must keep a cut-off or a division by the length it has always had, use the named variant (unit_above,unit_div,unit_div_above). The same holds for[f64; 2]withmitcad_vec3::vec2(perp,lerpand a scalarcrossbesides; the 2D length ishypot). The order of the floating-point operations there is part of the contract. - Rust first for new code of our own: new logic we write ourselves goes
in Rust (
core/), on what theKernelalready gives (meshes, faces, edges, distances), rather than as new C++ code. Mesh analyses, classification, arithmetic and bookkeeping over shapes belong in Rust. What OCCT already provides (exact B-rep construction, booleans, fillets and blend surfaces, sweeps, exact intersections) is called through the C++ facade, not reimplemented in Rust; existing C++ is not rewritten just because it is C++. A port patch to OCCT (third_party/vcpkg-ports/opencascade) only when nothing else works. - New geometry operation: a
Kernelmethod with a defaultErr(Unsupported)incore/model-base/src/kernel.rs, grouped by family; bridges per family (core/ffi/src/kernel/<family>.rs,core/cpp/bridge/<family>.{hpp,cpp},geometry/src/<family>.cpp). The trait and the data it takes and gives live below the model's core inmitcad-model-base(mitcad#777): a type aKernelmethod uses goes there too (the model re-exports it at its usual path), and its methods that need the core stay in the model as an extension trait. The mock kernel's side goes intocore/model-testkit/src/lib.rs. - New plain data or helpers that need nothing of the model's core (ids,
names, specifications, value types): into
core/model-base, re-exported by the model; the rest intocore/model. - Sketch code (2D geometry, constraints, the solve, regions, projections,
offsets, patterns, texts, SVG, the sketch edits and the sketch
definition
SketchDef): into the cratecore/sketch(mitcad-sketch, below the model's core, mitcad#780), which the model re-exports asmitcad_model::sketch; what needs the document (the sketch feature's references, checks against the timeline and evaluation) intocore/model/src/features/sketch.rs. A type the sketch needs from the core moves down intocore/model-base. A sketch command goes into the api'ssketch.rs. - New feature: a module in
core/model/src/features/, registered infeatures/mod.rs, documented incore/model-api/src/commands.md. Itsmap_paramscomes frommap_params!(features/mapping.rs) when every value maps under its field's name; the fields are listed in the order the values are visited (Adding to the API). UI commands: app/COMMANDS.md. - New command or query: a variant of a
named_enum!enum (core/model-api/src/dispatch.rs) with its name on the wire; a family with an enum of its own is one row ofDocument::command_families. The api is a crate above the model (mitcad-model-api), so its methods onDocumentare extension traits: a file's methods go into its<File>Api(public),<File>CrateOps/<File>Ops(the crate's) or<File>Local(the file's own) trait; model items it needs arepub, and those that are not the model's API are re-exported by the model'sinternalmodule (mitcad_model::internal::<module>, mitcad#811), where the api names them; their definitions stay#[doc(hidden)]or in a private module. Every split crate does the same: what another Mitcad crate needs of it but is not its API is under itsinternalmodule, so that its root and documented modules show its API alone. - BUILD: the planning of the BUILD commands (placing, connecting, timber,
frames, junctions, the cut list) goes into
core/model-build(mitcad-model-build, above the model, below the api), so that a planning edit does not recompile the model; its methods onDocumentare extension traits (<Block>Buildpublic,<Block>CrateOpsthe crate's;mitcad_model_build::prelude). What the design file keeps of BUILD (sources, records, the libraries'buildblocks) and what the features use stays incore/model/src/build/; the BUILD tests go intocore/model-tests/build-*. - Design comparison (
diff):core/model-diff(mitcad-model-diff), above the model; model items it reads that are not the model's API come frommitcad_model::internal; its tests go intocore/model-tests/files(diff_tests.rs). - Drawings: what a design file keeps of a drawing (a new stored field and
its check) goes into the model's
core/model/src/drawing/(def.rs,annotate_def.rs,tables_def.rs,template_def.rs); its layout on the sheet and the writers into the drawing cratecore/model-drawing(mitcad-model-drawing, above the model, re-exporting the model's drawing types under the same paths); a drawing command into the api'sdrawing*.rs. - New tests: a test that drives the model through the JSON api goes into
the test crate of its area under
core/model-tests/(a small crate per area, ctestcore.model.<area>; README), so that adding it recompiles only that crate; a new area is a new crate there, a member incore/Cargo.tomland amitcad_cargo_testincore/CMakeLists.txt. Tests of the model's own code that do not need the api stay incore/model(core.model), the api's unit tests in its files (core.model_api), the base's in its files (core.model_base), the drawing layout's in its files (core.model_drawing), the sketch's in its files (core.sketch). Shared fixtures: the model'stesting(the mock kernel, the cratemitcad-model-testkit) andtest_support(the block document, feature definitions, face and edge names) under itstestingfeature, and BUILD's test library incore/model-tests/support.
- MitCad's code is MIT with an SPDX identifier in every file.
- Third-party components are used under their most permissive offered licence (an MIT/Apache crate as MIT, Qt as LGPL-3.0).
- Not allowed: GPL-2.0-only, non-commercial or otherwise restricted licences, statically linked LGPL. LGPL components (OCCT, Qt) are linked dynamically.
- Accepted exception: the AppImage runtime (type2-runtime, MIT) is a
separate program statically linked with libfuse (LGPL-2.1), shipped
unchanged except for its cleared update information;
packaging/linux/THIRD-PARTY-NOTICES.txtnames it with the sources. - Copied or adapted code keeps its licence and headers in
third_party/. OCCT is built with patches of MitCad's (under OCCT's licence, asSPDX-License-Identifierlines in them say) through the vcpkg overlay portthird_party/vcpkg-ports/opencascade, whichvcpkg.jsonnames, so every platform builds the same OCCT, still as shared libraries; the patches are published with the source, the third-party notices name them, and its README gives their origin and licences. - The annotations' technical lettering (mitcad#902, an ISO 3098 type B
style font,
third_party/fonts/iso-lettering, its README gives the name and the source), is offered under GPL-3.0, GPL-2.0 or LGPL-3.0, each with a font exception, and used under LGPL-3.0 with the font exception: shipped unchanged as a file of its own (beside the executables,share/mitcad/fontsin the AppImage,Resources/fontsin a macOS bundle) and loaded at run time, as LGPL components are linked dynamically; never embedded in a program. The packages carry its licence text and the third-party notices name it. - If GPL components are ever included, the distribution becomes GPL-3.0-or-later; keep such components behind replaceable interfaces.
- A file format reader learned from the format's published reference
source (
core/3dm, mitcad#1715) takes only the format's facts from it (typecodes, ids, the order and meaning of the fields), written anew in Rust under MIT; no code of that source or of another reader is copied, and its README says where the knowledge comes from. - Rust dependencies are checked by cargo-deny (
core/deny.toml). - The fuzz crates (
core/fuzz,core/vcs/fuzz) are development tools in workspaces of their own, outsidecore/Cargo.lockand cargo-deny:libfuzzer-sys(its Rust code MIT OR Apache-2.0, the libFuzzer sources it builds under the LLVM project's permissive licence) andarbitrary(MIT OR Apache-2.0, whichlibfuzzer-sysdepends on and re-exports). Neither is linked into or shipped with MitCad. - ccache (GPL-3.0-or-later) and sccache (MPL-2.0) are development tools invoked as separate processes. Neither is linked into or shipped with MitCad, and neither adds a Cargo or native library dependency.
- Native libraries built from source and linked statically: QtKeychain
(BSD-3-Clause,
cmake/Keychain.cmake); its licence text goes into the packages and the third-party notices name it.tools/check-dependencies.shchecks the fetched source's licence text. libsecret (LGPL-2.1), which it uses on Linux, is loaded at run time from the system, not linked or shipped. - GPU SDKs (the render worker's GPU devices, #50,
rendering.md) are build tools only: nothing of
NVIDIA's CUDA toolkit (CUDA EULA), AMD's HIP SDK or Intel's oneAPI
compilers is linked statically or shipped; the GPU drivers are loaded
at run time (Cycles' cuew and hipew, Apache-2.0), and the kernels
shipped are Cycles' code compiled by them (the AppImage's
usr/lib/mitcad/cycles/lib, the Windows installer'sbin\cycles\lib; the notices name cuew). Open Image Denoise's CUDA device (Windows,build-cycles.ps1 -Cuda) contains CUTLASS (BSD-3-Clause) and CCCL header code and calls the driver through its own runtime; it links only the driver's import library. NVIDIA's OptiX SDK headers (a proprietary licence: binary-only, NVIDIA hardware only, recipients bound to its terms) would be compiled in, so MitCad does not build or ship OptiX: no OptiX code, header or binary in the repository, the packages or the downloads, and a release configure refuses a render prefix with it (cmake/RenderOptix.cmake). A user may build an OptiX worker for their own machine with the SDK they download from NVIDIA themselves (build-cycles.sh --optix,build-cycles.ps1 -Optix) and pick it in Preferences; passing it on is between that user and NVIDIA's licence (README, FAQ; rendering.md, mitcad#1332). - HEIF images of image references (mitcad#850): libheif and its HEVC
decoder libde265 (GNU LGPL version 3 or later, as their sources say;
vcpkg's metadata names LGPL-3.0-only) from vcpkg, decode only. The
manifest's default feature
heifasks forlibheifwithdefault-features: false: its default featurehevcis the x265 encoder (GPL-2.0-or-later), and no other encoder feature is turned on, so the dependencies are libde265 and vcpkg's build helpers. Both are shared libraries of the dynamic triplets, linked bymitcad(libde265 through libheif);app/CMakeLists.txtstops on a static libheif or libde265, andtools/check-dependencies.shon a static archive of either or an x265 or x264 in the build's vcpkg tree. They stay separate files a user can replace with interface-compatible builds (the AppImage'susr/lib/libheif.so*andlibde265.so*, the installer'sheif.dllandlibde265.dll, the bundle'sContents/Frameworks, where replacing a library breaks the bundle's signature as for Qt and OCCT). Their licence texts (their COPYING files, with the LGPL and the GPL it builds on, whichcheck-dependencies.shlooks for; libde265's withwin32cond.c's licence for the Windows build) go into the packages with the other vcpkg ports' copyright files, and the third-party notices name the versions and the corresponding sources: the upstream release tags, built unmodified but for the build patches of vcpkg's ports atvcpkg.json'sbuiltin-baseline. They are in a build only with-DMITCAD_HEIF=ON:MITCAD_HEIFis off by default, releases included, and such a build neither builds nor ships them. It reads HEIF images with the operating system's decoder instead (mitcad#1304; app/COMMANDS.md, "Image references"), each under its vendor's licence and installed by the user, never shipped or linked by MitCad: macOS' ImageIO, Windows' WIC with Microsoft's HEIF Image Extensions and HEVC Video Extensions, and on Linux the distribution's libheif and its HEVC plugin, loaded at run time by its name (libheif.so.1) with no libheif header at build time, so nothing of it is in MitCad's code or packages. The HEVC test data ofapp/tests/heif_image.cppwas made with ffmpeg's libx265 (GPL) bytools/heif-test-fixture.py, a separate program run by hand; nothing of it is linked or shipped. - The bundled material dataset (mitcad#1213,
third_party/material-properties):
data, not code, from the material-properties dataset under Apache-2.0,
a permissive licence this policy allows. It is converted into the
materials exchange format (no script of its repository was run) and
compiled into
mitcad-model(material_dataset.rs); itsLICENSEand aNOTICEof the attribution and the changes (Apache-2.0, section 4) ship with the packages (licenses/material-properties, the bundle'sMaterialData-*.txt), the third-party notices and the About box name it, and the Materials window's dataset browser says where the values come from and that they are typical. The vendor's name appears only in that attribution (the source's address). - The woods and panels beside it (mitcad#1552,
core/model/data/wood_materials.json): MitCad's own data under MIT, single published figures (densities, the woods' Young's moduli), each credited to its source in itsreference; the sources and why their terms allow it are in material-files.md (OEKOBAUDAT's datasets free of charge for all users and uses, manufacturers' published product data, measured values of The Wood Database, facts without its text or arrangement). - This is not a legal review; licence combinations are checked before a release.
The headless server is implemented in core/mcp (stdio protocol and
catalog), core/ffi/src/mcp.rs (native CAD tools and workspace paths),
and tools/cli/mcp.cpp (command-line entry). Live GUI access adds
app/mcp/LiveServer.* (its listening socket from
app/mcp/LoopbackListener.*), the shared private endpoint discovery in
app/mcp/LocalEndpoint.*, app/MainWindowMcp.cpp, the application's own
tools in app/MainWindowMcpUi.cpp (#265) and the CLI's
tools/cli/mcp-connect.* stdio bridge. Which commands and queries MCP
allows follows their class in core/model-api/src/classes.rs; its unit
tests (in core.model_api) fail for a command or query without one. The CLI dispatches MCP
before configuring global component libraries, and suppresses OCCT's
stdout message printers. User setup and modeling examples:
mcp.md.
In an approved isolated build environment, after mirroring the source and building with the usual preset, run:
ctest --preset dev -R '^(cli\.mcp|core\.mcp)$' --output-on-failure
# In the isolated macOS VM with a logged-in window server:
ctest --preset dev -R '^app\.ui-macos-mcp$' --output-on-failure
# In the Windows VM, configured with MITCAD_MESA_DIR (session 0):
ctest --preset dev -R '^app\.ui-windows-mcp$' --output-on-failure
# In the Linux environment, on Xvfb:
tools/check-all.sh --only ui-mcpcore.mcp uses the Cargo build fixture that CTest includes automatically.
cli.mcp is registered when Python 3 is available and runs
tools/cli/mcp-test.py against the built native executable. Its subprocess
reads and shutdowns have timeouts, and it creates temporary workspaces
under the build directory, cleaning them after each test. It checks
native box geometry, file round trips and STEP export in addition to
protocol and path refusals. On Windows the test receives Qt's DLL
directory on PATH, like the other CLI tests (mitcad-cli render loads
Qt).
app.ui-macos-mcp runs the actual application and CLI with a private
MITCAD_MCP_DISCOVERY_DIR, settings and recovery directories under the
build tree. The in-process TestDriver verifies model volumes, native
history and viewport screenshots after live MCP edits. The Python harness
checks authentication, stale and insecure records, ambiguous instances,
notification and file-operation refusals, geometry errors with applied
mutations, undo, full-width integer IDs, malformed/oversized frames,
reconnect, EOF retention and GUI New invalidating old handles. It runs
serially with the other Mac GUI tests and needs no Accessibility permission.
The live debugging flow (#265,
tools/ui-mcp-live.py) runs in app.ui-macos-mcp
and in the Linux UI test ui-mcp (tools/ui-mcp-test.sh) against a design
whose sketch holds a projection that no longer follows: queries and
sketch.add_line with the sketch open, ui_state, ui_select,
ui_screenshot, ui_command (Clean Up Stale Projections, Finish Sketch),
document_save and ui_log. app.ui-windows-mcp
(tools/ui-windows-mcp-test.ps1) drives the same flow from PowerShell
through mitcad-cli.exe mcp --connect in the Windows VM's session 0.
The Linux UI test ui-mcp-files-camera (tools/ui-mcp-files-camera-test.sh)
drives the bridge from the shell (jq, two FIFOs) for Save As and Open into
the folders for designs and for the camera (#402, #405).
The Linux UI test ui-mcp-document-new (tools/ui-mcp-document-new-test.sh)
drives it the same way for document_new (mitcad#1266), and
ui-mcp-recovery-dialog (tools/ui-mcp-recovery-dialog-test.sh) for the
refusals while the recovery dialog of the start-up or another dialog
waits for the user, and ui_state's dialog (mitcad#1725).
The Linux UI test ui-mcp-input (tools/ui-mcp-input-test.sh) drives it
the same way for ui_click, ui_type and ui_dialog in an application
started with --mcp-folder (mitcad#1735).
Follow the focused checks with tools/check-all.sh in the Linux isolated
environment and the documented Windows and macOS builds with CTest.
Builds, tests, formatters, package installation and runtime checks belong
in those isolated environments, never on the host. Commit messages must
identify any platforms whose checks were not run.