mirror of
https://github.com/storytold/harfbuzz.git
synced 2026-11-20 06:21:16 +01:00
Document that HarfBuzz fuzzers run with failing-malloc enabled so out-of-memory handling remains part of the expected exercised surface during fuzzing work. Testing: not run (documentation-only change) Assisted-by: OpenAI Codex
111 lines
6.2 KiB
Markdown
111 lines
6.2 KiB
Markdown
# AGENTS.md
|
|
|
|
HarfBuzz is a low-level text shaping engine with stable public API and ABI expectations. Keep changes narrow, preserve behavior unless the task explicitly requires otherwise, and avoid style-only churn.
|
|
|
|
## Read first
|
|
|
|
Before non-trivial work, read:
|
|
|
|
- `README.md`
|
|
- `BUILD.md`
|
|
- `TESTING.md`
|
|
- `CONFIG.md`
|
|
- `RELEASING.md`
|
|
|
|
## Core rules
|
|
|
|
- Prefer minimal diffs. Do not rename, reorder, or reformat unrelated code.
|
|
- Scope changes to one subsystem or concern when possible. Prefer incremental follow-up commits over large rewrites.
|
|
- Public API and ABI are hard constraints. Do not add new API unless explicitly asked. Do not change or remove existing API/ABI unless explicitly asked.
|
|
- Follow local conventions in the touched file.
|
|
- Preserve optional-feature behavior, reduced-feature builds, and compile-time feature guards.
|
|
- Keep out-of-memory behavior in mind. New code should fail safely and follow existing allocation and error-handling patterns.
|
|
- Prefer HarfBuzz's established `likely`/`unlikely` and nil-object/null-pattern conventions where they fit the surrounding code.
|
|
- Prefer HarfBuzz helpers from `hb-algs.hh` such as `hb_memcpy`, `hb_memcmp`, and `hb_memset` over raw `memcpy`, `memcmp`, and `memset` where those helpers are available.
|
|
- Do not introduce STL containers in library code. Follow HarfBuzz container and utility patterns instead.
|
|
- Leave unrelated user changes and untracked artifacts alone.
|
|
|
|
## Repo map
|
|
|
|
- `src/`: core library code.
|
|
- `src/OT/`: OpenType shaping/layout internals.
|
|
- `src/graph/`: subsetter graph helpers.
|
|
- `src/rust/`: HarfRust and fontations integration.
|
|
- `util/`: installed tools such as `hb-shape`, `hb-view`, `hb-info`, `hb-subset`, `hb-vector`, `hb-raster`.
|
|
- `test/`: API, shape, subset, vector, threads, and fuzzing tests.
|
|
- `perf/`: benchmarks.
|
|
- `docs/`: API/manual docs.
|
|
|
|
## Build and verify
|
|
|
|
Default flow:
|
|
|
|
```sh
|
|
meson setup build --reconfigure
|
|
meson compile -C build
|
|
meson test -C build
|
|
```
|
|
|
|
If `build/` does not exist yet, omit `--reconfigure`.
|
|
|
|
General expectations:
|
|
|
|
- Rebuild touched targets and make sure there are no new warnings.
|
|
- For shaping changes, run at least `meson test -C build --suite shape`.
|
|
- For subset changes, run at least `meson test -C build --suite subset`.
|
|
- For API changes, run at least `meson test -C build --suite api`.
|
|
- For `util/` changes, rebuild the relevant tool and exercise it on a small sample.
|
|
- When fixing a bug or hardening a parser, add or update the nearest regression test, fuzz seed, fuzz target, or expected output when practical.
|
|
- Treat portability regressions as real bugs. HarfBuzz regularly fixes GCC, Clang, MSVC, 32/64-bit, and reduced-feature build issues.
|
|
|
|
## Change-specific guidance
|
|
|
|
- Shaping work: check nearby tests under `test/shape/`.
|
|
- Subsetting work: check `test/subset/`; `src/graph/` is part of the subsetter.
|
|
- Raster/vector/SVG work: prefer extracting helpers and splitting oversized files by responsibility instead of adding more branching to large translation units.
|
|
- Fuzzing/parser-hardening work: inspect `test/fuzzing/` and existing guardrail code first. Fuzzers run with failing-malloc enabled, so treat out-of-memory handling as part of the exercised surface.
|
|
- Build-system work: keep Meson options, summaries, installed tools, tests, and dependent targets in sync. If packaging or cross-build behavior is affected, inspect CMake too.
|
|
- Generated data work: update the generator or makefile flow, then regenerate outputs. Do not hand-edit generated tables unless the task explicitly calls for it.
|
|
- Rust integration work: inspect `src/rust/meson.build` and `src/rust/Cargo.toml` before changing build glue.
|
|
|
|
For API work:
|
|
|
|
- Public API lives in `src/hb-*.h`, not `.hh`.
|
|
- If new API is explicitly requested, document it in `NEWS`, add `XSince: REPLACEME` in the public header docs, and update `docs/harfbuzz-sections.txt` and `docs/harfbuzz-docs.xml` when needed.
|
|
- If functionality becomes user-visible through tools or libraries, update the relevant docs and install/build wiring in the same change when appropriate.
|
|
- Keep documentation placement consistent with local practice: public API docs may live in source files, while generated section indexes live in `docs/`.
|
|
|
|
## Avoid
|
|
|
|
- Do not make broad formatting passes.
|
|
- Do not silently change Meson defaults or feature defaults unless required.
|
|
- Do not assume generated outputs, local fonts, or untracked artifacts are disposable.
|
|
- Do not disable tests to get a green run without documenting why.
|
|
|
|
## Working mindset
|
|
|
|
- Reproduce the issue before fixing it when practical.
|
|
- Understand root cause before writing code. If there is real ambiguity, ask instead of guessing.
|
|
- Validate simplifications carefully. This repo has many targeted reverts where a local cleanup broke broader behavior.
|
|
- If code looks unusually complex, it probably handles a real edge case. Check history before simplifying it.
|
|
- Centralize duplicated parsing, caching, or helper logic once duplication starts spreading.
|
|
|
|
## Commit guidance
|
|
|
|
- Before any commit, run the entire test suite with `meson test -C build`.
|
|
- Exception: simple documentation-only or CI-only changes may be committed without running tests if they do not affect code, build logic, generated outputs, or test inputs.
|
|
- Use descriptive commit messages with consistent bracketed subsystem prefixes such as `[subset]`, `[raster]`, `[util]`, or `[meson]`.
|
|
- Wrap commit message bodies to about 70 columns.
|
|
- For multi-line commit messages, write the message from a file or editor-backed input. Do not pass escaped `\n` sequences via shell `-m` arguments.
|
|
- Explain root cause, fix, and testing in the commit body when testing was actually performed or is relevant.
|
|
- When relevant, link issues or PRs with trailers such as `Fixes:`.
|
|
- Always include an `Assisted-by:` trailer on commits you write through the agent.
|
|
|
|
## Wisdom
|
|
|
|
- HarfBuzz sits at the bottom of the stack. Small changes can have very wide effects.
|
|
- If code looks unusually complex, assume it handles a real edge case until proven otherwise.
|
|
- Simplifications and optimizations are common sources of later reverts; validate them broadly.
|
|
- Prefer reproducible regressions over fix-only changes.
|
|
- When duplication starts to spread, extract the shared helper before it calcifies.
|