HarfRust Text Shaping Engine

HarfRust is designed for multi-threaded environments, but requires following specific ownership rules:

Thread-Safe Operations

• Shared Objects: Blobs, faces, and fonts can be used for shaping across multiple threads simultaneously. Reference counts are atomic, and internal caches (per-face plan cache, user data, lazily loaded tables) are protected by locks or atomics.
• Thread-Safe Callbacks: Unlike HarfBuzz, table callbacks (used in hr_face_create_for_tables) and font callbacks must be thread-safe, as they may be invoked from any thread that first touches a specific table.

Thread-Unsafe Operations (Ownership Rules)

• Buffers: A buffer belongs to exactly one thread. Shaping writes to the buffer, so it must not be shared.
• Modifying Fonts/Callbacks: You must not modify a font (e.g., via hr_font_set_scale, hr_font_set_variations, or hr_font_set_funcs) or a callback set while other threads are shaping with them.
• Best Practice: Populate and configure fonts and callbacks before sharing them across threads. Use hr_font_make_immutable or hr_font_funcs_make_immutable to prevent accidental races.

By default, HarfBuzz pulls HarfRust from the GitHub main branch. You can modify src/rust/Cargo.toml to use a specific branch or a local path.

Using a local HarfRust path

In src/rust/Cargo.toml:

[dependencies]
harfrust = { path = "../path/to/harfrust", optional = true }

Using a local Fontations path

If using a local HarfRust, you must also update the HarfRust Cargo.toml to point to your local fontations path under the read-fonts dependency:

read-fonts = { path = "../fontations/read-fonts", default-features = false, features = ["libm"] }

Forcing a rebuild

HarfBuzz will not automatically rebuild HarfRust or Fontations if you change their source code. To force a rebuild of the shaper, touch the HarfBuzz rust shaper file:

$ touch src/rust/shaper.rs && ninja -C build

# Example modification in src/rust/Cargo.toml
[dependencies]
harfrust = { path = "../../../harfrust", optional = true }

You can use include/hr-hb.h to map HarfBuzz names directly to HarfRust counterparts. By including <hr-hb.h> instead of <hb.h>, existing HarfBuzz shaping code can often be ported by simply renaming hb_ to hr_ (via the header's macros).

Important Constraints:

• No Co-existence: You cannot include both HarfBuzz and the compatibility header in the same translation unit, as the macros would conflict.
• Shaping Only: This compatibility layer only covers the shaping API. Other HarfBuzz features (like drawing, subsetting, or layout introspection) will cause compilation errors.

#include <hr-hb.h>

hb_blob_t   *blob   = hb_blob_create_from_file("font.ttf");
hb_face_t   *face   = hb_face_create(blob, 0);
hb_font_t   *font   = hb_font_create(face);
hb_buffer_t *buffer = hb_buffer_create();

hb_buffer_add_utf8(buffer, "Hello", -1, 0, -1);
hb_buffer_guess_segment_properties(buffer);
hb_shape(font, buffer, NULL, 0);

To generate Rust code from Ragel scripts, you must use the latest development branch of Ragel, as the stable version does not support native Rust generation. Building Ragel requires first building colm as a dependency. On macOS, ensure you have automake, autoconf, and libtool installed via Homebrew.

Follow these steps to build the dependencies:

1. Build colm: Clone the repository, run the autogen script, configure with a custom prefix, and install.
2. Build ragel: Clone the repository, run the autogen script, and configure using the --with-colm flag pointing to your colm installation path.

# Install macOS dependencies
brew install automake autoconf libtool

# 1. Build colm
git clone https://github.com/adrian-thurston/colm
cd colm
./autogen.sh
./configure --prefix=/path/to/colm/install
make
make install

cd ..

# 2. Build ragel
git clone https://github.com/adrian-thurston/ragel
./autogen.sh
./configure --prefix=/path/to/ragel/install --with-colm=/path/to/colm/install
make
make install

The build/perf/benchmark-shape tool runs shaping benchmarks against compiled backends.

Useful CLI Flags

• --benchmark_filter=REGEX: Selects specific benchmarks. Use --benchmark_filter=harfrust to run only HarfRust benchmarks, or --benchmark_filter='/(ot|harfrust)' to compare HarfRust against the standard HarfBuzz shaper (ot).
• --benchmark_out=FILE: Writes results to a JSON file for comparison.
• --benchmark_repetitions=NUM: Runs benchmarks multiple times for more stable results.

Running against custom fonts

To benchmark a specific font and text file, pass them as arguments to the tool: build/perf/benchmark-shape <FONT_FILE> <TEXT_FILE> [FLAGS]

# Run only HarfRust benchmarks
$ build/perf/benchmark-shape --benchmark_filter=harfrust

# Compare HarfRust and the standard 'ot' shaper
$ build/perf/benchmark-shape --benchmark_filter='/(ot|harfrust)'

# Benchmark a specific font and text file
$ build/perf/benchmark-shape Gulzar-Regular.ttf perf/texts/fa-words.txt --benchmark_filter='(ot|harfrust)'