Tips for developing Dawn code

June 12, 2026 ยท View on GitHub

Build/run as much stuff as possible locally, to find bugs before they hit CQ

  • Use scripts/standalone-maximal.gclient instead of standalone.gclient.
  • Set the dawn_maximal = true GN arg to default to building as many targets as possible given your host OS.
  • Build all targets (target all, which is the default if none is specified).
  • Develop on Linux or Mac, and set up build directories that cross-compile for other OSes (see building.md).
    • dawn_maximal = true is optional but still useful for cross-compile builds.
  • Also note you can run gn gen --check to locally run the presubmit check that C++ includes match the build files.

Set up your IDE to use clangd

  • Do the steps above, so that clangd will know how to build most files.
  • Do a full build in each build directory (to create generated files, etc.).
  • Set "custom_vars": { "checkout_clangd": True } in .gclient (or just use standalone-maximal.gclient).
  • Point your IDE to the binary at third_party/llvm-build/Release+Asserts/bin/clangd.
    • In VSCode: clangd.path
  • Configure clangd: Paste the relevant text into .clangd and then update the out/ paths in that file according to your needs.
    • Note the PathMatch paths aren't intended to be perfect, but please update this doc if you find platform-specific files that they miss.
    • If you have just one build directory, you can alternatively pass this as a clangd argument: --compile-commands-dir=out/Debug
      • In VSCode: clangd.arguments
    • For Chromium builds, take a look at chrome-remote-index.

For Mac/Linux hosts:

# This first section applies by default. Additional "fragments" below *also*
# apply, and may overwrite configs from less-specific fragments.
# Docs: https://clangd.llvm.org/config
CompileFlags:
  CompilationDatabase: out/Debug
  Add:
    - "-ferror-limit=0"
    # Additional personal configs can go here OR in your user-wide
    # `clangd/config.yml` (https://clangd.llvm.org/config#files). Suggestions:
    # - `--header-insertion=never` if you find yourself accidentally adding
    #   random headers when autocomplete goes sideways
---
If:
  PathMatch:
    - "src/dawn/native/d3d12/.*"
    - "src/.*_[Ww]in.*"
    - "src/.*_[Dd]3[Dd].*"
CompileFlags:
  CompilationDatabase: out/Debug-win

For Linux hosts, also add this:

---
If:
  PathMatch:
    - "src/dawn/native/metal/.*"
    - "src/.*_[Mm]ac.*"
    - "src/.*_[Aa]pple.*"
    - "src/.*_[Mm]etal.*"
CompileFlags:
  CompilationDatabase: out/Debug-mac