[GR-65446] Add an ABI check github job

msimacek · msimacek · commit f35bfbf64613 · 2026-03-18T16:44:40.000Z
PullRequest: graalpython/4308
diff --git a/.github/workflows/ci-unittests.yml b/.github/workflows/ci-unittests.yml
@@ -5,6 +5,36 @@ on:
   workflow_dispatch:
 
 jobs:
+  abi-check:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install libabigail
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y abigail-tools
+
+      - name: Get mx and labsjdk
+        shell: bash
+        run: |
+          git config --global http.timeout 600
+          git clone https://github.com/graalvm/mx
+          ./mx/mx fetch-jdk -A --jdk-id labsjdk-ce-latest
+
+      - name: Setup mx and JAVA_HOME
+        shell: bash
+        run: |
+          echo "$(pwd)/mx/" >> "$GITHUB_PATH"
+          echo "JAVA_HOME=$HOME/.mx/jdks/labsjdk-ce-latest" >> "$GITHUB_ENV"
+          echo "JVMCI_VERSION_CHECK=ignore" >> "$GITHUB_ENV"
+
+      - name: Run abi-check
+        shell: bash
+        run: mx abi-check
+
   build-standalone-artifacts:
     if: github.event.pull_request.draft == false && success()
     uses: ./.github/workflows/ci-matrix-gen.yml
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -42,4 +42,5 @@ repos:
   - id: check-toml
     exclude: '^graalpython/lib-python/.*'
   - id: check-added-large-files
+    exclude: '^abi/abi-.*\.xml'
   - id: check-symlinks
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,7 +1,8 @@
 # PROJECT KNOWLEDGE BASE
 
 ## OVERVIEW
-GraalPy (GraalVM Python) implementation: Java (Truffle) + C (CPython C-API compatibility) + Python stdlib/overrides, built and tested via the `mx` build tool.
+GraalPy is an alternative implementation of Python. The reference implementation of Python is CPython and GraalPy aims to be as compatible with CPython as possible.
+It consists of: Java (Truffle) + C (CPython C-API compatibility) + Python stdlib/overrides, built and tested via the `mx` build tool.
 
 ## STRUCTURE
 ```text
diff --git a/abi/abi-graalpy250.xml b/abi/abi-graalpy250.xml
diff --git a/abi/suppressions-base.ini b/abi/suppressions-base.ini
@@ -0,0 +1,9 @@
+[suppress_function]
+  label = GraalPy private symbols
+  symbol_name_regexp = ^GraalPyPrivate.*
+  drop = true
+
+[suppress_variable]
+  label = GraalPy private symbols
+  symbol_name_regexp = ^GraalPyPrivate.*
+  drop = true
diff --git a/abi/suppressions-graalpy250.ini b/abi/suppressions-graalpy250.ini
@@ -0,0 +1,4 @@
+[suppress_variable]
+  label = Removed ctypes private exported type objects
+  symbol_name_regexp = ^(PyCArrayType_Type|PyCData_Type|PyCPointerType_Type|PyCSimpleType|PyCStructType_Type|Simple_Type|UnionType_Type)$
+  drop = true
diff --git a/mx.graalpython/mx_graalpython.py b/mx.graalpython/mx_graalpython.py
@@ -2501,6 +2501,45 @@ def python_coverage(args):
         mx.run(cmdargs)
 
 
+def abi_check(_args):
+    for tool in ("abidw", "abidiff"):
+        if not shutil.which(tool):
+            mx.abort(f"Required tool '{tool}' was not found on PATH")
+
+    standalone_home = graalpy_standalone_home('jvm', dev=True, build=True)
+    shared_library = os.path.join(
+        standalone_home,
+        'lib',
+        f'graalpy{graal_version_short("major_minor")}',
+        'libpython-native.so',
+    )
+    if not os.path.exists(shared_library):
+        mx.abort(f"Could not find shared library to check: {shared_library}")
+
+    baseline = os.path.join(SUITE.dir, 'abi', f'abi-{GRAALPY_ABI_VERSION}.xml')
+    if not os.path.exists(baseline):
+        mx.abort(f"Could not find ABI baseline: {baseline}")
+
+    args = ['--suppressions', os.path.join(SUITE.dir, 'abi', 'suppressions-base.ini')]
+    versioned_suppressions = os.path.join(SUITE.dir, 'abi', f'suppressions-{GRAALPY_ABI_VERSION}.ini')
+    if os.path.exists(versioned_suppressions):
+        args += ['--suppressions', versioned_suppressions]
+
+    with tempfile.TemporaryDirectory(prefix='graalpy-abi-') as tmpdir:
+        dump_path = os.path.join(tmpdir, 'abi-current.xml')
+        run([
+            'abidw',
+            '--out-file', dump_path,
+            shared_library,
+        ])
+        run([
+            'abidiff',
+            *args,
+            baseline,
+            dump_path,
+        ], nonZeroIsFatal=True)
+
+
 class GraalpythonBuildTask(mx.ProjectBuildTask):
     class PrefixingOutput():
         def __init__(self, prefix, printfunc):
@@ -2932,6 +2971,7 @@ def update_github_unittest_tags(*args):
     'nativeclean': [nativeclean, ''],
     'python-src-import': [mx_graalpython_import.import_python_sources, ''],
     'python-coverage': [python_coverage, ''],
+    'abi-check': [abi_check, ''],
     'punittest': [punittest, ''],
     'graalpytest': [graalpytest, '[-h] [--python PYTHON] [TESTS]'],
     'clean': [python_clean, '[--just-pyc]'],
