WebGPU static plugin EP

.github/workflows/android.yml

@@ -79,8 +79,9 @@ jobs:
       run: |
         set -e -x
         BINARY_SIZE_THRESHOLD_ARGS=""
-        echo "Binary size threshold in bytes: 1599488"
-        BINARY_SIZE_THRESHOLD_ARGS="--threshold_size_in_bytes 1599488"
+        BINARY_SIZE_THRESHOLD_IN_BYTES=1601536
+        echo "Binary size threshold in bytes: ${BINARY_SIZE_THRESHOLD_IN_BYTES}"
+        BINARY_SIZE_THRESHOLD_ARGS="--threshold_size_in_bytes ${BINARY_SIZE_THRESHOLD_IN_BYTES}"
 
         # Ensure ANDROID_NDK_HOME is available and get its real path
         if [ -z "$ANDROID_NDK_HOME" ]; then

.github/workflows/linux-wasm-ci-build-and-test-workflow.yml

@@ -34,6 +34,10 @@ on:
         required: false
         type: boolean
         default: false
+      build_webgpu_static_plugin:
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-wasm:
@@ -159,6 +163,24 @@ jobs:
             --skip_tests
         working-directory: ${{ github.workspace }}
 
+      # Build-only coverage for registering the WebGPU EP as a statically linked plugin EP under Emscripten.
+      # The output is deliberately not published: it has the same file names as the published WebGPU build, and
+      # the ORT Web test harness selects the wasm binary by file name, so both variants cannot ship together.
+      # This leg becomes redundant once the published WebGPU wasm build switches over to the plugin EP.
+      - name: Build (simd + threads + WebGPU experimental, static plugin EP)
+        if: ${{ inputs.build_webgpu_static_plugin == true }}
+        run: |
+          python ./tools/ci_build/build.py \
+            ${{ env.common_build_args }} \
+            --build_dir ${{ github.workspace }}/build/wasm_inferencing_webgpu_static_plugin \
+            --use_webgpu static_plugin \
+            --use_webnn \
+            --target onnxruntime_webassembly \
+            ${{ inputs.build_config == 'Release' && '--enable_wasm_api_exception_catching' || '' }} \
+            ${{ env.reduced_size_build_args }} \
+            --skip_tests
+        working-directory: ${{ github.workspace }}
+
       - name: Create Artifacts
         if: ${{ inputs.skip_publish != true }}
         run: |

.github/workflows/linux_webgpu.yml

@@ -37,6 +37,28 @@ jobs:
     secrets:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Pass token for reusable workflow needs (e.g., docker build action)
 
+  # Builds the same WebGPU plugin EP sources linked into the ORT binary rather than as a separate
+  # shared library. Build-only, like the job above; this exists mainly to compile the static plugin
+  # configuration with GCC as well as MSVC. See docs/design/webgpu_ep_extraction/
+  # plugin_boundary_and_web_integration/static_plugin_ep_registration_design.md
+  build-linux-webgpu-static-plugin-x64-release:
+    name: Build Linux WebGPU Static Plugin x64 Release
+    uses: ./.github/workflows/reusable_linux_build.yml
+    with:
+      pool_name: "onnxruntime-github-Ubuntu2204-AMD-CPU" # Build pool
+      build_config: Release
+      architecture: x64
+      dockerfile_path: tools/ci_build/github/linux/docker/Dockerfile.manylinux2_28_webgpu
+      docker_image_repo: onnxruntimecpubuildpythonx64
+      extra_build_flags: '--use_binskim_compliant_compile_flags --build_wheel --use_webgpu static_plugin --cmake_extra_defines onnxruntime_BUILD_UNIT_TESTS=ON'
+      python_path_prefix: 'PATH=/opt/python/cp310-cp310/bin:$PATH'
+      run_tests: false
+      upload_build_output: false
+      execution_providers: 'webgpu'
+      job_identifier: build-linux-webgpu-static-plugin-x64-release
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Pass token for reusable workflow needs (e.g., docker build action)
+
   # TODO: the following test step is currently failing. Need to fix and re-enable it
 
   # test-linux-webgpu-x64-release:

.github/workflows/web.yml

@@ -56,6 +56,7 @@ jobs:
       extra_build_args: "--target onnxruntime_webassembly --skip_tests --disable_rtti"
       build_jsep: true
       build_webgpu: true
+      build_webgpu_static_plugin: true
 
   wasm_Release_static_library:
     needs: precheck

.github/workflows/windows_webgpu.yml

@@ -442,6 +442,77 @@ jobs:
             exit $lastExitCode
           }
 
+  # Same plugin EP sources as webgpu_plugin_build_x64_RelWithDebInfo, but linked into the ORT binary
+  # instead of built as a separate shared library.
+  webgpu_static_plugin_build_x64_RelWithDebInfo:
+    runs-on: [
+      "self-hosted",
+      "1ES.Pool=onnxruntime-github-Win2022-GPU-A10",
+      "JobId=webgpu_static_plugin_build_x64_RelWithDebInfo-${{ github.run_id }}-${{ github.run_number }}-${{ github.run_attempt }}"
+      ]
+    timeout-minutes: 300
+    env:
+      OnnxRuntimeBuildDirectory: ${{ github.workspace }}
+      setVcvars: true
+      ALLOW_RELEASED_ONNX_OPSET_ONLY: "0"
+      DocUpdateNeeded: false
+      NVIDIA_TF32_OVERRIDE: "0"
+      ONNXRUNTIME_TEST_GPU_DEVICE_ID: "0"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          submodules: none
+
+      - name: Setup Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          architecture: x64
+
+      - name: Locate vcvarsall and Setup Env
+        uses: ./.github/actions/locate-vcvarsall-and-setup-env
+        with:
+          architecture: x64
+
+      - name: Install python modules
+        run: python -m pip install -r tools\ci_build\github\windows\python\requirements.txt
+        shell: cmd
+        working-directory: ${{ github.workspace }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20.x"
+
+      - uses: actions/cache@v5
+        id: onnx-node-tests-cache
+        with:
+          path: ${{ github.workspace }}/js/test/
+          key: onnxnodetests-${{ hashFiles('js/scripts/prepare-onnx-node-tests.ts') }}
+
+      # onnxruntime_BUILD_DAWN_SHARED_LIBRARY is deliberately not enabled here. It is incompatible with
+      # onnxruntime_USE_EP_API_ADAPTERS, which --use_webgpu static_plugin turns on.
+      - name: Build and Test
+        shell: pwsh
+        run: |
+          python.exe ${{ github.workspace }}\tools\ci_build\build.py `
+            --config RelWithDebInfo `
+            --build_dir ${{ github.workspace }} `
+            --skip_submodule_sync `
+            --parallel `
+            --use_binskim_compliant_compile_flags `
+            --cmake_generator "Visual Studio 17 2022" `
+            --enable_onnx_tests `
+            --use_webgpu static_plugin `
+            --use_vcpkg --use_vcpkg_ms_internal_asset_cache `
+            --cmake_extra_defines onnxruntime_BUILD_UNIT_TESTS=ON onnxruntime_ENABLE_DAWN_BACKEND_D3D12=1 onnxruntime_ENABLE_DAWN_BACKEND_VULKAN=1
+
+          if ($lastExitCode -ne 0) {
+            exit $lastExitCode
+          }
+
   webgpu_external_dawn_build_x64_RelWithDebInfo:
     runs-on: [
         "self-hosted",

cmake/CMakeLists.txt

@@ -180,7 +180,8 @@ option(onnxruntime_USE_CANN "Build with CANN support" OFF)
 option(onnxruntime_USE_XNNPACK "Build with XNNPACK support. Provides an alternative math library on ARM, WebAssembly and x86." OFF)
 option(onnxruntime_USE_WEBNN "Build with WebNN support. Enable hardware acceleration in web browsers." OFF)
 option(onnxruntime_USE_WEBGPU "Build with WebGPU support. Enable WebGPU via C/C++ interface." OFF)
-option(onnxruntime_USE_EP_API_ADAPTERS "Build EP (e.g. WebGPU) as a plugin EP shared library using EP API adapters" OFF)
+option(onnxruntime_USE_EP_API_ADAPTERS "Build EP (e.g. WebGPU) as a plugin EP library using EP API adapters" OFF)
+option(onnxruntime_WEBGPU_STATIC_PLUGIN "Build the WebGPU plugin EP into the ORT binary instead of a separate shared library. Requires onnxruntime_USE_EP_API_ADAPTERS." OFF)
 option(onnxruntime_USE_EXTERNAL_DAWN "Build with treating Dawn as external dependency. Will not link Dawn at build time." OFF)
 option(onnxruntime_CUSTOM_DAWN_SRC_PATH "Path to custom Dawn src dir.")
 set(onnxruntime_DAWN_PREBUILT_DIR "" CACHE PATH "Directory containing Dawn headers and standalone proc sources for external Dawn")
@@ -456,6 +457,34 @@ if(onnxruntime_USE_EP_API_ADAPTERS)
   add_compile_definitions(ORT_USE_EP_API_ADAPTERS=1)
 endif()
 
+# The WebGPU plugin EP can either be a separate shared library or be linked into the ORT binary. In the latter case
+# ORT core registers it at OrtEnv creation time instead of the application loading it by path.
+if(onnxruntime_WEBGPU_STATIC_PLUGIN)
+  if(NOT onnxruntime_USE_WEBGPU)
+    message(FATAL_ERROR "onnxruntime_WEBGPU_STATIC_PLUGIN=ON requires onnxruntime_USE_WEBGPU=ON.")
+  endif()
+  if(NOT onnxruntime_USE_EP_API_ADAPTERS)
+    message(FATAL_ERROR "onnxruntime_WEBGPU_STATIC_PLUGIN=ON requires onnxruntime_USE_EP_API_ADAPTERS=ON.")
+  endif()
+  # A minimal build excludes core/session/plugin_ep, so the registration that a static plugin EP depends on is not
+  # compiled in. Without this check the EP would be linked into the binary but never registered, with no diagnostic
+  # at configure, build or run time. Supporting the combination is possible but requires making the plugin EP
+  # registration available to minimal builds first.
+  if(onnxruntime_MINIMAL_BUILD)
+    message(FATAL_ERROR "onnxruntime_WEBGPU_STATIC_PLUGIN=ON is not supported in a minimal build: the plugin EP "
+                        "registration in core/session/plugin_ep is excluded, so the EP would be linked in but "
+                        "never registered.")
+  endif()
+  add_compile_definitions(ORT_WEBGPU_STATIC_PLUGIN=1)
+endif()
+
+# True when the WebGPU EP is compiled into the ORT binary rather than built as a separate shared library.
+if(onnxruntime_USE_WEBGPU AND (NOT onnxruntime_USE_EP_API_ADAPTERS OR onnxruntime_WEBGPU_STATIC_PLUGIN))
+  set(onnxruntime_WEBGPU_LINKED_INTO_HOST ON)
+else()
+  set(onnxruntime_WEBGPU_LINKED_INTO_HOST OFF)
+endif()
+
 # General C# properties
 if (onnxruntime_BUILD_CSHARP)
   check_language(CSharp)

cmake/onnxruntime.cmake

@@ -256,7 +256,7 @@ if (onnxruntime_BUILD_QNN_EP_STATIC_LIB)
   list(APPEND onnxruntime_INTERNAL_PROVIDER_LIBRARIES onnxruntime_providers_qnn)
 endif()
 
-if (onnxruntime_USE_WEBGPU AND NOT onnxruntime_USE_EP_API_ADAPTERS)
+if (onnxruntime_WEBGPU_LINKED_INTO_HOST)
   list(APPEND onnxruntime_INTERNAL_PROVIDER_LIBRARIES onnxruntime_providers_webgpu)
 endif()
 

cmake/onnxruntime_common.cmake

@@ -104,6 +104,9 @@ elseif (LINUX)
 elseif (APPLE)
     list(APPEND onnxruntime_common_src_patterns
          "${ONNXRUNTIME_ROOT}/core/platform/apple/device_discovery.cc")
+elseif (CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
+    list(APPEND onnxruntime_common_src_patterns
+         "${ONNXRUNTIME_ROOT}/core/platform/emscripten/device_discovery.cc")
 else()
     list(APPEND onnxruntime_common_src_patterns
          "${ONNXRUNTIME_ROOT}/core/platform/device_discovery_default.cc")

cmake/onnxruntime_providers_webgpu.cmake

@@ -25,7 +25,7 @@
 
   if(NOT onnxruntime_USE_EP_API_ADAPTERS)
     #
-    # Build WebGPU EP as a static library
+    # Build WebGPU EP as an internal (non-plugin) static library
     #
 
     # For static library build, exclude the 'ep' folder
@@ -39,6 +39,24 @@
     onnxruntime_add_static_library(onnxruntime_providers_webgpu ${onnxruntime_providers_webgpu_cc_srcs})
     onnxruntime_add_include_to_target(onnxruntime_providers_webgpu
       onnxruntime_common onnx onnx_proto flatbuffers::flatbuffers Boost::mp11 safeint_interface)
+  elseif(onnxruntime_WEBGPU_STATIC_PLUGIN)
+    #
+    # Build WebGPU EP as a plugin EP that is statically linked into the ORT binary.
+    #
+    # This uses the same plugin EP sources ('ep' folder) and EP API adapters as the shared library build below.
+    # The difference is only in how the EP reaches the application: ORT core registers it at OrtEnv creation time
+    # instead of the application calling RegisterExecutionProviderLibrary() with a library path.
+    #
+    source_group(TREE ${ONNXRUNTIME_ROOT} FILES ${onnxruntime_providers_webgpu_cc_srcs})
+    onnxruntime_add_static_library(onnxruntime_providers_webgpu ${onnxruntime_providers_webgpu_cc_srcs})
+    onnxruntime_add_include_to_target(onnxruntime_providers_webgpu
+      onnxruntime_common onnx onnx_proto flatbuffers::flatbuffers Boost::mp11 safeint_interface)
+
+    # ORT_PLUGIN_EP_SKIP_API_MANUAL_INIT tells the shared plugin EP headers that OrtGetApiBase() is available
+    # in-process, so the C++ API must not be built with ORT_API_MANUAL_INIT (the rest of the binary is not).
+    target_compile_definitions(onnxruntime_providers_webgpu PRIVATE
+                               ORT_PLUGIN_EP_STATICALLY_LINKED=1
+                               ORT_PLUGIN_EP_SKIP_API_MANUAL_INIT=1)
   else()
     #
     # Build WebGPU EP as a shared library
@@ -77,27 +95,6 @@
     add_definitions("-DONNX_NAMESPACE=onnx")
     add_definitions("-DONNX_USE_LITE_PROTO=1")
 
-    # Default plugin EP version to ORT_VERSION with "-dev" suffix if not explicitly provided.
-    if(NOT DEFINED onnxruntime_PLUGIN_EP_VERSION)
-      set(onnxruntime_PLUGIN_EP_VERSION "${ORT_VERSION}-dev")
-    endif()
-
-    # Set preprocessor definition for plugin EP version
-    target_compile_definitions(onnxruntime_providers_webgpu PRIVATE
-                               ORT_PLUGIN_EP_VERSION="${onnxruntime_PLUGIN_EP_VERSION}")
-
-    # Bake the minimum compatible ORT version (the single source of truth lives in
-    # plugin-ep-webgpu/MIN_ONNXRUNTIME_VERSION) into the EP DLL so it can be enforced at runtime.
-    # Format is strict "MAJOR.MINOR.PATCH".
-    set(_ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION_FILE "${REPO_ROOT}/plugin-ep-webgpu/MIN_ONNXRUNTIME_VERSION")
-    file(STRINGS "${_ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION_FILE}" _ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION LIMIT_COUNT 1)
-    if(NOT _ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION)
-      message(FATAL_ERROR "WebGPU plugin EP minimum ORT version file is missing or empty: "
-                          "${_ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION_FILE}")
-    endif()
-    target_compile_definitions(onnxruntime_providers_webgpu PRIVATE
-                               ORT_PLUGIN_EP_MIN_ORT_VERSION="${_ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION}")
-
     # Set preprocessor definitions used in onnxruntime_providers_webgpu.rc
     if(WIN32)
       set(WEBGPU_DLL_FILE_DESCRIPTION "ONNX Runtime WebGPU Provider")
@@ -131,14 +128,50 @@
       message(FATAL_ERROR "WebGPU EP shared library build does not support build cache. Please disable build cache or use static library build.")
     endif()
     if (CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
-      message(FATAL_ERROR "WebGPU EP shared library build is not supported on Emscripten. Please use static library build.")
+      message(FATAL_ERROR "WebGPU EP shared library build is not supported on Emscripten. Please use '--use_webgpu static_plugin'.")
+    endif()
+  endif()
+
+  if (onnxruntime_USE_EP_API_ADAPTERS)
+    #
+    # Settings common to both plugin EP builds (shared library and statically linked).
+    #
+
+    # Default plugin EP version to ORT_VERSION with "-dev" suffix if not explicitly provided.
+    if(NOT DEFINED onnxruntime_PLUGIN_EP_VERSION)
+      set(onnxruntime_PLUGIN_EP_VERSION "${ORT_VERSION}-dev")
     endif()
 
-    # Configure precompiled headers for shared library build
-    # PCH ensures ep/adapters.h is included first and improves compilation speed
+    # Set preprocessor definition for plugin EP version
+    target_compile_definitions(onnxruntime_providers_webgpu PRIVATE
+                               ORT_PLUGIN_EP_VERSION="${onnxruntime_PLUGIN_EP_VERSION}")
+
+    # Bake the minimum compatible ORT version (the single source of truth lives in
+    # plugin-ep-webgpu/MIN_ONNXRUNTIME_VERSION) into the EP so it can be enforced at runtime.
+    # Format is strict "MAJOR.MINOR.PATCH".
+    set(_ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION_FILE "${REPO_ROOT}/plugin-ep-webgpu/MIN_ONNXRUNTIME_VERSION")
+    file(STRINGS "${_ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION_FILE}" _ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION LIMIT_COUNT 1)
+    if(NOT _ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION)
+      message(FATAL_ERROR "WebGPU plugin EP minimum ORT version file is missing or empty: "
+                          "${_ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION_FILE}")
+    endif()
+    target_compile_definitions(onnxruntime_providers_webgpu PRIVATE
+                               ORT_PLUGIN_EP_MIN_ORT_VERSION="${_ORT_PLUGIN_EP_WEBGPU_MIN_ORT_VERSION}")
+
+    # Configure precompiled headers for the plugin EP build.
+    # PCH ensures ep/adapters.h is included first and improves compilation speed.
     target_precompile_headers(onnxruntime_providers_webgpu PRIVATE
       "${REPO_ROOT}/include/onnxruntime/ep/adapters.h"
     )
+
+    # Suppress -Werror=maybe-uninitialized. The EP adapter types are defined entirely inline in headers,
+    # so GCC sees through the failure and exception paths of accessors like OpKernelInfo::GetAttr<> and
+    # falsely warns about values that are only read once the call has succeeded. It also produces false
+    # positives deep inside absl::InlinedVector for locals that are always constructed.
+    # This mirrors the same suppression on the CUDA plugin EP target.
+    target_compile_options(onnxruntime_providers_webgpu PRIVATE
+      $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:GNU>>:-Wno-maybe-uninitialized>
+    )
   endif()
 
   set_target_properties(onnxruntime_providers_webgpu PROPERTIES CXX_STANDARD_REQUIRED ON)
@@ -261,13 +294,14 @@
       endif()
     endif()
 
-    # In the plugin/adapter build (onnxruntime_USE_EP_API_ADAPTERS) the WebGPU EP is its own DLL
-    # (onnxruntime_providers_webgpu.dll) rather than being statically linked into onnxruntime.dll, so the
+    # In the plugin EP shared library build the WebGPU EP is its own DLL
+    # (onnxruntime_providers_webgpu.dll) rather than being linked into onnxruntime.dll, so the
     # delay-load flags accumulated above (notably /DELAYLOAD:user32.dll) must be applied to THIS target.
     # Without it the DLL keeps a static import on user32.dll and fails to load in a Win32k-lockdown sandbox
     # (e.g. Chromium's WebNN compiler process): 'depends on "USER32.dll" which is missing' (Error 1359).
-    # In the static build these same flags are applied to the onnxruntime target in onnxruntime.cmake.
-    if (WIN32 AND onnxruntime_USE_EP_API_ADAPTERS AND onnxruntime_DELAYLOAD_FLAGS)
+    # When the EP is linked into the ORT binary these same flags are applied to the onnxruntime target in
+    # onnxruntime.cmake.
+    if (WIN32 AND NOT onnxruntime_WEBGPU_LINKED_INTO_HOST AND onnxruntime_DELAYLOAD_FLAGS)
       target_link_options(onnxruntime_providers_webgpu PRIVATE ${onnxruntime_DELAYLOAD_FLAGS})
       target_link_libraries(onnxruntime_providers_webgpu PRIVATE delayimp.lib)
     endif()

cmake/onnxruntime_python.cmake

@@ -213,7 +213,7 @@ set(onnxruntime_pybind11_state_static_providers
 if(onnxruntime_BUILD_QNN_EP_STATIC_LIB)
   list(APPEND onnxruntime_pybind11_state_static_providers PRIVATE onnxruntime_providers_qnn)
 endif()
-if(onnxruntime_USE_WEBGPU AND NOT onnxruntime_USE_EP_API_ADAPTERS)
+if(onnxruntime_WEBGPU_LINKED_INTO_HOST)
   list(APPEND onnxruntime_pybind11_state_static_providers PRIVATE onnxruntime_providers_webgpu)
 endif()
 if(WIN32)