OCCT Upgrade History

Documents breaking changes and migration steps for each OCCT version upgrade.

Version Timeline

p1 to 8.0.1 (Unreleased)

OCCT 8.0.1 (tag V8_0_1, 2026-07-30) is the first maintenance release in the 8.0 series. Against our previous V8_0_0_p1 pin it is a clean fast-forward: 23 commits, 74 files, nothing reverted (behind_by = 0), so there is no divergent release branch to reconcile.

No API or ABI break

Upstream states the 8.0.0p1 C++ API/ABI baseline is unchanged, and that was checked rather than taken on trust: the only public header in the whole diff is ShapeAnalysis_FreeBounds.hxx, whose change is a single comment line. No migration is required for the OCCT API itself.

Ten carried patches retired

8.0.1 ships our own upstream contributions, so Scripts/patches/ shrinks from 21 files to 11. Retired: 0001–0009 and 0013, covering OCCTSwift issues #263, #280, #298, #310, #317, #318, #323 (three patches), and #348. Each merge commit was confirmed an ancestor of the tag rather than merely merged to master, and each patch was diffed against its as-merged form before deletion.

Nine came back unchanged. 0001 did not: upstream’s merged form also guards a removed face (anApplied.IsNull() ||), which ours did not, so that retirement is a strict upgrade. Full per-patch verdicts are in Scripts/patches/README.md under “Retired patches”.

Patch numbers are not reused: the carried sequence now reads 0010-0012, 0014-0021, and the gaps are the retirements.

Behaviour changes to watch

None of these break compilation; they change results. They are being measured against the wrapper surface rather than assumed inert, because two of them sit in code the OCCTSwift suite cannot see: there are no tests using INTERNAL/EXTERNAL edge orientation, and #645 records that the Gordon-family tests assert only status ordinals and never build a surface.

One release-note claim does not survive checking: #1375 is described as giving GeomLib_Tool::Parameter() closed-form evaluation, but GeomLib_Tool.cxx is not in the 74-file diff at all. The ALLOWED exemption for it in Scripts/repro/556-null-handle-guard-sweep therefore still holds.

Fixes we get for free

Beyond our own retired patches, 8.0.1 also brings ChFi3d_Builder::StartSol hardening (#1407), an ~8× speedup for BRepCheck_Face on faces with many holes (#1375), a 17–20% boolean improvement from the GeomLib_CheckCurveOnSurface fast path (#1373), and the periodic-seam meshing fix (#1338).

Beta2 to GA (v0.170.x → v1.0.0)

Breaking Changes

New APIs in GA

The headline GA additions (BRepGraph, Gordon Surfaces, TKHelix, ExtremaPC) all landed in earlier RCs/betas and are already wrapped. GA itself was a stabilization release — see OCCT discussion #1275.

Stability

• STEP read/write: now safe under the contract of one reader or writer per thread (per the GA announcement).
• SEGV fixes: chamfer, fillet, and pipe-shell operations received multiple stability patches in the rc5→GA window.

OCCTSwift API consolidation in v1.0.0

RC4 to RC5

Breaking Changes

New APIs in RC5

• GeomEval analytical curves: CircularHelixCurve, SineWaveCurve
• GeomEval analytical surfaces: Ellipsoid, Hyperboloid, Paraboloid, Helicoid, HypParaboloid
• Geom2dEval spirals: Archimedean, Logarithmic, CircleInvolute, SineWave
• GeomFill_Gordon: Transfinite interpolation surface from crossing curve networks
• PointSetLib: Point cloud centroid, inertia tensor, PCA analysis
• Approx_BSplineApproxInterp: Constrained least-squares B-spline fitting
• GeomEval TBezier/AHTBezier: Trigonometric and algebraic-hyperbolic-trigonometric basis curves/surfaces
• GeomAdaptor_TransformedCurve: Rigid transformation adaptor for curves

Thread Safety Improvements

• Reduced mutable global state in geometry evaluators
• final keyword on evaluation methods enables devirtualization
• Grid evaluation batch methods avoid per-call virtual dispatch

Not Wrappable

• GeomBndLib: .pxx implementation headers not distributed in xcframework. Deferred until OCCT ships them.

RC3 to RC4

Breaking Changes

Deprecated Typedefs

OCCT 8.0 deprecates many collection typedefs. Key replacements:

Full list of deprecated typedefs is available in the OCCT 8.0 migration scripts at Libraries/occt-src/adm/scripts/migration_800/.

Performance Improvements (automatic)

• Devirtualized geometry evaluation on hot paths
• Direct array members in BSpline/Bezier (no heap indirection)
• Thread-local error handling
• Contiguous TShape child storage
• Robin Hood hash maps for internal collections

Rebuilding After Upgrade

cd Libraries
rm -rf occt-src occt-build-* occt-install-*
cd ../Scripts && ./build-occt.sh

Removing occt-src is the load-bearing step, not housekeeping. build-occt.sh reuses an existing tree only when its HEAD is at the tag the script names, and aborts otherwise rather than building the wrong kernel under the new version’s name, which is what it silently did until the 8.0.1 re-pin, when it tested only whether the directory existed. If the abort fires, check git -C Libraries/occt-src status --porcelain for work worth keeping (a diagnostic probe from an investigation, a half-written patch) before deleting.

Build time: ~30-60 minutes. See guides/building-occt.md for details.