Implementation:Ggml org Ggml Webgpu wgsl preprocessor

Implementation Metadata

File Name	src/ggml-webgpu/pre_wgsl.hpp
Repository	ggml-org/ggml
Lines	778
Language	C++
Domain Tags	GPU_Computing, Preprocessor, WebGPU
Status	Active
Last Updated	2025-05-15 12:00 GMT
Knowledge Sources	ggml-org/ggml repository

Overview

pre_wgsl.hpp is a C preprocessor-like text preprocessor for WGSL (WebGPU Shading Language) files. It is essential for the WebGPU backend because WGSL has no built-in preprocessor, and this allows WGSL shaders to use conditional compilation and macro substitution for generating type-specific shader variants.

Description

The file implements a pre_wgsl namespace with a full preprocessor supporting:

• #define -- Macro definitions with recursive expansion and cycle detection
• #ifdef/#ifndef/#if/#elif/#else/#endif -- Conditional compilation directives
• #include -- File inclusion
• Expression parser -- Evaluates conditional expressions (implemented via ExprLexer and ExprParser classes)

Key components:

• Options -- Configures include paths and predefined macros
• Preprocessor -- Main processing class with a Cond stack for nested conditionals
• expandMacrosRecursiveInternal -- Identifier-aware macro substitution respecting word boundaries, with visited-set tracking to prevent infinite recursion

Usage

Used internally by the WebGPU shader library to process WGSL templates before compilation:

#include "pre_wgsl.hpp"

pre_wgsl::Options opts;
opts.macros.push_back("USE_F16=1");
opts.macros.push_back("WORKGROUP_SIZE=256");

pre_wgsl::Preprocessor pp(opts);
std::string processed_wgsl = pp.process(wgsl_template);

Code Reference

Source Location

Repository	File	Lines
ggml-org/ggml	src/ggml-webgpu/pre_wgsl.hpp	778

Key Signatures

namespace pre_wgsl {

struct Options {
    std::string              include_path = ".";
    std::vector<std::string> macros;
};

class ExprLexer { ... };
class ExprParser { ... };
class Preprocessor { ... };

static std::string trim(const std::string & s);
static bool isIdentChar(char c);

static std::string expandMacrosRecursiveInternal(const std::string & line,
    const std::unordered_map<std::string, std::string> & macros,
    std::unordered_set<std::string> & visiting);

static std::string expandMacroValue(const std::string & name,
    const std::unordered_map<std::string, std::string> & macros,
    std::unordered_set<std::string> & visiting);

}  // namespace pre_wgsl

I/O Contract

Inputs

• WGSL template text -- Shader source with preprocessor directives
• Options -- Include path and predefined macro list
• Include files -- Referenced WGSL files for #include

Outputs

• Processed WGSL -- Clean WGSL code with all macros expanded and conditionals resolved

Usage Examples

Conditional shader compilation:

// Input WGSL template:
// #ifdef USE_F16
// var<workgroup> shared_data: array<f16, 256>;
// #else
// var<workgroup> shared_data: array<f32, 128>;
// #endif

pre_wgsl::Options opts;
opts.macros.push_back("USE_F16");
pre_wgsl::Preprocessor pp(opts);
std::string result = pp.process(template_wgsl);
// Result contains the f16 variant

Related Pages

Implements Principle

• Principle:Ggml_org_Ggml_WebGPU_Computation

Related Implementations

• Implementation:Ggml_org_Ggml_Webgpu_shader_lib -- Shader library using this preprocessor
• Implementation:Ggml_org_Ggml_Webgpu_backend -- Main WebGPU backend