Revise Packaging.md#173
Conversation
|
no time or interest to finish this, but it's already an improvement to the exitsing file. OK to merge? |
mighdoll
left a comment
mighdoll
left a comment
There was a problem hiding this comment.
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.
|
|
||
| ## Using shader packages | ||
|
|
||
| Dependencies for your application are defined in the [`wesl.toml`] file. |
There was a problem hiding this comment.
dependencies in wesl.toml are optional for the wesl-js package (it gets them from package.json)
|
|
||
| ## Semver-compatibility and dependency unification | ||
|
|
||
| (TODO: unification with param const?) |
There was a problem hiding this comment.
suggest we remove TODO so this doesn't look incomplete. When param const comes in (soon I hope!) we can revise as appropriate.
|
|
||
| (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). |
There was a problem hiding this comment.
I think we might say that users are doing this unification. i.e. users of npm and cargo may unify them.
There was a problem hiding this comment.
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)
| (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 wary of. Module-scope declarations may, or may not be duplicated. |
There was a problem hiding this comment.
I think "This unification can have osbservable side-effects" is enough. (no need to scare people/agents away from using packages)
| 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 can 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. |
There was a problem hiding this comment.
'reachable' is a little confusing here. The declarations can of course be used indirectly. and does the root module matter here?
I think the point is that indirect package dependencies (via wesl.toml or package.json or cargo.toml) are not usable in WESL statements. You can only say import foo_pkg::bar; if foo_pkg is a direct dependency.
| * 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` |
There was a problem hiding this comment.
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::...
3 participants
It's time to un-draft Packaging.md