Publish uc-picker packages and rebuild bilingual documentation

.build-config.yml

@@ -1,7 +1,7 @@
 tools:
   verilator: v5.052
-  swig: v4.2.1
+  swig: v4.5.1
   node: 20.12.2
   python: 3.11
 dependencies:
-  xcomm: c39db6652cd08d46df05d08f0bb5a033b83e4d2f
+  xcomm: b3f48f40d3aa362b021fb8e4955ebd3765d56705

.github/workflows/ci.yml

@@ -52,6 +52,11 @@ jobs:
             echo 'run_build=false' >> "$GITHUB_OUTPUT"
           fi
 
+  portable-wheel:
+    needs: branch-or-pr
+    if: needs.branch-or-pr.outputs.run_build == 'true'
+    uses: ./.github/workflows/portable-wheel.yml
+
   build-and-test:
     needs: branch-or-pr
     if: needs.branch-or-pr.outputs.run_build == 'true'
@@ -88,6 +93,10 @@ jobs:
           echo "NODE_VERSION=$(sed -n 's/^  node:[[:space:]]*//p' .build-config.yml)" >> "$GITHUB_ENV"
           echo "PYTHON_VERSION=$(sed -n 's/^  python:[[:space:]]*//p' .build-config.yml)" >> "$GITHUB_ENV"
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
       - name: Install native build toolchain
         run: bash scripts/build/setup-native-toolchain.sh
 
@@ -156,8 +165,8 @@ jobs:
       - name: Build Python wheels
         if: matrix.full_test
         env:
-          # Match the planned xcomm 1.x release while it is still in development.
-          SETUPTOOLS_SCM_PRETEND_VERSION_FOR_XSPCOMM: 1.0.0.dev0
+          # Exercise the dependency range with the pinned upcoming uc-xcomm release.
+          SETUPTOOLS_SCM_PRETEND_VERSION_FOR_UC_XCOMM: 1.1.0
         run: |
           python3 -m venv /tmp/picker-wheel-builder
           /tmp/picker-wheel-builder/bin/python -m pip install 'build>=1,<2'

.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: Documentation
+
+on:
+  pull_request:
+    branches: [master]
+    paths:
+      - "doc/**"
+      - "README*"
+      - "CONTRIBUTING.md"
+      - "test/README.md"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - "scripts/docs.py"
+      - ".github/workflows/docs.yml"
+  push:
+    branches: [master, "docs/**"]
+    paths:
+      - "doc/**"
+      - "README*"
+      - "CONTRIBUTING.md"
+      - "test/README.md"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - "scripts/docs.py"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: documentation-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+      - name: Install documentation tools
+        run: python -m pip install -r requirements-docs.txt
+      - name: Check translations, links and example syntax
+        run: python scripts/docs.py check
+      - name: Build documentation site
+        run: python -m mkdocs build --strict
+      - name: Export Wiki pages
+        run: python scripts/docs.py wiki --output build/wiki-export
+      - name: Upload documentation preview
+        uses: actions/upload-artifact@v4
+        with:
+          name: picker-documentation
+          if-no-files-found: error
+          path: |
+            build/docs-site
+            build/wiki-export

.github/workflows/portable-wheel.yml

@@ -0,0 +1,93 @@
+name: Portable Picker wheel
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        type: string
+        default: ''
+      artifact-name:
+        type: string
+        default: picker-portable-wheel
+      xcomm-version:
+        type: string
+        default: ''
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.ref || github.sha }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build and audit the fully static wheel
+        run: |
+          python -m pip install 'cibuildwheel==3.4.1' 'twine>=6,<7'
+          XCOMM_SKIP_ALIGN=1 make init
+          python -m cibuildwheel --only cp312-manylinux_x86_64 --output-dir dist
+          python scripts/release/check_static_wheel.py dist/*.whl
+          python -m twine check --strict dist/*.whl
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ inputs.artifact-name }}
+          path: dist/*.whl
+          if-no-files-found: error
+
+  compatibility:
+    needs: build
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python: [cp311-cp311, cp312-cp312]
+        glibc: ['2.17', '2.28']
+        include:
+          - glibc: '2.17'
+            image: quay.io/pypa/manylinux2014_x86_64@sha256:3a591c1109773dbd79f16c038588fd1867d9f2f708b360dab5715852c7f96ef0
+          - glibc: '2.28'
+            image: quay.io/pypa/manylinux_2_28_x86_64@sha256:076b19ef6e698f28649fa817c49d14443201e01da85240e8e52f93e8daa49bff
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref || github.sha }}
+      - uses: actions/download-artifact@v4
+        with:
+          name: ${{ inputs.artifact-name }}
+          path: dist
+      - name: Fetch the released runtime and SWIG for integration checks
+        if: inputs.xcomm-version != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          XCOMM_VERSION: ${{ inputs.xcomm-version }}
+        run: |
+          mkdir -p dependencies
+          gh release download "v${XCOMM_VERSION}" -R XS-MLVP/xcomm \
+            --pattern 'uc_xcomm-*.whl' --dir dependencies
+          python3 -m pip download --only-binary=:all: --no-deps \
+            --dest dependencies 'swig>=4.2.1,<5'
+      - name: Install and exercise the same wheel on the target platform
+        env:
+          TEST_IMAGE: ${{ matrix.image }}
+          TEST_PYTHON: ${{ matrix.python }}
+          EXPECTED_GLIBC: ${{ matrix.glibc }}
+          CHECK_PICKER_RUNTIME: ${{ inputs.xcomm-version != '' && '1' || '' }}
+        run: |
+          docker run --rm --network none \
+            -v "$PWD:/project:ro" -e EXPECTED_GLIBC -e TEST_PYTHON -e CHECK_PICKER_RUNTIME \
+            "$TEST_IMAGE" bash -euo pipefail -c '
+              /opt/python/$TEST_PYTHON/bin/python -m venv /tmp/picker-test
+              export PATH="/tmp/picker-test/bin:$PATH"
+              if [[ "$CHECK_PICKER_RUNTIME" == 1 ]]; then
+                python -m pip install --no-index --find-links /project/dependencies /project/dist/*.whl
+                python -m pip check
+              else
+                python -m pip install --no-index --no-deps /project/dist/*.whl
+              fi
+              /tmp/picker-test/bin/python /project/scripts/release/check_installed_picker.py
+            '

.github/workflows/release-build.yml

@@ -11,7 +11,7 @@ on:
         required: true
         type: string
       xcomm_version:
-        description: "Optional compatible xspcomm release; latest compatible is selected by default"
+        description: "Optional compatible uc-xcomm release; latest compatible is selected by default"
         required: false
         type: string
 
@@ -56,7 +56,7 @@ jobs:
           python scripts/release/tag_policy.py verify HEAD
           echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
           echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
-      - name: Select compatible xspcomm release
+      - name: Select compatible uc-xcomm release
         id: xcomm
         env:
           GH_TOKEN: ${{ github.token }}
@@ -70,11 +70,13 @@ jobs:
           import os
           import re
           import tomllib
+          from urllib.error import HTTPError
+          from urllib.request import urlopen
           from packaging.requirements import Requirement
 
           with open("pyproject.toml", "rb") as config:
               dependencies = tomllib.load(config)["project"]["dependencies"]
-          requirement = next(Requirement(dependency) for dependency in dependencies if Requirement(dependency).name == "xspcomm")
+          requirement = next(Requirement(dependency) for dependency in dependencies if Requirement(dependency).name == "uc-xcomm")
           with open("/tmp/xspcomm-releases.json") as source:
               releases = json.load(source)
           compatible = []
@@ -84,22 +86,38 @@ jobs:
                   continue
               version = tag[1:]
               if requirement.specifier.contains(version):
-                  compatible.append((tuple(map(int, version.split("."))), version))
+                  try:
+                      with urlopen(f"https://pypi.org/pypi/uc-xcomm/{version}/json", timeout=30) as response:
+                          published = json.load(response)
+                  except HTTPError as error:
+                      if error.code == 404:
+                          continue
+                      raise
+                  if any(not artifact["yanked"] for artifact in published["urls"]):
+                      compatible.append((tuple(map(int, version.split("."))), version))
           requested = os.environ["REQUESTED_VERSION"]
           if requested:
               if requested not in {version for _, version in compatible}:
-                  raise SystemExit(f"xspcomm v{requested} is not a compatible published release")
+                  raise SystemExit(f"uc-xcomm v{requested} is not a compatible published release")
               version = requested
           elif compatible:
               version = max(compatible)[1]
           else:
-              raise SystemExit(f"No published xspcomm release satisfies {requirement}")
+              raise SystemExit(f"No published uc-xcomm release satisfies {requirement}")
           with open(os.environ["GITHUB_OUTPUT"], "a") as output:
               print(f"version={version}", file=output)
-          print(f"Using xspcomm v{version}")
+          print(f"Using uc-xcomm v{version}")
           PY
-  wheel:
+  portable-wheel:
     needs: resolve
+    uses: ./.github/workflows/portable-wheel.yml
+    with:
+      ref: ${{ github.event.client_payload.tag || inputs.tag }}
+      artifact-name: picker-release-wheel
+      xcomm-version: ${{ needs.resolve.outputs.xcomm_version }}
+
+  wheel:
+    needs: [resolve, portable-wheel]
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
@@ -109,24 +127,18 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - name: Build Picker wheel
-        run: |
-          set -euo pipefail
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends \
-            build-essential cmake ninja-build bison flex gperf zlib1g-dev liblz4-dev
-          python -m pip install 'build>=1,<2'
-          XCOMM_SKIP_ALIGN=1 make init
-          export CMAKE_BUILD_PARALLEL_LEVEL="$(nproc)"
-          NO_BUILD_XSPCOMM=1 python -m build --wheel
-      - name: Download released xspcomm wheel
+      - uses: actions/download-artifact@v4
+        with:
+          name: picker-release-wheel
+          path: dist
+      - name: Download released uc-xcomm wheels
         env:
           GH_TOKEN: ${{ github.token }}
           XCOMM_VERSION: ${{ needs.resolve.outputs.xcomm_version }}
         run: |
           mkdir -p wheelhouse
           gh release download "v${XCOMM_VERSION}" \
-            -R XS-MLVP/xcomm --pattern '*.whl' --dir wheelhouse
+            -R XS-MLVP/xcomm --pattern 'uc_xcomm-*.whl' --dir wheelhouse
       - name: Install and verify released wheels
         env:
           PICKER_WHEEL_DIR: dist
@@ -135,11 +147,6 @@ jobs:
           XCOMM_VERSION_EXPECTED: ${{ needs.resolve.outputs.xcomm_version }}
           VERIFY_PYTHON: python
         run: bash scripts/build/verify-wheel.sh
-      - uses: actions/upload-artifact@v4
-        with:
-          name: picker-release-wheel
-          path: dist/*.whl
-          if-no-files-found: error
 
   native:
     needs: resolve

.github/workflows/release.yml

@@ -66,7 +66,7 @@ jobs:
           archives = [name for name in assets if name.endswith(".tar.gz")]
           assert len(wheels) == 1 and len(appimages) == 2 and len(archives) == 2
           assert assets == set(wheels + appimages + archives + ["RELEASE-MANIFEST.json", "SHA256SUMS"])
-          assert wheels[0].startswith(f"picker-{tag[1:]}-")
+          assert wheels[0].startswith(f"uc_picker-{tag[1:]}-")
           assert set(appimages) == {f"picker-{tag}-linux-{arch}.AppImage" for arch in ("x86_64", "aarch64")}
           assert set(archives) == {f"picker-{tag}-linux-{arch}.tar.gz" for arch in ("x86_64", "aarch64")}
           with open(os.environ["GITHUB_OUTPUT"], "a") as output:
@@ -92,3 +92,30 @@ jobs:
           files: release-assets/*
           fail_on_unmatched_files: true
           overwrite_files: true
+
+  pypi:
+    needs: publish
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/uc-picker
+    permissions:
+      actions: read
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: picker-release-bundle
+          run-id: ${{ inputs.run_id }}
+          github-token: ${{ github.token }}
+          path: verified-assets
+      - name: Select the verified Python distribution
+        run: |
+          (cd verified-assets && sha256sum --check SHA256SUMS)
+          mkdir dist
+          cp verified-assets/*.whl dist/
+      - name: Publish with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

CMakeLists.txt

@@ -31,6 +31,7 @@ if(is_top_level_project)
 endif()
 
 # options
+option(PICKER_REQUIRE_STATIC "Require a fully static Picker executable" OFF)
 option(CPPAST_BUILD_TEST "whether or not to build the tests" OFF)
 option(CPPAST_BUILD_EXAMPLE "whether or not to build the examples" OFF)
 option(CPPAST_BUILD_TOOL "whether or not to build the tool" OFF)
@@ -40,7 +41,7 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lib)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/bin)
 
 #dependencies
-if ("$ENV{NO_BUILD_XSPCOMM}" STREQUAL "")
+if (NOT SKBUILD AND "$ENV{NO_BUILD_XSPCOMM}" STREQUAL "")
 add_subdirectory(dependence/xcomm)
 # Cover pinned xcomm revisions as well as their SWIG consumers. Standalone
 # xcomm wheels are built separately by the wheel target in the Makefile.