Rive runtime is built from inside its own tests directory

Six runtimes depend on this one repository

The first line of the page is the architectural fact. This is the lowest-level Rive runtime: a C++ library that loads the binary animation format, advances state machines and animations, and draws through an abstract renderer interface, with built-in GPU backends for Metal, Vulkan, D3D11, D3D12 and OpenGL or WebGL.

Then one sentence does more work than the rest of the page: Rive's Apple, Android, Flutter, Unity, Unreal and web runtimes all wrap this library.

Six products, six language bindings, one C++ core. That makes this repository the constraint on all of them. A regression here is a regression in a Flutter plugin, an Unreal plugin and a web runtime simultaneously, and the platforms it has to keep working on range from a phone GPU to a browser's WebGL implementation. It also explains why the page is written the way it is: with that many downstream consumers, the prerequisites section is the most important part of the documentation, and it is correspondingly specific.

The abstract renderer interface exists for a stated reason, which is to hook up an external vector renderer. The tree contains a separately named graphics renderer directory alongside the main one, and the container build compiles a large vector graphics library, so the external-renderer case is a real deployment rather than a hypothetical.

The build runs from inside the tests directory

The documented build is three commands, and the middle one is the surprise.

git clone https://github.com/rive-app/rive-runtime.git
cd rive-runtime/tests
../build/build_rive.sh release

The helper script must be run from a directory that contains a build script for the build tool, and the page says that directory is typically the tests one, because that is where the build script builds the core library, the GPU renderer and a sample application.

So the repository root is not a build directory. The root does hold a build script of its own, under a different name, and it is not the one the helper looks for. Artefacts then land in an output directory relative to wherever you built from, which for the documented commands means inside the tests directory, and the configuration name encodes any platform and architecture flags you passed, so a host release build and an Android arm64 release build produce differently named directories side by side.

It is an odd layout, and it is defensible. Putting the build next to the test harness means the same invocation produces both the library and the three binaries the harness needs, and a consumer who only wants the library gets it in the same place. A consumer who packages the output directory wholesale gets more than they asked for, which is the subject of a later section.

Windows needs two individual components and one installer checkbox

The Windows prerequisites are the longest part of the page, and they are not a summary of a standard install. You need Visual Studio 2022 with two individual components selected rather than a workload: the C++ clang compiler for Windows, and MSBuild support for the LLVM toolset.

Then there is the second requirement, which is the one that catches people. The build script clones its build tool on first run, which needs a POSIX shell, so you need Git for Windows installed with the setup option that puts its optional Unix tools on the command prompt path, specifically so that the shell executable lands on the search path. The page names the exact option string to pick.

And there is a third, quieter one. The PowerShell wrapper exists for convenience and it shells out to the bash script, so using PowerShell on Windows does not remove the need for a bash environment. The page says so in the build section rather than in the prerequisites, which is where somebody would look.

One small thing worth noting about the repository itself: its summary field on the hosting site is a Windows toolchain instruction. The description that appears next to the project name is the Windows compiler requirement, which tells you which platform the author found hardest to document.

The required Windows compiler cannot run the task the repository ships

The Windows build uses clang-cl by default. Microsoft's own compiler is available behind a flag, and the page adds a parenthetical that deserves more attention than it gets: the build's warning suppressions cover that compiler too.

That is an unusual arrangement. On a Windows project, the expectation is that the native vendor toolchain is the tested path and the clang toolchain is the experiment. Here it is inverted, and the warning suppressions for the native compiler were added because it was made to work rather than because it is preferred.

The same asymmetry reappears at the end of the page. There is a task for inspecting generated assembly, which needs a disassembler extension for the editor, and its underlying task invokes the clang C++ compiler executable directly. That works out of the box on macOS and on most Linux distributions. It does not work on a default Windows install with Visual Studio, because that install provides the clang-cl executable and not the clang++ one.

So on the one platform where this documentation is longest, the compiler the build requires is the one the developer tooling cannot use. Both facts are stated plainly on the page; they are simply not connected to each other, and a Windows developer will find out at the moment they try the assembly view.

A pixel diff is the primary test oracle

The page says the runtime's primary form of testing is golden testing: render known scenes, diff the output against reference images checked into the repository, using two dedicated harness binaries. Unit tests are described as secondary, use a C++ test framework, and are discovered automatically by filename convention in two directories, one for the core runtime and one for the renderer.

For a vector renderer this is a defensible choice and probably the right one, because the bugs that matter in this kind of library are visual: a wrong blend mode, a mis-transformed path, a clipping rule applied in the wrong order. A unit test on the geometry would pass while the picture was wrong.

The cost is equally clear. A golden comparison is a function of the driver, the graphics backend, the instruction set and the operating system's font and antialiasing behaviour. The very backends listed in the first paragraph, five of them across three vendors, are exactly the variables a golden image cannot hold constant. A project whose primary gate is that gate has to be able to reproduce its reference images, and the page's own answer to that is a directory of rebaselining instructions rather than a claim about cross-platform stability.

The second asymmetry is smaller and just as useful. There is a memory check that wraps the test binary with a leak detector that ships with macOS, and it is explicitly ignored on the other two platforms. So of the three supported platforms, exactly one gets leak detection, and it is the one whose leak detector is already installed.

Deliverables and internal tooling share one output directory

The artefacts table is short and mixes two kinds of thing without marking the difference.

First the deliverables: a static library for the core runtime, with the platform's own extension, and a second static library for the GPU renderer. Then a sample application, which loads and renders a format file, so somebody can confirm the build works without writing any code. Then three test harness binaries, described as being for regression, golden images and benchmarking. Then a list of supporting libraries, which is where the abbreviation problem starts: the GPU renderer library carries a three-letter prefix in its filename that the page never expands, and the supporting list includes a text shaping library and a separate decoders library, both described only as supporting.

For a downstream packager this matters. The runtime's own consumers want two static libraries, and the output directory also contains a sample executable, three internal test binaries and however many supporting libraries got built. Nothing marks which two files are the product, so a packaging script has to encode that knowledge by name, and the name it has to encode contains an abbreviation the documentation does not explain.

The tree also carries two small files that say what the library is built against: the format revision the runtime targets, tracked in a dotfile, and a debugger visualisation file for Visual Studio. Tracking the format revision in the repository is the right call for a library whose input is a binary format, and it is the closest thing to a version number, since the repository publishes no releases at all.

The container for a C++ library starts from a Dart image

The container definition at the root of the repository tells a different story from the build documentation, and it is worth reading as a separate artefact.

Its base image is the stable image for the Dart language. It then installs a graphical toolkit development package, a virtual framebuffer, the Rust toolchain, ninja, and a C++ compiler, sets the compiler and C++ compiler environment variables to point at clang explicitly, and downloads a beta release of the build tool directly by URL rather than through a package.

What it then builds is not the runtime. It builds a large vector graphics library, using two scripts copied in from the tree, then a windowing library for it, then a thumbnail generator inside that library's own directory. The runtime's own source is added to the image but never compiled.

Two details explain the shape. The build expects two sibling checkouts, one for the runtime and one for the graphics library, added to separate paths, so the container cannot be built from a single clone of this repository alone. And one line that would have added a dependency-building script is commented out, so the file records a decision to skip a step without recording why.

The explanation is probably that this image serves the graphics library's own tooling rather than this project's tests. But nothing in the file says so, and a developer who finds the container definition looking for a way to build the runtime in a container will spend a while before realising they are looking at somebody else's build.

Editorial conclusion

This is a well written build page for a hard dependency, and the honesty about which platform gets which check is the most useful thing on it. Three things to check before you build it. Expect to build from inside the tests directory and to find the libraries, the sample application and three internal test binaries mixed in one output directory, so anything packaging that output needs to exclude half of it. Read the Windows prerequisites as a shopping list rather than a summary, because two individually installed components and one installer checkbox decide whether the build works at all. And decide whether golden-image testing is sufficient for your platform, since that oracle is a rendering of a scene on hardware the project does not control, and the leak check that would catch a different class of bug runs on one of the three platforms.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases