Wording tweaks by k2d222 · Pull Request #205 · webgpu-tools/wesl-spec

k2d222 · 2026-07-22T15:01:13Z

Per our Discord discussion I clarify the meaning of root module which was confused with package root directory and package:: module path. I also went ahead and tweaked the glossary.

renamed root module -> entry module.
removed wesl translator which was a bit redundant with wesl linker.
tweaked and moved other definitions.

k2d222 · 2026-07-22T15:02:16Z

@@ -292,9 +292,9 @@ fn fragment_main() -> @location(0) vec4f {

 ### Aggregating entry points


btw I still think this section should be moved from spec to docs, It is just informative.

or maybe a non-normative Note? Or do you have a spot in mind in the docs? (can be a separate PR if we don't have a plan yet)

mighdoll

heroic editing! Clarity will improve with these changes.

More edits requested to complete the de-root.
maybe main module rather than entry module?
couple of substantive changes mixed in (e.g. package visible pipeline-relevant items in the module-formerly-known-as-root are also pipeline-visible)

mighdoll · 2026-07-22T22:29:30Z

+
+* **Module**: A unit of WESL or WGSL code with its own top-level scope, stored in a single module source.
+* **Module Source**: The stored text of a module, typically in a WESL or WGSL file.
+* **Entry Module**: The WESL module from which translation starts. Its public declarations form the **shader-host interface** and are not mangled. A single application can have many entry modules.


alternate: do you like 'Main Module', like 'main()' in C?

entry is better than root and I'm fine with it, but today I'm kinda liking main.

my worry is that a module containing entry points needn't be the entry module, and talking about entry modules and entry points will require the reader to distinguish the two related but different senses of entry.

I lean main as I write this but I'm aok either way.

yeah i like main !

k2d222

ready for another round @mighdoll @stefnotch

k2d222 · 2026-07-23T10:31:54Z

+* **Entry Module**: The WESL module from which translation starts. Its public declarations form the **shader-host interface** and are not mangled. A single application can have many entry modules.
+* **Module Path**: A `::`-separated path naming a module; equivalently, a declaration path minus its final segment.
+* **Declaration Path**: A `::`-separated path whose final segment names a declared item.
+* **Canonical Path**: A fully qualified module/ declaration path (which does not contain any `super::`). There is exactly one canonical path per module or declaration within a package.


yeah I introduced canonical path which is not referenced in the spec. The idea is that we have not term for non-canonical paths since the current spec calls any path canonical, and that's confusing.

k2d222 · 2026-07-23T10:36:41Z

-  exposes it to the host (see [Visibility](Visibility.md)).
+* **wesl.toml**: The optional configuration file for a package. See [WeslToml](WeslToml.md).
+* **Module Path Resolution**: Mapping between module paths and module source within a package. Choice of mapping is implementation-specific.
+* **Filesystem Resolution**: The default module path resolution. It maps module paths to file paths relative to a **Package Root Directory**. See [Filesystem Resolution][Imports.md#filesystem-resolution].


cHnged to

The standard path resolution for a filesystem storage

k2d222 · 2026-07-23T10:47:00Z

+* **wesl.toml**: The optional configuration file for a package. See [WeslToml](WeslToml.md).
+* **Module Path Resolution**: Mapping between module paths and module source within a package. Choice of mapping is implementation-specific.
+* **Filesystem Resolution**: The default module path resolution. It maps module paths to file paths relative to a **Package Root Directory**. See [Filesystem Resolution][Imports.md#filesystem-resolution].
+* **Package Root Module Path**: The module path consisting only of `package`. Corresponds to `package.wesl` in the package root directory with the filesystem resolution.


reworded slightly.

k2d222 · 2026-07-23T11:48:09Z

+* **Entry Module**: The WESL module from which translation starts. Its public declarations form the **shader-host interface** and are not mangled. A single application can have many entry modules.
+* **Module Path**: A `::`-separated path naming a module; equivalently, a declaration path minus its final segment.
+* **Declaration Path**: A `::`-separated path whose final segment names a declared item.
+* **Canonical Path**: A fully qualified module/ declaration path (which does not contain any `super::`). There is exactly one canonical path per module or declaration within a package.


What would you prefer:

remove canonical from glossary

a module path can be relative or canonical, and filesystem resolution first canonicalizes the path

k2d222 · 2026-07-23T11:48:34Z

+* **Module Source**: The stored text of a module, typically in a WESL or WGSL file.
+* **Entry Module**: The WESL module from which translation starts. Its public declarations form the **shader-host interface** and are not mangled. A single application can have many entry modules.
+* **Module Path**: A `::`-separated path naming a module; equivalently, a declaration path minus its final segment.
+* **Declaration Path**: A `::`-separated path whose final segment names a declared item.


see comment about canonical

k2d222 · 2026-07-23T11:49:08Z

+* **Module**: A unit of WESL or WGSL code with its own top-level scope, stored in a single module source.
+* **Module Source**: The stored text of a module, typically in a WESL or WGSL file.
+* **Entry Module**: The WESL module from which translation starts. Its public declarations form the **shader-host interface** and are not mangled. A single application can have many entry modules.
+* **Module Path**: A `::`-separated path naming a module; equivalently, a declaration path minus its final segment.


is it only import paths that can have super? not inline paths?

mighdoll · 2026-07-23T21:36:10Z

What would you prefer:

remove canonical from glossary

a module path can be relative or canonical, and filesystem resolution first canonicalizes the path

I think remove. I wouldn't tie module path terms to fs resolution.

I like canonical, might make things more clear. Reworking the text to use it and hopefully drop one or two of the other definitions seems worthy, but it'd be easier to review in a separate PR.

mighdoll · 2026-07-23T21:41:06Z

is it only import paths that can have super? not inline paths?

they can too! the terminology just needs a way to distinguish the thing you might type in from the thing that's... canonical :-). currently a module path or and a declaration path are canonical, and there's no glossary term for inline path I think.

It would be nice to clean up the terms, I think you're onto something.

k2d222

addressed comments.

k2d222 · 2026-07-28T11:35:41Z

+* **Module**: A unit of WESL or WGSL code with its own top-level scope, stored in a single module source.
+* **Module Source**: The stored text of a module, typically in a WESL or WGSL file.
+* **Entry Module**: The WESL module from which translation starts. Its public declarations form the **shader-host interface** and are not mangled. A single application can have many entry modules.
+* **Module Path**: A `::`-separated path naming a module; equivalently, a declaration path minus its final segment.


Added back.

k2d222 · 2026-07-28T11:35:51Z

+* **Module Source**: The stored text of a module, typically in a WESL or WGSL file.
+* **Entry Module**: The WESL module from which translation starts. Its public declarations form the **shader-host interface** and are not mangled. A single application can have many entry modules.
+* **Module Path**: A `::`-separated path naming a module; equivalently, a declaration path minus its final segment.
+* **Declaration Path**: A `::`-separated path whose final segment names a declared item.


k2d222 · 2026-07-28T11:38:14Z

+* **Entry Module**: The WESL module from which translation starts. Its public declarations form the **shader-host interface** and are not mangled. A single application can have many entry modules.
+* **Module Path**: A `::`-separated path naming a module; equivalently, a declaration path minus its final segment.
+* **Declaration Path**: A `::`-separated path whose final segment names a declared item.
+* **Canonical Path**: A fully qualified module/ declaration path (which does not contain any `super::`). There is exactly one canonical path per module or declaration within a package.


I kept it and made module path / declaration path derive from it. There was too much complexity to pack in one definition.

mighdoll

lookin' good! a few minor fixes for you. pretty minor, a couple would be misleading. fix those and lgtm w/o further review.

mighdoll · 2026-07-30T05:24:31Z

+* **Module**: A unit of WESL or WGSL code with its own top-level scope, stored in a single module source.
+* **Module Source**: The stored text of a module, typically in a WESL or WGSL file.
+* **Main module**: The WESL module from which translation starts. It defines the Pipeline-visible API. A single application can have many main modules.
+* **Pipeline-visible API**, The set of items which are visible to the host (CPU-side). Pipeline-visible item names are not mangled.


k2d222 added 4 commits July 22, 2026 16:47

organize glossary

8431959

rename wesl translator -> wesl linker

846a647

rename root module -> entry module

ab5e379

slight reword in aggregating entry points

2019796

github-project-automation Bot added this to specs and docs Jul 22, 2026

github-project-automation Bot moved this to Todo in specs and docs Jul 22, 2026

k2d222 commented Jul 22, 2026

View reviewed changes

tweak "package root module"

09bb697

mighdoll requested changes Jul 23, 2026

View reviewed changes

apply revisions from comments

af8236a

k2d222 commented Jul 23, 2026

View reviewed changes

comments

9879efa

k2d222 commented Jul 28, 2026

View reviewed changes

mighdoll requested changes Jul 30, 2026

View reviewed changes

comments

e17ed4d

k2d222 requested a review from stefnotch July 30, 2026 09:22

stefnotch approved these changes Aug 12, 2026

View reviewed changes

k2d222 merged commit 1611489 into main Aug 19, 2026
1 check passed

k2d222 deleted the wording-tweaks branch August 19, 2026 17:51

github-project-automation Bot moved this from Todo to Done in specs and docs Aug 19, 2026

		@@ -292,9 +292,9 @@ fn fragment_main() -> @location(0) vec4f {

		### Aggregating entry points

Uh oh!

Conversation

k2d222 commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mighdoll left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

k2d222 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mighdoll commented Jul 23, 2026

Uh oh!

mighdoll commented Jul 23, 2026

Uh oh!

k2d222 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mighdoll left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

k2d222 commented Jul 22, 2026 •

edited

Loading