docs: Document naga WGSL bundling and module composition capabilities

[Copilot]

Connections

Investigation requested to understand naga's facilities for shader modularity, bundling, and test harness separation.

Description

Investigated naga's WGSL frontend for import/include/linking capabilities. Key findings:

Naga does NOT provide:

• Import/include directives for WGSL
• Module linking or bundling
• Preprocessor macros (GLSL has pp_rs, WGSL does not)

Available extension points:

• Enable extensions: f16, dual_source_blending, clip_distances, wgpu_mesh_shader, wgpu_ray_query
• Language extensions: readonly_and_readwrite_storage_textures, packed_4x8_integer_dot_product, pointer_composite_access

External solutions exist:

• naga_oil - Bevy's shader composition library with #import syntax
• WESL - Emerging WGSL extension standard with import support

Added docs/naga-bundling-capabilities.md documenting:

• Naga Module IR structure
• Available extension mechanisms
• External solutions comparison
• Recommendations for test harness separation (multiple entry points + --compact)
• Potential native implementation - Analysis of how import/export, linking, and source mapping could be added to naga:
  • Import/Export syntax parsing at AST level (~2-3 weeks effort)
  • IR-level linking with handle remapping (~4-6 weeks effort)
  • Source mapping support leveraging existing Span infrastructure (~2-3 weeks effort)

Testing

Documentation only. No code changes.

Squash or Rebase?

Squash

Checklist

• Run cargo fmt.
• Run taplo format.
• Run cargo clippy --tests. If applicable, add:
  • --target wasm32-unknown-unknown
• Run cargo xtask test to run tests.
• If this contains user-facing changes, add a CHANGELOG.md entry.

Original prompt

I want you to look into the https://github.com/gfx-rs/wgpu/tree/trunk/naga files for the naga wgsl binary that transpiles shader code. I want you to see if there are any facilities in naga that enable encapsulating different functions into separate coherent files, and then combining them into a shared codebase (like a bundle file) - as well as assembling test harnesses in separate non-production bundle. Some examples that could allow this would be preprocessor macros that enable import or perhaps naga specific wgsl extensions. Ideally there would be full linking. My suggestions are not complete so please look and see if any features of naga enable this "bundling"[

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[bytesandwich]

@copilot Do you think we could change naga to do two additional passes import/export and link, and also provide a source mapping? How wild we go about it? Please explain

[Copilot]

@copilot Do you think we could change naga to do two additional passes import/export and link, and also provide a source mapping? How wild we go about it? Please explain

Yes, adding import/export and linking to naga is technically feasible but would be a significant undertaking. Here's how it could be approached:

Architecture for Import/Export/Link

1. Import/Export Pass (Pre-parse or AST level)

Add new directive handling in naga/src/front/wgsl/parse/directive/:

export fn myFunction() { ... }
import "module_path" { myFunction, MyType }

This would:

• Extend the lexer/parser to recognize import/export keywords
• Track exported symbols in a new ExportTable structure
• Track import references as unresolved dependencies

2. Linking Pass (IR level)

Create a new naga/src/link/mod.rs module that:

• Takes multiple naga::Module instances
• Remaps all Handle<T> references when merging arenas (types, constants, functions, etc.)
• Resolves cross-module references using a symbol table
• Deduplicates equivalent types using UniqueArena
• Validates no circular dependencies exist

The trickiest part is handle remapping—naga's arena-based IR uses Handle<T> extensively, and merging modules requires translating all handles from source module arenas to the combined module.

3. Source Mapping

Naga already has Span infrastructure (naga/src/span.rs) that tracks byte offsets. To extend this:

• Add a SourceMap type mapping Span → (file_path, original_span)
• Modify parsing to accept file identifiers
• Preserve mappings through lowering and IR transformations
• Output source maps in a standard format (e.g., similar to JavaScript source maps)

Effort Estimate

• Import/Export syntax: ~2-3 weeks (parser changes, AST extensions)
• Linking pass: ~4-6 weeks (handle remapping, type deduplication, validation)
• Source mapping: ~2-3 weeks (span tracking through all passes)

Alternative: Expose Parser API

A lighter approach (as discussed in #6250) would be exposing naga's lexer/parser as a public API, letting tools like naga_oil handle composition at the source level before naga parsing. This is essentially what naga_oil does today but with regex-based preprocessing.