Donner is intended as a hobby project with the latest C++ spec, so it is likely that toolchains that support it won't be pre-installed.

Requirements

Bazel
On macOS: A working Xcode installation
CMake builds on Linux: pkg-config and development libraries for Fontconfig and Freetype. For Debian/Ubuntu:

sudo apt-get install pkg-config libfontconfig1-dev libfreetype6-dev

Installing Bazel

The recommended way to use Bazel is to install Bazelisk, which will automatically download Bazel as required. To install:

Navigate to the Bazelisk releases page: https://github.com/bazelbuild/bazelisk/releases
Download the latest releases, and install it as ~/bin/bazel
chmod +x ~/bin/bazel
Update your ~/.bashrc (or equivalent) to add this directory to your path:
export PATH=$PATH:$HOME/bin

That's it!

Verify that you can build with

bazel build //donner/...

All other dependencies will be downloaded on-demand.

The first build downloads LLVM and other external dependencies, and builds all dependencies from source. With the default tiny-skia backend, clean build times are reasonable. After dependencies are downloaded, clean build times are:

Apple Silicon M1: ~2 minutes

Running Tests

To run the tests, run:

bazel test //donner/...

To include experimental code as well, run:

bazel test //...

Build Reports

See the latest Build report.

To generate a build report locally:

Install prerequisites. On macOS:
brew install lcov genhtml
Run the command:
python3 tools/generate_build_report.py --all

To regenerate the checked-in build report at docs/build_report.md:

python3 tools/generate_build_report.py --all --save docs/build_report.md

When saving to docs/build_report.md the script automatically switches to --link-mode=docs. In that mode:

The binary-size HTML report and bargraph are copied verbatim into docs/reports/binary-size/ and the build report links to them with relative paths, so they render from GitHub's web view of the repo and from the Doxygen site alike.
The lcov HTML tree from coverage-report/ is repacked into a single docs/reports/coverage.zip (a few MB compressed instead of ~26 MB spread over hundreds of files, which keeps the working tree light and fuzzy file-name search clean). The build report's coverage link points at the absolute docs-site URL, since the zip can't render directly from a GitHub web view.

To build the Doxygen site with the bundled reports:

tools/build_docs.sh

tools/build_docs.sh runs doxygen Doxyfile, copies docs/reports/binary-size/ into the generated HTML output, and extracts docs/reports/coverage.zip into reports/coverage/ so the deployed docs site has both reports live.

To collect coverage without generating the local HTML report:

tools/coverage.sh --quiet --no-html

CMake build

Bazel is the primary build system, but CMake support is also available through a Bazel-to-CMake converter. This is for users who want to integrate Donner into their CMake-based projects.

python3 tools/cmake/gen_cmakelists.py
cmake -S . -B build
cmake --build build -j$(nproc)

To run tests, they must be enabled during the CMake configuration step:

cmake -S . -B build -DDONNER_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build

This fetches dependencies via FetchContent and builds the libraries. Unit tests are not built by default and can be enabled with the DONNER_BUILD_TESTS option.

CMake configuration options

Option	Default	Description
DONNER_RENDERER_BACKEND	"tiny_skia"	Renderer backend selection; the supported default is "tiny_skia"
DONNER_TEXT	ON	Enable text rendering (<text>, <tspan>)
DONNER_TEXT_WOFF2	ON	Enable WOFF2 web font loading
DONNER_FILTERS	ON	Enable SVG filter effects
DONNER_BUILD_TESTS	OFF	Build unit tests (adds googletest dependency)

Bazel configuration options

Config / Flag	Description
--config=geode	Use the experimental Geode GPU backend (WebGPU/Dawn + Slug); also enables --//donner/svg/renderer/geode:enable_geode=true
--config=text-full	Enable HarfBuzz text shaping + WOFF2 (advanced text layout)
--config=asan-fuzzer	Build fuzzers with AddressSanitizer
--config=latest_llvm	Use the latest LLVM toolchain (required for coverage)

Frequently Asked Questions (FAQ)

On macOS: bazel crashed due to an internal error

That indicates that xcode is not installed, the bad error message is a known bazel issue: https://github.com/bazelbuild/bazel/issues/23111

Validate that xcode is installed with:

xcodebuild -version

If it is not installed, install it from the App Store. Once this is complete clean bazel state and retry:

bazel clean --expunge

What's with the build times?

Donner builds everything from source. The tiny-skia backend stays relatively fast because it has no large external rendering dependency. Incremental builds are fast due to Bazel's caching.

How do I build the editor?

The full native editor lives at //donner/editor:editor:

bazel run //donner/editor -- donner_splash.svg

bazel run //donner/editor -- --experimental path/to/file.svg

--experimental enables editor-only experimental behavior such as the in-progress composited drag path. Without the flag, the editor uses the default non-experimental interaction path.

The browser build lives at //donner/editor/wasm and is toolchain-gated behind --config=editor-wasm:

bazel build --config=editor-wasm //donner/editor/wasm:wasm_web_package
bazel run --config=editor-wasm //donner/editor/wasm:serve_http
bazel run --config=editor-wasm //donner/editor/wasm:serve_http -- --https

Use -- --https for LAN access with the generated local certificate. Then open the served index.html in a browser. See docs/design_docs/0020-editor.md for the editor design and milestone plan.