skia-gn-workflow

This skill provides expert guidance for building and testing Skia using the GN build system and Ninja. It covers common workflows for correctness testing (dm), performance benchmarking (nanobench), and interactive visualization (viewer).

Core Principles

• Hermeticity: Always use ./bin/gn for configuration and ./bin/fetch-ninja to ensure the correct version of Ninja is available.
• Verification: Always build and run tests/benchmarks before documenting or finalizing changes.
• Filtering: Use the --match flag (aliased as -m) to target specific tests and reduce execution time.
• Build Directories: NEVER override a user's existing build directory settings (e.g. out/Debug). If you need a different configuration, create a new directory (e.g. out/Debug2, out/ASAN). Only modify settings in an existing directory if explicitly asked by the user.
• Toolchain Paths: When a build requires specific toolchain paths (e.g. cc, cxx, or clang_win for Clang/LLVM), ALWAYS ask the user where these are extracted on their machine. Different developers have these in different locations.

Setup & Troubleshooting

1. Syncing Dependencies

If you encounter compilation errors in third_party or missing headers, run:

python3 tools/git-sync-deps

2. Fetching Ninja

If the ninja command is not found or you want to ensure a hermetic version:

./bin/fetch-ninja

3. Formatting Code

Near the end of your workflow, before uploading a CL or finalizing changes, format your code using:

git clang-format origin/main

4. Cleaning Builds

If the build system gets into a broken state, clean the directory:

./bin/gn -q clean out/Dir

5. Inspecting the Build

To understand how a target is being built or to find available targets:

• List all targets: ./bin/gn ls out/Dir or ninja -C out/Dir -t targets
• Inspect a target: ./bin/gn desc out/Dir //:dm (shows flags, defines, sources, etc.)
• Check why a file is included: ./bin/gn path out/Dir //:dm //src/core/SkPath.cpp

6. Rust Dependencies (Bazel)

If a build requires Rust dependencies (in third_party), use bazelisk to manage the toolchain:

• Download: https://github.com/bazelbuild/bazelisk/releases

Build Workflows

1. Common Build Arguments

• is_debug=false: Create an optimized Release build.
• is_official_build=true: Optimized build, links against system libraries. Suitable for shipping.
• is_component_build=true: Build Skia as a shared library.
• sanitize="ASAN"|"MSAN"|"TSAN"|"UBSAN": Enable memory, address, thread, or undefined behavior sanitizers.
• extra_cflags=["..."], extra_ldflags=["..."]: Add custom compiler/linker flags.
• cc="clang" cxx="clang++": Specify the compiler (highly recommended for performance).

2. Sanitizer Builds (xsan)

• ASAN: ./bin/gn gen -q out/ASAN --args='sanitize="ASAN" cc="<path_to_clang>" cxx="<path_to_clang++>"'
• MSAN: ./bin/gn gen -q out/MSAN --args='sanitize="MSAN" cc="<path_to_clang>" cxx="<path_to_clang++>" skia_use_fontconfig=false'
  • Note: Run dm with --nogpu under MSAN to avoid driver noise.
• TSAN: ./bin/gn gen -q out/TSAN --args='sanitize="TSAN" is_debug=false cc="<path_to_clang>" cxx="<path_to_clang++>"'

3. Platform Specifics

• Android: ./bin/gn gen -q out/android --args='ndk="~/ndk" target_cpu="arm64"'
• iOS: ./bin/gn gen -q out/ios --args='target_os="ios" target_cpu="arm64"'
• Windows: Use clang_win="<path_to_llvm>" to build with clang-cl (highly recommended).

4. Other Build Notes

• Unless otherwise instructed, build with: ninja --quiet -C {OUT_DIR} {TARGET}. If given an ninja command that is missing --quiet, you must add --quiet.

Tool Reference

dm (Correctness Testing)

dm runs GMs (graphics tests), unit tests, and compares images.

• Common Flags:
  • --src <types>: e.g., --src tests gm skp image.
  • --config <configs>: e.g., --config 8888 gl.
  • --match / -m: Case-sensitive substring filter. Supports ~ (exclude), ^ (start), $ (end).
  • --skip <config> <src> <srcOptions> <name>: Skip specific test cases. Use _ for wildcards.
  • --writePath / -w: Write result bitmaps as PNGs.
  • --readPath / -r: Read reference bitmaps for comparison.
  • --threads / -j: Number of threads (default: one per core).
  • --verbose / -v: Detailed output.
• Extended Help: For detailed documentation on specific flags, use --help <flag_name>.
  • Example: out/Debug/dm --help config.

nanobench (Performance Benchmarking)

Always use a Release build for benchmarking.

• Common Flags:
  • --samples <N>: Number of samples per benchmark (default 10).
  • --ms <time>: Run each benchmark for at least <time> milliseconds.
  • --cpuprofile <file>: Write pprof CPU profile (requires skia_use_pprof=true).
  • --match / -m: Filter benchmarks.
• Baseline Preservation: It is recommended to copy a stable baseline binary to nanobench_control (outside the out/ directory) to compare against a new build.

viewer (Interactive Visualization)

• Common Flags:
  • --backend / -b: sw, gl, vulkan, metal, d3d.
  • --slide <name>: Jump to a specific GM or SKP.
  • --match / -m: Filter slides.
• Hotkeys: i (HUD), z (zoom), [/] (navigation).

Advanced: "Via" Configs

dm supports "via" configs in the format [via-]*backend. These wrap a rendering sink to test additional logic.

• Examples:
  • serialize-8888: Serialize and then deserialize the canvas before drawing.
  • srgb-8888: Run the 8888 sink in the sRGB color space.
• Common Vias:
  • serialize: Serializes/Deserializes drawing.
  • pic: Records to SkPicture and plays back.
  • rtblend: Uses a runtime blend mode.
  • matrix: Applies a 2x2 matrix (requires --matrix "s0 s1 s2 s3").
  • upright: Applies a matrix and then uprights it.
• Color Space Vias: srgb, linear, p3, rec2020, narrow.

Writing Tests

• Unit Tests: Use DEF_TEST(Name, reporter) in tests/.
• GMs: Use DEF_GM(return new MyGM;) in gm/.

6. Debugging Fuzz Cases & Writing Reproduction Tests

To build and run a fuzzer (like Clusterfuzz or oss-fuzz) to reproduce a crash:

ninja --quiet -C out/Debug fuzz
out/Debug/fuzz --bytes <path_to_testcase>

For the full workflow (including writing reproduction unit tests), see Fuzz Debugging.

Available Resources

• Build Arguments
• dm Usage
• nanobench Usage
• viewer Usage
• Testing
• GMs
• Fuzz Debugging
• Other Tools