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

Author: sebroy

.github/workflows/ci.yml

@@ -35,14 +35,12 @@ concurrency:
 
 jobs:
   test:
-    # 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
+    runs-on: ubuntu-22.04
     strategy:
       matrix:
         python-version: ${{ (github.event_name == 'push' || inputs.test_all_python_versions)
-                            && fromJSON('["3.13", "3.12", "3.11", "3.10", "3.9", "3.8", "3.7", "3.6"]')
-                            || fromJSON('["3.12", "3.6"]')}}
+                            && fromJSON('["3.14", "3.13", "3.12", "3.11", "3.10", "3.9", "3.8"]')
+                            || fromJSON('["3.13", "3.8"]')}}
         cc: [gcc, clang]
       fail-fast: false
     env:
@@ -55,21 +53,18 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
-      - name: Check Python version for pre-commit
-        # Only run pre-commit / mypy on upstream supported Python versions
-        run: |
-          if [[ "${{ matrix.python-version }}" =~ ^3\.([89]|[0-9][0-9])$ ]]; then
-              echo USE_PRE_COMMIT=1 >> $GITHUB_ENV
-          fi
       - name: Install dependencies
         run: |
           sudo apt-get update -y
           sudo apt-get install -y btrfs-progs check 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 setuptools ${USE_PRE_COMMIT/1/pre-commit}
+          # pyroute2 0.9.1 dropped support for Python < 3.9.
+          if [[ "${{ matrix.python-version }}" =~ ^3\.[678]$ ]]; then
+              pyroute2_version="<0.9.1"
+          fi
+          pip install "pyroute2$pyroute2_version" setuptools pre-commit
       - name: Generate version.py
         run: python setup.py --version
       - name: Check with mypy
-        if: ${{ env.USE_PRE_COMMIT == '1' }}
         run: pre-commit run --all-files mypy
       - name: Build and test with ${{ matrix.cc }}
         run: CONFIGURE_FLAGS="--enable-compiler-warnings=error" python setup.py test -K ${{ inputs.test_all_kernel_flavors && '-F' || '' }}

.github/workflows/dco-check.yml

@@ -18,14 +18,22 @@ jobs:
           git init
           git fetch --filter=blob:none "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY" "$GITHUB_BASE_REF" "$GITHUB_REF"
       - name: Check for DCO sign-offs
+        shell: bash
         run: |
-          no_sign_off="$(git log --no-merges --grep=Signed-off-by --invert-grep "FETCH_HEAD..$GITHUB_SHA")"
-          if [ -z "$no_sign_off" ]; then
+          status=0
+          while read -r commit; do
+              author="$(git show --no-patch --pretty='format:%an <%ae>' "$commit")"
+              if ! git show --no-patch --pretty='format:%(trailers:key=Signed-off-by,valueonly)' "$commit" | grep -Fxq "$author"; then
+                  if [ $status -eq 0 ]; then
+                      echo "The following commits are missing a Developer Certificate of Origin sign-off;"
+                      echo "see https://github.com/osandov/drgn/blob/main/CONTRIBUTING.rst#signing-off"
+                      echo
+                  fi
+                  status=1
+                  git show --no-patch "$commit"
+              fi
+          done < <(git rev-list --no-merges "FETCH_HEAD..$GITHUB_SHA")
+          if [ $status -eq 0 ]; then
               echo "All commits have a Developer Certificate of Origin sign-off"
-          else
-              echo "The following commits are missing a Developer Certificate of Origin sign-off;"
-              echo "see https://github.com/osandov/drgn/blob/main/CONTRIBUTING.rst#signing-off"
-              echo
-              echo "$no_sign_off"
-              exit 1
           fi
+          exit $status

.github/workflows/vmtest-build.yml

@@ -13,9 +13,7 @@ jobs:
         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
+    runs-on: ubuntu-22.04
     permissions:
       contents: write
     env:

.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+exclude: ^contrib/
+repos:
+-   repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+    -   id: isort
+        name: isort (python)
+-   repo: https://github.com/psf/black
+    rev: 24.8.0
+    hooks:
+    -   id: black
+        exclude: ^docs/exts/details\.py$
+-   repo: https://github.com/pycqa/flake8
+    rev: 7.1.2
+    hooks:
+    -   id: flake8
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+    -   id: mypy
+        args: [--show-error-codes, --strict, --no-warn-return-any]
+        files: ^(drgn/.*\.py|_drgn.pyi|_drgn_util/.*\.py|tools/.*\.py)$
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+    -   id: trailing-whitespace
+        exclude_types: [diff]
+    -   id: end-of-file-fixer
+        exclude_types: [diff]
+    -   id: check-yaml
+    -   id: check-added-large-files
+    -   id: debug-statements
+    -   id: check-merge-conflict
+-   repo: https://github.com/netromdk/vermin
+    rev: v1.6.0
+    hooks:
+    -   id: vermin
+        args: ['-t=3.8-', '--violations', '--eval-annotations']

.readthedocs.yaml

@@ -3,6 +3,8 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3"
+  apt_packages:
+    - graphviz
 sphinx:
   configuration: docs/conf.py
 python:

CONTRIBUTING.rst

@@ -18,12 +18,11 @@ instructions <README.rst#from-source>`_, then run:
     $ CONFIGURE_FLAGS="--enable-compiler-warnings=error" python3 setup.py build_ext -i
     $ python3 -m drgn --help
 
-Drgn can build, run, and pass its test suite on Python 3.6 or later. However,
+Drgn can build, run, and pass its test suite on Python 3.8 or later. However,
 many of the tools used as part of the development workflow do not support Python
 versions once they have reached their end-of-life. Thus, your main drgn
 development environment should use a Python version which is actively supported
-upstream. In particular, the drgn development workflow no longer supported on
-Python 3.6.
+upstream.
 
 Testing
 -------
@@ -74,9 +73,6 @@ Or you can run them manually:
 
     $ pre-commit run --all-files
 
-Please remember that these pre-commit hooks do not support Python 3.6; they
-require a Python major version which is actively supported upstream.
-
 Coding Guidelines
 -----------------
 
@@ -189,7 +185,7 @@ drgn assumes some `implementation-defined behavior
 Python
 ^^^^^^
 
-Python code in drgn should be compatible with Python 3.6 and newer.
+Python code in drgn should be compatible with Python 3.8 and newer.
 
 Python code is formatted with `Black <https://github.com/psf/black>`_ and
 `isort <https://github.com/PyCQA/isort>`_.

README.rst

@@ -66,17 +66,17 @@ Package Manager
 
 drgn can be installed using the package manager on some Linux distributions.
 
-.. image:: https://repology.org/badge/vertical-allrepos/drgn.svg
+.. image:: https://repology.org/badge/vertical-allrepos/drgn.svg?exclude_unsupported=1
     :target: https://repology.org/project/drgn/versions
     :alt: Packaging Status
 
-* Fedora >= 32
+* Fedora, RHEL/CentOS Stream >= 9
 
   .. code-block:: console
 
       $ sudo dnf install drgn
 
-* RHEL/CentOS >= 8
+* RHEL/CentOS < 9
 
   `Enable EPEL <https://docs.fedoraproject.org/en-US/epel/#_quickstart>`_. Then:
 
@@ -86,32 +86,35 @@ drgn can be installed using the package manager on some Linux distributions.
 
 * Oracle Linux >= 8
 
-  Enable the ``ol8_addons`` or ``ol9_addons`` repository and install drgn:
+  Enable the ``ol8_addons`` or ``ol9_addons`` repository. Then:
 
   .. code-block:: console
 
       $ sudo dnf config-manager --enable ol8_addons  # OR: ol9_addons
       $ sudo dnf install drgn
 
-  Drgn is also available for Python versions in application streams. For
+  drgn is also available for Python versions in application streams. For
   example, use ``dnf install python3.12-drgn`` to install drgn for Python 3.12.
   See the documentation for drgn in `Oracle Linux 9
   <https://docs.oracle.com/en/operating-systems/oracle-linux/9/drgn/how_to_install_drgn.html>`_
   and `Oracle Linux 8
   <https://docs.oracle.com/en/operating-systems/oracle-linux/8/drgn/how_to_install_drgn.html>`_
   for more information.
 
-* Arch Linux
+* Debian >= 12 (Bookworm)/Ubuntu >= 24.04 (Noble Numbat)
 
   .. code-block:: console
 
-      $ sudo pacman -S drgn
+      $ sudo apt install python3-drgn
 
-* Debian >= 12 (Bookworm)
+  To get the latest version on Ubuntu, enable the `michel-slm/kernel-utils PPA
+  <https://launchpad.net/~michel-slm/+archive/ubuntu/kernel-utils>`_ first.
+
+* Arch Linux
 
   .. code-block:: console
 
-    $ sudo apt install python3-drgn
+      $ sudo pacman -S drgn
 
 * Gentoo
 
@@ -125,15 +128,6 @@ drgn can be installed using the package manager on some Linux distributions.
 
       $ sudo zypper install python3-drgn
 
-* Ubuntu
-
-  Enable the `michel-slm/kernel-utils PPA <https://launchpad.net/~michel-slm/+archive/ubuntu/kernel-utils>`_.
-  Then:
-
-  .. code-block:: console
-
-      $ sudo apt install python3-drgn
-
 pip
 ^^^
 
@@ -152,27 +146,29 @@ This will install a binary wheel by default. If you get a build error, then pip
 wasn't able to use the binary wheel. Install the dependencies listed `below
 <#from-source>`_ and try again.
 
-Note that RHEL/CentOS 6, Debian Stretch, Ubuntu Trusty, and Ubuntu Xenial (and
-older) ship Python versions which are too old. Python 3.6 or newer must be
-installed.
+Note that RHEL/CentOS 7, Debian 10 ("buster"), and Ubuntu 18.04 ("Bionic
+Beaver") (and older) ship Python versions which are too old. Python 3.8 or
+newer must be installed.
+
+.. _installation-from-source:
 
 From Source
 ^^^^^^^^^^^
 
 To get the development version of drgn, you will need to build it from source.
 First, install dependencies:
 
-* Fedora
+* Fedora, RHEL/CentOS Stream >= 9
 
   .. code-block:: console
 
-      $ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
+      $ sudo dnf install autoconf automake check-devel elfutils-debuginfod-client-devel elfutils-devel gcc git libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel
 
-* RHEL/CentOS/Oracle Linux
+* RHEL/CentOS < 9, Oracle Linux
 
   .. code-block:: console
 
-      $ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
+      $ sudo dnf install autoconf automake check-devel elfutils-devel gcc git libtool make pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel
 
   Optionally, install ``libkdumpfile-devel`` from EPEL on RHEL/CentOS >= 8 or
   install `libkdumpfile <https://github.com/ptesarik/libkdumpfile>`_ from
@@ -191,28 +187,29 @@ First, install dependencies:
 
   .. code-block:: console
 
-      $ sudo apt install autoconf automake check gcc git liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev
+      $ sudo apt install autoconf automake check gcc git libdebuginfod-dev libkdumpfile-dev liblzma-dev libelf-dev libdw-dev libtool make pkgconf python3 python3-dev python3-pip python3-setuptools zlib1g-dev
 
-  Optionally, install libkdumpfile from source if you want support for the
-  makedumpfile format.
+  On Debian <= 11 (Bullseye) and Ubuntu <= 22.04 (Jammy Jellyfish),
+  ``libkdumpfile-dev`` is not available, so you must install libkdumpfile from
+  source if you want support for the makedumpfile format.
 
 * Arch Linux
 
   .. code-block:: console
 
-      $ sudo pacman -S --needed autoconf automake check gcc git libelf libkdumpfile libtool make pkgconf python python-pip python-setuptools
+      $ sudo pacman -S --needed autoconf automake check gcc git libelf libkdumpfile libtool make pkgconf python python-pip python-setuptools xz
 
 * Gentoo
 
   .. code-block:: console
 
-      $ sudo emerge --noreplace --oneshot dev-build/autoconf dev-build/automake dev-libs/check dev-libs/elfutils sys-devel/gcc dev-vcs/git dev-libs/libkdumpfile dev-build/libtool dev-build/make dev-python/pip virtual/pkgconfig dev-lang/python dev-python/setuptools
+      $ sudo emerge --noreplace --oneshot dev-build/autoconf dev-build/automake dev-libs/check dev-libs/elfutils sys-devel/gcc dev-vcs/git dev-libs/libkdumpfile dev-build/libtool dev-build/make dev-python/pip virtual/pkgconfig dev-lang/python dev-python/setuptools app-arch/xz-utils
 
 * openSUSE
 
   .. code-block:: console
 
-      $ sudo zypper install autoconf automake check-devel gcc git libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools
+      $ sudo zypper install autoconf automake check-devel gcc git libdebuginfod-devel libdw-devel libelf-devel libkdumpfile-devel libtool make pkgconf python3 python3-devel python3-pip python3-setuptools xz-devel
 
 Then, run:
 
@@ -233,20 +230,20 @@ Quick Start
 
 .. start-quick-start
 
-drgn debugs the running kernel by default; run ``sudo drgn``. To debug a
-running program, run ``sudo drgn -p $PID``. To debug a core dump (either a
-kernel vmcore or a userspace core dump), run ``drgn -c $PATH``. Make sure to
-`install debugging symbols
+drgn debugs the running kernel by default; simply run ``drgn``. To debug a
+running program, run ``drgn -p $PID``. To debug a core dump (either a kernel
+vmcore or a userspace core dump), run ``drgn -c $PATH``. Make sure to `install
+debugging symbols
 <https://drgn.readthedocs.io/en/latest/getting_debugging_symbols.html>`_ for
 whatever you are debugging.
 
-Then, you can access variables in the program with ``prog['name']`` and access
+Then, you can access variables in the program with ``prog["name"]`` and access
 structure members with ``.``:
 
 .. code-block:: pycon
 
-    $ sudo drgn
-    >>> prog['init_task'].comm
+    $ drgn
+    >>> prog["init_task"].comm
     (char [16])"swapper/0"
 
 You can use various predefined helpers:
@@ -260,14 +257,14 @@ You can use various predefined helpers:
     [b'findmnt', b'-p']
 
 You can get stack traces with ``stack_trace()`` and access parameters or local
-variables with ``trace['name']``:
+variables with ``trace["name"]``:
 
 .. code-block:: pycon
 
     >>> trace = stack_trace(task)
     >>> trace[5]
     #5 at 0xffffffff8a5a32d0 (do_sys_poll+0x400/0x578) in do_poll at ./fs/select.c:961:8 (inlined)
-    >>> poll_list = trace[5]['list']
+    >>> poll_list = trace[5]["list"]
     >>> file = fget(task, poll_list.entries[0].fd)
     >>> d_path(file.f_path.address_of_())
     b'/proc/115/mountinfo'