You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Summary
- Harden shared `src/` for **desktop OCCT 8** vs **WASM OCCT 7.9.3**: `standard_failure_message()`, `*_ptr` aliases instead of `Handle(T)`, agent conventions for both.
- Clear native/WASM compiler warnings (nodiscard `clear_tmps`, `Standard_Real`, doc-link wchar narrowing, ImGui dock enum OR under emscripten).
Closes#196
## Test plan
- [x] Native Debug rebuild `EzyCad_lib` / `EzyCad_tests` (listed C4834 / C4996 / C4244 gone)
- [x] WASM `build-em-793` ninja link succeeds; dock enum warning addressed
- [x] CI Windows MSVC green
- [x] Spot-check fillet/chamfer/revolve error paths still surface OCCT messages
- [x] Spot-check Esc cancel still two-stage (tmp tool then parent mode)
## Notes
- Temporary agent note `agents/conventions/occt-wasm-dual-version.md` should be retired when wasm on OCCT 8 is supported.
- Prefer `agents/conventions/occt-handles.md` for new handle types (add to `utl_types.h`).
Made with [Cursor](https://cursor.com)
Copy file name to clipboardExpand all lines: agents.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,6 +21,8 @@ Pointer for AI coding assistants. Details live in [agents/README.md](agents/READ
21
21
- Script consoles: [src/doc/script.md](src/doc/script.md) (read; update when bindings or console UI change)
22
22
- Utilities: [src/doc/utility.md](src/doc/utility.md) (read; update when utl_* contracts or I/O change)
23
23
- Build/test: [agents/workflows/local-dev.md](agents/workflows/local-dev.md) or root README
24
+
- OCCT APIs / WASM (desktop 8 vs wasm 7.9.3): [agents/conventions/occt-wasm-dual-version.md](agents/conventions/occt-wasm-dual-version.md) — until wasm works on OCCT 8
25
+
- OCCT handles (`Handle` vs `*_ptr`): [agents/conventions/occt-handles.md](agents/conventions/occt-handles.md)
Prefer the pattern in [`src/utl_types.h`](../../src/utl_types.h):
4
+
5
+
```cpp
6
+
using AIS_Shape_ptr = opencascade::handle<AIS_Shape>;
7
+
```
8
+
9
+
Use those `*_ptr` aliases (or `opencascade::handle<T>` inline) in new and touched code.
10
+
11
+
## Why not `Handle(T)`?
12
+
13
+
OCCT's `Handle(T)` macro is valid and expands to `opencascade::handle<T>`, but **clang-format does not treat it as a type**. With `PointerAlignment: Left`, format runs produce awkward spacing such as:
14
+
15
+
```cpp
16
+
constHandle(Geom_TrimmedCurve) & curve; // bad (formatter)
17
+
const Geom_TrimmedCurve_ptr& curve; // good
18
+
```
19
+
20
+
Do **not** paper over this with `// clang-format off` for routine handle declarations.
21
+
22
+
## Agent rules
23
+
24
+
1. For a type used as a handle in EzyCad, add or reuse a `using TypeName_ptr = opencascade::handle<TypeName>;` in `utl_types.h` (forward-declare the class there if needed, matching existing entries).
25
+
2. Prefer `TypeName_ptr` in signatures, locals, and members.
26
+
3. `DownCast`: `TypeName_ptr::DownCast(obj)` (or `opencascade::handle<TypeName>::DownCast(obj)`), not `Handle(TypeName)::DownCast(obj)`.
27
+
4. When editing a function that already uses `Handle(...)`, convert that local scope to `*_ptr` / `opencascade::handle` if the change is small; do not mass-rewrite unrelated files.
**Temporary:** keep this file until EzyCad WASM builds and runs correctly against OCCT **8.x** (GLES shading and any remaining regressions fixed; see [docs/bugs.md](../../docs/bugs.md)). Then delete this convention and drop the pointers from `AGENTS.md` / `agents/README.md` / `token-lean.md`.
Most app code is one tree linked against **desktop 8** and **wasm 7.9.3**. Prefer the **API intersection**. Do not assume an OCCT 8-only symbol or overload is available on the wasm kit.
18
+
19
+
### `Standard_Failure` messages
20
+
21
+
Use `standard_failure_message(e)` from [`utl_occt.h`](../../src/utl_occt.h) — not raw `what()` or `GetMessageString()`:
22
+
23
+
```cpp
24
+
catch (const Standard_Failure& e)
25
+
{
26
+
const char* msg = standard_failure_message(e);
27
+
// ...
28
+
}
29
+
```
30
+
31
+
OCCT **8** (desktop) deprecates `GetMessageString()` in favor of `what()`; OCCT **7.9.3** (wasm) has no `what()` on `Standard_Failure`. The helper picks the right API via `OCC_VERSION_HEX` so shared code builds on both without warnings or missing-member errors.
32
+
33
+
### Other dual-version habits
34
+
35
+
- Prefer existing call patterns already used for both targets over newer OCCT 8 helpers.
36
+
- If you must use an 8-only API, gate it or verify a wasm 7.9.3 configure/build still succeeds.
37
+
- Default wasm work to **7.9.3**; use the v8 wasm script only when comparing upstream regressions.
38
+
39
+
## When retiring this note
40
+
41
+
After wasm on OCCT 8 is the supported path: switch demo/release scripts to `build-occt-v8-wasm.ps1`, update [docs/building-occt.md](../../docs/building-occt.md) / [docs/bugs.md](../../docs/bugs.md), then remove this file and its index links.
Shared `src/` must build against desktop OCCT **8.0.0** and recommended WASM OCCT **7.9.3** until OCCT 8 GLES shading works for wasm. Harden that split: stop using `Handle(T)`, add dual-version `Standard_Failure` messaging, document agent conventions, clear native/WASM warnings.
25
+
26
+
### Acceptance criteria
27
+
28
+
-[x]`standard_failure_message()` used at `Standard_Failure` catch sites
29
+
-[x]`Handle(...)` -> `*_ptr` aliases in `utl_types.h`
Copy file name to clipboardExpand all lines: agents/workflows/local-dev.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,6 +47,8 @@ See root [README.md](../../README.md#building-instructions) and [docs/building-o
47
47
48
48
## WebAssembly (Emscripten)
49
49
50
+
**Agent note:** desktop uses OCCT **8**, recommended wasm uses **7.9.3** until OCCT 8 wasm works. Shared `src/` must compile on both — see [conventions/occt-wasm-dual-version.md](../conventions/occt-wasm-dual-version.md).
51
+
50
52
Full OCCT + EzyCad wasm instructions live in [docs/building-occt.md](../../docs/building-occt.md#webassembly-emscripten) and the root README.
-**Helper functions** (`.cpp`): Prefer **file-local static helpers** in an anonymous namespace at the **bottom** of the implementing `.cpp` file. Forward-declare them near the top (or above their first use) when needed. Avoid large helper blocks at the top of the file; the goal is high-level code first, helpers last for readability.
70
70
-**PIMPL** (`class Foo; class Foo::Impl`): Use when hiding implementation details or when you want to swap implementations (e.g. `Sketch_nodes`, `Sketch_op_recorder`). Keep the public surface in the header; put data members, private record types, and apply/clone logic in `Impl` inside the `.cpp`.
71
71
-**Templates**: Prefer putting template implementations in `.inl` files included from the header (e.g. `utl_types.inl`, `utl.inl`).
72
-
-**OCCT handles**: Use `opencascade::handle<T>` and project aliases (e.g. `AIS_Shape_ptr`, `Shp_ptr`).
72
+
-**OCCT handles**: Prefer `opencascade::handle<T>` and project `*_ptr` aliases from `utl_types.h` (e.g. `AIS_Shape_ptr`, `Shp_ptr`). Avoid the OCCT `Handle(T)` macro in new/touched code -- clang-format mishandles it with `PointerAlignment: Left` (e.g. `Handle(Foo) &`). See [agents/conventions/occt-handles.md](../agents/conventions/occt-handles.md).
73
+
-**OCCT desktop vs WASM**: Until WASM runs correctly on OCCT 8, desktop is OCCT **8** and recommended WASM is **7.9.3**. Prefer APIs available on both; for `Standard_Failure` use `standard_failure_message(e)` from `utl_occt.h` (not raw `what()` / `GetMessageString()`). See [agents/conventions/occt-wasm-dual-version.md](../agents/conventions/occt-wasm-dual-version.md).
73
74
-**Result/error handling**: See **Fail fast** below. Use `Result<T>` and `Status` from `utl.h`, `CHK_RET(...)` for early return on failure.
74
75
-**Assertions**: See **Fail fast** below. Use `EZY_ASSERT` and `EZY_ASSERT_MSG` from `utl_dbg.h`; use `DBG_MSG` for debug logging.
0 commit comments