The documentation build was failing with two errors:
1. "6 unused declarations" - depend API functions weren't listed in
harfbuzz-sections.txt
2. "doesn't appear to include xml/api-index-REPLACEME.xml" - the
version placeholder needed to be replaced with an actual version
Changes:
- Add hb-depend section to docs/harfbuzz-sections.txt with all 6 API
symbols (hb_depend_t, hb_depend_from_face_or_fail,
hb_depend_get_glyph_entry, hb_depend_get_set_from_index,
hb_depend_print, hb_depend_destroy)
- Replace "REPLACEME" with "12.4.0" in src/hb-depend.h
- Add api-index-12-4-0 entry to docs/harfbuzz-docs.xml
This fixes the harfbuzz:harfbuzz-doc-check test failure.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Three related fixes for depend API and check-symbols test:
1. Add HB_INTERNAL to hb_depend_t private methods
The get_*_dependencies() methods are internal implementation
details and should not be exported. Adding HB_INTERNAL ensures
they're hidden symbols.
2. Fix function declaration formatting in hb-depend.h
Added space before opening parenthesis to match HarfBuzz style
and allow gen-def.py regex to detect all function names. Without
the space, only 2 of 5 functions were found.
3. Update check-symbols.py to allow hb_depend_* in subset library
The depend API is intentionally part of libharfbuzz-subset with
its own prefix. Updated the internal symbols check to allow
hb_depend_* symbols when checking libharfbuzz-subset.
With these changes, check-symbols passes both with and without
depend_api enabled.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The depend API follows the same pattern as experimental_api: the code
is always compiled (guarded by #ifdef HB_DEPEND_API), but symbols
should only be exported when the option is enabled.
Changes:
1. gen-def.py: Add --depend-api flag and filter list (like --experimental-api)
2. src/meson.build: Pass --depend-api flag when option is enabled
This ensures depend symbols are excluded from .def files when depend_api=false
(the CI default), fixing macOS check-symbols test failures.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The depend fuzzers (hb-depend-fuzzer and hb-depend-closure-parity)
use the depend API which is only available when the depend_api build
option is enabled. However, the fuzzing meson.build was unconditionally
building these fuzzers for all configurations, causing CI build failures
when depend_api was disabled (the default).
This change:
- Splits the fuzzers list into regular tests and depend_tests
- Only builds depend-related fuzzers when HB_DEPEND_API is defined
- Maintains existing behavior for all other fuzzers
- Keeps the test execution conditional as before (lines 142-166)
This fixes all CI build failures across Linux, macOS, Windows (MSVC/MinGW),
and sanitizer builds.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace manual pointer arithmetic with std::addressof with the
cleaner get_paint() method that LayerList provides.
Changes:
- colrv1-depend.hh: Use paint_offset_lists.get_paint(i)
- colrv1-closure.hh: Use paint_offset_lists.get_paint(i)
Both files now use the same clean pattern: get_paint() encapsulates
the offset arithmetic (this+(*this)[i]) in a single method call.
Instead of just checking that the ligature set is non-empty, now verify
it contains the expected component glyphs (1823 and 1829) that form the
ligature 1910 (uni03020300).
This matches the validation pattern used in the NotoSans-Bold test and
provides proper regression testing.
Enhance test_depend_gsub_formats to fully exercise the ligature set API
for SourceSansPro-Regular.otf, not just check that a set index is returned.
Changes:
- Create temporary set to retrieve ligature set contents
- Call hb_depend_get_set_from_index to retrieve the set
- Verify the set is non-empty (contains component glyphs)
- Log the number of components found
- Destroy temporary set
This matches the validation pattern used in the NotoSans-Bold test and
ensures the full depend API is exercised consistently across all
ligature tests.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update hb-depend-fuzzer to fully exercise the depend API by actually
retrieving and validating sets, not just accessing edge values.
Changes:
- Retrieve ligature sets when present using hb_depend_get_set_from_index
- Retrieve context sets when present using hb_depend_get_set_from_index
- Handle nested context sets (indirect references with 0x80000000 bit)
- Check all sets for sanity using hb_set_get_population
- Warn if empty sets are encountered (which shouldn't happen)
This catches bugs in set storage, retrieval, and the encoding of nested
context set references.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace manual command-line parsing with glib's GOptionContext/GOptionEntry
system to match other HarfBuzz test tools.
Changes:
- Add glib_dep to meson.build for hb-depend-closure-parity
- Use G_OPTION_ARG_INT64 for hex test seeds (requires 0x prefix)
- Implement parse_inject_rate callback for optional float args with defaults
- Update help text to require 0x prefix for hex values
- Call print_usage() on argument validation errors
- All test seed output verified to use 0x prefix
Benefits:
- Automatic --help generation by glib
- Consistent with other HarfBuzz utilities
- Simpler error handling and validation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Refactor edge deduplication to follow HarfBuzz's established pattern
(as used in hb-serialize.hh and elsewhere), using struct-based hashing
instead of manual hash computation.
Changes:
1. Add operator== and hash() to hb_depend_data_record_t
- Self-contained equality comparison of all identity fields
- FNV-1a hash implementation
- Flags intentionally excluded (metadata about discovery, not identity)
- Documents why flags are excluded from equality
2. Add edge_key_t struct for deduplication
- Combines source glyph with edge record
- Simple operators that delegate to record's operator== and hash()
- Requires default constructor for hashmap usage
3. Remove manual hash code (~110 lines deleted)
- Delete get_edge_components() (~37 lines)
- Delete compute_edge_hash() (~37 lines)
- Delete edges_equal() (~33 lines)
4. Simplify add_depend_layout() (from ~50 to ~25 lines)
- Create key, check hashmap, add if new
- No collision handling needed (hashmap handles it)
- No component vector storage
5. Replace storage
- Old: hb_hashmap_t<uint64_t, hb_vector_t<uint32_t>> edge_hashes
- New: hb_hashmap_t<edge_key_t, bool> seen_edges
- Update cleanup in hb-depend.cc
Semantic change:
- Old: Compared set CONTENTS (iterated through set elements)
- New: Compares set INDICES directly
- Safe because: context sets deduplicated (same contents = same index),
ligature sets intentionally unique (different rules = different indices)
- In practice: no real fonts have identical ligature components with
different indices for the same layout_tag
Benefits:
- Follows established HarfBuzz pattern
- Simpler semantic (index-based comparison)
- Less code (~110 lines eliminated)
- Less memory (no component vector storage)
- More maintainable (single source of truth in record struct)
- Better separation of concerns (hashing logic in struct)
All tests pass.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit addresses multiple code review comments:
1. Switch RNG to std::mt19937 for deterministic tests
- Replace std::rand/srand with std::mt19937 in parity checker
- Use std::uniform_int_distribution for all random number generation
- Ensures test determinism across platforms for non-error-injection tests
2. Convert debug fprintf to DEBUG_MSG_LEVEL
- Convert GSUB lookup processing prints to DEBUG_MSG_LEVEL(DEPEND, nullptr, 1, 0, ...)
- Visible at HB_DEBUG_DEPEND=2 or higher for detailed per-lookup debugging
3. Rename function for consistency
- hb_depend_from_face → hb_depend_from_face_or_fail
- Follows HarfBuzz convention for functions returning nullptr on failure
- Update all call sites, documentation, and code comments
4. Adopt established set deduplication pattern
- Change from hb_vector_t<hb_set_t> to hb_vector_t<hb::unique_ptr<hb_set_t>>
- Use pointer-based hashmap: hb_hashmap_t<const hb_set_t*, hb_codepoint_t>
- Leverages hb_hash's content-based deduplication via pointer dereferencing
- Follows pattern established elsewhere in HarfBuzz codebase
5. Separate ligature and context set semantics
- Rename free_set → free_ligature_set (no hashmap manipulation)
- Rename new_set → new_ligature_set (no hashmap manipulation)
- Rename find_or_create_set → find_or_create_context_set (only function using hashmap)
- Makes it explicit which sets are deduplicated (context) vs unique (ligature)
- Update all call sites in Ligature.hh, ReverseChainSingleSubstFormat1.hh, hb-ot-layout-gsubgpos.hh
6. Code cleanup
- Remove unused add_to_ligature_set function (dead code)
- Refactor new_ligature_set(cp) to delegate to new_ligature_set(set)
- Move set_to_index declaration near sets/free_set_list for better organization
All tests pass.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Two related fixes:
1. Context set under-approximation fix (hb-ot-layout-gsubgpos.hh):
When a direct requirement (from input positions) overlapped with a
disjunctive set (backtrack/lookahead), the code incorrectly added
the filtered (remaining) set as an additional requirement. Fix:
if position_context intersects with original_set at all, the
disjunctive requirement is already satisfied - don't add anything.
2. Parity checker ligature fix (hb-depend-closure-parity.cc):
When processing deferred ligatures, store {dependent, ligature_set,
flags} at deferral time instead of re-scanning edges later. This
preserves the feature filtering that was already done and correctly
propagates edge flags.
Also updates edge flag documentation to correctly explain the mechanism:
- Depend extraction records edges based on static input coverage/class
- During closure, lookups within a rule are applied sequentially
- Lookups at earlier positions may transform later positions
- Multiple lookups at same position may interact (one produces a glyph,
another immediately consumes it as an "intermediate")
- So a glyph matching coverage might not persist when closure traverses
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Two bugs were fixed in the closure parity checker:
1. Feature filtering for ligatures: When processing deferred ligatures,
the code re-scanned all edges to find satisfying ligature sets but
forgot to filter by active features. This allowed ligatures to be
added via edges from inactive features if their ligature set happened
to be satisfied.
2. Flag checking for ligatures: When adding ligatures, we weren't
checking or propagating the edge flags (FROM_CONTEXT_POSITION,
FROM_NESTED_CONTEXT), so flagged ligature edges weren't being
reported as expected over-approximation.
Also includes related changes to the depend extraction:
- Add FROM_NESTED_CONTEXT flag for nested contextual lookups
- Add context handling for ReverseChainSingleSubstFormat1
- Remove cmap from glyf/CFF closure stage (UVS edges shouldn't be
followed for glyph-based closure)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Added missing documentation for the hit_flagged_edge output parameter
in process_edges_for_tables() and compute_depend_closure() function
comments. This parameter tracks whether edges marked with
FROM_CONTEXT_POSITION flag are traversed during closure computation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Edges created from non-zero positions in multi-position contextual rules
can consume intermediate glyphs (glyphs produced then immediately consumed,
never settling in closure). This causes depend's closure to include extra
glyphs compared to subset's closure, which is expected behavior.
Added HB_DEPEND_EDGE_FLAG_FROM_CONTEXT_POSITION flag to mark these edges
at extraction time. Updated parity checker to track when such edges are
hit during closure computation and distinguish between:
- Expected over-approximation (hit flagged edge): informational only
- Unexpected over-approximation (no flagged edge): critical error
This enables detection of genuine bugs (unexpected over-approximation)
while allowing expected cases from intermediate glyphs.
Updated all API callers and documentation to include nullable flags
parameter. Renamed parity checker terminology from "fuzzer" to "parity"
for clarity.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Documentation updates:
- Add comprehensive context_set documentation to depend-api.md with
encoding details and example code for check_context_satisfied()
- Update depend-for-closure.md: remove obsolete over-approximation
analysis, reflect that recent testing shows no over-approximation
with proper context_set filtering
- Update depend-implementation.md: correct descriptions of active
glyph filtering, sequential accumulation, ligature sets, and
context recording to match current implementation
- Fix terminology: change 'binning' to 'segmentation' throughout
- Fix hb-depend-data.hh:557: use HB_CODEPOINT_INVALID instead of 0
for layout_tag default value
Fuzzer enhancements (hb-depend-closure-parity):
- Add explicit test mode with command-line options similar to
hb-subset conventions:
--unicodes=LIST Unicode codepoints (U+XXXX, decimal, ranges)
--gids=LIST Glyph IDs (decimal, ranges)
--no-layout-closure Skip GSUB closure
--layout-features=LIST GSUB features (comma-separated or *)
- Support multiple input formats:
--unicodes=U+0041,U+0042,U+0043
--unicodes=65-90
--gids=10-50 --no-layout-closure
--layout-features=liga,calt or --layout-features='*'
- Add robust input parsing with validation to prevent infinite loops
on invalid input (e.g., --gids=abc or --unicodes=U+GGGG)
- Add error checking for conflicting options
This allows reproducing random test cases manually and testing
specific scenarios without finding the right seed.
Tested: All modes produce identical results to seed-based tests.
Renames:
- hb-depend-fuzzer.cc → hb-depend-closure-parity.cc
- hb-depend-fuzzer-main.cc → hb-depend-closure-parity-main.cc
- hb-depend-security-fuzzer.cc → hb-depend-fuzzer.cc
The closure parity test validates correctness by comparing the depend
API implementation against the battle-tested subset closure calculation,
ensuring the two implementations stay synchronized. It runs on valid
fonts from test/api/fonts/.
The depend fuzzer is a security fuzzer that tests robustness against
malformed input, following the standard HarfBuzz fuzzer pattern. It runs
on malformed fonts from test/fuzzing/fonts/.
Updated test/fuzzing/README.md to document both tools and their distinct
purposes. Updated meson.build to reflect the new naming in test
registration.
This commit implements the experimental depend API for extracting glyph
dependency graphs from OpenType fonts. The depend API provides the foundation
for computing glyph closures and analyzing font structure.
The implementation significantly improves upon the initial draft (commit
3f59433d5) by adding contextual filtering to reduce over-approximation while
still capturing complete dependency graphs.
Core Architecture
-----------------
The depend implementation operates in graph extraction mode: it walks all font
tables once to build a complete dependency graph. The key innovation is
contextual filtering that reduces over-approximation compared to the naive
approach.
Contextual Filtering for Reduced Over-Approximation
----------------------------------------------------
The initial implementation (3f59433d5) recorded dependencies for ALL glyphs in
every lookup's coverage, leading to significant over-approximation. The current
implementation filters dependencies based on context:
**Individual Lookups**: Each lookup's depend() method filters by active glyphs:
// Old approach (3f59433d5)
+ hb_iter (this+coverage) // ALL coverage glyphs
| hb_apply (record_dependency)
// New approach
hb_set_t intersection;
(this+coverage).intersect_set (c->parent_active_glyphs(), intersection);
+ hb_iter (intersection) // ONLY contextually relevant glyphs
| hb_apply (record_dependency)
**Contextual Lookups**: ContextFormat1/2/3 and ChainContextFormat1/2/3 set up
active glyph contexts for nested lookups:
hb_set_t* cur_active_glyphs = c->push_cur_active_glyphs();
get_coverage().intersect_set(*c->glyphs, *cur_active_glyphs);
// Process rules with filtered coverage
+ hb_zip (this+coverage, ruleSet)
| hb_filter ([&] (hb_codepoint_t g) {
return c->parent_active_glyphs().has(g);
}, hb_first)
| hb_apply (process_rule)
This significantly reduces over-approximation for simple cases while maintaining
complete graph coverage.
**Intentional Over-Approximation at Nested Boundaries**: When contextual rules
invoke nested lookups, we pass ALL glyphs to ensure no edges are missed:
// In context_depend_recurse_lookups()
cur_active_glyphs->set (*c->glyphs); // Universe for nested lookups
This design choice prioritizes completeness over precision at contextual
boundaries, which is appropriate for graph extraction.
Edge Deduplication and Performance
-----------------------------------
Dependency extraction can generate millions of potential edges. To maintain
acceptable performance:
- Edge hashing (compute_edge_hash): O(1) duplicate detection via hash table
keyed on (source, table_tag, layout_tag, dependent, ligature_set_contents)
- Hash collision handling: Falls back to O(n) linear search through glyph's
existing dependencies only on collision (rare)
- Component vectors: Stores edge components for collision detection
- Post-extraction cleanup: Frees temporary structures (edge_hashes,
lookup_features) to reduce memory footprint
Table-Specific Extraction
--------------------------
- **cmap**: Unicode → glyph mappings including UVS (Unicode Variation Sequences)
- **GSUB**: All substitution rules with feature tags and ligature set tracking
- Handles all 8 GSUB lookup types including Extension (type 7)
- Records which features reference each dependency
- Groups ligature alternatives via ligature_set indices
- **glyf**: TrueType composite glyph components
- **CFF**: CFF1 SEAC (Standard Encoding Accented Character) composites
- **COLR**: Color layer dependencies for both COLRv0 and COLRv1
- Filters self-referential PaintGlyph to prevent trivial cycles
- **MATH**: Mathematical variant glyphs and assembly components
CFF SEAC dependencies use table_tag='CFF ' with layout_tag=0 and
ligature_set=HB_CODEPOINT_INVALID, matching the pattern used for glyf.
Data Structure: hb_depend_data_record_t
----------------------------------------
Each dependency edge contains:
- table_tag: Source table (GSUB, glyf, CFF, COLR, MATH, cmap)
- dependent: Target glyph ID
- layout_tag: Feature tag (for GSUB) or UVS codepoint (for cmap), else 0
- ligature_set: Index into sets array for ligature alternatives, else INVALID
- context_set: Reserved for future contextual filtering (currently unused)
Graph stored as vector indexed by glyph ID, each containing vector of records.
Testing and Documentation
--------------------------
- test/api/test-ot-depend.c: Comprehensive test suite (645 lines)
- Tests all table types and GSUB substitution formats
- Includes regression tests for edge cases
- Uses ContextFormat2-Depend-Test.ttf (minimized from 486KB to 85KB)
- test/fuzzing/hb-depend-fuzzer.cc: Production-quality closure implementation
- Demonstrates correct ligature set handling
- Includes feature filtering and over-approximation analysis
- Reference implementation for depend-based closure computation
- docs/depend-api.md: Public API documentation with usage examples
- docs/depend-for-closure.md: Guide to using depend for closure computation
- docs/depend-implementation.md: Implementation details and architecture
Build System
-------------
- Meson option: -Ddepend_api=true
- Compile flag: -DHB_DEPEND_API
- Symbols in libharfbuzz-subset.dylib (applications must link both
libharfbuzz and libharfbuzz-subset)
Status: Experimental API, subject to change.
This commit adds complete documentation for the dependency analysis API
at all levels: public API, internal structures, and implementation.
Public API documentation (src/hb-depend.cc, src/hb-depend.h):
- Replaced "XXX Todo" placeholder in SECTION comment with detailed
module description explaining dependency graphs and use cases
- Fixed misleading hb_depend_t description (was only mentioning UVS)
- Added full documentation for hb_depend_print() with debugging notes
- Added usage examples to all three public functions
- Updated all version tags from "?.0.0" to "REPLACEME"
- Added experimental API warnings throughout
Internal documentation (src/hb-depend-data.hh, src/hb-depend.hh):
- Documented 5 internal structures with purpose and ownership semantics
- Added comments explaining data relationships and lifecycle
Algorithm documentation (src/hb-depend.cc):
- Added detailed algorithm comments to 5 extraction methods explaining
how dependencies are collected from each OpenType table (cmap, GSUB,
glyf, COLR, MATH)
User guide (docs/depend-api.md):
- Created comprehensive 250-line API guide with:
* Introduction with mechanism overview
* Basic usage example (iterating dependencies)
* Advanced examples (computing reachable glyphs, ligature sets)
* API details and compilation instructions
* Implementation notes including ownership semantics
* Use cases (subsetting, coverage analysis, binning, testing)
- Prominent experimental API warnings
Build configuration (meson_options.txt):
- Updated option description to emphasize experimental status
All documentation follows HarfBuzz conventions and includes gtk-doc
formatting for API reference generation.
After rebasing onto main, the depend code needs to use format.v
instead of format directly, due to main's "Wrap formats in struct"
change (346b8dcf9).
Updated:
- hb-ot-cmap-table.hh: _.u.format == 14 → _.u.format.v == 14
- COLR.hh: switch (u.format) → switch (u.format.v)
* [gvar] Speed up by using a fused delta application codepath
6% speedup in hanzi VARC font rendering.
* [gvar] Improve fused delta application
Another 1%.