v2.0.0-beta.1

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+on:
+  pull_request:
+permissions:
+  contents: read
+concurrency:
+  group: ci-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+jobs:
+  lint:
+    uses: ./.github/workflows/lint.yml
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        runner: [ubuntu-24.04, windows-2022, macos-15]
+    uses: ./.github/workflows/tests.yml
+    with:
+      runner: ${{ matrix.runner }}

.github/workflows/lint.yml

@@ -0,0 +1,35 @@
+name: Lint
+on:
+  workflow_call:
+permissions:
+  contents: read
+env:
+  RUSTUP_TOOLCHAIN: '1.97.1'
+  CARGO_PROFILE_DEV_DEBUG: '0'
+  CARGO_INCREMENTAL: '0'
+  CARGO_BUILD_JOBS: '2'
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 40
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.10'
+      - name: Install Rust
+        run: rustup toolchain install "$RUSTUP_TOOLCHAIN" --profile minimal --component rustfmt --component clippy --no-self-update
+      - name: Rust formatting
+        run: cargo fmt --all -- --check
+      - name: Clippy
+        run: |
+          export PYO3_PYTHON="$(command -v python)"
+          cargo clippy --workspace --all-targets --locked -- -D warnings
+      - name: Python and C formatting
+        run: |
+          python -m pip install ruff==0.15.17 clang-format==22.1.5
+          ruff check crates/binding-python tools/ci.py
+          ruff format --check crates/binding-python tools/ci.py
+          git ls-files -z 'crates/binding-c/*.c' 'crates/binding-c/*.h' | xargs -0 -r clang-format --dry-run --Werror

.github/workflows/tests.yml

@@ -0,0 +1,63 @@
+name: Tests
+on:
+  workflow_call:
+    inputs:
+      runner:
+        type: string
+        required: true
+permissions:
+  contents: read
+env:
+  RUSTUP_TOOLCHAIN: '1.97.1'
+  CARGO_PROFILE_DEV_DEBUG: '0'
+  CARGO_PROFILE_TEST_DEBUG: '0'
+  CARGO_INCREMENTAL: '0'
+  CARGO_BUILD_JOBS: '2'
+jobs:
+  tests:
+    name: Rust, Python and C (${{ inputs.runner }})
+    runs-on: ${{ inputs.runner }}
+    timeout-minutes: 90
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.10'
+      - name: Install Rust
+        run: rustup toolchain install "$RUSTUP_TOOLCHAIN" --profile minimal --no-self-update
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: tests-${{ runner.os }}-${{ runner.arch }}
+      - name: Run development tests (no distribution packages or uploads)
+        run: |
+          python -m venv .ci-venv
+          if [ "$RUNNER_OS" = Windows ]; then
+            source .ci-venv/Scripts/activate
+          else
+            source .ci-venv/bin/activate
+          fi
+          python -m pip install maturin==1.14.1 pytest==8.4.2 resvg-py==0.5.0 packaging==25.0 tomli==2.2.1 'numpy>=2.1.0' cmake==3.31.6
+          export PYO3_PYTHON="$(python -c 'import sys; print(sys.executable)')"
+          python tools/ci.py versions
+          cargo test --workspace --locked
+          python tools/ci.py ctest
+          maturin develop --locked --manifest-path crates/binding-python/Cargo.toml
+          cd crates/binding-python
+          python -m pytest tests
+      - name: Upload visualization diagnostics on failure
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: visualization-diagnostics-${{ inputs.runner }}
+          path: |
+            crates/cqlib-core/src/visualization/**/figure/**/*.png
+            crates/cqlib-core/src/visualization/**/figure/*.svg
+            crates/binding-python/tests/visualization/figure/**/*.png
+            crates/binding-python/tests/visualization/figure/*.svg
+          if-no-files-found: ignore
+          retention-days: 7

.github/workflows/wheels-build.yml

@@ -0,0 +1,147 @@
+name: Build release artifacts
+on:
+  workflow_call:
+permissions:
+  contents: read
+env:
+  RUSTUP_TOOLCHAIN: '1.97.1'
+  CARGO_PROFILE_DEV_DEBUG: '0'
+  CARGO_PROFILE_TEST_DEBUG: '0'
+  CARGO_INCREMENTAL: '0'
+  CARGO_BUILD_JOBS: '2'
+jobs:
+  platforms:
+    name: Wheel and C SDK (${{ matrix.platform }})
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 180
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: windows-x86_64-msvc
+            runner: windows-2022
+          - platform: linux-glibc2.28-x86_64
+            runner: ubuntu-24.04
+            image: quay.io/pypa/manylinux_2_28_x86_64:latest
+          - platform: linux-glibc2.28-aarch64
+            runner: ubuntu-24.04-arm
+            image: quay.io/pypa/manylinux_2_28_aarch64:latest
+          - platform: macos11-x86_64
+            runner: macos-15-intel
+          - platform: macos11-arm64
+            runner: macos-15
+    env:
+      MACOSX_DEPLOYMENT_TARGET: '11.0'
+      CMAKE_OSX_DEPLOYMENT_TARGET: '11.0'
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        if: runner.os != 'Linux'
+        with:
+          python-version: '3.10'
+      - name: Set up native build tools
+        if: runner.os != 'Linux'
+        run: |
+          rustup toolchain install "$RUSTUP_TOOLCHAIN" --profile minimal --no-self-update
+          python -m pip install maturin==1.14.1 packaging==25.0 tomli==2.2.1 cmake==3.31.6
+      - name: Build C SDK and abi3 wheel, run C and installed-wheel tests
+        if: runner.os != 'Linux'
+        env:
+          PLATFORM: ${{ matrix.platform }}
+        run: python tools/ci.py release --platform "$PLATFORM"
+      - name: Build and test inside native manylinux 2.28
+        if: runner.os == 'Linux'
+        env:
+          IMAGE: ${{ matrix.image }}
+          PLATFORM: ${{ matrix.platform }}
+        run: |
+          docker pull "$IMAGE"
+          docker image inspect "$IMAGE" --format '{{json .RepoDigests}}'
+          docker run --rm -v "$GITHUB_WORKSPACE:/io" -w /io \
+            -e PLATFORM -e RUSTUP_TOOLCHAIN -e CARGO_PROFILE_DEV_DEBUG \
+            -e CARGO_PROFILE_TEST_DEBUG -e CARGO_INCREMENTAL -e CARGO_BUILD_JOBS \
+            "$IMAGE" bash -euo pipefail -c '
+              export PATH="/opt/python/cp310-cp310/bin:$HOME/.cargo/bin:$PATH"
+              export CARGO_TARGET_DIR=/tmp/cqlib-manylinux-target
+              curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/rustup.sh
+              sh /tmp/rustup.sh -y --profile minimal --default-toolchain "$RUSTUP_TOOLCHAIN"
+              python -m pip install maturin==1.14.1 packaging==25.0 tomli==2.2.1 cmake==3.31.6
+              cargo test --locked -p cqlib-core -p binding-c -p cqlib
+              python tools/ci.py release --platform "$PLATFORM"
+              for version in 311 312 313 314; do
+                /opt/python/cp$version-cp$version/bin/python -m pip install packaging==25.0
+                /opt/python/cp$version-cp$version/bin/python tools/ci.py wheel-test
+              done
+            '
+      - uses: actions/setup-python@v6
+        if: runner.os != 'Linux'
+        with:
+          python-version: '3.11'
+      - name: Test the same wheel on Python 3.11
+        if: runner.os != 'Linux'
+        run: |
+          python -m pip install packaging==25.0
+          python tools/ci.py wheel-test
+      - uses: actions/setup-python@v6
+        if: runner.os != 'Linux'
+        with:
+          python-version: '3.12'
+      - name: Test the same wheel on Python 3.12
+        if: runner.os != 'Linux'
+        run: |
+          python -m pip install packaging==25.0
+          python tools/ci.py wheel-test
+      - uses: actions/setup-python@v6
+        if: runner.os != 'Linux'
+        with:
+          python-version: '3.13'
+      - name: Test the same wheel on Python 3.13
+        if: runner.os != 'Linux'
+        run: |
+          python -m pip install packaging==25.0
+          python tools/ci.py wheel-test
+      - uses: actions/setup-python@v6
+        if: runner.os != 'Linux'
+        with:
+          python-version: '3.14'
+      - name: Test the same wheel on Python 3.14
+        if: runner.os != 'Linux'
+        run: |
+          python -m pip install packaging==25.0
+          python tools/ci.py wheel-test
+      - uses: actions/upload-artifact@v7
+        with:
+          name: release-${{ github.ref_name }}-${{ matrix.platform }}
+          path: target/ci-dist/*
+          if-no-files-found: error
+          retention-days: 30
+          compression-level: 0
+  sources:
+    name: Python sdist and Rust crate
+    runs-on: ubuntu-24.04
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.10'
+      - name: Install build tools
+        run: |
+          rustup toolchain install "$RUSTUP_TOOLCHAIN" --profile minimal --no-self-update
+          python -m pip install maturin==1.14.1 packaging==25.0 tomli==2.2.1
+      - name: Package sdist and independently compile the Rust crate
+        run: python tools/ci.py sources
+      - uses: actions/upload-artifact@v7
+        with:
+          name: release-${{ github.ref_name }}-sources
+          path: target/ci-dist/*
+          if-no-files-found: error
+          retention-days: 30
+          compression-level: 0

.github/workflows/wheels.yml

@@ -0,0 +1,40 @@
+name: Release artifacts (manual publishing only)
+on:
+  push:
+    tags: ['v*']
+permissions:
+  contents: read
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+jobs:
+  versions:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.10'
+      - run: python -m pip install packaging==25.0 tomli==2.2.1
+      - name: Check tag and component versions
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: python tools/ci.py versions --tag "$RELEASE_TAG"
+  lint:
+    needs: versions
+    uses: ./.github/workflows/lint.yml
+  tests:
+    needs: versions
+    strategy:
+      fail-fast: false
+      matrix:
+        runner: [windows-2022, ubuntu-24.04, ubuntu-24.04-arm, macos-15-intel, macos-15]
+    uses: ./.github/workflows/tests.yml
+    with:
+      runner: ${{ matrix.runner }}
+  build:
+    needs: [lint, tests]
+    uses: ./.github/workflows/wheels-build.yml

.typos.toml

@@ -14,6 +14,7 @@ MCH = "MCH"
 paeth = "paeth"
 pngs = "pngs"
 PNGs = "PNGs"
+Strang = "Strang"
 
 [default.extend-identifiers]
 PNGs = "PNGs"

README.CN.md

@@ -115,19 +115,18 @@ let evaluated = qc.assign_parameters( & Some(bindings)).unwrap();
 ### C
 
 ```c
-#include <cqlib/circuit.h>
+#include <cqlib_c.h>
 
 int main(void) {
     // 创建 2 比特 Bell 态线路
-    cqlib_circuit_t *qc = cqlib_circuit_new(2);
-    cqlib_circuit_h(qc, 0);
-    cqlib_circuit_cx(qc, 0, 1);
+    CCircuit *qc = circuit_new(2);
+    circuit_h(qc, 0);
+    circuit_cx(qc, 0, 1);
 
     // 查看线路信息
-    uint32_t n = cqlib_circuit_num_qubits(qc);    // 2
-    size_t ops = cqlib_circuit_operation_count(qc); // 2
+    size_t ops = (size_t)circuit_num_operations(qc); // 2
 
-    cqlib_circuit_free(qc);
+    circuit_free(qc);
     return 0;
 }
 ```
@@ -159,6 +158,8 @@ maturin develop --release -m crates/binding-python/Cargo.toml
 cargo build --release -p binding-c
 ```
 
+> 提示：MinGW gcc 链接 C 接口时，需改用 `cargo build --release -p binding-c --target x86_64-pc-windows-gnu` 构建，详见 [crates/binding-c/README.md](crates/binding-c/README.md)。
+
 运行测试：
 
 ```bash
@@ -172,6 +173,7 @@ pytest crates/binding-python/tests/
 |-----------------|----------------------------------------------------------|
 | API 参考 (Rust)   | [docs.rs/cqlib-core](https://docs.rs/cqlib-core)         |
 | API 参考 (Python) | [qc.zdxlz.com/docs](https://qc.zdxlz.com/)               |
+| API 参考 (C)      | [docs/api/cn/c/0_overview.md](docs/api/cn/c/0_overview.md)     |
 | 源码仓库 (Gitee)    | [gitee.com/cq-lib/cqlib](https://gitee.com/cq-lib/cqlib) |
 | 源码仓库 (GitHub)   | [github.com/cq-lib/cqlib](https://github.com/cq-lib/cqlib) |