Skip to content

Add opt-in HarfBuzz tracing messages - #528

Open
behdad wants to merge 6 commits into
mainfrom
tracing/message-callbacks
Open

behdad wants to merge 6 commits into
mainfrom
tracing/message-callbacks

Conversation

@behdad

@behdad behdad commented Oct 10, 2026 •

Copy link
Copy Markdown
Member

Add opt-in HarfBuzz shaping messages through Buffer::set_message_function and hr-shape --trace. This completes Simon Cozens's implementation from #280 and rebases it onto the current public buffer and font APIs.

  • Gate callback storage, message formatting, and intermediate snapshots behind one tracing Cargo feature, disabled by default. Support no_std with libm. Include the detailed per-glyph and recursion messages that HarfBuzz enables with HB_BUFFER_MESSAGE_MORE=1.
  • Accept FnMut + Send + Sync + 'static callbacks receiving the public Buffer, ShaperFont, and message. Returning false from a skippable start message skips that operation; per-glyph and recursion notifications ignore the return value. Callbacks survive buffer reuse and can be replaced or removed.
  • Serialize intermediate Unicode and glyph buffers, including substitution output before positions exist. Present snapshots without modifying live shaping state, preserving results even when malformed fonts reach shaping limits.
  • Cover OpenType, AAT, script processing, and fallback positioning; include feature tags in lookup messages. Write CLI traces to stderr and glyph results to stdout or the requested output file. The library rendering API includes traces in its returned string.

Audited message sites, callback return handling, and text serialization against HarfBuzz source at c82300aefb. Corrected normalization boundaries, recursion notifications, kerning boundaries and zero-based subtable numbers, mort labels, lookup skip reporting, tag formatting, message truncation, and trace line formatting. This was a source audit; no HarfBuzz runtime output comparison was performed.

Validation: workspace tests pass with and without ICU (6,524 tests in each configuration), including 13 callback tests, CLI trace formatting and stream routing, and checks that tracing preserves shaping results across the existing corpus. Formatting and Clippy (--all-features --all-targets, warnings denied) pass, including Clippy on Rust 1.99. Rust 1.85 workspace and embedded no_std builds pass with tracing enabled and disabled; C++ compatibility checks pass. CI builds both tracing configurations explicitly.

Supersedes #280. Fixes #245.

simoncozens and others added 4 commits October 9, 2026 22:31
Expose FnMut callbacks using Buffer and ShaperFont, and present substitution snapshots without changing live shaping state. Complete the tracing feature, CLI output, regression coverage, documentation, and no_std CI builds.
@behdad behdad mentioned this pull request Oct 10, 2026
@behdad
behdad requested a review from dfrg October 10, 2026 04:50
@behdad

behdad commented Oct 10, 2026

Copy link
Copy Markdown
Member Author

This should be ready for review.

Comment thread README.md
`false` from a skippable `start` message to skip that operation. Per-glyph and
recursion messages are informational and ignore the return value. Mutable closures
are supported; callbacks own their captures and must be `Send + Sync + 'static`.
Use `buffer.clear_message_function()` to remove a callback.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should set_message_function instead take an option?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support HarfBuzz message callback

2 participants