#Name mangling

Linker will mangle names internally, but we’re hoping to keep the mangling details out of the public api.

See also renaming host visible names in Visibility.

(TBD)

• Extend scheme to support generics.
• Can we find an explicit naming scheme where packages specify names for their host exposed WESL parts rather than publishing automatically mangled names?
  • e.g. @publicName("mypkg_util_bar") @compute fn compute_shader() {}
  • that way the host code doesn’t need to change if the WESL file structure is refactored.

#What gets mangled

All declaration identifiers get mangled, except:

• root module declarations (this is being discussed, see https://github.com/wgsl-tooling-wg/wesl-js/issues/98)
• declarations imported in the root module
  • if the import renames the declaration (using the import foo as bar syntax), the declaration is renamed.
  • if the import is a module (import some::module where some/module.wesl exists) it does not affect mangling.

#Mangling

To join multiple modules into one, we need to make sure that names do not collide. This is done by name mangling.

Mangling is the process of renaming a declaration and its references to avoid name collisions. It is not easy: because of name shadowing, local-scope declarations can have the same name as module-scope ones. To rename all references to a declaration, one has to walk the syntax tree while keeping track of the scope (list of local declarations).

Compiled WGSL files have a few exposed parts, namely the names of the entry functions and pipeline overridable constants (together called “host-visible names”).

#Underscore-count mangling

For sharing tests, we need a stable and predictable scheme. This one is also reversible and human-readable.

For name mangling, we introduce the concept of a fully qualified path. This is the absolute path to the module, plus the item. e.g. bevy_pbr::lighting::main

1. _ is the path separator
2. Split into segments (bevy_pbr, lighting, main)
3. If a segment contains _, prefix it with _n where n the number of underscores it contains. (_1bevy_pbr, lighting, main)
4. The result is joined with _. (_1bevy_pbr_lighting_main)

#Only-conflict mangling

A simple mangling strategy is

• load everything in a predictable order
• when emitting, keep track of which identifier names have already been used at the global scope
• if one identifier name is used twice, give the second one a name with an incrementing number appended to it

This strategy is very human readable, but cannot be unmangled, since information is lost. For reproducible builds: It relies on the linker assigning these names in a predictable order. This could be violated by hashmaps, async code or incremental re-compilation, so special care must be taken.