From 83e965c786c06a11aedca2e7a3ecdc2a0243deda Mon Sep 17 00:00:00 2001 From: Mathis Brossier Date: Fri, 19 Dec 2025 19:39:14 +0100 Subject: [PATCH 01/10] revise Packaging.md --- Packaging.md | 114 ++++++++++++++++++++++++++++----------------------- 1 file changed, 62 insertions(+), 52 deletions(-) diff --git a/Packaging.md b/Packaging.md index a25867c..a106eb4 100644 --- a/Packaging.md +++ b/Packaging.md @@ -1,57 +1,67 @@ # Packaging -(TBD) - -The section will discuss packaging WESL in reusable crates or npm packages. - -See also [Visibility](Visibility.md). - -* What goes in `package.json`? - * at runtime in the browser, the linker needs - WESL strings and relative paths for every needed WESL file, from every every package. - * (this so the linker can resolve imports) - * something needs to tell javascript bundlers to include needed WESL files in the bundle: - * we could ask package publishers to produce a javascript file containing a map of relative paths and WESL strings - * perhaps better would be to have a vite/rollup plugin trace from the source WESL to the needed package WESL files (using the linker as a library to parse WESL) - * this would avoid requiring publishers to manually publish string maps of WESL text, - instead publishers would just publish files in dist. - * the consumer plugin tool would bundle files into strings. - * corner case issue: runtime conditional compilation could potentially change the imported - files required. Perhaps we'll need some workaround markers in this rare case, so tree shaking can still work. - * note that the WESL-linker already has this problem of bundling local WGSL files - and asks users to 'self package' WGSL using import.meta.glob - (which bundles files into [file path, WGSL string] pairs) - * what other metadata should be available to the linker? - * name of package. - * host visible bits from WGSL? e.g. entry points, runtime variables, overrides, binding groups, uniforms? - An IDE tool could use that data to typecheck/autocomplete host calls. - Things like entry points are computable from the WGSL, - but it's a lot to ask of a language server to parse through all the WGSL in advance to find them. - Probably better to put it into the metadata if we need it. - * these are parts of the API of the package as a whole and can reduce bugs by making them visible - * how do we handle packages with multiple entry points e.g. stoneberry/reduce stoneberry/prefixSum. -* What goes in `cargo.toml`? - -## `wesl.toml` file -The `wesl.toml` file is a configuration file that tells the language server where to find the packages. It is similar to a `Cargo.toml` file in that regard. - -```toml -name = "my" -edition = "2024" - -[dependencies] -bevy_ui = { cargo = "bevy_ui" } -shader_wiz = { path = "./node_modules/shader_wiz/src/main.wgsl" } + +WESL enables shader packages for reusing shader code by other packages or applications. Shader packages are published to repositories such as [npm] or [crates.io]. + +## Using shader packages + +Dependencies for your application are defined in the [`wesl.toml`] file. The WESL linker is responsible for finding and downloading dependencies: [wesl-js] will fetch packages from [npm] and [wesl-rs] will fetch them from [crates.io]. +Inside your shader modules, you can reach declarations in dependencies with import paths, as explained in [imports]. + +## Creating and publishing shader packages + +Any [`wesl.toml`] file declares a new shader package, which can be published by the linker's CLI. +Publishing packages is implementation-specific, follow the instructions for your linker ([wesl-js] or [wesl-rs]). + +### Package naming guidelines + +You can publish your package with whatever name you like. We however recommend following these recommendations so your package can be easily found by searching the package registry. + +* Use a name that is also a valid WGSL identifier. Otherwise, end-users will have to rename it in [`wesl.toml`]. +* 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` +* 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. + +## Semver-compatibility and dependency unification + +(TODO: unification with param const?) + +If two packages in the dependency tree are [semver-compatible](https://semver.org/), the WESL linker will unify them, meaning it will include only one version of the package in its output (usually the highest semver-compatible version available). +This unification can have observable side-effects that a user must be warry of. Module-scope declarations may, or may not be duplicated. + +### Example + +```wgsl +// package random +// -------------- +var prng_state: f32 = 0; + +// return a random float in [0, 1]. Do not actually use this function, it is awful. +fn rand() -> f32 { + prng_state = fract(sin(x)*12345.6789); + return prng_state; +} ``` -We specify how to resolve the paths of packages instead of scanning folders for `*.wgsl` files. -In the Javascript world, it is common to have a `node_modules` folder with 10k files, which is not practical for a language server to scan. +Here, the `random::rand()` function has internal state represented by `prng_state`. +If two packages depend on semver-compatible versions of `random`, then they would share that internal state. +If however they depend on non-semver-compatible versions, two copies of the state and the `rand()` function will be used, suddenly producing different results. + +## Visibility + +All declarations reachable from a direct dependency's root module can be accessed from the parent package. +Declarations in indirect dependencies (i.e., dependencies of dependencies) are never reachable. + +Future iterations of WESL may introduce a re-export and/or visibility control mechanism. See [visibility]. -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. -### Unresolved questions -* Is .toml the best file format for the `wesl.toml`? Some alternatives would be JSON/JSON5 and StrictYAML. -* do we need to put paths for every package's WGSL in `wesl.toml`? - * Fine to get started that way if need be, but its a maintenance burden every user.. - * Better if we could get the language servers to find the WGSL in packages in node_modules. -* Do we need to list the WGSL package names in `wesl.toml`? - They'll already be listed in as `cargo.toml` / `package.json`.. +[npm]: https://www.npmjs.com/ +[crates.io]: https://crates.io/ +[`wesl.toml`]: WeslToml.md +[imports]: Imports.md +[visibility]: Visibility.md +[wesl-js]: https://github.com/wgsl-tooling-wg/wesl-js +[wesl-rs]: https://github.com/wgsl-tooling-wg/wesl-rs From e5982b616f263833064f8de328aefd8621ff45c2 Mon Sep 17 00:00:00 2001 From: Mathis Brossier Date: Fri, 19 Dec 2025 19:44:26 +0100 Subject: [PATCH 02/10] minor --- Packaging.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Packaging.md b/Packaging.md index a106eb4..8eb7b8c 100644 --- a/Packaging.md +++ b/Packaging.md @@ -4,17 +4,18 @@ WESL enables shader packages for reusing shader code by other packages or applic ## Using shader packages -Dependencies for your application are defined in the [`wesl.toml`] file. The WESL linker is responsible for finding and downloading dependencies: [wesl-js] will fetch packages from [npm] and [wesl-rs] will fetch them from [crates.io]. +Dependencies for your application are defined in the [`wesl.toml`] file. +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]. Inside your shader modules, you can reach declarations in dependencies with import paths, as explained in [imports]. ## Creating and publishing shader packages -Any [`wesl.toml`] file declares a new shader package, which can be published by the linker's CLI. +Any [`wesl.toml`] file declares a new shader package, which can be published using the linker's CLI. Publishing packages is implementation-specific, follow the instructions for your linker ([wesl-js] or [wesl-rs]). ### Package naming guidelines -You can publish your package with whatever name you like. We however recommend following these recommendations so your package can be easily found by searching the package registry. +You can publish your package with whatever name you like. We however recommend following these guidelines so your package can be easily found and consumed by end users. * Use a name that is also a valid WGSL identifier. Otherwise, end-users will have to rename it in [`wesl.toml`]. * Add the `_wgsl` suffix to the name: `mypackage_wgsl`. From 7b51dfdb54d535c3dbff3620a17d583cd9d07501 Mon Sep 17 00:00:00 2001 From: Mathis Brossier Date: Sat, 28 Feb 2026 20:32:41 +0100 Subject: [PATCH 03/10] Update Packaging.md --- Packaging.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Packaging.md b/Packaging.md index 8eb7b8c..48b102f 100644 --- a/Packaging.md +++ b/Packaging.md @@ -1,4 +1,4 @@ -# Packaging +.# Packaging WESL enables shader packages for reusing shader code by other packages or applications. Shader packages are published to repositories such as [npm] or [crates.io]. @@ -30,7 +30,7 @@ You can publish your package with whatever name you like. We however recommend f (TODO: unification with param const?) -If two packages in the dependency tree are [semver-compatible](https://semver.org/), the WESL linker will unify them, meaning it will include only one version of the package in its output (usually the highest semver-compatible version available). +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). This unification can have observable side-effects that a user must be warry of. Module-scope declarations may, or may not be duplicated. ### Example @@ -49,7 +49,7 @@ fn rand() -> f32 { Here, the `random::rand()` function has internal state represented by `prng_state`. If two packages depend on semver-compatible versions of `random`, then they would share that internal state. -If however they depend on non-semver-compatible versions, two copies of the state and the `rand()` function will be used, suddenly producing different results. +If however they depend on non-semver-compatible versions, two copies of the state and the `rand()` function can be used, suddenly producing different results. ## Visibility From 64fa55fb751483f52a0251138d4733e891aa9675 Mon Sep 17 00:00:00 2001 From: Mathis Brossier Date: Sat, 28 Feb 2026 20:33:40 +0100 Subject: [PATCH 04/10] oops --- Packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Packaging.md b/Packaging.md index 48b102f..84ceab3 100644 --- a/Packaging.md +++ b/Packaging.md @@ -1,4 +1,4 @@ -.# Packaging +# Packaging WESL enables shader packages for reusing shader code by other packages or applications. Shader packages are published to repositories such as [npm] or [crates.io]. From 56c36d3f50d3dcba15db1250e8724ddc59e6e825 Mon Sep 17 00:00:00 2001 From: Mathis Brossier Date: Sat, 28 Feb 2026 20:34:33 +0100 Subject: [PATCH 05/10] typo --- Packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Packaging.md b/Packaging.md index 84ceab3..79c76a0 100644 --- a/Packaging.md +++ b/Packaging.md @@ -31,7 +31,7 @@ You can publish your package with whatever name you like. We however recommend f (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). -This unification can have observable side-effects that a user must be warry of. Module-scope declarations may, or may not be duplicated. +This unification can have observable side-effects that a user must be wary of. Module-scope declarations may, or may not be duplicated. ### Example From 464b4be4765baffca5f0bec0d13281acb7b320fc Mon Sep 17 00:00:00 2001 From: Mathis Brossier Date: Tue, 7 Jul 2026 17:00:45 +0200 Subject: [PATCH 06/10] Update Packaging.md apply revisions --- Packaging.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/Packaging.md b/Packaging.md index 79c76a0..bd0ce46 100644 --- a/Packaging.md +++ b/Packaging.md @@ -4,34 +4,35 @@ WESL enables shader packages for reusing shader code by other packages or applic ## Using shader packages -Dependencies for your application are defined in the [`wesl.toml`] file. 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]. -Inside your shader modules, you can reach declarations in dependencies with import paths, as explained in [imports]. +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]. ## Creating and publishing shader packages Any [`wesl.toml`] file declares a new shader package, which can be published using the linker's CLI. -Publishing packages is implementation-specific, follow the instructions for your linker ([wesl-js] or [wesl-rs]). +Publishing packages is implementation-specific, linkers ([wesl-js] or [wesl-rs]) provide documentation on how to publish to their respective package repositories. ### Package naming guidelines -You can publish your package with whatever name you like. We however recommend following these guidelines so your package can be easily found and consumed by end users. +A package can be published under any name. We however recommend following these guidelines, so the package can be easily found and consumed by end users. * Use a name that is also a valid WGSL identifier. Otherwise, end-users will have to rename it in [`wesl.toml`]. * 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` + * For [wesl-js] specifically, you can use the common naming convention `@mycompany/mypackage_wgsl`.[^1] * 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. -## Semver-compatibility and dependency unification +[^1]: When a package name contains `/` or `@`, [wesl-js] will sanitize it to become a valid WGSL identifier. Refer to its documentation for more information. -(TODO: unification with param const?) +## Semver-compatibility and dependency unification -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). -This unification can have observable side-effects that a user must be wary of. Module-scope declarations may, or may not be duplicated. +[wesl-js] and [wesl-rs] both delegate package installation and version management to npm or Cargo. +These package managers typically apply _dependency version unification_: if two packages in the dependency tree are [semver-compatible](https://semver.org/), the package manager installs only one version of the package, often the latest semver-compatible version available. +For WESL, dependency unification can have observable side-effects; for instance, module-scope declarations may or may not be duplicated. ### Example @@ -47,14 +48,15 @@ fn rand() -> f32 { } ``` -Here, the `random::rand()` function has internal state represented by `prng_state`. -If two packages depend on semver-compatible versions of `random`, then they would share that internal state. -If however they depend on non-semver-compatible versions, two copies of the state and the `rand()` function can be used, suddenly producing different results. +In this example, the `random::rand()` function has internal state represented by `prng_state`. +If two packages depend on semver-compatible versions of `random`, there will be two copies the `rand()` function and its internal state. Calls to `rand()` from both packages refer to the same declaratione. +If however they depend on non-semver-compatible versions, there will be two copies the `rand()` function and its internal state. Calls to `rand()` from both packages refer to distinct declarations. ## Visibility -All declarations reachable from a direct dependency's root module can be accessed from the parent package. -Declarations in indirect dependencies (i.e., dependencies of dependencies) are never reachable. +A package can only import declarations in its direct dependencies, using an import statement or an inline import (see [imports]). +It cannot import declarations in its indirect dependencies (i.e., dependencies of dependencies). +Declarations in indirect dependencies can be indirectly used by the package, for instance if a direct dependency provides a function which calls a function in one of its dependencies. Future iterations of WESL may introduce a re-export and/or visibility control mechanism. See [visibility]. @@ -66,3 +68,4 @@ Future iterations of WESL may introduce a re-export and/or visibility control me [visibility]: Visibility.md [wesl-js]: https://github.com/wgsl-tooling-wg/wesl-js [wesl-rs]: https://github.com/wgsl-tooling-wg/wesl-rs + From ea59b54dceafaf6a16c9ee484a9768e89928da1f Mon Sep 17 00:00:00 2001 From: Mathis Brossier Date: Thu, 9 Jul 2026 14:56:12 +0200 Subject: [PATCH 07/10] Update Packaging.md @mighdoll comment revisions --- Packaging.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/Packaging.md b/Packaging.md index bd0ce46..853611b 100644 --- a/Packaging.md +++ b/Packaging.md @@ -1,12 +1,12 @@ # Packaging -WESL enables shader packages for reusing shader code by other packages or applications. Shader packages are published to repositories such as [npm] or [crates.io]. +WESL enables shader packages for reusing shader code by other packages or applications. Shader packages are typically published to repositories such as [npm] or [crates.io]. ## 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`]. -Inside shader modules, one can reach declarations in dependencies with import paths, as explained in [imports]. +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). ## Creating and publishing shader packages @@ -21,13 +21,11 @@ A package can be published under any name. We however recommend following these * 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`.[^1] + * For [wesl-js] specifically, you can use the common naming convention `@mycompany/mypackage_wgsl`.[^2] * 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. - -[^1]: When a package name contains `/` or `@`, [wesl-js] will sanitize it to become a valid WGSL identifier. Refer to its documentation for more information. - + * ## Semver-compatibility and dependency unification [wesl-js] and [wesl-rs] both delegate package installation and version management to npm or Cargo. @@ -49,17 +47,15 @@ fn rand() -> f32 { ``` In this example, the `random::rand()` function has internal state represented by `prng_state`. -If two packages depend on semver-compatible versions of `random`, there will be two copies the `rand()` function and its internal state. Calls to `rand()` from both packages refer to the same declaratione. -If however they depend on non-semver-compatible versions, there will be two copies the `rand()` function and its internal state. Calls to `rand()` from both packages refer to distinct declarations. +If two packages depend on semver-compatible versions of `random`, there will be a single copy of the `rand()` function and its internal state. Calls to `rand()` from both packages refer to the same declaration. +If however they depend on non-semver-compatible versions, there will be two copies of the `rand()` function and its internal state. Calls to `rand()` from both packages refer to distinct declarations. -## Visibility +## Package visibility -A package can only import declarations in its direct dependencies, using an import statement or an inline import (see [imports]). -It cannot import declarations in its indirect dependencies (i.e., dependencies of dependencies). +A package can only import from packages that are its direct dependencies, using an import statement or an inline import (see [imports]). +It cannot import from indirect dependencies (i.e., dependencies of dependencies). Declarations in indirect dependencies can be indirectly used by the package, for instance if a direct dependency provides a function which calls a function in one of its dependencies. -Future iterations of WESL may introduce a re-export and/or visibility control mechanism. See [visibility]. - [npm]: https://www.npmjs.com/ [crates.io]: https://crates.io/ @@ -69,3 +65,6 @@ Future iterations of WESL may introduce a re-export and/or visibility control me [wesl-js]: https://github.com/wgsl-tooling-wg/wesl-js [wesl-rs]: https://github.com/wgsl-tooling-wg/wesl-rs +[^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. + From afc3a5a2e969d84e9a45f43e31db2afc2df0ac27 Mon Sep 17 00:00:00 2001 From: Mathis Brossier Date: Wed, 15 Jul 2026 14:53:42 +0200 Subject: [PATCH 08/10] Update Packaging.md --- Packaging.md | 37 ++++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/Packaging.md b/Packaging.md index 853611b..1fe7341 100644 --- a/Packaging.md +++ b/Packaging.md @@ -2,30 +2,50 @@ WESL enables shader packages for reusing shader code by other packages or applications. Shader packages are typically published to repositories such as [npm] or [crates.io]. -## Using shader packages - 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). +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`]. ## Creating and publishing shader packages Any [`wesl.toml`] file declares a new shader package, which can be published using the linker's CLI. Publishing packages is implementation-specific, linkers ([wesl-js] or [wesl-rs]) provide documentation on how to publish to their respective package repositories. +### Accessing packages from shader code + +Packages' contents are reachable from user code via module paths prefixed with the package name, e.g. `package_name::declaration_name`. This mechanism is detailed in the [import resolution algorithm](Imports.md#resolving-a-declaration-path). +The package name in shader code is the same as the name published on [npm] or [crates.io], with two exceptions: + +1. The name is sanitized to remove certain common symbols that are invalid in WGSL identifiers (see following section). +2. The name can be overriden in the dependencies list in [`wesl.toml`], e.g. `wgsl_name = { package = "@published/name" }`. + +If after these operations, the shader name is still not a valid WGSL identifier, the package will not be reachable from user code. + +### Package name sanitization + +[wesl-js] performs the following sanitization: +* `@` (at sign) is removed. +* `-` (minus sign) is replaced with `_` (underscore). +* `/` (forward slash) is replaced with `__` (double underscore). + +_Example: a package published on npm with the name `@mycompany/mypackage_wgsl` can be imported with the prefix `mycompany__mypackage_wgsl`._ + +[wesl-rs] only replaces `-` (minus sign) with `_` (underscore). It does not allow `@` or `/`. + +_Example: a package published on npm with the name `my-package-wgsl` can be imported with the prefix `my_package_wgsl`._ + ### Package naming guidelines -A package can be published under any name. We however recommend following these guidelines, so the package can be easily found and consumed by end users. +A package can be published under any name matching the requrements of the section above. We however recommend following these guidelines, so the package can be easily found and consumed by end users. * Use a name that is also a valid WGSL identifier. Otherwise, end-users will have to rename it in [`wesl.toml`]. * 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`.[^2] + * For [wesl-js] specifically, you can use the common naming convention `@mycompany/mypackage_wgsl`.[^1] * 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. - * + ## Semver-compatibility and dependency unification [wesl-js] and [wesl-rs] both delegate package installation and version management to npm or Cargo. @@ -65,6 +85,5 @@ Declarations in indirect dependencies can be indirectly used by the package, for [wesl-js]: https://github.com/wgsl-tooling-wg/wesl-js [wesl-rs]: https://github.com/wgsl-tooling-wg/wesl-rs -[^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. +[^1]: The name will be sanitized in shader code, see [#package-name-sanitization]. From 248dc7adb12b7a8629b92d80e76e8c4e477b2c1c Mon Sep 17 00:00:00 2001 From: Mathis Brossier Date: Wed, 15 Jul 2026 14:55:38 +0200 Subject: [PATCH 09/10] typo --- Packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Packaging.md b/Packaging.md index 1fe7341..0e74aa7 100644 --- a/Packaging.md +++ b/Packaging.md @@ -35,7 +35,7 @@ _Example: a package published on npm with the name `my-package-wgsl` can be impo ### Package naming guidelines -A package can be published under any name matching the requrements of the section above. We however recommend following these guidelines, so the package can be easily found and consumed by end users. +A package can be published under any name matching the requirements of the section above. We however recommend following these guidelines, so the package can be easily found and consumed by end users. * Use a name that is also a valid WGSL identifier. Otherwise, end-users will have to rename it in [`wesl.toml`]. * Add the `_wgsl` suffix to the name: `mypackage_wgsl`. From 201a13ae22add7cde4a3a8945c710e1d0cc78e5e Mon Sep 17 00:00:00 2001 From: Mathis Brossier Date: Wed, 15 Jul 2026 14:56:49 +0200 Subject: [PATCH 10/10] typo 2 --- Packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Packaging.md b/Packaging.md index 0e74aa7..e321a92 100644 --- a/Packaging.md +++ b/Packaging.md @@ -16,7 +16,7 @@ Packages' contents are reachable from user code via module paths prefixed with t The package name in shader code is the same as the name published on [npm] or [crates.io], with two exceptions: 1. The name is sanitized to remove certain common symbols that are invalid in WGSL identifiers (see following section). -2. The name can be overriden in the dependencies list in [`wesl.toml`], e.g. `wgsl_name = { package = "@published/name" }`. +2. The name can be overridden in the dependencies list in [`wesl.toml`], e.g. `wgsl_name = { package = "@published/name" }`. If after these operations, the shader name is still not a valid WGSL identifier, the package will not be reachable from user code.