Initial change to enable WebGPU EP to suport plugin API (#25705)

### Description

This is the first PR among a list of PRs to make WebGPU EP able to use
the plugin API (EP ABI).

This PR adds new build flags for WebGPU:
- `--use_webgpu shared_lib` to enable building WebGPU EP based on the
plugin API (EP ABI).
- keep `--use_webgpu` or `--use_webgpu static_lib` behavior no change.

Currently `--use_webgpu shared_lib` will fail, but it is fine because no
one is using it.

#### Why making small changes

Huge PR is very difficult to review. Splitting a huge PR into multiple
ones has the benefits that each small PR is relatively easier to review.

#### Plan

- [x] STEP.1 - Introduce build flags (this PR)
- [ ] STEP.2 - Changes some macros and util functions to support both
static and shared
- [ ] STEP.3 - Core implementation of EP API based WebGPU EP
- [ ] STEP.4 - Builds/Tests/etc.

Author: fs-eire

cmake/CMakeLists.txt

@@ -142,6 +142,7 @@ option(onnxruntime_USE_XNNPACK "Build with XNNPACK support. Provides an alternat
 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_WGSL_TEMPLATE "Specify the code generator for WGSL template. Default is static." "static")
+option(onnxruntime_BUILD_WEBGPU_EP_STATIC_LIB "Build WebGPU EP as a static library" 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.")
 option(onnxruntime_BUILD_DAWN_SHARED_LIBRARY "Build Dawn as a shared library" OFF)
@@ -978,8 +979,13 @@ if (onnxruntime_USE_WEBGPU)
   endif()
 
   if (onnxruntime_BUILD_DAWN_SHARED_LIBRARY)
-    list(APPEND ORT_PROVIDER_FLAGS -DBUILD_DAWN_SHARED_LIBRARY=1)
+    if (onnxruntime_BUILD_WEBGPU_EP_STATIC_LIB)
+      list(APPEND ORT_PROVIDER_FLAGS -DBUILD_DAWN_SHARED_LIBRARY=1)
+    else()
+      message(FATAL_ERROR "onnxruntime_BUILD_WEBGPU_EP_STATIC_LIB=OFF is not supported with onnxruntime_BUILD_DAWN_SHARED_LIBRARY=ON")
+    endif()
   endif()
+
   if (onnxruntime_USE_EXTERNAL_DAWN)
     list(APPEND ORT_PROVIDER_FLAGS -DUSE_EXTERNAL_DAWN=1)
   endif()

cmake/onnxruntime.cmake

@@ -225,7 +225,6 @@ set(onnxruntime_INTERNAL_PROVIDER_LIBRARIES
   ${PROVIDERS_RKNPU}
   ${PROVIDERS_VSINPU}
   ${PROVIDERS_XNNPACK}
-  ${PROVIDERS_WEBGPU}
   ${PROVIDERS_WEBNN}
   ${PROVIDERS_AZURE}
   ${PROVIDERS_INTERNAL_TESTING}
@@ -235,6 +234,10 @@ if (onnxruntime_BUILD_QNN_EP_STATIC_LIB)
   list(APPEND onnxruntime_INTERNAL_PROVIDER_LIBRARIES onnxruntime_providers_qnn)
 endif()
 
+if (onnxruntime_BUILD_WEBGPU_EP_STATIC_LIB)
+  list(APPEND onnxruntime_INTERNAL_PROVIDER_LIBRARIES onnxruntime_providers_webgpu)
+endif()
+
 # This list is a reversed topological ordering of library dependencies.
 # Earlier entries may depend on later ones. Later ones should not depend on earlier ones.
 set(onnxruntime_INTERNAL_LIBRARIES

cmake/onnxruntime_providers_webgpu.cmake

@@ -6,6 +6,10 @@
   endif()
 
   add_compile_definitions(USE_WEBGPU=1)
+  if(onnxruntime_BUILD_WEBGPU_EP_STATIC_LIB)
+    add_compile_definitions(BUILD_WEBGPU_EP_STATIC_LIB=1)
+  endif()
+
   if (onnxruntime_ENABLE_WEBASSEMBLY_THREADS)
     add_definitions(-DENABLE_WEBASSEMBLY_THREADS=1)
   endif()
@@ -20,20 +24,108 @@
   elseif (NOT onnxruntime_WGSL_TEMPLATE STREQUAL "static")
     message(FATAL_ERROR "Unsupported value for onnxruntime_WGSL_TEMPLATE: ${onnxruntime_WGSL_TEMPLATE}. Supported values are 'static' or 'dynamic'.")
   endif()
+
   file(GLOB_RECURSE onnxruntime_providers_webgpu_cc_srcs CONFIGURE_DEPENDS
     "${ONNXRUNTIME_ROOT}/core/providers/webgpu/*.h"
     "${ONNXRUNTIME_ROOT}/core/providers/webgpu/*.cc"
   )
   if(NOT onnxruntime_DISABLE_CONTRIB_OPS)
-    source_group(TREE ${ONNXRUNTIME_ROOT} FILES ${onnxruntime_webgpu_contrib_ops_cc_srcs})
     list(APPEND onnxruntime_providers_webgpu_cc_srcs ${onnxruntime_webgpu_contrib_ops_cc_srcs})
   endif()
 
-  source_group(TREE ${REPO_ROOT} FILES ${onnxruntime_providers_webgpu_cc_srcs})
-  onnxruntime_add_static_library(onnxruntime_providers_webgpu ${onnxruntime_providers_webgpu_cc_srcs})
-  target_compile_features(onnxruntime_providers_webgpu PRIVATE cxx_std_20)
-  onnxruntime_add_include_to_target(onnxruntime_providers_webgpu
-    onnxruntime_common onnx onnx_proto flatbuffers::flatbuffers Boost::mp11 safeint_interface)
+  if(onnxruntime_BUILD_WEBGPU_EP_STATIC_LIB)
+    #
+    # Build WebGPU EP as a static library
+    #
+
+    # For static library build, exclude the 'ep' folder
+    file(GLOB_RECURSE ep_files_to_exclude
+      "${ONNXRUNTIME_ROOT}/core/providers/webgpu/ep/*.h"
+      "${ONNXRUNTIME_ROOT}/core/providers/webgpu/ep/*.cc"
+    )
+    list(REMOVE_ITEM onnxruntime_providers_webgpu_cc_srcs ${ep_files_to_exclude})
+
+    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)
+  else()
+    #
+    # Build WebGPU EP as a shared library
+    #
+    if(WIN32)
+      # Sets the DLL version info on Windows: https://learn.microsoft.com/en-us/windows/win32/menurc/versioninfo-resource
+      list(APPEND onnxruntime_providers_webgpu_cc_srcs "${ONNXRUNTIME_ROOT}/core/providers/webgpu/ep/versioninfo.rc")
+    endif()
+    source_group(TREE ${ONNXRUNTIME_ROOT} FILES ${onnxruntime_providers_webgpu_cc_srcs})
+
+    onnxruntime_add_shared_library(onnxruntime_providers_webgpu ${onnxruntime_providers_webgpu_cc_srcs})
+    onnxruntime_add_include_to_target(onnxruntime_providers_webgpu
+        ${REPO_ROOT}/include/onnxruntime/core/session
+        onnxruntime_common
+        onnx
+        onnx_proto
+        flatbuffers::flatbuffers
+        Boost::mp11
+        safeint_interface)
+
+    target_link_libraries(onnxruntime_providers_webgpu PRIVATE
+        onnxruntime_optimizer
+        onnxruntime_providers
+        onnxruntime_lora
+        onnxruntime_framework
+        onnxruntime_graph
+        onnxruntime_util
+        ${ONNXRUNTIME_MLAS_LIBS}
+        onnxruntime_common
+        onnxruntime_flatbuffers
+        ${onnxruntime_EXTERNAL_LIBRARIES}
+    )
+
+    # Add ONNX compiler definitions
+    add_definitions("-DONNX_ML=1")
+    add_definitions("-DONNX_NAMESPACE=onnx")
+    add_definitions("-DONNX_USE_LITE_PROTO=1")
+
+    # Set preprocessor definitions used in onnxruntime_providers_webgpu.rc
+    if(WIN32)
+      set(WEBGPU_DLL_FILE_DESCRIPTION "ONNX Runtime WebGPU Provider")
+
+      target_compile_definitions(onnxruntime_providers_webgpu PRIVATE FILE_DESC=\"${WEBGPU_DLL_FILE_DESCRIPTION}\")
+      target_compile_definitions(onnxruntime_providers_webgpu PRIVATE FILE_NAME=\"onnxruntime_providers_webgpu.dll\")
+    endif()
+
+    # Set linker flags for function(s) exported by EP DLL
+    if(UNIX)
+      if (APPLE)
+        set_property(TARGET onnxruntime_providers_webgpu APPEND_STRING PROPERTY LINK_FLAGS
+                     "-Xlinker -dead_strip")
+      elseif (NOT CMAKE_SYSTEM_NAME MATCHES "AIX")
+        target_link_options(onnxruntime_providers_webgpu PRIVATE
+                            "LINKER:--version-script=${ONNXRUNTIME_ROOT}/core/providers/webgpu/ep/version_script.lds"
+                            "LINKER:--gc-sections"
+                            "LINKER:-rpath=\$ORIGIN")
+        # TODO: -z noexecstack
+      endif()
+    elseif(WIN32)
+      set_property(TARGET onnxruntime_providers_webgpu APPEND_STRING PROPERTY LINK_FLAGS
+                   "-DEF:${ONNXRUNTIME_ROOT}/core/providers/webgpu/ep/symbols.def")
+    else()
+      message(FATAL_ERROR "onnxruntime_providers_webgpu unknown platform, need to specify shared library exports for it")
+    endif()
+
+    set_target_properties(onnxruntime_providers_webgpu PROPERTIES LINKER_LANGUAGE CXX)
+
+    if (onnxruntime_BUILD_CACHE)
+      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.")
+    endif()
+  endif()
+
+  set_target_properties(onnxruntime_providers_webgpu PROPERTIES CXX_STANDARD_REQUIRED ON)
+  set_target_properties(onnxruntime_providers_webgpu PROPERTIES FOLDER "ONNXRuntime")
 
   if (CMAKE_SYSTEM_NAME STREQUAL "Emscripten")
     # target "emdawnwebgpu_c" is created by Dawn, including "-fno-exceptions" in its compile options by default.
@@ -89,7 +181,7 @@
     set(onnxruntime_providers_webgpu_dll_deps)
 
     if (onnxruntime_BUILD_DAWN_SHARED_LIBRARY)
-      target_link_libraries(onnxruntime_providers_webgpu dawn::webgpu_dawn)
+      target_link_libraries(onnxruntime_providers_webgpu PUBLIC dawn::webgpu_dawn)
 
       if (WIN32)
         if (onnxruntime_ENABLE_DELAY_LOADING_WIN_DLLS)
@@ -116,9 +208,9 @@
       list(APPEND onnxruntime_providers_webgpu_dll_deps "$<TARGET_FILE:dawn::webgpu_dawn>")
     else()
       if (NOT onnxruntime_USE_EXTERNAL_DAWN)
-        target_link_libraries(onnxruntime_providers_webgpu dawn::dawn_native)
+        target_link_libraries(onnxruntime_providers_webgpu PRIVATE dawn::dawn_native)
       endif()
-      target_link_libraries(onnxruntime_providers_webgpu dawn::dawn_proc)
+      target_link_libraries(onnxruntime_providers_webgpu PRIVATE dawn::dawn_proc)
     endif()
 
     if (WIN32 AND onnxruntime_ENABLE_DAWN_BACKEND_D3D12)
@@ -153,7 +245,8 @@
     endif()
   endif()
 
-  add_dependencies(onnxruntime_providers_webgpu ${onnxruntime_EXTERNAL_DEPENDENCIES})
+  target_compile_features(onnxruntime_providers_webgpu PRIVATE cxx_std_20)
+  add_dependencies(onnxruntime_providers_webgpu onnx ${onnxruntime_EXTERNAL_DEPENDENCIES})
 
   if (onnxruntime_WGSL_TEMPLATE)
     # Define the WGSL templates directory and output directory
@@ -239,7 +332,7 @@
       # Add the generated directory to include paths
       target_include_directories(onnxruntime_providers_webgpu PRIVATE ${WGSL_GENERATED_ROOT})
     elseif(onnxruntime_WGSL_TEMPLATE STREQUAL "dynamic")
-      target_link_libraries(onnxruntime_providers_webgpu duktape_static)
+      target_link_libraries(onnxruntime_providers_webgpu PRIVATE duktape_static)
       onnxruntime_add_include_to_target(onnxruntime_providers_webgpu duktape_static)
 
       # Define the path to the generated templates.js file
@@ -251,4 +344,10 @@
     add_dependencies(onnxruntime_providers_webgpu onnxruntime_webgpu_wgsl_generation)
   endif()
 
-  set_target_properties(onnxruntime_providers_webgpu PROPERTIES FOLDER "ONNXRuntime")
+  if (NOT onnxruntime_BUILD_SHARED_LIB)
+    install(TARGETS onnxruntime_providers_webgpu EXPORT ${PROJECT_NAME}Targets
+            ARCHIVE   DESTINATION ${CMAKE_INSTALL_LIBDIR}
+            LIBRARY   DESTINATION ${CMAKE_INSTALL_LIBDIR}
+            RUNTIME   DESTINATION ${CMAKE_INSTALL_BINDIR}
+            FRAMEWORK DESTINATION ${CMAKE_INSTALL_BINDIR})
+  endif()

cmake/onnxruntime_python.cmake

@@ -192,13 +192,15 @@ set(onnxruntime_pybind11_state_static_providers
     ${PROVIDERS_ACL}
     ${PROVIDERS_ARMNN}
     ${PROVIDERS_XNNPACK}
-    ${PROVIDERS_WEBGPU}
     ${PROVIDERS_AZURE}
 )
 
 if(onnxruntime_BUILD_QNN_EP_STATIC_LIB)
   list(APPEND onnxruntime_pybind11_state_static_providers PRIVATE onnxruntime_providers_qnn)
 endif()
+if(onnxruntime_BUILD_WEBGPU_EP_STATIC_LIB)
+  list(APPEND onnxruntime_pybind11_state_static_providers PRIVATE onnxruntime_providers_webgpu)
+endif()
 if(WIN32)
   # onnxruntime_pybind11_state is a DLL
   target_sources(onnxruntime_pybind11_state PRIVATE "${ONNXRUNTIME_ROOT}/core/dll/dllmain.cc")

cmake/onnxruntime_unittests.cmake

@@ -644,10 +644,6 @@ if(onnxruntime_USE_JSEP)
   list(APPEND onnxruntime_test_providers_dependencies onnxruntime_providers_js)
 endif()
 
-if(onnxruntime_USE_WEBGPU)
-  list(APPEND onnxruntime_test_providers_dependencies onnxruntime_providers_webgpu)
-endif()
-
 if(onnxruntime_USE_RKNPU)
   list(APPEND onnxruntime_test_providers_dependencies onnxruntime_providers_rknpu)
 endif()
@@ -682,7 +678,6 @@ set(ONNXRUNTIME_TEST_STATIC_PROVIDER_LIBS
     ${PROVIDERS_NNAPI}
     ${PROVIDERS_VSINPU}
     ${PROVIDERS_JS}
-    ${PROVIDERS_WEBGPU}
     ${PROVIDERS_SNPE}
     ${PROVIDERS_RKNPU}
     ${PROVIDERS_DML}
@@ -696,6 +691,9 @@ set(ONNXRUNTIME_TEST_STATIC_PROVIDER_LIBS
 if (onnxruntime_BUILD_QNN_EP_STATIC_LIB)
   list(APPEND ONNXRUNTIME_TEST_STATIC_PROVIDER_LIBS onnxruntime_providers_qnn)
 endif()
+if (onnxruntime_BUILD_WEBGPU_EP_STATIC_LIB)
+  list(APPEND ONNXRUNTIME_TEST_STATIC_PROVIDER_LIBS onnxruntime_providers_webgpu)
+endif()
 
 set(ONNXRUNTIME_TEST_LIBS
     onnxruntime_session
@@ -754,7 +752,7 @@ if(onnxruntime_USE_JSEP)
   list(APPEND onnxruntime_test_providers_libs onnxruntime_providers_js)
 endif()
 
-if(onnxruntime_USE_WEBGPU)
+if(onnxruntime_USE_WEBGPU AND onnxruntime_BUILD_WEBGPU_EP_STATIC_LIB)
   list(APPEND onnxruntime_test_framework_src_patterns  ${TEST_SRC_DIR}/providers/webgpu/*)
   list(APPEND onnxruntime_test_providers_dependencies onnxruntime_providers_webgpu)
   list(APPEND onnxruntime_test_providers_libs onnxruntime_providers_webgpu)

onnxruntime/core/dll/delay_load_hook.cc

@@ -21,10 +21,13 @@
 // - https://learn.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order#alternate-search-order-for-unpackaged-apps
 //
 // The DLL DelayLoad hook is only enabled when the compiler is MSVC and at least one of the following is True:
-// - both USE_WEBGPU and BUILD_DAWN_SHARED_LIBRARY are defined
+// - all of the following are defined:
+//   - USE_WEBGPU
+//   - BUILD_WEBGPU_EP_STATIC_LIB
+//   - BUILD_DAWN_SHARED_LIBRARY
 // - USE_DML is defined
 //
-#if defined(USE_WEBGPU) && defined(BUILD_DAWN_SHARED_LIBRARY)
+#if defined(USE_WEBGPU) && defined(BUILD_WEBGPU_EP_STATIC_LIB) && defined(BUILD_DAWN_SHARED_LIBRARY)
 #define ORT_DELAY_LOAD_WEBGPU_DAWN_DLL 1
 #else
 #define ORT_DELAY_LOAD_WEBGPU_DAWN_DLL 0

onnxruntime/core/providers/get_execution_providers.cc

@@ -158,7 +158,7 @@ constexpr ProviderInfo kProvidersInPriorityOrder[] =
         },
         {
             kWebGpuExecutionProvider,
-#ifdef USE_WEBGPU
+#if defined(USE_WEBGPU) && defined(BUILD_WEBGPU_EP_STATIC_LIB)
             true,
 #else
             false,

onnxruntime/core/providers/webgpu/ep/README.md

@@ -0,0 +1,30 @@
+## The `ep` folder
+
+The current folder contains the implementation of EP ABI adapter for WebGPU.
+
+### Design considerations
+
+To ensure both static library and dynamic library builds work, we need to make as few changes to existing code as possible. A few design decisions are as below:
+
+- No changes to static library build. It should still work as before.
+
+- For dynamic library:
+
+  - use and only use the EP ABI. (no support for `GetProvider`)
+
+  - still depends on onnxruntime targets.
+
+  - use a bridge to connect EP ABI and the internal classes
+
+### Missing parts
+
+This section describes what is missing.
+
+- need a way to do WebGPU cleanup (`OrtEnv::~OrtEnv()` currently calls `webgpu::CleanupWebGpuContexts()` in static lib build)
+
+- need a way to setup "default configurations" for WebGPU. (currently missing for both static lib and shared lib)
+  - we want something like `SetCurrentGpuDeviceId` in ORT C-API, which set a global state and is directly available to user.
+    - to make it general, it can be something like:
+      ```c++
+      ORT_API2_STATUS(SetEpDefaultConfig, _In_ const char* ep_name, _In_ const char* key, _In_ const char* value);
+      ```

onnxruntime/core/providers/webgpu/ep/symbols.def

@@ -0,0 +1,4 @@
+LIBRARY "onnxruntime_providers_webgpu.dll"
+EXPORTS
+ CreateEpFactories @1
+ ReleaseEpFactory @2

onnxruntime/core/providers/webgpu/ep/version_script.lds

@@ -0,0 +1,7 @@
+VERS_1.0.0 {
+ global:
+  CreateEpFactories;
+  ReleaseEpFactory;
+ local:
+    *;
+};