Revise Packaging.md by k2d222 · Pull Request #173 · webgpu-tools/wesl-spec

k2d222 · 2025-12-19T18:41:36Z

It's time to un-draft Packaging.md

k2d222 · 2026-02-28T13:26:37Z

no time or interest to finish this, but it's already an improvement to the exitsing file. OK to merge?

mighdoll

It'll be good to get this in! sorry for forgetting about it and glad you're pushing it forward. lmk if you want help on any of the minor edits, I can make more specific text proposals if needed.

mighdoll · 2026-02-28T19:41:54Z

+
+(TODO: unification with param const?)
+
+If two packages in the dependency tree are [semver-compatible](https://semver.org/), npm or Cargo will likely unify them, meaning it will include only one version of the package in its output (often the highest semver-compatible version available).


I think we might say that users are doing this unification. i.e. users of npm and cargo may unify them.

Oh, I see, the point is that package managers will sometimes unify by default. I think that's the default for npm, though the rules are overridable and expectations vary on whether indirect dependencies are unified. (AFAIR by default pnpm doesn't unify indirect dependencies, but npm might still do that)

lemme know if the current revision clarifies.

mighdoll · 2026-02-28T20:11:06Z

+* Add the `_wgsl` suffix to the name: `mypackage_wgsl`.
+* Use snake_case (underscores to separate words): `my_great_package_wgsl`.
+* If your package is part of a larger project, or produced by a company, you can prefix it with that name: `mycompany_mypackage_wgsl`.
+  * For [wesl-js] specifically, you can use the common naming convention `@mycompany/mypackage_wgsl`


we might add a note here that package names with @ and - and / are sanitized for use in WESL:
"@scope/my-package" => import scope__my_package::...

I don't know the exact sanitization rules in -js, so I added vague footnote

apply revisions

mighdoll

Looks good, nice work moving this forward! Suggestions below are mostly editorial.

mighdoll · 2026-07-09T04:34:32Z

+## Using shader packages
+
+The WESL linker is responsible for finding and downloading dependencies: [wesl-js] will fetch packages from [npm], while [wesl-rs] will fetch them from [crates.io].
+The package dependencies of a shader project are either discovered automatically by the WESL linker, or explicitly listed in the `dependencies` section of [`wesl.toml`].


wesl-rs currently uses build.rs?
wesl-js normally infers from shader code + package.json.
(I don't think we actually use wesl.toml deps in linking at present..)

wesl-rs currently uses build.rs?

yes, packages are built in the build script. Currently the -rs expects that packages are manually provided in the build command.

added a note to be removed once we have better sopport of wesl-toml.

mighdoll · 2026-07-09T04:35:24Z

+
+The WESL linker is responsible for finding and downloading dependencies: [wesl-js] will fetch packages from [npm], while [wesl-rs] will fetch them from [crates.io].
+The package dependencies of a shader project are either discovered automatically by the WESL linker, or explicitly listed in the `dependencies` section of [`wesl.toml`].
+Inside shader modules, one can reach declarations in dependencies with import paths, as explained in [imports].


perhaps something in this direction:

WESL tools resolve module paths in WESL code using the algorithm described in import resolution. Each ecosystem package format provides a standard way for WESL tools to map from module paths to shader code.

my goal was to explain how packages can be used inside shader code, and that is using import statment. I've settled on a sentence in-between yours and mine.

mighdoll · 2026-07-09T04:35:47Z

+
+## Creating and publishing shader packages
+
+Any [`wesl.toml`] file declares a new shader package, which can be published using the linker's CLI.


in js, wesl-packager is currently a separate cli (from the wesl-link cli).

@mighdoll

@mighdoll comment revisions

experimentslee

looking good. best not promise to wesl.toml deps for wesl-js.
resolve/review the 4 comments and then LGTM w/o further review

experimentslee · 2026-07-13T20:52:17Z

+* Look for packages with the same name in both [npm] and [crates.io].
+  * It is courtesy to leave the name free for the original author if they wish to publish to the other registry.
+  * It also avoids confusion for end-users who may think it is the same package.
+  * 


extra bullet

experimentslee · 2026-07-13T20:53:14Z

+
+In development, packages are typically loaded from repositories by ecosystem package managers like npm or cargo. [wesl-js] will fetch packages from [npm], while [wesl-rs] will fetch them from [crates.io].
+The package dependencies of a shader project are either provided manually using linker-specific settings, discovered automatically by the linker, or explicitly listed in the `dependencies` section of [`wesl.toml`][^1].
+A package contents is reachable from user code via module paths starting with the package name. This mechanism is detailed in the [import resolution algorithm](Imports.md#resolving-a-declaration-path).


package's contents are

experimentslee · 2026-07-13T20:56:21Z

+[wesl-rs]: https://github.com/wgsl-tooling-wg/wesl-rs

-We are planning on taking advantage of existing package managers, such as `cargo` for Rust, and `npm` for Javascript. This makes it easier for users to consume shaders, and makes sense for ecosystem-specific tools.
+[^1]: At the time of writing, [wesl-js] and [wesl-rs] do not support reading dependencies in `wesl.toml`, but that will become the preferred way of discovering dependencies in the near future.


perhaps just drop the footnote for now, the base sentence covers the options already we don't need to predict in a spec footnote that will soon go out of date.

(also, I think wesl-js probably stays default auto, and maybe still ignores the wesl.toml deps? not sure, but we'll discuss with #194)

experimentslee · 2026-07-13T21:02:41Z


-We are planning on taking advantage of existing package managers, such as `cargo` for Rust, and `npm` for Javascript. This makes it easier for users to consume shaders, and makes sense for ecosystem-specific tools.
+[^1]: At the time of writing, [wesl-js] and [wesl-rs] do not support reading dependencies in `wesl.toml`, but that will become the preferred way of discovering dependencies in the near future.
+[^2]: When a package name contains symbols such as `-` `/` or `@`, [wesl-js] will sanitize it to become a valid WGSL identifier, e.g. a package named `@mycompany/mypackage_wgsl` can be imported with the prefix `mycompany__mypackage_wgsl`. [wesl-js] forbids symbols, with the exception of `-` (dash) which is replaced with `_` (underscore). Refer to the linkers' documentation for more information.


for wesl-js, it's:

@ is removed

/ becomes __

- becomes _

I think maybe the second ref has a typo, supposed to be to wesl-rs.

I think it's goodness to mention the sanitizations, since we have to keep them stable.

instead of a footnote, I'll write a subsection "package name sanitization". It deserves q deeper explanation.

revise Packaging.md

83e965c

github-project-automation Bot added this to specs and docs Dec 19, 2025

github-project-automation Bot moved this to Todo in specs and docs Dec 19, 2025

minor

e5982b6

k2d222 marked this pull request as ready for review February 28, 2026 13:26

stefnotch reviewed Feb 28, 2026

View reviewed changes

Comment thread Packaging.md Outdated

stefnotch reviewed Feb 28, 2026

View reviewed changes

Comment thread Packaging.md Outdated

stefnotch reviewed Feb 28, 2026

View reviewed changes

Comment thread Packaging.md

k2d222 added 3 commits February 28, 2026 20:32

Update Packaging.md

7b51dfd

oops

64fa55f

typo

56c36d3

mighdoll reviewed Feb 28, 2026

View reviewed changes

Update Packaging.md

464b4be

apply revisions

k2d222 requested review from mighdoll and stefnotch July 7, 2026 15:03

mighdoll requested changes Jul 9, 2026

View reviewed changes

mighdoll reviewed Jul 9, 2026

View reviewed changes

Comment thread Packaging.md Outdated

Update Packaging.md

ea59b54

@mighdoll comment revisions

experimentslee suggested changes Jul 13, 2026

View reviewed changes

stefnotch approved these changes Jul 14, 2026

View reviewed changes


		(TODO: unification with param const?)

		If two packages in the dependency tree are [semver-compatible](https://semver.org/), npm or Cargo will likely unify them, meaning it will include only one version of the package in its output (often the highest semver-compatible version available).


		## Creating and publishing shader packages

		Any [`wesl.toml`] file declares a new shader package, which can be published using the linker's CLI.

Uh oh!

Conversation

k2d222 commented Dec 19, 2025

Uh oh!

k2d222 commented Feb 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mighdoll left a comment

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

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!

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!

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!

experimentslee 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants