Roll Mesa Dependency
Use this skill to roll third_party/mesa/src in Dawn and update Dawn's custom
GN and CMake build rules in third_party/mesa/.
Workflow
1. Verify .gclient Configuration
- Read
.gclientin the Dawn workspace root. - Verify that
"checkout_mesa": Trueis set insidecustom_vars. - If
checkout_mesais missing or not set toTrue, stop and prompt the user to set"checkout_mesa": Truein.gclient(or ask if they would like you to update.gclientfor them) so thatgclient syncpullsthird_party/mesa/src,third_party/llvm-dev, andthird_party/zstd.
2. Verify third_party/mesa/src is Present
- Check whether
third_party/mesa/srcexists and is populated (e.g., check forthird_party/mesa/src/meson.build). - If
third_party/mesa/srcis missing or empty, prompt the user to rungclient sync(or ask permission to rungclient syncnow) before proceeding.
3. Roll third_party/mesa/src in DEPS
- Record the current
third_party/mesa/srccommit hash fromDEPSso you can diff upstream Mesa changes later (<old_hash>). - Ask the user if they have already performed the roll / updated the
third_party/mesa/srchash inDEPS. - If they have not updated it yet:
- Run
roll-dep(fromdepot_tools) to update the hash inDEPS:
(If the working tree has local changes or the user wants a specific commit, passroll-dep third_party/mesa/src--ignore-dirty-treeand/or--roll-to <commit>as appropriate, or update the hash inDEPSdirectly if requested.)
- Run
- Record the new
third_party/mesa/srccommit hash fromDEPS(<new_hash>).
4. Sync the Updated Mesa Checkout
Run gclient sync to check out the updated third_party/mesa/src revision:
gclient sync
5. Build and Fix the GN Mesa Build
- Check the GN build directory (
out/activeby default):- Read
out/active/args.gnand check that both of the following args are enabled:tint_build_mesa = true tint_build_fuzzer_vulkan_support = true - If
out/active/args.gndoes not exist or does not have both args set totrue, ask the user whether they want to updateout/active/args.gnor use a different GN build directory.
- Read
- Run the GN build:
autoninja -C <gn_build_dir> third_party/mesa:mesa tint_wgsl_mesa_fuzzer tint_ir_mesa_fuzzer - Analyze GN build results:
- If the build fails, inspect the errors and compare upstream Mesa build
changes between the old and new commits:
git -C third_party/mesa/src diff <old_hash>..<new_hash> -- "**/meson.build" "meson_options.txt" - Check for external dependency requirements: Determine whether the
failure requires updating another external dependency, such as
third_party/llvm-dev(e.g., Mesa requires a newer LLVM version or newly added LLVM C++/C APIs not present inthird_party/llvm-dev),third_party/zstd, or Python packages invpython.toml.- STOP CONDITION: If another dependency (
llvm-dev,zstd, etc.) must be updated to roll Mesa, advise the user of the exact details and do not proceed, as updating those prebuilt packages requires manual steps outside the scope of this skill.
- STOP CONDITION: If another dependency (
- Mitigate within
third_party/mesa/: If the failure is caused by upstream Mesa source/codegen/flag changes that can be resolved in Dawn's custom GN rules, update:third_party/mesa/mesa_sources.gni: Add, remove, or rename source files in the source lists, or updatemesa_common_defines/mesa_common_cflags*.third_party/mesa/BUILD.gn: Update_mesa_action/ shader codegen targets, arguments, inputs, outputs, include directories, or_mesa_source_setdependencies, then rungn format third_party/mesa/BUILD.gn third_party/mesa/mesa_sources.gni.third_party/mesa/mesa_llvm_sysroot_compat.ccorthird_party/mesa/mesa_action.pyif needed.
- Re-run
autoninjauntilthird_party/mesa:mesa,tint_wgsl_mesa_fuzzer, andtint_ir_mesa_fuzzercompile and link cleanly.
- If the build fails, inspect the errors and compare upstream Mesa build
changes between the old and new commits:
- Test the GN build: Run a smoke test with
tint_wgsl_mesa_fuzzerto confirmlibvulkan_lvp.soloads vialvp_icd.jsonand validates a WGSL shader cleanly:./<gn_build_dir>/tint_wgsl_mesa_fuzzer --vk-icd=./<gn_build_dir>/lvp_icd.json --verbose test/tint/out_of_order_decls/alias/struct.wgsl
6. Build and Fix the CMake Mesa Build
- Sync any GN rule changes to CMake: If you modified
third_party/mesa/mesa_sources.gniorthird_party/mesa/BUILD.gnin Step 5, apply the corresponding updates tothird_party/mesa/mesa_sources.cmakeandthird_party/mesa/CMakeLists.txt. - Check the CMake build directory (
out/cmakeby default):- Check
out/cmake/CMakeCache.txtto verify thatTINT_BUILD_MESA:BOOL=ONandTINT_BUILD_FUZZER_VULKAN_SUPPORT:BOOL=ON(along withTINT_BUILD_FUZZERS:BOOL=ON) are enabled. - If
out/cmakedoes not exist or those options are not enabled, prompt the user to ask whether to enable them inout/cmake(viacmake -B out/cmake -DTINT_BUILD_MESA=ON -DTINT_BUILD_FUZZER_VULKAN_SUPPORT=ON -DTINT_BUILD_FUZZERS=ON) or use a different CMake build directory.
- Check
- Run the CMake build:
cmake --build <cmake_build_dir> --target mesa tint_wgsl_mesa_fuzzer tint_ir_mesa_fuzzer - Analyze CMake build results:
- If the CMake build fails, determine whether the failure can be mitigated
with changes to
third_party/mesa/mesa_sources.cmakeorthird_party/mesa/CMakeLists.txt. - STOP CONDITION: Just as in the GN step, if the CMake build failure
indicates that another dependency (
llvm-dev,zstd, etc.) requires an update, inform the user with the details and do not proceed. - Re-run
cmake --builduntilmesa,tint_wgsl_mesa_fuzzer, andtint_ir_mesa_fuzzerbuild cleanly with zero undefined symbols.
- If the CMake build fails, determine whether the failure can be mitigated
with changes to
- Test the CMake build: Run a smoke test with the CMake
tint_wgsl_mesa_fuzzerbinary:./<cmake_build_dir>/tint_wgsl_mesa_fuzzer --vk-icd=./<cmake_build_dir>/lvp_icd.json --verbose test/tint/out_of_order_decls/alias/struct.wgsl