Backporting Process

Intro

While the porting process of rustybuzz is complete, backporting is a never-ending task. And even if we would be able to port simple commits in 5min, multiply it by a thousand and you would understand why we're so behind. This is why any help is welcome.

If you want to help, you don't have to know anything about text shaping, fonts or even C++ and Rust. Most harfbuzz commits consist of minor tweaks and fixes, which can easily be ported by anyone with even basic CS knowledge.

If you have any questions, we have a dedicated discussion for backporting.

Working Environment

Ideally, you should use Linux or macOS. While working on Windows is potentially possible, it would be pain. Mainly because of harfbuzz and not rustybuzz. harfbuzz relies on many Unix tools.

For one, you would need at least: git, Python, Rust, clang/gcc and meson. Potentially even ragel, but it has to be built from sources.

General Algorithm

The porting algorithm is quite simple and applies to most projects.

Take the latest not ported harfbuzz commit. You can find the last ported in rustybuzz commit messages.
Analyze it to make sure it applies to rustybuzz or not.
Port it to rustybuzz.
Port harfbuzz tests (if needed).
Run rustybuzz tests (cargo test).
Run auto-format cargo fmt.
Commit.
Rinse and repeat.

Overall, if tests are passing - we're good. Everything else doesn't really matter.

Analyzing Changes

The main difference between harfbuzz and rustybuzz is that rustybuzz is just a shaper, while harfbuzz is collection of things. More specifically, harfbuzz includes: shaping, subsetting, fonts parsing, Unicode tables, precompiled state-machines, custom C++ containers (instead of std one) and bindings to 3rd-party libraries.

rustybuzz doesn't have subsetting. If you see changes in a file/function with a name subset or a commit with the [subset] prefix, you can easily skip those.

Fonts parsing is done via ttf-parser and any changes to the fonts parsing in harfbuzz probably do not affect us, unless new tests are failing. In which case better ask about in the discussion.

Unicode tables and related routines are done differently in rustybuzz, usually by using 3rd-party crates instead of a custom solution. Again, better ask about such changes in the discussion.

Precompiled state-machines are generated by ragel. Follow the linked instruction if you see that any of *.rl files had changed.

We do not use any custom C++ containers harfbuzz implements and rely on Rust's std instead. So changes to those can be ignored as well.

Changes to the harfbuzz build systems (it has 3... welcome to C++) should be completely ignored as well.

Overall, if you see a change in a hb-ot-* file - this change probably affects rustybuzz.

Updating Tests

Almost all of harfbuzz shaping tests (found in test/shaping) are as simple as font + text = glyph ids + positions. The difference is that harfbuzz uses Python to run tests, while we auto-generate the default Rust tests. And to do so, we use scripts/gen-shaping-tests.py.

But to get the expected output, we first have to build harfbuzz at the commit we're porting. You cannot use the latest harfbuzz version to do so. For example the one installed on your system if you're using Linux.

The easies way to do so is to use meson:

git clone https://github.com/harfbuzz/harfbuzz
cd harfbuzz
git checkout HASH # put the required hash here
meson builddir --reconfigure # `--reconfigure` is needed only on the first run
ninja -Cbuilddir

Now you can run:

# Pass harfbuzz clone dir, not `harfbuzz/src` one.
cd rustybuzz/scripts
./gen-shaping-tests.py /path/to/harfbuzz

It will do everything for you. All you need is to run cargo test afterward to make sure all tests are passing.

If not, then either your change was incorrect or there is a bug in rustybuzz.

Commit Messages

Make sure each rustybuzz commit contains a link to the related harfbuzz commit. Example. Commit message itself can be copy-pasted from harfbuzz.

4.3 KiB Raw Blame History