mirror of
https://github.com/encounter/dawn-cmake.git
synced 2025-06-11 09:03:28 +00:00
93e8f527ee
Handle access control on var declarations instead of via [[access]] decorations. This change does the minimal work to migrate the WGSL parser over to the new syntax. Additional changes will be needed to correctly generate defaulted access qualifiers, as well as validating access usage. The [[access]] decorations are still supported by the WGSL parser, with new deprecated warnings, but not for aliases. Example: var x : [[access(x)]] alias_to_struct; Making this work is far more effort than I want to dedicate to backwards compatibility, and I do not beleive any real-world usage will be doing this. Still TODO: * Adding access control as the optional, third parameter to ptr<>. * Calculating default accesses for the various storage types. * Validating usage of variables against the different accesses. Bug: tint:846 Change-Id: If8ca82e5d16ec319ecd01f9a2cafffd930963bde Reviewed-on: https://dawn-review.googlesource.com/c/tint/+/53088 Commit-Queue: Ben Clayton <bclayton@google.com> Reviewed-by: James Price <jrprice@google.com> Reviewed-by: David Neto <dneto@google.com> Kokoro: Kokoro <noreply+kokoro@google.com>
126 lines
3.1 KiB
Markdown
126 lines
3.1 KiB
Markdown
# Tint diagnostic style guide
|
|
|
|
This guide provides a set of best practices when writing code that emits
|
|
diagnostic messages in Tint. These diagnostics are messages presented to the
|
|
user in case of error or warning.
|
|
|
|
The goal of this document is to have our diagnostic messages be clear and
|
|
understandable to our users, so that problems are easy to fix, and to try and
|
|
keep a consistent style.
|
|
|
|
## Message style
|
|
|
|
* Start diagnostic messages with a lower-case letter
|
|
* Try to keep the message to a single sentence, if possible
|
|
* Do not end the message with punctuation (full stop, exclamation mark, etc)
|
|
|
|
**Don't:**
|
|
|
|
```
|
|
shader.wgsl:7:1 error: Cannot take the address of expression.
|
|
```
|
|
|
|
**Do:**
|
|
|
|
```
|
|
shader.wgsl:7:1 error: cannot take the address of expression
|
|
```
|
|
|
|
**Justification:**
|
|
|
|
Succinct messages are more important than grammatical correctness. \
|
|
This style matches the style found in most other compilers.
|
|
|
|
## Prefer to use a `Source` location instead of quoting the code in the message
|
|
|
|
**Don't:**
|
|
|
|
```
|
|
shader.wgsl:5:7 error: structure 'UBO' requires block decoration
|
|
|
|
struct UBO {
|
|
^^^
|
|
```
|
|
|
|
**Do:**
|
|
|
|
```
|
|
shader.wgsl:5:7 error: structure requires block decoration
|
|
|
|
struct UBO {
|
|
^^^
|
|
```
|
|
|
|
**Justification:**
|
|
|
|
The highlighted line provides even more contextual information than the quoted
|
|
source, and duplicating this information doesn't provide any more help to the
|
|
developer.
|
|
|
|
## Use `note` diagnostics for providing additional links to relevant code
|
|
|
|
**Don't:**
|
|
|
|
```
|
|
shader.wgsl:5:11 error: type cannot be used in storage class 'storage' as it is non-host-shareable
|
|
|
|
cond : bool;
|
|
^^^^
|
|
```
|
|
|
|
**Do:**
|
|
|
|
```
|
|
shader.wgsl:5:11 error: type cannot be used in storage class 'storage' as it is non-host-shareable
|
|
|
|
cond : bool;
|
|
^^^^
|
|
|
|
shader.wgsl:8:4 note: while instantiating variable 'StorageBuffer'
|
|
|
|
var<storage> sb : StorageBuffer;
|
|
^^
|
|
```
|
|
|
|
**Justification:**
|
|
|
|
To properly understand some diagnostics requires looking at more than a single
|
|
line. \
|
|
Multi-source links can greatly reduce the time it takes to properly
|
|
understand a diagnostic message. \
|
|
This is especially important for diagnostics raised from complex whole-program
|
|
analysis, but can also greatly aid simple diagnostics like symbol collision errors.
|
|
|
|
## Use simple terminology
|
|
|
|
**Don't:**
|
|
|
|
```
|
|
shader.wgsl:7:1 error: the originating variable of the left-hand side of an assignment expression must not be declared with read access control.
|
|
```
|
|
|
|
**Do:**
|
|
|
|
```
|
|
shader.wgsl:7:1 error: cannot assign to variable with read access control
|
|
|
|
x.y = 1;
|
|
^^^^^^^
|
|
|
|
shader.wgsl:2:8 note: read access control declared here
|
|
|
|
var<storage, read> x : i32;
|
|
^^^^
|
|
```
|
|
|
|
**Justification:**
|
|
|
|
Diagnostics will be read by Web developers who may not be native English
|
|
speakers and are unlikely to be familiar with WGSL specification terminology.
|
|
Too much technical jargon can be intimidating and confusing. \
|
|
Diagnostics should give enough information to explain what's wrong, and most
|
|
importantly, give enough information so that a fix actionable.
|
|
|
|
**Caution:** Be careful to not over simplify. Use the specification terminology
|
|
if there's potential ambiguity by not including it.
|