# This workflow will build wheels for the major Python versions and test them on multiple distros

name: Build and Test Wheels

on:

release:

types: [published]

push:

branches: [ "main", "dev" ]

workflow_dispatch:

jobs:

build_wheels:

runs-on: ${{ matrix.os }}

strategy:

fail-fast: false # Allow all wheel builds to complete

matrix:

os: [ubuntu-24.04, ubuntu-24.04-arm]

steps:

- name: Checkout Repository

uses: actions/checkout@v4

- name: Build Wheels

uses: pypa/cibuildwheel@v3.2.1

- name: Upload Build Artifacts

uses: actions/upload-artifact@v4

with:

name: libdebug-manylinux-wheels-${{ runner.arch }}

path: ./wheelhouse/*.whl

test_wheels:

needs: build_wheels

runs-on: ${{ matrix.os }}

strategy:

fail-fast: false

matrix:

os: [ubuntu-24.04, ubuntu-24.04-arm]

distro:

- ubuntu:22.04

- ubuntu:24.04

- ubuntu:latest

- debian:12

- debian:sid

- fedora:40

- fedora:41

- fedora:42

- archlinux:latest

- opensuse/leap:15.6

- opensuse/tumbleweed:latest

- alpine:3.18

- alpine:3.20

- alpine:3.22

- alpine:latest

python_version: ["3.10", "3.11", "3.12", "3.13", "3.14"]

exclude:

# Alpine 3.18, only test with Python 3.11

- distro: alpine:3.18

python_version: "3.10"

- distro: alpine:3.18

python_version: "3.12"

- distro: alpine:3.18

python_version: "3.13"

- distro: alpine:3.18

python_version: "3.14"

# Alpine 3.20, only test with Python 3.12

- distro: alpine:3.20

python_version: "3.10"

- distro: alpine:3.20

python_version: "3.11"

- distro: alpine:3.20

python_version: "3.13"

- distro: alpine:3.20

python_version: "3.14"

# Alpine 3.22, only test with Python 3.12

- distro: alpine:3.22

python_version: "3.10"

- distro: alpine:3.22

python_version: "3.11"

- distro: alpine:3.22

python_version: "3.13"

- distro: alpine:3.22

python_version: "3.14"

# Alpine Latest, only test with Python 3.12

- distro: alpine:latest

python_version: "3.10"

- distro: alpine:latest

python_version: "3.11"

- distro: alpine:latest

python_version: "3.13"

- distro: alpine:latest

python_version: "3.14"

# Debian 12, only test with Python 3.11

- distro: debian:12

python_version: "3.10"

- distro: debian:12

python_version: "3.12"

- distro: debian:12

python_version: "3.13"

- distro: debian:12

python_version: "3.14"

# Debian Sid, only test with Python 3.13, and 3.14

- distro: debian:sid

python_version: "3.10"

- distro: debian:sid

python_version: "3.11"

- distro: debian:sid

python_version: "3.12"

# OpenSUSE Leap 15.6 does not support Python 3.13 or 3.14

- distro: opensuse/leap:15.6

python_version: "3.13"

- distro: opensuse/leap:15.6

python_version: "3.14"

# OpenSUSE Tumbleweed does not support Python 3.14

- distro: opensuse/tumbleweed:latest

python_version: "3.14"

# Arch Linux is not available on Arm

- distro: archlinux:latest

os: ubuntu-24.04-arm

# GitHub's CI doesn't work with Alpine on Arm

- distro: alpine:3.18

os: ubuntu-24.04-arm

- distro: alpine:3.20

os: ubuntu-24.04-arm

- distro: alpine:3.22

os: ubuntu-24.04-arm

- distro: alpine:latest

os: ubuntu-24.04-arm

container:

image: ${{ matrix.distro }}

options: --privileged

steps:

- name: Cache package managers

uses: actions/cache@v4

with:

path: |

/var/cache/apt

/var/lib/apt

/var/cache/dnf

/var/cache/yum

/var/cache/zypp

/var/cache/apk

~/.cache/pip

key: ${{ matrix.os}}-${{ matrix.distro }}-${{ matrix.python_version }}-packages-${{ github.sha }}

restore-keys: |

${{ matrix.os}}-${{ matrix.distro }}-${{ matrix.python_version }}-packages-

${{ matrix.os}}-${{ matrix.distro }}-packages-

- name: Install tar if needed

if: contains(matrix.distro, 'opensuse')

run: |

zypper --non-interactive --gpg-auto-import-keys refresh

zypper --non-interactive install -y tar gzip findutils

- name: Checkout code

uses: actions/checkout@v4

- name: Download Build Artifacts (x64)

if: matrix.os == 'ubuntu-24.04'

uses: actions/download-artifact@v4

with:

name: libdebug-manylinux-wheels-X64

path: ./wheels

- name: Download Build Artifacts (ARM64)

if: matrix.os == 'ubuntu-24.04-arm'

uses: actions/download-artifact@v4

with:

name: libdebug-manylinux-wheels-ARM64

path: ./wheels

- name: Install bash on Alpine Linux

if: contains(matrix.distro, 'alpine')

shell: sh

run: |

echo "Alpine detected. Installing bash..."

apk add --no-cache --quiet bash gcc python3-dev musl-dev linux-headers

- name: Install Python and dependencies (Ubuntu/Debian)

shell: bash

env:

DEBIAN_FRONTEND: noninteractive # For non-interactive apt-get

if: contains(matrix.distro, 'ubuntu') || contains(matrix.distro, 'debian')

run: |

apt-get update

apt-get install -y --no-install-recommends software-properties-common curl gpg-agent libc6-dbg

# Install Python from deadsnakes PPA for newer versions

if [[ "${{ matrix.distro }}" == "ubuntu"* ]]; then

add-apt-repository ppa:deadsnakes/ppa -y

apt-get update

fi

apt-get install -y --no-install-recommends python${{ matrix.python_version }} python${{ matrix.python_version }}-venv

if [[ "${{ matrix.distro }}" == "ubuntu:20.04" ]]; then

python${{ matrix.python_version }} -m ensurepip

python${{ matrix.python_version }} -m pip install --upgrade pip wheel

fi

- name: Install Python and dependencies (Fedora)

if: contains(matrix.distro, 'fedora')

run: |

dnf update -y

dnf install -y python${{ matrix.python_version }}

python${{ matrix.python_version }} -m ensurepip

python${{ matrix.python_version }} -m pip install --upgrade pip wheel

- name: Install Python and dependencies (Arch Linux)

if: contains(matrix.distro, 'archlinux')

run: |

pacman -Syu --noconfirm

pacman -S --noconfirm --needed sudo git base-devel pyenv

eval "$(pyenv init -)"

pyenv install ${{ matrix.python_version }}

pyenv global ${{ matrix.python_version }}

- name: Install Python and dependencies (openSUSE)

if: contains(matrix.distro, 'opensuse')

run: |

zypper refresh

zypper install -y python$(echo "${{ matrix.python_version }}" | tr -d '.') python$(echo "${{ matrix.python_version }}" | tr -d '.')-curses

if [[ "${{ matrix.distro }}" == "opensuse/leap:15.6" ]]; then

python${{ matrix.python_version }} -m ensurepip

python${{ matrix.python_version }} -m pip install --upgrade pip wheel

elif [[ "${{ matrix.python_version }}" == "3.10" ]]; then

# On tumbleweed, distro-managed Python packages is enabled from >= 3.11 for some reason

python${{ matrix.python_version }} -m ensurepip

python${{ matrix.python_version }} -m pip install --upgrade pip wheel

else

zypper install -y python$(echo "${{ matrix.python_version }}" | tr -d '.')-pip

fi

- name: Install Python and dependencies (Alpine)

if: contains(matrix.distro, 'alpine')

run: |

apk update

apk add python3 py3-pip

- name: List available wheels

run: |

ls -la ./wheels/

echo "Available wheel files:"

find ./wheels/ -name "*.whl" -type f

- name: Create a Virtual Environment

shell: bash

run: |

if [[ "${{ matrix.distro }}" == "arch"* ]]; then

eval "$(pyenv init -)"

pyenv global ${{ matrix.python_version }}

fi

python${{ matrix.python_version }} -m venv venv

- name: Install and test wheel (All other distros - manylinux)

shell: bash

if: "!contains(matrix.distro, 'alpine')"

run: |

source venv/bin/activate

#

# Get Python version without dot (e.g., "3.11" -> "311")

PY_VER_NODOT=$(echo "${{ matrix.python_version }}" | tr -d '.')

#

# Get architecture mapping

ARCH=$(uname -m)

if [ "$ARCH" = "x86_64" ]; then

WHEEL_ARCH="x86_64"

elif [ "$ARCH" = "i686" ] || [ "$ARCH" = "i386" ]; then

WHEEL_ARCH="i686"

elif [ "$ARCH" = "aarch64" ]; then

WHEEL_ARCH="aarch64"

else

echo "Unsupported architecture: $ARCH"

exit 1

fi

#

echo "Looking for wheel with Python ${{ matrix.python_version }} (${PY_VER_NODOT}) on ${WHEEL_ARCH}"

#

# Try to find specific Python version wheel first (cp310, cp311, etc.)

WHEEL_FILE=$(find ./wheels/ -name "*manylinux*" -name "*cp${PY_VER_NODOT}-cp${PY_VER_NODOT}*" -name "*${WHEEL_ARCH}*" -type f | head -1)

#

# If not found, try to find abi3 wheel that's compatible (cp312-abi3 works for Python 3.12+)

if [ -z "$WHEEL_FILE" ] && [ "${{ matrix.python_version }}" != "3.10" ] && [ "${{ matrix.python_version }}" != "3.11" ]; then

echo "Specific wheel not found, trying abi3 wheel..."

WHEEL_FILE=$(find ./wheels/ -name "*manylinux*" -name "*cp312-abi3*" -name "*${WHEEL_ARCH}*" -type f | head -1)

fi

#

if [ -z "$WHEEL_FILE" ]; then

echo "No compatible manylinux wheel found for Python ${{ matrix.python_version }} on ${WHEEL_ARCH}"

echo "Available wheels:"

ls -la ./wheels/

exit 1

fi

#

echo "Installing manylinux wheel: $WHEEL_FILE"

python${{ matrix.python_version }} -m pip install "$WHEEL_FILE"

#

# Change Directory

cd test

# Basic import test

python${{ matrix.python_version }} -c "import libdebug; print('libdebug imported successfully on glibc-based distro')"

- name: Install and test wheel (Alpine - musllinux)

shell: bash

if: contains(matrix.distro, 'alpine')

run: |

source venv/bin/activate

#

# Get Python version without dot (e.g., "3.11" -> "311")

PY_VER_NODOT=$(echo "${{ matrix.python_version }}" | tr -d '.')

#

# Get architecture mapping

ARCH=$(uname -m)

if [ "$ARCH" = "x86_64" ]; then

WHEEL_ARCH="x86_64"

elif [ "$ARCH" = "i686" ] || [ "$ARCH" = "i386" ]; then

WHEEL_ARCH="i686"

elif [ "$ARCH" = "aarch64" ]; then

WHEEL_ARCH="aarch64"

else

echo "Unsupported architecture: $ARCH"

exit 1

fi

#

echo "Looking for musllinux wheel with Python ${{ matrix.python_version }} (${PY_VER_NODOT}) on ${WHEEL_ARCH}"

#

# Try to find specific Python version wheel first (cp310, cp311, etc.)

WHEEL_FILE=$(find ./wheels/ -name "*musllinux*" -name "*cp${PY_VER_NODOT}-cp${PY_VER_NODOT}*" -name "*${WHEEL_ARCH}*" -type f | head -1)

#

# If not found, try to find abi3 wheel that's compatible (cp312-abi3 works for Python 3.12+)

if [ -z "$WHEEL_FILE" ] && [ "${{ matrix.python_version }}" != "3.10" ] && [ "${{ matrix.python_version }}" != "3.11" ]; then

echo "Specific wheel not found, trying abi3 wheel..."

WHEEL_FILE=$(find ./wheels/ -name "*musllinux*" -name "*cp312-abi3*" -name "*${WHEEL_ARCH}*" -type f | head -1)

fi

#

if [ -z "$WHEEL_FILE" ]; then

echo "No compatible musllinux wheel found for Python ${{ matrix.python_version }} on ${WHEEL_ARCH}"

echo "Available wheels:"

ls -la ./wheels/

exit 1

fi

#

echo "Installing musllinux wheel: $WHEEL_FILE"

python3 -m pip install "$WHEEL_FILE"

#

# Change Directory

cd test

# Basic import test

python3 -c "import libdebug; print('libdebug imported successfully on Alpine/musl')"

- name: Install Python build tools and test dependencies

shell: bash

run: |

source venv/bin/activate

if [[ "${{ matrix.python_version }}" == "3.14" ]]; then

# For Python 3.14, manually install pwntools dependencies to avoid unicorn version conflicts

python3 -m pip install paramiko mako pyelftools capstone ropgadget pyserial requests pip pygments pysocks python-dateutil packaging psutil intervaltree sortedcontainers rpyc colored_traceback unix-ar zstandard

# Install unicorn (unicorn 2.1.3 and 2.1.4 have some issues, but are fine for our purposes)

python3 -m pip install "unicorn>=2.0.1"

# Install pwntools without dependencies

python3 -m pip install --no-deps pwntools

# Install other test dependencies

python3 -m pip install pytest requests objgraph

else

python3 -m pip install pytest pwntools requests objgraph

fi

if [[ "${{ matrix.distro_image }}" == "opensuse/tumbleweed:latest" ]]; then

zypper --non-interactive install -y python313-curses

fi

- name: Run comprehensive tests

shell: bash

if: "!contains(matrix.distro, 'alpine') && matrix.distro != 'ubuntu:20.04'"

run: |

source venv/bin/activate

echo "Testing on ${{ matrix.distro }} with Python ${{ matrix.python_version }} (${{ matrix.os }})"

echo "Kernel version: $(uname -r)"

echo "Architecture: $(uname -m)"

echo "Distribution info:"

if command -v lsb_release &> /dev/null; then

lsb_release -a

elif [ -f /etc/os-release ]; then

cat /etc/os-release

fi

cd test && python3 -m pytest --ignore=other_tests --ignore scripts/atexit_handler_test.py