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.
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.
The porting algorithm is quite simple and applies to most projects.
- Take the latest not ported
harfbuzzcommit. You can find the last ported inrustybuzzcommit messages. - Analyze it to make sure it applies to
rustybuzzor not. - Port it to
rustybuzz. - Port
harfbuzztests (if needed). - Run
rustybuzztests (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.
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.
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 -CbuilddirNow you can run:
# Pass harfbuzz clone dir, not `harfbuzz/src` one.
cd rustybuzz/scripts
./gen-shaping-tests.py /path/to/harfbuzzIt 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.
Make sure each rustybuzz commit contains a link to the related harfbuzz commit.
Example.
Commit message itself can be copy-pasted from harfbuzz.