ReviewOS

zig-utils/zig-js

docs(dev): clarify per-module sanitizer and optimization flag ordering

#1094
Closed chris opened this 9 days ago ·
9 days ago

The per-module unit-test recipe needs to document Zig option ordering. During #1092 validation, appending -OReleaseSafe or -fsanitize-thread after the final -Mgc declaration left the engine root in Debug without instrumentation. The resulting test passes did not qualify the intended engine mode.

Executed evidence: the unqualified engine artifact had no __tsan_init symbol. Repeating -fsanitize-thread before each module declaration produced a different engine artifact with __tsan_init and __tsan_read8 symbols; the 21-case group then passed without suppressions. Likewise, placing -OReleaseSafe before each declaration passed the same group in ReleaseSafe.

Definition of done:

  • Clarify in CLAUDE.md that optimization and sanitizer options apply to the next module declaration, with a concrete correctly ordered engine-root example.
  • Explain repeating flags for dependency modules and checking instrumentation before claiming a sanitizer pass.
  • Land the operating-manual correction in a small conventional commit.
9 days ago

Landed in 2fc1383c.

CLAUDE.md now gives a correctly ordered per-module TSan command, explains repeating optimization/sanitizer flags before dependency declarations, and requires checking linked instrumentation and suppression settings before recording a sanitizer pass. The corrected commands passed the 21-case engine group in ReleaseSafe and unsuppressed TSan; nm confirmed __tsan_init and __tsan_read8 in the instrumented artifact. Documentation only, 0 test262 flips.

Sign in to comment on this issue.