Building Donner

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

Installing Bazel

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

1. Navigate to the Bazelisk releases page: https://github.com/bazelbuild/bazelisk/releases
2. Download the latest releases, and install it as ~/bin/bazel
3. chmod +x ~/bin/bazel
4. 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 is slow since it downloads LLVM and other external dependencies (a few GB), and builds all dependencies from source, including Skia. After dependencies are downloaded, clean build times are:

• Apple Silicon M1: 2 minutes
• GitHub Codespaces (4-core): 10 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:

1. Install prerequisites. On macOS:

   brew install lcov genhtml

2. 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

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, and particularly the skia dependency is large and slow to build. The first build is slow, but incremental builds are fast due to bazel's caching.

How do I build the editor?

The Editor is an early prototype and hasn't made it to the tree. The Editor is built on the same foundation as the experimental svg_viewer in the tree. Run it with an opt build for the best experience:

bazel run -c opt --run_under="cd $PWD &&" //experimental/viewer:svg_viewer -- donner_icon.svg