Merge remote-tracking branch 'origin/upstreams/develop' into merge

.github/workflows/ci.yml

@@ -1,27 +1,54 @@
 name: CI
 
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      test_all_python_versions:
+        description: "Run tests on all Python versions"
+        type: boolean
+        default: false
+        required: true
+  workflow_call:
+    inputs:
+      test_all_python_versions:
+        description: "Run tests on all Python versions"
+        type: boolean
+        default: false
+        required: true
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    # We're stuck on Ubuntu 20.04 as long as we want to keep testing on Python
+    # 3.6 due to actions/setup-python#544.
+    runs-on: ubuntu-20.04
     strategy:
       matrix:
-        python-version: ['3.10', '3.9', '3.8', '3.7', '3.6']
+        python-version: ${{ (github.event_name == 'push' || inputs.test_all_python_versions)
+                            && fromJSON('["3.12", "3.11", "3.10", "3.9", "3.8", "3.7", "3.6"]')
+                            || fromJSON('["3.11", "3.6"]')}}
         cc: [gcc, clang]
       fail-fast: false
     env:
       CC: ${{ matrix.cc }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
       - name: Install dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install libelf-dev libdw-dev qemu-kvm zstd ${{ matrix.cc == 'clang' && 'libomp-$(clang --version | sed -rn "s/.*clang version ([0-9]+).*/\\1/p")-dev' || '' }}
+          sudo apt-get install dwarves libelf-dev libdw-dev qemu-kvm zstd ${{ matrix.cc == 'clang' && 'libomp-$(clang --version | sed -rn "s/.*clang version ([0-9]+).*/\\1/p")-dev' || '' }}
           pip install pyroute2 pre-commit
       - name: Generate version.py
         run: python setup.py --version
@@ -33,9 +60,11 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
       - name: Install dependencies
         run: pip install pre-commit
       - name: Run pre-commit hooks

.github/workflows/dco-check.yml

@@ -4,6 +4,10 @@ on:
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   check:
     if: ${{ !github.event.pull_request.draft }}

.github/workflows/pull_request.yml

@@ -0,0 +1,16 @@
+name: Pull Request CI
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - labeled
+
+jobs:
+  test:
+    uses: ./.github/workflows/ci.yml
+    if: ${{ github.event.action != 'labeled' || github.event.label.name == 'test-all-python-versions' }}
+    with:
+      test_all_python_versions: ${{ contains(github.event.pull_request.labels.*.name, 'test-all-python-versions') }}

.github/workflows/vmtest-build.yml

@@ -7,22 +7,37 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        flavor: [default, alternative, tiny]
+        arch: [x86_64, aarch64, ppc64, s390x, arm]
+      fail-fast: false
+      max-parallel: 5
+    # Build on 20.04 so that we don't get host binaries (e.g., objtool) that
+    # depend on libraries too new for other distros.
+    runs-on: ubuntu-20.04
+    permissions:
+      contents: write
     env:
       GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Install dependencies
         run: |
           sudo apt-get update
           sudo apt-get install dwarves libelf-dev
           pip install aiohttp uritemplate
-      - name: Build and upload assets
-        run: python3 -m vmtest.manage --kernel-directory build/vmtest/linux.git --build-directory build/vmtest/kbuild -K
+      - name: Build and upload ${{ matrix.arch }} ${{ matrix.flavor }} kernels
+        run: python3 -m vmtest.manage --kernel-directory build/vmtest/linux.git --build-directory build/vmtest/kbuild -K -a ${{ matrix.arch }} -f ${{ matrix.flavor }}
       - name: Upload kernel build logs
         if: always()
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: kernel-build-logs
           path: build/vmtest/kbuild/*.log
           if-no-files-found: ignore
+  test:
+    needs: build
+    uses: ./.github/workflows/ci.yml
+    with:
+      test_all_python_versions: true

.packit.yaml

@@ -2,7 +2,7 @@
 # https://packit.dev/docs/configuration/
 
 specfile_path: python-drgn.spec
-synced_files:
+files_to_sync:
   - python-drgn.spec
   - .packit.yaml
 
@@ -13,55 +13,60 @@ actions:
   # Fetch the specfile from Rawhide, drop any patches and disable rpmautospec
   post-upstream-clone: "bash -c \"curl -s https://src.fedoraproject.org/rpms/python-drgn/raw/main/f/python-drgn.spec | sed -e '/^Patch[0-9]/d' -e '/^%autochangelog$/d' > python-drgn.spec\""
 
+srpm_build_deps:
+  - bash
+  - curl
+  - python3-setuptools
+  - sed
+
 jobs:
 - job: copr_build
   trigger: commit
-  metadata:
-    owner: "@meta"
-    project: drgn
-    targets:
-      - fedora-all-aarch64
-      - fedora-all-armhfp
-      - fedora-all-i386
-      - fedora-all-ppc64le
-      - fedora-all-s390x
-      - fedora-all-x86_64
-      - fedora-eln-aarch64
-      - fedora-eln-i386
-      - fedora-eln-ppc64le
-      - fedora-eln-s390x
-      - fedora-eln-x86_64
-      - epel-8-aarch64
-      - epel-8-ppc64le
-      - epel-8-s390x
-      - epel-8-x86_64
-      - epel-9-aarch64
-      - epel-9-ppc64le
-      - epel-9-s390x
-      - epel-9-x86_64
+  owner: "@meta"
+  project: drgn
+  targets:
+    - fedora-all-aarch64
+    # Disabled due to https://bugzilla.redhat.com/show_bug.cgi?id=2152259.
+    # - fedora-all-armhfp
+    - fedora-all-i386
+    - fedora-all-ppc64le
+    - fedora-all-s390x
+    - fedora-all-x86_64
+    - fedora-eln-aarch64
+    - fedora-eln-i386
+    - fedora-eln-ppc64le
+    - fedora-eln-s390x
+    - fedora-eln-x86_64
+    - epel-8-aarch64
+    - epel-8-ppc64le
+    - epel-8-s390x
+    - epel-8-x86_64
+    - epel-9-aarch64
+    - epel-9-ppc64le
+    - epel-9-s390x
+    - epel-9-x86_64
 
 - job: copr_build
   trigger: pull_request
-  metadata:
-    owner: "@meta"
-    project: drgn
-    targets:
-      - fedora-all-aarch64
-      - fedora-all-armhfp
-      - fedora-all-i386
-      - fedora-all-ppc64le
-      - fedora-all-s390x
-      - fedora-all-x86_64
-      - fedora-eln-aarch64
-      - fedora-eln-i386
-      - fedora-eln-ppc64le
-      - fedora-eln-s390x
-      - fedora-eln-x86_64
-      - epel-8-aarch64
-      - epel-8-ppc64le
-      - epel-8-s390x
-      - epel-8-x86_64
-      - epel-9-aarch64
-      - epel-9-ppc64le
-      - epel-9-s390x
-      - epel-9-x86_64
+  owner: "@meta"
+  project: drgn
+  targets:
+    - fedora-all-aarch64
+    # - fedora-all-armhfp
+    - fedora-all-i386
+    - fedora-all-ppc64le
+    - fedora-all-s390x
+    - fedora-all-x86_64
+    - fedora-eln-aarch64
+    - fedora-eln-i386
+    - fedora-eln-ppc64le
+    - fedora-eln-s390x
+    - fedora-eln-x86_64
+    - epel-8-aarch64
+    - epel-8-ppc64le
+    - epel-8-s390x
+    - epel-8-x86_64
+    - epel-9-aarch64
+    - epel-9-ppc64le
+    - epel-9-s390x
+    - epel-9-x86_64

.readthedocs.yml → .readthedocs.yaml

@@ -1,4 +1,8 @@
 version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3"
 sphinx:
   configuration: docs/conf.py
 python:

CONTRIBUTING.rst

@@ -49,7 +49,6 @@ Coding Guidelines
 * Core functionality should be implemented in ``libdrgn`` and exposed to Python
   via the `C extension <libdrgn/python>`_. Only the CLI and helpers should be
   in pure Python.
-* Linux kernel helpers should work on all supported kernels if possible.
 
 C
 ^
@@ -107,6 +106,61 @@ and `isort <https://github.com/PyCQA/isort>`_ and checked with `flake8
 Type hints should be provided for all interfaces (including helpers and the C
 extension).
 
+Linux Kernel Helpers
+^^^^^^^^^^^^^^^^^^^^
+
+Linux kernel helpers should work on all `supported kernels
+<https://drgn.readthedocs.io/en/latest/support_matrix.html#linux-kernel-versions>`_
+if possible. This may require handling changes between kernel releases.
+
+* Do NOT check the kernel version number to do this; Linux distributions often
+  backport changes without updating the version number. Instead, use the
+  presence or absence of variables, types, structure members, etc.
+* Optimize for the latest kernel release, and follow "easier to ask for
+  forgiveness than permission" (`EAFP
+  <https://docs.python.org/3/glossary.html#term-EAFP>`_). For example, assume
+  that a structure member from the latest release exists and catch the
+  exception if it doesn't.
+* Reference the diverging commit and version number in the format ``Linux
+  kernel commit $abbreviated_commit_hash "$commit_subject" (in
+  v$kernel_version)``.
+
+  For example:
+
+  .. code-block:: python3
+
+      # Since Linux kernel commit 2f064a59a11f ("sched: Change
+      # task_struct::state") (in v5.14), the task state is named "__state".
+      # Before that, it is named "state".
+      try:
+          return task.__state
+      except AttributeError:
+          return task.state
+
+  NOT:
+
+  .. code-block:: python3
+
+      # BAD
+      if hasattr(task, "state"):
+          return task.state
+      else:
+          return task.__state
+
+* Document the expected C types of arguments and return values. For example:
+
+  .. code-block:: python3
+
+      def cgroup_parent(cgrp: Object) -> Object:
+          """
+          Return the parent cgroup of the given cgroup if it exists, ``NULL``
+          otherwise.
+
+          :param cgrp: ``struct cgroup *``
+          :return: ``struct cgroup *``
+          """
+          ...
+
 pre-commit
 ^^^^^^^^^^