emscripten-core · kainino0x · May 22, 2025 · Apr 30, 2025 · May 20, 2025 · May 20, 2025
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -23,6 +23,13 @@ See docs/process.md for more on how version tagging works.
 - The `-sASYNCIFY_LAZY_LOAD_CODE` setting was deprecated.  This setting was
   added as an experiment a long time ago and as far we know has no active users.
   In addition, it cannot work with JSPI (the future of ASYNCIFY). (#24383)
+- `-sUSE_WEBGPU` was deprecated in favor of the external port Emdawnwebgpu, a
+  fork of Emscripten's original bindings, implementing a newer, more stable
+  version of the standardized `webgpu.h` interface. Please try migrating using
+  `--use-port=emdawnwebgpu`. If you find issues, verify in the [latest
+  nightly release](https://github.com/google/dawn/releases) and file feedback
+  with Dawn. (Emdawnwebgpu is maintained as part of Dawn, the open-source
+  WebGPU implementation used by Chromium, but it is still cross-browser.)
 
 4.0.9 - 05/19/25
 ----------------

diff --git a/site/source/docs/tools_reference/settings_reference.rst b/site/source/docs/tools_reference/settings_reference.rst
@@ -880,7 +880,12 @@ Default value: false
 USE_WEBGPU
 ==========
 
-Enables support for WebGPU (via "webgpu/webgpu.h").
+Enables the built-in implementation of ``<webgpu/webgpu.h>``.
+Deprecated: Please try migrating to ``--use-port=emdawnwebgpu``,
+which implements a newer, incompatible version of webgpu.h (see
+tools/ports/emdawnwebgpu.py for more info).
+
+.. note:: This setting is deprecated
 
 Default value: false
 

diff --git a/src/lib/libwebgpu.js b/src/lib/libwebgpu.js
@@ -7,9 +7,8 @@
 /*
  * WebGPU support.
  *
- * IMPORTANT NOTICE:
- * These bindings are in a temporary **breaking-change freeze**.
- * Bugfixes and small feature additions are still welcome.
+ * **IMPORTANT NOTICE:**
+ * These bindings are **deprecated and unmaintained** and will be removed.
  * Please see system/include/webgpu/README.md for more information.
  *
  * This file and system/lib/webgpu/webgpu.cpp together implement the

diff --git a/src/settings.js b/src/settings.js
@@ -572,8 +572,12 @@ var GL_FFP_ONLY = false;
 // [link]
 var GL_PREINITIALIZED_CONTEXT = false;
 
-// Enables support for WebGPU (via "webgpu/webgpu.h").
+// Enables the built-in implementation of ``<webgpu/webgpu.h>``.
+// Deprecated: Please try migrating to ``--use-port=emdawnwebgpu``,
+// which implements a newer, incompatible version of webgpu.h (see
+// tools/ports/emdawnwebgpu.py for more info).
 // [link]
+// [deprecated]
 var USE_WEBGPU = false;
 
 // Enables building of stb-image, a tiny public-domain library for decoding

diff --git a/system/include/webgpu/README.md b/system/include/webgpu/README.md
@@ -1,74 +1,17 @@
-## Important Notice
-
-Emscripten's WebGPU bindings are in a temporary **breaking-change freeze**.
-Bugfixes and small feature additions are still welcome.
-
-Stable headers are being developed in [webgpu-headers](https://github.com/webgpu-native/webgpu-headers)
-but will require a number of breaking changes relative to Emscripten's current implementation.
-Instead of constantly landing incremental breaking changes in Emscripten, the Dawn project
-(native C++ implementation of webgpu.h) has forked Emscripten's bindings to do these incremental
-changes, before upstreaming all of the changes at once back into Emscripten.
-See [emdawnwebgpu](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/emdawnwebgpu/) for more info.
-
 # WebGPU Bindings
 
-These files, and several snippets of other files, are generated by Dawn
-(Chromium's WebGPU library):
-- [Generator](https://source.chromium.org/chromium/chromium/src/+/main:third_party/dawn/generator/)
-- [Generator input](https://source.chromium.org/chromium/chromium/src/+/main:third_party/dawn/dawn.json)
-- [Generator output](https://source.chromium.org/chromium/chromium/src/+/main:out/linux-Debug/gen/third_party/dawn/emscripten-bits/)
-
-The C header is intended to be mostly the same as the "upstream"
-[`webgpu.h`](https://github.com/webgpu-native/webgpu-headers/blob/main/webgpu.h),
-but both are in flux, and some experimental elements are included and other
-native-specific elements are excluded.
-
-The C++ files are **currently** Dawn-specific, but included in Emscripten for
-better compatibility with Dawn: it has roughly the same API as Dawn's copy, but
-is included here because it is strongly tied to an exact `webgpu.h` revision.
-
-To update these bindings from Dawn:
-(TODO: these links are broken because Chromium Code Search is not currently building these generated files.)
-
-1. Copy [`webgpu_enum_class_bitmasks.h`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/dawn/include/webgpu/webgpu_enum_class_bitmasks.h) from Dawn's source to `system/include/webgpu/webgpu_enum_class_bitmasks.h`
-1. Build Dawn's `emdawnwebgpu_headers_gen` and `emdawnwebgpu_js_gen` targets (in a gn build of Dawn, or a build of Chromium) - or, use the Chromium Code Search copy of the generated files if no changes are needed
-1. Copy the generated [`include`](https://source.chromium.org/chromium/chromium/src/+/main:out/linux-Debug/gen/third_party/dawn/src/emdawnwebgpu/include/) files into Emscripten's `system` directory:
-    - `system/include/webgpu/webgpu.h`
-    - `system/include/webgpu/webgpu_cpp.h`
-    - `system/include/webgpu/webgpu_cpp_chained_struct.h`
-1. Paste the contents of [`library_webgpu_enum_tables.js`](https://source.chromium.org/chromium/chromium/src/+/main:out/linux-Debug/gen/third_party/dawn/src/emdawnwebgpu/library_webgpu_enum_tables.js) over the "Map from enum number to enum string" section of [`library_webgpu.js`](../../../src/library_webgpu.js)
-1. Copy the generated [`struct_info_webgpu.json`](https://source.chromium.org/chromium/chromium/src/+/main:out/linux-Debug/gen/third_party/dawn/src/emdawnwebgpu/struct_info_webgpu.json) to [`struct_info_webgpu.json`](../../../src/struct_info_webgpu.json).
-1. **Manually update the `globalThis.gpu` compile-time enum tables (AdapterType, BackendType, etc.)**:
-    - Inspect the `webgpu.h` diff for changes to the integer values of any enums used here. (It's not necessary to add new enum values to these tables until they're needed for something.)
-1. **Manually update the "Map from enum string back to enum number" tables.**
-    - Inspect the `webgpu.h` diff for changes to these enums. (These tables need to be complete so that we can handle any enum string the browser gives us.)
-1. Update Emscripten's auto-generated files:
-
-    ```
-    emcc --clear-cache
-    ./tools/gen_struct_info.py
-    ./tools/gen_struct_info.py --wasm64
-    ./tools/maint/gen_sig_info.py
-    ```
-
-## Testing
-
-There is a `browser.test_webgpu_basic_rendering` with minimal WebGPU API testing that can be handy to test manually before making a contribution. Use `browser64.test_webgpu_basic_rendering` to test the MEMORY64 build.
-
-```
-test/runner browser.test_webgpu_basic_rendering
-test/runner browser64.test_webgpu_basic_rendering
-```
-
-You may need to specify extra browser cmd args to assign the WebGPU supported browser, which is needed if you work on linux where WebGPU is not enabled by default in chrome at present.
+**IMPORTANT NOTICE:**
 
-```
-test/runner browser.test_webgpu_basic_rendering --browser="google-chrome-unstable --enable-unsafe-webgpu --enable-features=Vulkan,UseSkiaRenderer"
-```
+Emscripten's WebGPU bindings `-sUSE_WEBGPU` are **deprecated and unmaintained**
+and will be removed. Please migrate to Emdawnwebgpu via
+[`--use-port=emdawnwebgpu`](../../../tools/ports/emdawnwebgpu.py):
 
-Alternatively you can test your emscripten updates by building the source file, and then serve (e.g. use node http-server) and view in browser to make sure things work fine.
+> Emdawnwebgpu is a fork of Emscripten's original `USE_WEBGPU`, implementing a
+> newer, more stable version of the standardized webgpu.h interface. If you
+> find issues, verify in the latest nightly release
+> (<https://github.com/google/dawn/releases>) and file feedback with Dawn.
+> (Emdawnwebgpu is maintained as part of Dawn, the open-source WebGPU
+> implementation used by Chromium, but it is still cross-browser.)
 
-```
-emcc --clear-cache
-emcc test/webgpu_basic_rendering.cpp -sUSE_WEBGPU -o path/to/index.html
-```
+(Information about maintaining the `USE_WEBGPU` bindings has been removed,
+since they won't be maintained anymore.)
diff --git a/test/test_browser.py b/test/test_browser.py
@@ -4503,23 +4503,21 @@ def test_webgl_simple_extensions(self, webgl_version, simple_enable_extensions):
   })
   @requires_webgpu
   def test_webgpu_basic_rendering(self, args):
-    self.btest_exit('webgpu_basic_rendering.cpp', emcc_args=['-sUSE_WEBGPU'] + args)
+    self.btest_exit('webgpu_basic_rendering.cpp', emcc_args=['-Wno-error=deprecated', '-sUSE_WEBGPU'] + args)
 
   @requires_webgpu
   def test_webgpu_required_limits(self):
-    self.btest_exit('webgpu_required_limits.c', emcc_args=['-sUSE_WEBGPU', '-sASYNCIFY'])
+    self.btest_exit('webgpu_required_limits.c', emcc_args=['-Wno-error=deprecated', '-sUSE_WEBGPU', '-sASYNCIFY'])
 
-  # TODO(#19645): Extend this test to proxied WebGPU when it's re-enabled.
   @requires_webgpu
   def test_webgpu_basic_rendering_pthreads(self):
-    self.btest_exit('webgpu_basic_rendering.cpp', emcc_args=['-sUSE_WEBGPU', '-pthread', '-sOFFSCREENCANVAS_SUPPORT'])
+    self.btest_exit('webgpu_basic_rendering.cpp', emcc_args=['-Wno-error=deprecated', '-sUSE_WEBGPU', '-pthread', '-sOFFSCREENCANVAS_SUPPORT'])
 
   def test_webgpu_get_device(self):
-    self.btest_exit('webgpu_get_device.cpp', emcc_args=['-sUSE_WEBGPU', '-sASSERTIONS', '--closure=1'])
+    self.btest_exit('webgpu_get_device.cpp', emcc_args=['-Wno-error=deprecated', '-sUSE_WEBGPU', '-sASSERTIONS', '--closure=1'])
 
-  # TODO(#19645): Extend this test to proxied WebGPU when it's re-enabled.
   def test_webgpu_get_device_pthreads(self):
-    self.btest_exit('webgpu_get_device.cpp', emcc_args=['-sUSE_WEBGPU', '-pthread'])
+    self.btest_exit('webgpu_get_device.cpp', emcc_args=['-Wno-error=deprecated', '-sUSE_WEBGPU', '-pthread'])
 
   # Tests the feature that shell html page can preallocate the typed array and place it
   # to Module.buffer before loading the script page.