Packaging Dependencies and Wheel Building

.github/workflows/codeql.yml

@@ -2,15 +2,14 @@ name: CodeQL
 
 on:
   push:
-    branches: [main, develop, swmm6_rel]
+    branches: [main]                         # drop develop — covered by PR
+    paths: ['src/**', 'include/**', 'python/**', 'CMakeLists.txt', 'vcpkg.json']
   pull_request:
-    branches: [main, develop, swmm6_rel]
-  schedule:
-    # Weekly scan so newly disclosed CWE queries hit dormant branches too.
-    # Mondays at 06:00 UTC — outside US-business hours but before EU-morning.
-    - cron: "0 6 * * 1"
+    branches: [main]
+    paths: ['src/**', 'include/**', 'python/**', 'CMakeLists.txt', 'vcpkg.json']
+  schedule: [{ cron: "0 6 * * 1" }]
   workflow_dispatch:
-
+    
 env:
   VCPKG_ROOT: ${{ github.workspace }}/vcpkg
   VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"

.github/workflows/deployment.yml

@@ -2,7 +2,10 @@ name: Deployment
 
 on:
   push:
+    branches: [main]
     tags: ["v*.*.*"]
+  pull_request:
+    branches: [main, develop]
   workflow_dispatch:
 
 env:
@@ -124,173 +127,123 @@ jobs:
             build-${{ matrix.vcpkg_triplet }}/*.zip
 
   # ──────────────────────────────────────────────────────────────────────
-  #  Python wheels
+  #  Python wheels — cibuildwheel matrix (one runner per OS/arch).
+  #
+  #  Each runner produces wheels for every supported CPython version
+  #  (3.10–3.13) in a single job. Linux builds run inside manylinux_2_28
+  #  containers; vcpkg is bootstrapped INSIDE the container by the
+  #  `before-all` hook in pyproject.toml's [tool.cibuildwheel.linux]
+  #  block. macOS / Windows run on the host runner and use the vcpkg
+  #  checkout below.
+  #
+  #  See docs/CIBUILDWHEEL_REVERT_PLAN.md for full rationale.
   # ──────────────────────────────────────────────────────────────────────
   wheels:
-    name: "Python Wheels (${{ matrix.alias }})"
+    name: "Wheels (${{ matrix.os }})"
     needs: build
     strategy:
       fail-fast: false
       matrix:
-        include:
-          - os: ubuntu-latest
-            alias: Linux-x64
-            shell_ext: .sh
-            vcpkg_triplet: x64-linux
-            cmake_osx_arch: ""
-
-          - os: macos-latest
-            alias: macOS-arm64
-            cmake_preset: Darwin
-            shell_ext: .sh
-            vcpkg_triplet: arm64-osx
-            cmake_osx_arch: arm64
-
-          - os: macos-15-intel
-            alias: macOS-x64
-            cmake_preset: Darwin
-            shell_ext: .sh
-            vcpkg_triplet: x64-osx
-            cmake_osx_arch: x86_64
-
-          - os: windows-latest
-            alias: Windows-x64
-            cmake_preset: Windows
-            shell_ext: .bat
-            vcpkg_triplet: x64-windows
-            cmake_osx_arch: ""
-
+        os:
+          - ubuntu-24.04          # Linux x86_64
+          - ubuntu-24.04-arm      # Linux aarch64 (native, no QEMU)
+          - windows-2025          # Windows x86_64
+          - macos-15              # macOS arm64
+          - macos-15-intel        # macOS x86_64
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v5
 
-      # vcpkg is required by python/CMakePresets.json (toolchainFile = $env{VCPKG_ROOT}/...).
-      # Each runner is a fresh machine so we must check it out and bootstrap it here.
-      - name: Checkout vcpkg
+      # Export GHA cache creds so the in-container vcpkg (Linux) and the
+      # host vcpkg (macOS/Windows) can both reuse the x-gha binary cache.
+      - name: Export GitHub Actions cache variables
+        uses: actions/github-script@v8
+        with:
+          script: |
+            core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
+            core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
+
+      # On macOS and Windows there is no container; vcpkg lives on the host
+      # and is referenced by python/CMakePresets.json via $env{VCPKG_ROOT}.
+      - name: Checkout vcpkg (host-side, macOS/Windows)
+        if: runner.os != 'Linux'
         uses: actions/checkout@v5
         with:
           repository: microsoft/vcpkg
           ref: 2025.02.14
           path: vcpkg
 
-      - name: Install OpenMP and Ninja (macOS)
+      - name: Bootstrap vcpkg (macOS)
         if: runner.os == 'macOS'
-        run: brew install libomp ninja
-
-      - name: Install Ninja (Linux)
-        if: runner.os == 'Linux'
-        run: sudo apt-get update && sudo apt-get install -y ninja-build
+        run: ./vcpkg/bootstrap-vcpkg.sh -disableMetrics
 
       - name: Bootstrap vcpkg (Windows)
         if: runner.os == 'Windows'
-        working-directory: ${{ env.VCPKG_ROOT }}
-        run: |
-          .\bootstrap-vcpkg${{ matrix.shell_ext }}
-          .\vcpkg.exe integrate install
+        run: .\vcpkg\bootstrap-vcpkg.bat -disableMetrics
 
-      - name: Bootstrap vcpkg (Unix)
-        if: runner.os != 'Windows'
-        working-directory: ${{ env.VCPKG_ROOT }}
-        run: |
-          ./bootstrap-vcpkg${{ matrix.shell_ext }}
-          chmod +x vcpkg
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v3.1.4
+        with:
+          package-dir: ./python
+          output-dir:  ./wheelhouse
+        env:
+          # Host-side VCPKG_ROOT consumed by macOS/Windows builds.
+          # Linux ignores this (VCPKG_ROOT is set to /host/vcpkg inside
+          # the container by pyproject.toml's before-all hook).
+          VCPKG_ROOT: ${{ github.workspace }}/vcpkg
+          VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
+          # Force the macOS deployment target via cibuildwheel's env channel.
+          # Setting it ONLY in pyproject.toml [tool.cibuildwheel.macos].environment
+          # was not propagating to the x86_64 build's wheel-tag computation
+          # (wheel ended up tagged macosx_10_9 despite the toml override).
+          # CIBW_ENVIRONMENT_MACOS is read early and applied uniformly.
+          CIBW_ENVIRONMENT_MACOS: MACOSX_DEPLOYMENT_TARGET=15.0 VCPKG_ROOT=${{ github.workspace }}/vcpkg
 
-      # Export the GHA cache tokens so vcpkg can restore binary packages built
-      # by the build job (avoids re-compiling SUNDIALS, etc.).
-      - name: Export GitHub Actions cache variables
-        uses: actions/github-script@v8
+      - name: Upload Python wheels
+        if: always()
+        uses: actions/upload-artifact@v5
         with:
-          script: |
-            core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
-            core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
+          name: python-wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
 
-      # Run a cmake configure-only pass on Windows to pre-populate the vcpkg
-      # installed directory using the binary cache from the build job.
-      # cibuildwheel's isolated build env sometimes fails to hit the GHA binary
-      # cache, causing vcpkg to try (and fail) to build SUNDIALS from source.
-      # The installed dir is then forwarded to skbuild via OPENSWMM_CMAKE_ARGS.
-      - name: Pre-install vcpkg dependencies (Windows)
-        if: runner.os == 'Windows'
-        run: >
-          cmake
-          --preset=${{ matrix.cmake_preset }}
-          -B build-vcpkg-prefetch
-          -DOPENSWMM_BUILD_TESTS=OFF
-          -DOPENSWMM_BUILD_UNIT_TESTS=OFF
-          -DOPENSWMM_BUILD_REGRESSION_TESTS=OFF
-          -DOPENSWMM_BUILD_BENCHMARKS=OFF
-          --no-warn-unused-cli
+  # ──────────────────────────────────────────────────────────────────────
+  #  Python source distribution (sdist) — platform-independent, built once.
+  # ──────────────────────────────────────────────────────────────────────
+  sdist:
+    name: "Python sdist"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.13"
 
-      - name: Install Python requirements
-        working-directory: python
+      - name: Install build frontend
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -r requirements.txt
+          python -m pip install build
 
-      - name: Clean stale build cache
-        run: python -c "import shutil, os; shutil.rmtree('python/_skbuild', ignore_errors=True)"
-
-      - name: Build wheels
-        uses: pypa/cibuildwheel@v2.23.2
-        with:
-          package-dir: ./python
-          output-dir: ./python/wheelhouse
-        env:
-          CMAKE_OSX_ARCHITECTURES: ${{ matrix.cmake_osx_arch }}
-          CIBW_BUILD_VERBOSITY: 3
-          CIBW_BEFORE_BUILD_LINUX: pip install ninja
-          CIBW_BEFORE_BUILD_MACOS: pip install delocate
-          CIBW_ENVIRONMENT_MACOS: >-
-            MACOSX_DEPLOYMENT_TARGET=15.0
-            CMAKE_OSX_ARCHITECTURES=${{ matrix.cmake_osx_arch }}
-            VCPKG_ROOT=${{ env.VCPKG_ROOT }}
-            VCPKG_BINARY_SOURCES="clear;x-gha,readwrite"
-            VCPKG_MANIFEST_DIR=${{ github.workspace }}
-            ACTIONS_CACHE_URL=${{ env.ACTIONS_CACHE_URL }}
-            ACTIONS_RUNTIME_TOKEN=${{ env.ACTIONS_RUNTIME_TOKEN }}
-          CIBW_ENVIRONMENT_LINUX: >-
-            VCPKG_ROOT=${{ env.VCPKG_ROOT }}
-            VCPKG_BINARY_SOURCES="clear;x-gha,readwrite"
-            VCPKG_MANIFEST_DIR=${{ github.workspace }}
-            ACTIONS_CACHE_URL=${{ env.ACTIONS_CACHE_URL }}
-            ACTIONS_RUNTIME_TOKEN=${{ env.ACTIONS_RUNTIME_TOKEN }}
-          CIBW_BEFORE_BUILD_WINDOWS: pip install delvewheel
-          CIBW_ENVIRONMENT_WINDOWS: >-
-            CMAKE_GENERATOR="Visual Studio 17 2022"
-            VCPKG_ROOT=${{ env.VCPKG_ROOT }}
-            VCPKG_BINARY_SOURCES="clear;x-gha,readwrite"
-            VCPKG_MANIFEST_DIR=${{ github.workspace }}
-            VCPKG_DEFAULT_TRIPLET=x64-windows
-            OPENSWMM_CMAKE_ARGS=-DVCPKG_INSTALLED_DIR=${{ github.workspace }}/build-vcpkg-prefetch/vcpkg_installed
-            ACTIONS_CACHE_URL=${{ env.ACTIONS_CACHE_URL }}
-            ACTIONS_RUNTIME_TOKEN=${{ env.ACTIONS_RUNTIME_TOKEN }}
-          CIBW_REPAIR_WHEEL_COMMAND_LINUX: auditwheel repair -w {dest_dir} {wheel}
-          CIBW_REPAIR_WHEEL_COMMAND_MACOS: delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel}
-          CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: "delvewheel repair -w {dest_dir} {wheel}"
-          CIBW_TEST_REQUIRES: pytest numpy
-          CIBW_TEST_COMMAND: pytest {package}/tests -v --import-mode=importlib
+      - name: Build sdist
+        working-directory: python
+        run: python -m build --sdist
 
-      - name: Upload Python wheels
-        if: always()
+      - name: Upload sdist
         uses: actions/upload-artifact@v5
         with:
-          name: python-wheels-${{ matrix.vcpkg_triplet }}
-          path: |
-            python/wheelhouse/*.whl
-            python/dist/*.whl
+          name: python-sdist
+          path: python/dist/*.tar.gz
+
   # ──────────────────────────────────────────────────────────────────────
   #  Create GitHub Release
   # ──────────────────────────────────────────────────────────────────────
   release:
     name: Create GitHub Release
     if: startsWith(github.ref, 'refs/tags/v')
-    needs: [build, wheels]
+    needs: [build, wheels, sdist]
     runs-on: ubuntu-latest
     permissions:
       contents: write

.github/workflows/documentation.yml

@@ -2,10 +2,12 @@ name: Documentation
 
 on:
   push:
-    branches: [main, develop, swmm6_rel]
+    branches: [main, develop]
     tags: ["v*.*.*"]
+    paths: ['docs/**', 'python/docs/**', 'python/openswmm/**', 'include/**', '**/*.md']
   pull_request:
-    branches: [main, develop, swmm6_rel]
+    branches: [main, develop]
+    paths: ['docs/**', 'python/docs/**', 'python/openswmm/**', 'include/**', '**/*.md']
   workflow_dispatch:
 
 # Allow only one concurrent deployment.  Do NOT cancel in-progress runs so