Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Impeller] Update guidance on how to run with Metal validation without Xcode. #44190

Merged
merged 1 commit into from
Jul 31, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 16 additions & 16 deletions impeller/docs/metal_validation.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
# Enable Metal Validation without Xcode.

To enable validation of all Metal calls without using Xcode, add the following
to your rc file.
Metal validation can be enabled for command-line application using environment
variables.

These flags are not documented and have been reverse engineered from observing
what Xcode does to enable these validation layers.
Apple [documents these environment variables on their developer site](https://developer.apple.com/documentation/xcode/validating-your-apps-metal-api-usage#Enable-API-Validation-with-environment-variables).
More documentation about these environment variables is also available via a man
page entry: `man MetalValidation`

To enable all relevant Metal API and shader validation without using Xcode, add
the following to your `.rc` file.

``` sh
# Metal Validation Defaults
export MTL_DEBUG_LAYER=1
export MTL_DEBUG_LAYER_ERROR_MODE=assert
# Set this to assert for stricter runtime checks. Set to "ignore" if too chatty.
export MTL_DEBUG_LAYER_WARNING_MODE=nslog
export MTL_SHADER_VALIDATION=1
```
# Metal Tracing Defaults
export DYLD_INSERT_LIBRARIES="/usr/lib/libMTLCapture.dylib:/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/GPUToolsPlatform/libMTLToolsDiagnostics.dylib"
export METAL_DEBUG_ERROR_MODE=0
export METAL_DEVICE_FORCE_COMMAND_BUFFER_ENHANCED_ERRORS=1
export METAL_DEVICE_WRAPPER_TYPE=5
export METAL_DIAGNOSTICS_ENABLED=1
export METAL_LOAD_INTERPOSER=1
export MTL_FORCE_COMMAND_BUFFER_ENHANCED_ERRORS=1
export DYMTL_TOOLS_DYLIB_PATH="/usr/lib/libMTLCapture.dylib"
```


These flags have been validated to work on macOS Monterey (12.0.1)
These environment variable are good defaults but there are more validation
related knobs and dials to turn. See `man MetalValidation`.