Qiskit · IvanIsCoding · May 10, 2025 · May 11, 2025 · May 11, 2025 · May 11, 2025
diff --git a/.cargo/config.toml b/.cargo/config.toml
@@ -9,3 +9,14 @@ rustflags = [
   "-C", "link-arg=-undefined",
   "-C", "link-arg=dynamic_lookup",
 ]
+
+[target.wasm32-unknown-emscripten]
+rustflags = [
+  "-C", "target-feature=+atomics,+bulk-memory,+mutable-globals",
+  "-C", "link-arg=-sSIDE_MODULE=2",
+  "-C", "link-arg=-sWASM_BIGINT",
+  "-Z", "emscripten-wasm-eh",
+]
+
+[unstable]
+build-std = ["std", "panic_abort"]
diff --git a/.gitattributes b/.gitattributes
@@ -1,2 +1,4 @@
 docs/* linguist-documentation
 releasenotes/* linguist-documentation
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -198,3 +198,16 @@ jobs:
         with:
           name: html_docs
           path: docs/build/html
+  pyodide-build:
+    if: github.repository_owner == 'Qiskit'
+    needs: [tests]
+    name: Pyodide Build + Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.8
+        with:
+          manifest-path: pyproject.toml
+          pixi-version: v0.46.0
+          environments: default
+      - run: pixi run build_pyodide_and_test
diff --git a/.gitignore b/.gitignore
@@ -25,3 +25,15 @@ rustworkx-core/Cargo.lock
 **/.DS_Store
 venv/
 .python-version
+
+# pixi environments
+.pixi
+*.egg-info
+
+# pyodide xbuild
+.xbuildenv
+
+# Node.js
+node_modules/
+jspm_packages/
+.npm
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -560,6 +560,80 @@ has the necessary approvals and is tagged as `automerge` unless it has a merge
 conflict or has a failed CI run. Doing so will just waste CI resources and
 delay everything from merging, including your PR.
 
+### Pyodide Support
+
+`rustworkx` has experimental support for Pyodide, the Python distribution for
+the browser.
+
+Because building for Pyodide is a more involved process, we use [Pixi](https://pixi.sh/latest/)
+to manage the dependencies of the build. Currently, the scripts work only for Linux x86-64.
+It is also possible to run the build on Windows with Windows Subsystem for Linux (WSL). At
+the moment, aarch64 platforms like macOS cannot run the script.
+
+Please refer to the [Pixi](https://pixi.sh/latest/) page for the latest instructions on how
+to install Pixi. Once installed, there's a single command that needs to be run.
+
+#### Building for Pyodide
+
+At the root of the directory, simply run:
+
+```bash
+pixi run build_pyodide
+```
+
+This will create a separate environment with all of the required toolchains. At the end,
+a Pyodide wheel will be available in the `dist` folder if the build is successful.
+
+#### Testing Pyodide Wheels
+
+After running `pixi run build_pyodide`, we can run the test suite with:
+
+```bash
+pixi run pyodide_test
+```
+
+It is also possible to run the tests with a specific wheel via an **absolute path**:
+```
+pixi run pyodide_test $ABSOLUTE_PATH_TO_WHEEL
+```
+
+> [!WARNING]  
+> If there are multiple Pyodide wheels in the dist/ folder, the test will fail
+> to prevent anyone from testing an outdated wheel. This scenario can happen when
+> we update the rustworkx version, update the minimum Python ABI, or update Pyodide. To fix,
+> clean the directory with `rm -r dist` and re-run `pixi run build_pyodide`
+
+> [!TIP]
+> You can build and test with a single command with `pixi run build_pyodide_and_test`.
+
+#### Updating `pyodide-build` and dependencies
+
+All the dependencies for the Pyodide build are listed under `[tool.pixi.dependencies]`. To find a set
+of versions that works, visit the [pyodide-cross-build-environments.json](https://github.com/pyodide/pyodide/blob/main/pyodide-cross-build-environments.json) file in the `pyodide` repository.
+
+We'll need to align the [Emscripten](https://anaconda.org/conda-forge/emscripten) version from `conda-forge` with one
+of the public releases. Then, we pick a `pyodide-build` version higher than the required build version and the equivalent Python
+version also specified in the cross build environments. Lastly, update `[tool.pixi.tasks.install_xbuildenv]` to install
+the selected version of Pyodide.
+
+We need to pin the Rust compiler. To find an appropriate Rust compiler version, run:
+
+```bash
+pixi shell
+pyodide config list
+```
+
+This will output a list including `rust_toolchain`. Currently, `pyodide-build` requires Rust Nightly. Because conda-forge
+only provides stable releases, we'll need to map a nightly version to a stable version. Some repositories like [oxalica/rust-overlay]([oxalica/rust-overlay](https://github.com/oxalica/rust-overlay/tree/master/manifests/nightly/)) contain a list of the nightly releases. For example, `nightly-2025-02-01`
+maps roughly to `1.86`. If that version was not yet stable, we could try picking `1.85` as well.
+
+After updating the versions in `[tool.pixi.dependencies]`, run `pixi lock` which will update `pixi.lock`. Onwards, all builds
+will use the same environment. As long as `pixi run build_pyodide` passes locally or on CI it should keep compiling and building.
+
+Lastly, remember to update the Pyodide version in `tests/pyodide_tests`. Change the version in `tests/pyodide_tests/package.json`
+and run `pixi run install_pyodide_test_env` to generate the new lockfile. If you forget to update the Pyodide version, the tests
+will fail.
+
 ### Stable Branch Policy and Backporting
 
 The stable branch is intended to be a safe source of fixes for high-impact bugs,

diff --git a/Cargo.toml b/Cargo.toml
@@ -75,5 +75,5 @@ default-features = false
 features = ["multi_thread"]
 
 [profile.release]
-lto = 'fat'
+lto = "fat"
 codegen-units = 1
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -113,6 +113,10 @@ source.
      - i686 or x86_64
      - :ref:`tier-2` (Python < 3.10), :ref:`tier-3` (Python >= 3.10)
      -
+   * - Pyodide 
+     - WASM (Emscripten)
+     - :ref:`tier-experimental`
+     -
 
 
 .. _manylinux 2014: https://peps.python.org/pep-0599/>
@@ -166,6 +170,18 @@ functioning Python environment and may require a C/C++ compiler or additional
 programs to build dependencies from source as part of the installation process.
 Support for these platforms are best effort only.
 
+.. _tier-experimental:
+
+Tier Experimental
+-----------------
+
+Tier Experimental platforms are not tested upstream as part of the development process.
+Pre-compiled binaries are built by the external community in separate repositories. Not all of rustworkx might compile for
+platforms of this tier and features can be removed. Often, platforms in this tier use unstable features
+from the Rust compiler and might break at any time. Support for these platforms are best effort only.
+
+Currently, the only platform in this tier is Pyodide, which is a port of Python that can run in the browser and on Node.js.
+
 Using rustworkx
 ===============
 

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -0,0 +1,6 @@
+{
+  "name": "rustworkx-pyodide",
+  "dependencies": {
+    "pyodide": "^0.27.6"
+  }
+}